File Doc Category Size Date Package
SignedObject.java API Doc Java SE 5 API 8878 Fri Aug 26 14:57:16 BST 2005 java.security

SignedObject

java.lang.Object

public final class SignedObject extends Object implements Serializable

SignedObject is a class for the purpose of creating authentic runtime objects whose integrity cannot be compromised without being detected.

More specifically, a SignedObject contains another Serializable object, the (to-be-)signed object and its signature.

The signed object is a "deep copy" (in serialized form) of an original object. Once the copy is made, further manipulation of the original object has no side effect on the copy.

The underlying signing algorithm is designated by the Signature object passed to the constructor and the verify method. A typical usage for signing is the following:

Signature signingEngine = Signature.getInstance(algorithm,
provider);
SignedObject so = new SignedObject(myobject, signingKey,
signingEngine);

A typical usage for verification is the following (having received SignedObject so):

Signature verificationEngine =
Signature.getInstance(algorithm, provider);
if (so.verify(publickey, verificationEngine))
try {
Object myobj = so.getObject();
} catch (java.lang.ClassNotFoundException e) {};

Several points are worth noting. First, there is no need to initialize the signing or verification engine, as it will be re-initialized inside the constructor and the verify method. Secondly, for verification to succeed, the specified public key must be the public key corresponding to the private key used to generate the SignedObject.

More importantly, for flexibility reasons, the constructor and verify method allow for customized signature engines, which can implement signature algorithms that are not installed formally as part of a crypto provider. However, it is crucial that the programmer writing the verifier code be aware what Signature engine is being used, as its own implementation of the verify method is invoked to verify a signature. In other words, a malicious Signature may choose to always return true on verification in an attempt to bypass a security check.

The signature algorithm can be, among others, the NIST standard DSA, using DSA and SHA-1. The algorithm is specified using the same convention as that for signatures. The DSA algorithm using the SHA-1 message digest algorithm can be specified, for example, as "SHA/DSA" or "SHA-1/DSA" (they are equivalent). In the case of RSA, there are multiple choices for the message digest algorithm, so the signing algorithm could be specified as, for example, "MD2/RSA", "MD5/RSA" or "SHA-1/RSA". The algorithm name must be specified, as there is no default.

The name of the Cryptography Package Provider is designated also by the Signature parameter to the constructor and the verify method. If the provider is not specified, the default provider is used. Each installation can be configured to use a particular provider as default.

Potential applications of SignedObject include:

It can be used internally to any Java runtime as an unforgeable authorization token -- one that can be passed around without the fear that the token can be maliciously modified without being detected.
It can be used to sign and serialize data/object for storage outside the Java runtime (e.g., storing critical access control data on disk).
Nested SignedObjects can be used to construct a logical sequence of signatures, resembling a chain of authorization and delegation.

see: Signature
version: 1.43, 12/19/03
author: Li Gong

Fields Summary
private static final long
serialVersionUID
private byte[]
content
private byte[]
signature
private String
thealgorithm
Constructors Summary
public SignedObject(Serializable object, PrivateKey signingKey, Signature signingEngine)
Constructs a SignedObject from any Serializable object. The given object is signed with the given signing key, using the designated signature engine.
param
object the object to be signed.
param
signingKey the private key for signing.
param
signingEngine the signature signing engine.
exception
IOException if an error occurs during serialization
exception
InvalidKeyException if the key is invalid.
exception
SignatureException if signing fails.
// creating a stream pipe-line, from a to b ByteArrayOutputStream b = new ByteArrayOutputStream(); ObjectOutput a = new ObjectOutputStream(b); // write and flush the object content to byte array a.writeObject(object); a.flush(); a.close(); this.content = b.toByteArray(); b.close(); // now sign the encapsulated object this.sign(signingKey, signingEngine);
Methods Summary
public java.lang.String getAlgorithm()
Retrieves the name of the signature algorithm.
return
the signature algorithm name.
return this.thealgorithm;
public java.lang.Object getObject()
Retrieves the encapsulated object. The encapsulated object is de-serialized before it is returned.
return
the encapsulated object.
exception
IOException if an error occurs during de-serialization
exception
ClassNotFoundException if an error occurs during de-serialization
// creating a stream pipe-line, from b to a ByteArrayInputStream b = new ByteArrayInputStream(this.content); ObjectInput a = new ObjectInputStream(b); Object obj = a.readObject(); b.close(); a.close(); return obj;
public byte[] getSignature()
Retrieves the signature on the signed object, in the form of a byte array.
return
the signature. Returns a new array each time this method is called.
byte[] sig = (byte[])this.signature.clone(); return sig;
private void readObject(java.io.ObjectInputStream s)
readObject is called to restore the state of the SignedObject from a stream.
s.defaultReadObject(); content = (byte[])content.clone(); signature = (byte[])signature.clone();
private void sign(java.security.PrivateKey signingKey, java.security.Signature signingEngine)
// initialize the signing engine signingEngine.initSign(signingKey); signingEngine.update((byte[])this.content.clone()); this.signature = (byte[])signingEngine.sign().clone(); this.thealgorithm = signingEngine.getAlgorithm();
public boolean verify(java.security.PublicKey verificationKey, java.security.Signature verificationEngine)
Verifies that the signature in this SignedObject is the valid signature for the object stored inside, with the given verification key, using the designated verification engine.
param
verificationKey the public key for verification.
param
verificationEngine the signature verification engine.
exception
SignatureException if signature verification failed.
exception
InvalidKeyException if the verification key is invalid.
return
true if the signature is valid, false otherwise
verificationEngine.initVerify(verificationKey); verificationEngine.update((byte[])this.content.clone()); return verificationEngine.verify((byte[])this.signature.clone());