java.security

Class SignedObject

Implemented Interfaces:
Serializable

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 (ClassNotFoundException ignored) {};
 

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 DSS, 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:

Since:
1.2
See Also:
Signature, Serialized Form

Constructor Summary

SignedObject(Serializable object, PrivateKey signingKey, Signature signingEngine)
Constructs a SignedObject from any Serializable object.

Method Summary

String
getAlgorithm()
Retrieves the name of the signature algorithm.
Object
getObject()
Retrieves the encapsulated object.
byte[]
getSignature()
Retrieves the signature on the signed object, in the form of a byte array.
boolean
verify(PublicKey verificationKey, 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SignedObject

public SignedObject(Serializable object,
                    PrivateKey signingKey,
                    Signature signingEngine)
            throws IOException,
                   InvalidKeyException,
                   SignatureException
Constructs a SignedObject from any Serializable object. The given object is signed with the given signing key, using the designated signature engine.
Parameters:
object - the object to be signed.
signingKey - the private key for signing.
signingEngine - the signature signing engine.
Throws:
IOException - if an error occurs during serialization.
InvalidKeyException - if the key is invalid.
SignatureException - if signing fails.

Method Details

getAlgorithm

public String getAlgorithm()
Retrieves the name of the signature algorithm.
Returns:
the signature algorithm name.

getObject

public Object getObject()
            throws IOException,
                   ClassNotFoundException
Retrieves the encapsulated object. The encapsulated object is de-serialized before it is returned.
Returns:
the encapsulated object.
Throws:
IOException - if an error occurs during de-serialization.
ClassNotFoundException - if an error occurs during de-serialization.

getSignature

public byte[] getSignature()
Retrieves the signature on the signed object, in the form of a byte array.
Returns:
a copy of the signature.

verify

public boolean verify(PublicKey verificationKey,
                      Signature verificationEngine)
            throws InvalidKeyException,
                   SignatureException
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.
Parameters:
verificationKey - the public key for verification.
verificationEngine - the signature verification engine.
Returns:
true if the signature is valid, false otherwise.
Throws:
SignatureException - if signature verification failed.
InvalidKeyException - if the verification key is invalid.

SignedObject.java --- Signed Object Class Copyright (C) 1999, 2003, Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.