diff options
Diffstat (limited to 'libjava/classpath/java/security/SignedObject.java')
| -rw-r--r-- | libjava/classpath/java/security/SignedObject.java | 177 |
1 files changed, 70 insertions, 107 deletions
diff --git a/libjava/classpath/java/security/SignedObject.java b/libjava/classpath/java/security/SignedObject.java index d565b2ea3b4..be5a6746122 100644 --- a/libjava/classpath/java/security/SignedObject.java +++ b/libjava/classpath/java/security/SignedObject.java @@ -46,82 +46,34 @@ import java.io.ObjectOutputStream; import java.io.Serializable; /** - * <p><code>SignedObject</code> is a class for the purpose of creating authentic - * runtime objects whose integrity cannot be compromised without being detected. - * </p> - * - * <p>More specifically, a <code>SignedObject</code> contains another - * {@link Serializable} object, the (to-be-)signed object and its signature.</p> - * - * <p>The signed object is a <i>"deep copy"</i> (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.</p> - * - * <p>The underlying signing algorithm is designated by the {@link Signature} - * object passed to the constructor and the <code>verify()</code> method. A - * typical usage for signing is the following:</p> - * - * <pre> - * Signature signingEngine = Signature.getInstance(algorithm, provider); - * SignedObject so = new SignedObject(myobject, signingKey, signingEngine); - * </pre> - * - * <p>A typical usage for verification is the following (having received - * <code>SignedObject</code> so):</p> - * - * <pre> - * Signature verificationEngine = Signature.getInstance(algorithm, provider); - * if (so.verify(publickey, verificationEngine)) - * try - * { - * Object myobj = so.getObject(); - * } - * catch (ClassNotFoundException ignored) {}; - * </pre> - * - * <p>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 <code>verify()</code> method. Secondly, for verification - * to succeed, the specified public key must be the public key corresponding to - * the private key used to generate the <code>SignedObject</code>.</p> - * - * <p>More importantly, for flexibility reasons, the <code>constructor</code> - * and <code>verify()</code> 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 {@link Signature} engine is being used, as - * its own implementation of the <code>verify()</code> method is invoked to - * verify a signature. In other words, a malicious {@link Signature} may choose - * to always return <code>true</code> on verification in an attempt to bypass a - * security check.</p> - * - * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>, - * using <i>DSA</i> and <i>SHA-1</i>. The algorithm is specified using the same - * convention as that for signatures. The <i>DSA</i> algorithm using the - * <i>SHA-1</i> message digest algorithm can be specified, for example, as - * <code>"SHA/DSA"</code> or <code>"SHA-1/DSA"</code> (they are equivalent). In - * the case of <i>RSA</i>, there are multiple choices for the message digest - * algorithm, so the signing algorithm could be specified as, for example, - * <code>"MD2/RSA"</code>, <code>"MD5/RSA"</code> or <code>"SHA-1/RSA"</code>. - * The algorithm name must be specified, as there is no default.</p> - * - * <p>The name of the Cryptography Package Provider is designated also by the - * {@link Signature} parameter to the <code>constructor</code> and the <code> - * verify()</code> method. If the provider is not specified, the default - * provider is used. Each installation can be configured to use a particular - * provider as default.</p> - * - * <p>Potential applications of <code>SignedObject</code> include:</p> - * - * <ul> - * <li>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.</li> - * <li>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).</li> - * <li>Nested <i>SignedObjects</i> can be used to construct a logical sequence - * of signatures, resembling a chain of authorization and delegation.</li> - * </ul> + * <code>SignedObject</code> is used for storing runtime objects whose + * integrity cannot be compromised without being detected. + * + * <p><code>SignedObject</code> contains a {@link Serializable} object which is + * yet to be signed and a digital signature of that object.</p> + * + * <p>The signed copy is a "deep copy" (in serialized form) of an original + * object. Any changes to that original instance are not reflected in the + * enclosed copy inside this <code>SignedObject</code>.</p> + * + * <p>Several things to note are that, first there is no need to initialize the + * signature engine as this class will handle that automatically. Second, + * verification will only succeed if the public key corresponds to the private + * key used to generate the digital signature inside this + * <code>SignedObject</code>.</p> + * + * <p>For fexibility, the signature engine can be specified in the constructor + * or the <code>verify()</code> method. Programmers wishing to verify + * <code>SignedObject</code>s should be aware of the {@link Signature} engine + * they use. A malicious or flawed {@link Signature} implementation may always + * return true on verification thus circumventing the intended secrity check + * provided by the <code>SignedObject</code>.</p> + * + * <p>The GNU security provider offers an implementation of the standard NIST + * DSA which uses "DSA" and "SHA-1". It can be specified by "SHA/DSA", + * "SHA-1/DSA" or its OID. If the RSA signature algorithm is provided then it + * could be "MD2/RSA". "MD5/RSA", or "SHA-1/RSA". The algorithm must be + * specified because there is no default.</p> * * @author Mark Benvenuto (ivymccough@worldnet.att.net) * @since 1.2 @@ -139,16 +91,22 @@ public final class SignedObject implements Serializable private String thealgorithm; /** - * Constructs a <code>SignedObject</code> from any {@link 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. - * @throws IOException if an error occurs during serialization. - * @throws InvalidKeyException if the key is invalid. - * @throws SignatureException if signing fails. + * Constructs a new instance of <code>SignedObject</code> from a + * {@link Serializable} object. The object is signed with a designated + * private key and a signature engine. + * + * @param object + * the object to sign. + * @param signingKey + * the key to use. + * @param signingEngine + * the signature engine to use. + * @throws IOException + * if a serialization error occurred. + * @throws InvalidKeyException + * if the key is invalid. + * @throws SignatureException + * if a signing error occurs. */ public SignedObject(Serializable object, PrivateKey signingKey, Signature signingEngine) @@ -170,12 +128,14 @@ public final class SignedObject implements Serializable } /** - * Retrieves the encapsulated object. The encapsulated object is de-serialized - * before it is returned. - * + * Returns the encapsulated object. The object is de-serialized before being + * returned. + * * @return the encapsulated object. - * @throws IOException if an error occurs during de-serialization. - * @throws ClassNotFoundException if an error occurs during de-serialization. + * @throws IOException + * if a de-serialization error occurs. + * @throws ClassNotFoundException + * if the encapsulated object's class was not found. */ public Object getObject() throws IOException, ClassNotFoundException { @@ -189,9 +149,9 @@ public final class SignedObject implements Serializable } /** - * Retrieves the signature on the signed object, in the form of a byte array. - * - * @return a copy of the signature. + * Returns the signature bytes of the encapsulated object. + * + * @return the signature bytes of the encapsulated object. */ public byte[] getSignature() { @@ -200,9 +160,9 @@ public final class SignedObject implements Serializable } /** - * Retrieves the name of the signature algorithm. - * - * @return the signature algorithm name. + * Returns the name of the signature algorithm. + * + * @return the name of the signature algorithm. */ public String getAlgorithm() { @@ -210,16 +170,19 @@ public final class SignedObject implements Serializable } /** - * Verifies that the signature in this <code>SignedObject</code> 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. - * @return <code>true</code> if the signature is valid, <code>false</code> - * otherwise. - * @throws SignatureException if signature verification failed. - * @throws InvalidKeyException if the verification key is invalid. + * Verifies the encapsulated digital signature by checking that it was + * generated by the owner of a designated public key. + * + * @param verificationKey + * the public key to use. + * @param verificationEngine + * the signature engine to use. + * @return <code>true</code> if signature is correct, <code>false</code> + * otherwise. + * @throws InvalidKeyException + * if the key is invalid. + * @throws SignatureException + * if verification fails. */ public boolean verify(PublicKey verificationKey, Signature verificationEngine) throws InvalidKeyException, SignatureException |