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