author | wetmore |
Fri, 11 May 2018 15:53:12 -0700 | |
branch | JDK-8145252-TLS13-branch |
changeset 56542 | 56aaa6cb3693 |
parent 47216 | 71c04702a3d5 |
child 56548 | 208b4e9365cd |
permissions | -rw-r--r-- |
2 | 1 |
/* |
56542 | 2 |
* Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved. |
2 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 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 |
* |
|
5506 | 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. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.security; |
|
27 |
||
28 |
import java.io.*; |
|
56542 | 29 |
import java.security.spec.AlgorithmParameterSpec; |
2 | 30 |
|
31 |
/** |
|
32 |
* <p> SignedObject is a class for the purpose of creating authentic |
|
33 |
* runtime objects whose integrity cannot be compromised without being |
|
34 |
* detected. |
|
35 |
* |
|
36 |
* <p> More specifically, a SignedObject contains another Serializable |
|
37 |
* object, the (to-be-)signed object and its signature. |
|
38 |
* |
|
39 |
* <p> The signed object is a "deep copy" (in serialized form) of an |
|
40 |
* original object. Once the copy is made, further manipulation of |
|
41 |
* the original object has no side effect on the copy. |
|
42 |
* |
|
43 |
* <p> The underlying signing algorithm is designated by the Signature |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
44 |
* object passed to the constructor and the {@code verify} method. |
2 | 45 |
* A typical usage for signing is the following: |
46 |
* |
|
21334 | 47 |
* <pre>{@code |
2 | 48 |
* Signature signingEngine = Signature.getInstance(algorithm, |
49 |
* provider); |
|
50 |
* SignedObject so = new SignedObject(myobject, signingKey, |
|
56542 | 51 |
* signingParams, signingEngine); |
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
52 |
* }</pre> |
2 | 53 |
* |
54 |
* <p> A typical usage for verification is the following (having |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
55 |
* received SignedObject {@code so}): |
2 | 56 |
* |
21334 | 57 |
* <pre>{@code |
2 | 58 |
* Signature verificationEngine = |
59 |
* Signature.getInstance(algorithm, provider); |
|
56542 | 60 |
* if (so.verify(verificationKey, verificationParams, verificationEngine)) |
2 | 61 |
* try { |
62 |
* Object myobj = so.getObject(); |
|
63 |
* } catch (java.lang.ClassNotFoundException e) {}; |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
64 |
* }</pre> |
2 | 65 |
* |
66 |
* <p> Several points are worth noting. First, there is no need to |
|
67 |
* initialize the signing or verification engine, as it will be |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
68 |
* re-initialized inside the constructor and the {@code verify} |
2 | 69 |
* method. Secondly, for verification to succeed, the specified |
70 |
* public key must be the public key corresponding to the private key |
|
56542 | 71 |
* used to generate the SignedObject. If signing parameters are used, |
72 |
* the same parameters must be specified when calling {@code verify} |
|
73 |
* method for verification to succeed. |
|
2 | 74 |
* |
75 |
* <p> More importantly, for flexibility reasons, the |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
76 |
* constructor and {@code verify} method allow for |
2 | 77 |
* customized signature engines, which can implement signature |
78 |
* algorithms that are not installed formally as part of a crypto |
|
79 |
* provider. However, it is crucial that the programmer writing the |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
80 |
* verifier code be aware what {@code Signature} engine is being |
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
81 |
* used, as its own implementation of the {@code verify} method |
2 | 82 |
* is invoked to verify a signature. In other words, a malicious |
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
83 |
* {@code Signature} may choose to always return true on |
2 | 84 |
* verification in an attempt to bypass a security check. |
85 |
* |
|
86 |
* <p> The signature algorithm can be, among others, the NIST standard |
|
46053
6f7e93cb432a
8169080: Improve documentation examples for crypto applications
wetmore
parents:
45434
diff
changeset
|
87 |
* DSA, using DSA and SHA-256. The algorithm is specified using the |
2 | 88 |
* same convention as that for signatures. The DSA algorithm using the |
46053
6f7e93cb432a
8169080: Improve documentation examples for crypto applications
wetmore
parents:
45434
diff
changeset
|
89 |
* SHA-256 message digest algorithm can be specified, for example, as |
6f7e93cb432a
8169080: Improve documentation examples for crypto applications
wetmore
parents:
45434
diff
changeset
|
90 |
* "SHA256withDSA". In the case of |
6f7e93cb432a
8169080: Improve documentation examples for crypto applications
wetmore
parents:
45434
diff
changeset
|
91 |
* RSA the signing algorithm could be specified as, for example, |
6f7e93cb432a
8169080: Improve documentation examples for crypto applications
wetmore
parents:
45434
diff
changeset
|
92 |
* "SHA256withRSA". The algorithm name must be |
2 | 93 |
* specified, as there is no default. |
94 |
* |
|
95 |
* <p> The name of the Cryptography Package Provider is designated |
|
96 |
* also by the Signature parameter to the constructor and the |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
97 |
* {@code verify} method. If the provider is not |
2 | 98 |
* specified, the default provider is used. Each installation can |
99 |
* be configured to use a particular provider as default. |
|
100 |
* |
|
101 |
* <p> Potential applications of SignedObject include: |
|
102 |
* <ul> |
|
103 |
* <li> It can be used |
|
104 |
* internally to any Java runtime as an unforgeable authorization |
|
105 |
* token -- one that can be passed around without the fear that the |
|
106 |
* token can be maliciously modified without being detected. |
|
107 |
* <li> It |
|
108 |
* can be used to sign and serialize data/object for storage outside |
|
109 |
* the Java runtime (e.g., storing critical access control data on |
|
110 |
* disk). |
|
111 |
* <li> Nested SignedObjects can be used to construct a logical |
|
112 |
* sequence of signatures, resembling a chain of authorization and |
|
113 |
* delegation. |
|
114 |
* </ul> |
|
115 |
* |
|
116 |
* @see Signature |
|
117 |
* |
|
118 |
* @author Li Gong |
|
45434
4582657c7260
8181082: class-level since tag issues in java.base & java.datatransfer module
mli
parents:
25859
diff
changeset
|
119 |
* @since 1.2 |
2 | 120 |
*/ |
121 |
||
122 |
public final class SignedObject implements Serializable { |
|
123 |
||
124 |
private static final long serialVersionUID = 720502720485447167L; |
|
125 |
||
126 |
/* |
|
127 |
* The original content is "deep copied" in its serialized format |
|
128 |
* and stored in a byte array. The signature field is also in the |
|
129 |
* form of byte array. |
|
130 |
*/ |
|
131 |
||
132 |
private byte[] content; |
|
133 |
private byte[] signature; |
|
134 |
private String thealgorithm; |
|
135 |
||
136 |
/** |
|
137 |
* Constructs a SignedObject from any Serializable object. |
|
56542 | 138 |
* The given object is signed with the given signing key with |
139 |
* no signature parameters, using the designated signature engine. |
|
2 | 140 |
* |
141 |
* @param object the object to be signed. |
|
142 |
* @param signingKey the private key for signing. |
|
143 |
* @param signingEngine the signature signing engine. |
|
144 |
* |
|
145 |
* @exception IOException if an error occurs during serialization |
|
146 |
* @exception InvalidKeyException if the key is invalid. |
|
147 |
* @exception SignatureException if signing fails. |
|
148 |
*/ |
|
149 |
public SignedObject(Serializable object, PrivateKey signingKey, |
|
150 |
Signature signingEngine) |
|
151 |
throws IOException, InvalidKeyException, SignatureException { |
|
56542 | 152 |
// creating a stream pipe-line, from a to b |
153 |
ByteArrayOutputStream b = new ByteArrayOutputStream(); |
|
154 |
ObjectOutput a = new ObjectOutputStream(b); |
|
155 |
||
156 |
// write and flush the object content to byte array |
|
157 |
a.writeObject(object); |
|
158 |
a.flush(); |
|
159 |
a.close(); |
|
160 |
this.content = b.toByteArray(); |
|
161 |
b.close(); |
|
162 |
||
163 |
// now sign the encapsulated object |
|
164 |
try { |
|
165 |
this.sign(signingKey, null, signingEngine); |
|
166 |
} catch (InvalidAlgorithmParameterException e) { |
|
167 |
// should not happen, re-throw just in case |
|
168 |
throw new SignatureException(e); |
|
169 |
} |
|
170 |
} |
|
2 | 171 |
|
56542 | 172 |
/** |
173 |
* Constructs a SignedObject from any Serializable object. |
|
174 |
* The given object is signed with the given signing key and |
|
175 |
* signature parameters, using the designated signature engine. |
|
176 |
* If the signature algorithm does not use any signature parameters, |
|
177 |
* {@code signingParams} should be null. |
|
178 |
* |
|
179 |
* @param object the object to be signed. |
|
180 |
* @param signingKey the private key for signing. |
|
181 |
* @param signingParams the signature parameters used for signing, |
|
182 |
* may be null. |
|
183 |
* @param signingEngine the signature signing engine. |
|
184 |
* |
|
185 |
* @exception IOException if an error occurs during serialization |
|
186 |
* @exception InvalidKeyException if the key is invalid. |
|
187 |
* @exception InvalidAlgorithmParameterException if the given signature |
|
188 |
* parameters is invalid. |
|
189 |
* @exception SignatureException if signing fails. |
|
190 |
* @since 11 |
|
191 |
*/ |
|
192 |
public SignedObject(Serializable object, PrivateKey signingKey, |
|
193 |
AlgorithmParameterSpec signingParams, |
|
194 |
Signature signingEngine) |
|
195 |
throws IOException, InvalidKeyException, |
|
196 |
InvalidAlgorithmParameterException, SignatureException { |
|
197 |
// creating a stream pipe-line, from a to b |
|
198 |
ByteArrayOutputStream b = new ByteArrayOutputStream(); |
|
199 |
ObjectOutput a = new ObjectOutputStream(b); |
|
2 | 200 |
|
56542 | 201 |
// write and flush the object content to byte array |
202 |
a.writeObject(object); |
|
203 |
a.flush(); |
|
204 |
a.close(); |
|
205 |
this.content = b.toByteArray(); |
|
206 |
b.close(); |
|
207 |
||
208 |
// now sign the encapsulated object |
|
209 |
this.sign(signingKey, signingParams, signingEngine); |
|
2 | 210 |
} |
211 |
||
212 |
/** |
|
213 |
* Retrieves the encapsulated object. |
|
214 |
* The encapsulated object is de-serialized before it is returned. |
|
215 |
* |
|
216 |
* @return the encapsulated object. |
|
217 |
* |
|
218 |
* @exception IOException if an error occurs during de-serialization |
|
219 |
* @exception ClassNotFoundException if an error occurs during |
|
220 |
* de-serialization |
|
221 |
*/ |
|
222 |
public Object getObject() |
|
56542 | 223 |
throws IOException, ClassNotFoundException { |
2 | 224 |
// creating a stream pipe-line, from b to a |
225 |
ByteArrayInputStream b = new ByteArrayInputStream(this.content); |
|
226 |
ObjectInput a = new ObjectInputStream(b); |
|
227 |
Object obj = a.readObject(); |
|
228 |
b.close(); |
|
229 |
a.close(); |
|
230 |
return obj; |
|
231 |
} |
|
232 |
||
233 |
/** |
|
234 |
* Retrieves the signature on the signed object, in the form of a |
|
235 |
* byte array. |
|
236 |
* |
|
237 |
* @return the signature. Returns a new array each time this |
|
238 |
* method is called. |
|
239 |
*/ |
|
240 |
public byte[] getSignature() { |
|
241 |
return this.signature.clone(); |
|
242 |
} |
|
243 |
||
244 |
/** |
|
245 |
* Retrieves the name of the signature algorithm. |
|
246 |
* |
|
247 |
* @return the signature algorithm name. |
|
248 |
*/ |
|
249 |
public String getAlgorithm() { |
|
250 |
return this.thealgorithm; |
|
251 |
} |
|
252 |
||
253 |
/** |
|
254 |
* Verifies that the signature in this SignedObject is the valid |
|
255 |
* signature for the object stored inside, with the given |
|
56542 | 256 |
* verification key with no signature parameters, using the designated |
257 |
* verification engine. |
|
2 | 258 |
* |
259 |
* @param verificationKey the public key for verification. |
|
260 |
* @param verificationEngine the signature verification engine. |
|
261 |
* |
|
25524
e623ca817d50
4867890: Clarify the return value/exception for java.security.SignedObject.verify
mullan
parents:
21334
diff
changeset
|
262 |
* @exception SignatureException if signature verification failed (an |
e623ca817d50
4867890: Clarify the return value/exception for java.security.SignedObject.verify
mullan
parents:
21334
diff
changeset
|
263 |
* exception prevented the signature verification engine from completing |
e623ca817d50
4867890: Clarify the return value/exception for java.security.SignedObject.verify
mullan
parents:
21334
diff
changeset
|
264 |
* normally). |
2 | 265 |
* @exception InvalidKeyException if the verification key is invalid. |
266 |
* |
|
18579
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
267 |
* @return {@code true} if the signature |
b678846778ad
8019360: Cleanup of the javadoc <code> tag in java.security.*
juh
parents:
9826
diff
changeset
|
268 |
* is valid, {@code false} otherwise |
2 | 269 |
*/ |
270 |
public boolean verify(PublicKey verificationKey, |
|
271 |
Signature verificationEngine) |
|
272 |
throws InvalidKeyException, SignatureException { |
|
56542 | 273 |
try { |
274 |
return verify(verificationKey, null, verificationEngine); |
|
275 |
} catch (InvalidAlgorithmParameterException e) { |
|
276 |
// should not happen, re-throw just in case |
|
277 |
throw new SignatureException(e); |
|
278 |
} |
|
279 |
} |
|
280 |
||
281 |
/** |
|
282 |
* Verifies that the signature in this SignedObject is the valid |
|
283 |
* signature for the object stored inside, with the given |
|
284 |
* verification key and signature parameters, using the designated |
|
285 |
* verification engine. If the signature algorithm does not use any |
|
286 |
* signature parameters, {@code verificationParams} should be null. |
|
287 |
* When signature parameters are used in signing, the same parameters |
|
288 |
* must be specified when calling {@code verify} method for the |
|
289 |
* verification to succeed. |
|
290 |
* |
|
291 |
* @param verificationKey the public key for verification. |
|
292 |
* @param verificationParams the signature parameters for verification. |
|
293 |
* @param verificationEngine the signature verification engine. |
|
294 |
* |
|
295 |
* @exception SignatureException if signature verification failed (an |
|
296 |
* exception prevented the signature verification engine from completing |
|
297 |
* normally). |
|
298 |
* @exception InvalidKeyException if the verification key is invalid. |
|
299 |
* @exception InvalidAlgorithmParameterException if the given signature |
|
300 |
* parameters is invalid |
|
301 |
* @return {@code true} if the signature is valid, {@code false} otherwise |
|
302 |
* @since 11 |
|
303 |
*/ |
|
304 |
public boolean verify(PublicKey verificationKey, |
|
305 |
AlgorithmParameterSpec verificationParams, |
|
306 |
Signature verificationEngine) |
|
307 |
throws InvalidKeyException, InvalidAlgorithmParameterException, |
|
308 |
SignatureException { |
|
309 |
// set parameteres before Signature.initSign/initVerify call, |
|
310 |
// so key can be checked when it's set |
|
311 |
try { |
|
312 |
verificationEngine.setParameter(verificationParams); |
|
313 |
} catch (UnsupportedOperationException e) { |
|
314 |
// for backward compatibility, only re-throw when |
|
315 |
// parameters is not null |
|
316 |
if (verificationParams != null) throw e; |
|
317 |
} |
|
318 |
verificationEngine.initVerify(verificationKey); |
|
319 |
verificationEngine.update(this.content.clone()); |
|
320 |
return verificationEngine.verify(this.signature.clone()); |
|
2 | 321 |
} |
322 |
||
323 |
/* |
|
324 |
* Signs the encapsulated object with the given signing key, using the |
|
325 |
* designated signature engine. |
|
326 |
* |
|
327 |
* @param signingKey the private key for signing. |
|
56542 | 328 |
* @param signingParams the signature parameters for signing. |
2 | 329 |
* @param signingEngine the signature signing engine. |
330 |
* |
|
331 |
* @exception InvalidKeyException if the key is invalid. |
|
56542 | 332 |
* @exception InvalidAlgorithmParameterException if the given signature |
333 |
* parameters is invalid |
|
2 | 334 |
* @exception SignatureException if signing fails. |
335 |
*/ |
|
56542 | 336 |
private void sign(PrivateKey signingKey, |
337 |
AlgorithmParameterSpec signingParams, |
|
338 |
Signature signingEngine) |
|
339 |
throws InvalidKeyException, InvalidAlgorithmParameterException, |
|
340 |
SignatureException { |
|
341 |
// set parameteres before Signature.initSign/initVerify call, |
|
342 |
// so key can be checked when it's set |
|
343 |
try { |
|
344 |
signingEngine.setParameter(signingParams); |
|
345 |
} catch (UnsupportedOperationException e) { |
|
346 |
// for backward compatibility, only re-throw when |
|
347 |
// parameters is not null |
|
348 |
if (signingParams != null) throw e; |
|
349 |
} |
|
350 |
signingEngine.initSign(signingKey); |
|
351 |
signingEngine.update(this.content.clone()); |
|
352 |
this.signature = signingEngine.sign().clone(); |
|
353 |
this.thealgorithm = signingEngine.getAlgorithm(); |
|
2 | 354 |
} |
355 |
||
356 |
/** |
|
357 |
* readObject is called to restore the state of the SignedObject from |
|
358 |
* a stream. |
|
359 |
*/ |
|
360 |
private void readObject(java.io.ObjectInputStream s) |
|
9826
0f553990ca93
6618658: Deserialization allows creation of mutable SignedObject
weijun
parents:
5506
diff
changeset
|
361 |
throws java.io.IOException, ClassNotFoundException { |
56542 | 362 |
java.io.ObjectInputStream.GetField fields = s.readFields(); |
363 |
content = ((byte[])fields.get("content", null)).clone(); |
|
364 |
signature = ((byte[])fields.get("signature", null)).clone(); |
|
365 |
thealgorithm = (String)fields.get("thealgorithm", null); |
|
2 | 366 |
} |
367 |
} |