SignedObject


1   /*
2    * @(#)SignedObject.java    1.43 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7    
8   package java.security;
9   
10  import java.io.*;
11  
12  /**
13   * <p> SignedObject is a class for the purpose of creating authentic
14   * runtime objects whose integrity cannot be compromised without being
15   * detected.
16   *
17   * <p> More specifically, a SignedObject contains another Serializable
18   * object, the (to-be-)signed object and its signature.
19   *
20   * <p> The signed object is a "deep copy" (in serialized form) of an
21   * original object.  Once the copy is made, further manipulation of
22   * the original object has no side effect on the copy.
23   *
24   * <p> The underlying signing algorithm is designated by the Signature
25   * object passed to the constructor and the <code>verify</code> method.
26   * A typical usage for signing is the following:
27   *
28   * <p> <code> <pre>
29   * Signature signingEngine = Signature.getInstance(algorithm,
30   *                                                 provider);
31   * SignedObject so = new SignedObject(myobject, signingKey,
32   *                                    signingEngine);
33   * </pre> </code>
34   *
35   * <p> A typical usage for verification is the following (having
36   * received SignedObject <code>so</code>):
37   *
38   * <p> <code> <pre>
39   * Signature verificationEngine =
40   *     Signature.getInstance(algorithm, provider);
41   * if (so.verify(publickey, verificationEngine))
42   *     try {
43   *         Object myobj = so.getObject();
44   *     } catch (java.lang.ClassNotFoundException e) {};
45   * </pre> </code>
46   *
47   * <p> Several points are worth noting.  First, there is no need to
48   * initialize the signing or verification engine, as it will be
49   * re-initialized inside the constructor and the <code>verify</code>
50   * method. Secondly, for verification to succeed, the specified
51   * public key must be the public key corresponding to the private key
52   * used to generate the SignedObject.
53   *
54   * <p> More importantly, for flexibility reasons, the
55   * constructor and <code>verify</code> method allow for
56   * customized signature engines, which can implement signature
57   * algorithms that are not installed formally as part of a crypto
58   * provider.  However, it is crucial that the programmer writing the
59   * verifier code be aware what <code>Signature</code> engine is being
60   * used, as its own implementation of the <code>verify</code> method
61   * is invoked to verify a signature.  In other words, a malicious
62   * <code>Signature</code> may choose to always return true on
63   * verification in an attempt to bypass a security check.
64   *
65   * <p> The signature algorithm can be, among others, the NIST standard
66   * DSA, using DSA and SHA-1.  The algorithm is specified using the
67   * same convention as that for signatures. The DSA algorithm using the
68   * SHA-1 message digest algorithm can be specified, for example, as
69   * "SHA/DSA" or "SHA-1/DSA" (they are equivalent).  In the case of
70   * RSA, there are multiple choices for the message digest algorithm,
71   * so the signing algorithm could be specified as, for example,
72   * "MD2/RSA", "MD5/RSA" or "SHA-1/RSA".  The algorithm name must be
73   * specified, as there is no default.
74   *
75   * <p> The name of the Cryptography Package Provider is designated
76   * also by the Signature parameter to the constructor and the
77   * <code>verify</code> method.  If the provider is not
78   * specified, the default provider is used.  Each installation can
79   * be configured to use a particular provider as default.
80   *
81   * <p> Potential applications of SignedObject include: 
82   * <ul>
83   * <li> It can be used
84   * internally to any Java runtime as an unforgeable authorization
85   * token -- one that can be passed around without the fear that the
86   * token can be maliciously modified without being detected. 
87   * <li> It
88   * can be used to sign and serialize data/object for storage outside
89   * the Java runtime (e.g., storing critical access control data on
90   * disk). 
91   * <li> Nested SignedObjects can be used to construct a logical
92   * sequence of signatures, resembling a chain of authorization and
93   * delegation.
94   * </ul>
95   *
96   * @see Signature
97   *
98   * @version     1.43, 12/19/03
99   * @author Li Gong
100  */
101 
102 public final class SignedObject implements Serializable {
103 
104     private static final long serialVersionUID = 720502720485447167L;
105 
106     /*
107      * The original content is "deep copied" in its serialized format
108      * and stored in a byte array.  The signature field is also in the
109      * form of byte array.
110      */
111 
112     private byte[] content;
113     private byte[] signature;
114     private String   thealgorithm;
115 
116     /**
117      * Constructs a SignedObject from any Serializable object.
118      * The given object is signed with the given signing key, using the
119      * designated signature engine.
120      *
121      * @param object the object to be signed. 
122      * @param signingKey the private key for signing.
123      * @param signingEngine the signature signing engine.
124      *
125      * @exception IOException if an error occurs during serialization
126      * @exception InvalidKeyException if the key is invalid.
127      * @exception SignatureException if signing fails.
128      */
129     public SignedObject(Serializable object, PrivateKey   signingKey,
130             Signature   signingEngine)
131     throws IOException, InvalidKeyException  , SignatureException   {
132         // creating a stream pipe-line, from a to b
133         ByteArrayOutputStream b = new ByteArrayOutputStream();
134         ObjectOutput a = new ObjectOutputStream(b);
135         
136         // write and flush the object content to byte array
137         a.writeObject(object);
138         a.flush();
139         a.close();
140         this.content = b.toByteArray();
141         b.close();
142         
143         // now sign the encapsulated object
144         this.sign(signingKey, signingEngine);
145     }
146 
147     /**
148      * Retrieves the encapsulated object.
149      * The encapsulated object is de-serialized before it is returned.
150      * 
151      * @return the encapsulated object.
152      *
153      * @exception IOException if an error occurs during de-serialization
154      * @exception ClassNotFoundException if an error occurs during 
155      * de-serialization
156      */
157     public Object   getObject() 
158     throws IOException, ClassNotFoundException  
159     {
160     // creating a stream pipe-line, from b to a
161     ByteArrayInputStream b = new ByteArrayInputStream(this.content);
162     ObjectInput a = new ObjectInputStream(b);
163     Object   obj = a.readObject();
164     b.close();
165     a.close();
166     return obj;
167     }
168 
169     /**
170      * Retrieves the signature on the signed object, in the form of a
171      * byte array.
172      * 
173      * @return the signature. Returns a new array each time this 
174      * method is called.
175      */
176     public byte[] getSignature() {
177     byte[] sig = (byte[])this.signature.clone();
178     return sig;
179     }
180 
181     /**
182      * Retrieves the name of the signature algorithm.
183      *
184      * @return the signature algorithm name.
185      */
186     public String   getAlgorithm() {
187     return this.thealgorithm;
188     }
189 
190     /** 
191      * Verifies that the signature in this SignedObject is the valid
192      * signature for the object stored inside, with the given
193      * verification key, using the designated verification engine.
194      * 
195      * @param verificationKey the public key for verification.
196      * @param verificationEngine the signature verification engine.
197      *
198      * @exception SignatureException if signature verification failed.
199      * @exception InvalidKeyException if the verification key is invalid.
200      *
201      * @return <tt>true</tt> if the signature 
202      * is valid, <tt>false</tt> otherwise
203      */
204     public boolean verify(PublicKey   verificationKey,
205               Signature   verificationEngine)
206      throws InvalidKeyException  , SignatureException   {
207          verificationEngine.initVerify(verificationKey);
208          verificationEngine.update((byte[])this.content.clone());
209          return verificationEngine.verify((byte[])this.signature.clone());
210     }
211 
212     /*
213      * Signs the encapsulated object with the given signing key, using the
214      * designated signature engine.
215      * 
216      * @param signingKey the private key for signing.
217      * @param signingEngine the signature signing engine.
218      *
219      * @exception InvalidKeyException if the key is invalid.
220      * @exception SignatureException if signing fails.
221      */
222     private void sign(PrivateKey   signingKey, Signature   signingEngine)
223     throws InvalidKeyException  , SignatureException   {
224         // initialize the signing engine
225         signingEngine.initSign(signingKey);
226         signingEngine.update((byte[])this.content.clone());
227         this.signature = (byte[])signingEngine.sign().clone();
228         this.thealgorithm = signingEngine.getAlgorithm();
229     }
230 
231     /**
232      * readObject is called to restore the state of the SignedObject from
233      * a stream.
234      */
235     private void readObject(java.io.ObjectInputStream   s)
236          throws java.io.IOException  , ClassNotFoundException  
237     {
238     s.defaultReadObject();
239     content = (byte[])content.clone();
240     signature = (byte[])signature.clone();
241     }
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags