1 /*
2 * Copyright (c) 1996, 2016, 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.util.*;
29 import java.util.regex.*;
30
31 import java.security.Provider.Service;
32
33 import sun.security.jca.*;
34 import sun.security.jca.GetInstance.Instance;
35 import sun.security.util.Debug;
36
37 /**
38 * This class provides a cryptographically strong random number
39 * generator (RNG).
40 *
41 * <p>A cryptographically strong random number
42 * minimally complies with the statistical random number generator tests
43 * specified in
44 * <a href="http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf">
45 * <i>FIPS 140-2, Security Requirements for Cryptographic Modules</i></a>,
46 * section 4.9.1.
47 * Additionally, SecureRandom must produce non-deterministic output.
48 * Therefore any seed material passed to a SecureRandom object must be
49 * unpredictable, and all SecureRandom output sequences must be
50 * cryptographically strong, as described in
51 * <a href="http://tools.ietf.org/html/rfc4086">
52 * <i>RFC 4086: Randomness Requirements for Security</i></a>.
53 *
54 * <p>A caller obtains a SecureRandom instance via the
55 * no-argument constructor or one of the {@code getInstance} methods:
56 *
57 * <pre>
58 * SecureRandom random = new SecureRandom();
59 * </pre>
60 *
61 * <p> Many SecureRandom implementations are in the form of a pseudo-random
62 * number generator (PRNG), which means they use a deterministic algorithm
63 * to produce a pseudo-random sequence from a true random seed.
64 * Other implementations may produce true random numbers,
65 * and yet others may use a combination of both techniques.
66 *
67 * <p> Typical callers of SecureRandom invoke the following methods
68 * to retrieve random bytes:
69 *
70 * <pre>
71 * SecureRandom random = new SecureRandom();
72 * byte[] bytes = new byte[20];
73 * random.nextBytes(bytes);
74 * </pre>
75 *
76 * <p> Callers may also invoke the {@code generateSeed} method
77 * to generate a given number of seed bytes (to seed other random number
78 * generators, for example):
79 * <pre>
80 * byte[] seed = random.generateSeed(20);
81 * </pre>
82 *
83 * Note: Depending on the implementation, the {@code generateSeed} and
84 * {@code nextBytes} methods may block as entropy is being gathered,
85 * for example, if they need to read from /dev/random on various Unix-like
86 * operating systems.
87 *
88 * @see java.security.SecureRandomSpi
89 * @see java.util.Random
90 *
91 * @author Benjamin Renaud
92 * @author Josh Bloch
93 */
94
95 public class SecureRandom extends java.util.Random {
96
97 private static final Debug pdebug =
98 Debug.getInstance("provider", "Provider");
99 private static final boolean skipDebug =
100 Debug.isOn("engine=") && !Debug.isOn("securerandom");
101
102 /**
103 * The provider.
104 *
105 * @serial
106 * @since 1.2
107 */
108 private Provider provider = null;
109
110 /**
111 * The provider implementation.
112 *
113 * @serial
114 * @since 1.2
115 */
116 private SecureRandomSpi secureRandomSpi = null;
117
118 /*
119 * The algorithm name of null if unknown.
120 *
121 * @serial
122 * @since 1.5
123 */
124 private String algorithm;
125
126 // Seed Generator
127 private static volatile SecureRandom seedGenerator;
128
129 /**
130 * Constructs a secure random number generator (RNG) implementing the
131 * default random number algorithm.
132 *
133 * <p> This constructor traverses the list of registered security Providers,
134 * starting with the most preferred Provider.
135 * A new SecureRandom object encapsulating the
136 * SecureRandomSpi implementation from the first
137 * Provider that supports a SecureRandom (RNG) algorithm is returned.
138 * If none of the Providers support a RNG algorithm,
139 * then an implementation-specific default is returned.
140 *
141 * <p> Note that the list of registered providers may be retrieved via
142 * the {@link Security#getProviders() Security.getProviders()} method.
143 *
144 * <p> See the SecureRandom section in the <a href=
145 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SecureRandom">
146 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
147 * for information about standard RNG algorithm names.
148 *
149 * <p> The returned SecureRandom object has not been seeded. To seed the
150 * returned object, call the {@code setSeed} method.
151 * If {@code setSeed} is not called, the first call to
152 * {@code nextBytes} will force the SecureRandom object to seed itself.
153 * This self-seeding will not occur if {@code setSeed} was
154 * previously called.
155 */
156 public SecureRandom() {
157 /*
158 * This call to our superclass constructor will result in a call
159 * to our own {@code setSeed} method, which will return
160 * immediately when it is passed zero.
161 */
162 super(0);
163 getDefaultPRNG(false, null);
164 }
165
166 /**
167 * Constructs a secure random number generator (RNG) implementing the
168 * default random number algorithm.
169 * The SecureRandom instance is seeded with the specified seed bytes.
170 *
171 * <p> This constructor traverses the list of registered security Providers,
172 * starting with the most preferred Provider.
173 * A new SecureRandom object encapsulating the
174 * SecureRandomSpi implementation from the first
175 * Provider that supports a SecureRandom (RNG) algorithm is returned.
176 * If none of the Providers support a RNG algorithm,
177 * then an implementation-specific default is returned.
178 *
179 * <p> Note that the list of registered providers may be retrieved via
180 * the {@link Security#getProviders() Security.getProviders()} method.
181 *
182 * <p> See the SecureRandom section in the <a href=
183 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SecureRandom">
184 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
185 * for information about standard RNG algorithm names.
186 *
187 * @param seed the seed.
188 */
189 public SecureRandom(byte[] seed) {
190 super(0);
191 getDefaultPRNG(true, seed);
192 }
193
194 private void getDefaultPRNG(boolean setSeed, byte[] seed) {
195 String prng = getPrngAlgorithm();
196 if (prng == null) {
197 // bummer, get the SUN implementation
198 prng = "SHA1PRNG";
199 this.secureRandomSpi = new sun.security.provider.SecureRandom();
200 this.provider = Providers.getSunProvider();
201 if (setSeed) {
202 this.secureRandomSpi.engineSetSeed(seed);
203 }
204 } else {
205 try {
206 SecureRandom random = SecureRandom.getInstance(prng);
207 this.secureRandomSpi = random.getSecureRandomSpi();
208 this.provider = random.getProvider();
209 if (setSeed) {
210 this.secureRandomSpi.engineSetSeed(seed);
211 }
212 } catch (NoSuchAlgorithmException nsae) {
213 // never happens, because we made sure the algorithm exists
214 throw new RuntimeException(nsae);
215 }
216 }
217 // JDK 1.1 based implementations subclass SecureRandom instead of
218 // SecureRandomSpi. They will also go through this code path because
219 // they must call a SecureRandom constructor as it is their superclass.
220 // If we are dealing with such an implementation, do not set the
221 // algorithm value as it would be inaccurate.
222 if (getClass() == SecureRandom.class) {
223 this.algorithm = prng;
224 }
225 }
226
227 /**
228 * Creates a SecureRandom object.
229 *
230 * @param secureRandomSpi the SecureRandom implementation.
231 * @param provider the provider.
232 */
233 protected SecureRandom(SecureRandomSpi secureRandomSpi,
234 Provider provider) {
235 this(secureRandomSpi, provider, null);
236 }
237
238 private SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider,
239 String algorithm) {
240 super(0);
241 this.secureRandomSpi = secureRandomSpi;
242 this.provider = provider;
243 this.algorithm = algorithm;
244
245 if (!skipDebug && pdebug != null) {
246 pdebug.println("SecureRandom." + algorithm +
247 " algorithm from: " + this.provider.getName());
248 }
249 }
250
251 /**
252 * Returns a SecureRandom object that implements the specified
253 * Random Number Generator (RNG) algorithm.
254 *
255 * <p> This method traverses the list of registered security Providers,
256 * starting with the most preferred Provider.
257 * A new SecureRandom object encapsulating the
258 * SecureRandomSpi implementation from the first
259 * Provider that supports the specified algorithm is returned.
260 *
261 * <p> Note that the list of registered providers may be retrieved via
262 * the {@link Security#getProviders() Security.getProviders()} method.
263 *
264 * <p> The returned SecureRandom object has not been seeded. To seed the
265 * returned object, call the {@code setSeed} method.
266 * If {@code setSeed} is not called, the first call to
267 * {@code nextBytes} will force the SecureRandom object to seed itself.
268 * This self-seeding will not occur if {@code setSeed} was
269 * previously called.
270 *
271 * @implNote
272 * The JDK Reference Implementation additionally uses the
273 * {@code jdk.security.provider.preferred}
274 * {@link Security#getProperty(String) Security} property to determine
275 * the preferred provider order for the specified algorithm. This
276 * may be different than the order of providers returned by
277 * {@link Security#getProviders() Security.getProviders()}.
278 *
279 * @param algorithm the name of the RNG algorithm.
280 * See the SecureRandom section in the <a href=
281 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SecureRandom">
282 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
283 * for information about standard RNG algorithm names.
284 *
285 * @return the new SecureRandom object.
286 *
287 * @exception NoSuchAlgorithmException if no Provider supports a
288 * SecureRandomSpi implementation for the
289 * specified algorithm.
290 *
291 * @see Provider
292 *
293 * @since 1.2
294 */
295 public static SecureRandom getInstance(String algorithm)
296 throws NoSuchAlgorithmException {
297 Instance instance = GetInstance.getInstance("SecureRandom",
298 SecureRandomSpi.class, algorithm);
299 return new SecureRandom((SecureRandomSpi)instance.impl,
300 instance.provider, algorithm);
301 }
302
303 /**
304 * Returns a SecureRandom object that implements the specified
305 * Random Number Generator (RNG) algorithm.
306 *
307 * <p> A new SecureRandom object encapsulating the
308 * SecureRandomSpi implementation from the specified provider
309 * is returned. The specified provider must be registered
310 * in the security provider list.
311 *
312 * <p> Note that the list of registered providers may be retrieved via
313 * the {@link Security#getProviders() Security.getProviders()} method.
314 *
315 * <p> The returned SecureRandom object has not been seeded. To seed the
316 * returned object, call the {@code setSeed} method.
317 * If {@code setSeed} is not called, the first call to
318 * {@code nextBytes} will force the SecureRandom object to seed itself.
319 * This self-seeding will not occur if {@code setSeed} was
320 * previously called.
321 *
322 * @param algorithm the name of the RNG algorithm.
323 * See the SecureRandom section in the <a href=
324 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SecureRandom">
325 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
326 * for information about standard RNG algorithm names.
327 *
328 * @param provider the name of the provider.
329 *
330 * @return the new SecureRandom object.
331 *
332 * @exception NoSuchAlgorithmException if a SecureRandomSpi
333 * implementation for the specified algorithm is not
334 * available from the specified provider.
335 *
336 * @exception NoSuchProviderException if the specified provider is not
337 * registered in the security provider list.
338 *
339 * @exception IllegalArgumentException if the provider name is null
340 * or empty.
341 *
342 * @see Provider
343 *
344 * @since 1.2
345 */
346 public static SecureRandom getInstance(String algorithm, String provider)
347 throws NoSuchAlgorithmException, NoSuchProviderException {
348 Instance instance = GetInstance.getInstance("SecureRandom",
349 SecureRandomSpi.class, algorithm, provider);
350 return new SecureRandom((SecureRandomSpi)instance.impl,
351 instance.provider, algorithm);
352 }
353
354 /**
355 * Returns a SecureRandom object that implements the specified
356 * Random Number Generator (RNG) algorithm.
357 *
358 * <p> A new SecureRandom object encapsulating the
359 * SecureRandomSpi implementation from the specified Provider
360 * object is returned. Note that the specified Provider object
361 * does not have to be registered in the provider list.
362 *
363 * <p> The returned SecureRandom object has not been seeded. To seed the
364 * returned object, call the {@code setSeed} method.
365 * If {@code setSeed} is not called, the first call to
366 * {@code nextBytes} will force the SecureRandom object to seed itself.
367 * This self-seeding will not occur if {@code setSeed} was
368 * previously called.
369 *
370 * @param algorithm the name of the RNG algorithm.
371 * See the SecureRandom section in the <a href=
372 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SecureRandom">
373 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
374 * for information about standard RNG algorithm names.
375 *
376 * @param provider the provider.
377 *
378 * @return the new SecureRandom object.
379 *
380 * @exception NoSuchAlgorithmException if a SecureRandomSpi
381 * implementation for the specified algorithm is not available
382 * from the specified Provider object.
383 *
384 * @exception IllegalArgumentException if the specified provider is null.
385 *
386 * @see Provider
387 *
388 * @since 1.4
389 */
390 public static SecureRandom getInstance(String algorithm,
391 Provider provider) throws NoSuchAlgorithmException {
392 Instance instance = GetInstance.getInstance("SecureRandom",
393 SecureRandomSpi.class, algorithm, provider);
394 return new SecureRandom((SecureRandomSpi)instance.impl,
395 instance.provider, algorithm);
396 }
397
398 /**
399 * Returns the SecureRandomSpi of this SecureRandom object.
400 */
401 SecureRandomSpi getSecureRandomSpi() {
402 return secureRandomSpi;
403 }
404
405 /**
406 * Returns the provider of this SecureRandom object.
407 *
408 * @return the provider of this SecureRandom object.
409 */
410 public final Provider getProvider() {
411 return provider;
412 }
413
414 /**
415 * Returns the name of the algorithm implemented by this SecureRandom
416 * object.
417 *
418 * @return the name of the algorithm or {@code unknown}
419 * if the algorithm name cannot be determined.
420 * @since 1.5
421 */
422 public String getAlgorithm() {
423 return Objects.toString(algorithm, "unknown");
424 }
425
426 /**
427 * Reseeds this random object. The given seed supplements, rather than
428 * replaces, the existing seed. Thus, repeated calls are guaranteed
429 * never to reduce randomness.
430 *
431 * @param seed the seed.
432 *
433 * @see #getSeed
434 */
435 public synchronized void setSeed(byte[] seed) {
436 secureRandomSpi.engineSetSeed(seed);
437 }
438
439 /**
440 * Reseeds this random object, using the eight bytes contained
441 * in the given {@code long seed}. The given seed supplements,
442 * rather than replaces, the existing seed. Thus, repeated calls
443 * are guaranteed never to reduce randomness.
444 *
445 * <p>This method is defined for compatibility with
446 * {@code java.util.Random}.
447 *
448 * @param seed the seed.
449 *
450 * @see #getSeed
451 */
452 @Override
453 public void setSeed(long seed) {
454 /*
455 * Ignore call from super constructor (as well as any other calls
456 * unfortunate enough to be passing 0). It's critical that we
457 * ignore call from superclass constructor, as digest has not
458 * yet been initialized at that point.
459 */
460 if (seed != 0) {
461 secureRandomSpi.engineSetSeed(longToByteArray(seed));
462 }
463 }
464
465 /**
466 * Generates a user-specified number of random bytes.
467 *
468 * <p> If a call to {@code setSeed} had not occurred previously,
469 * the first call to this method forces this SecureRandom object
470 * to seed itself. This self-seeding will not occur if
471 * {@code setSeed} was previously called.
472 *
473 * @param bytes the array to be filled in with random bytes.
474 */
475 @Override
476 public void nextBytes(byte[] bytes) {
477 secureRandomSpi.engineNextBytes(bytes);
478 }
479
480 /**
481 * Generates an integer containing the user-specified number of
482 * pseudo-random bits (right justified, with leading zeros). This
483 * method overrides a {@code java.util.Random} method, and serves
484 * to provide a source of random bits to all of the methods inherited
485 * from that class (for example, {@code nextInt},
486 * {@code nextLong}, and {@code nextFloat}).
487 *
488 * @param numBits number of pseudo-random bits to be generated, where
489 * {@code 0 <= numBits <= 32}.
490 *
491 * @return an {@code int} containing the user-specified number
492 * of pseudo-random bits (right justified, with leading zeros).
493 */
494 @Override
495 protected final int next(int numBits) {
496 int numBytes = (numBits+7)/8;
497 byte[] b = new byte[numBytes];
498 int next = 0;
499
500 nextBytes(b);
501 for (int i = 0; i < numBytes; i++) {
502 next = (next << 8) + (b[i] & 0xFF);
503 }
504
505 return next >>> (numBytes*8 - numBits);
506 }
507
508 /**
509 * Returns the given number of seed bytes, computed using the seed
510 * generation algorithm that this class uses to seed itself. This
511 * call may be used to seed other random number generators.
512 *
513 * <p>This method is only included for backwards compatibility.
514 * The caller is encouraged to use one of the alternative
515 * {@code getInstance} methods to obtain a SecureRandom object, and
516 * then call the {@code generateSeed} method to obtain seed bytes
517 * from that object.
518 *
519 * @param numBytes the number of seed bytes to generate.
520 *
521 * @return the seed bytes.
522 *
523 * @see #setSeed
524 */
525 public static byte[] getSeed(int numBytes) {
526 SecureRandom seedGen = seedGenerator;
527 if (seedGen == null) {
528 seedGen = new SecureRandom();
529 seedGenerator = seedGen;
530 }
531 return seedGen.generateSeed(numBytes);
532 }
533
534 /**
535 * Returns the given number of seed bytes, computed using the seed
536 * generation algorithm that this class uses to seed itself. This
537 * call may be used to seed other random number generators.
538 *
539 * @param numBytes the number of seed bytes to generate.
540 *
541 * @return the seed bytes.
542 */
543 public byte[] generateSeed(int numBytes) {
544 return secureRandomSpi.engineGenerateSeed(numBytes);
545 }
546
547 /**
548 * Helper function to convert a long into a byte array (least significant
549 * byte first).
550 */
551 private static byte[] longToByteArray(long l) {
552 byte[] retVal = new byte[8];
553
554 for (int i = 0; i < 8; i++) {
555 retVal[i] = (byte) l;
556 l >>= 8;
557 }
558
559 return retVal;
560 }
561
562 /**
563 * Gets a default PRNG algorithm by looking through all registered
564 * providers. Returns the first PRNG algorithm of the first provider that
565 * has registered a SecureRandom implementation, or null if none of the
566 * registered providers supplies a SecureRandom implementation.
567 */
568 private static String getPrngAlgorithm() {
569 for (Provider p : Providers.getProviderList().providers()) {
570 for (Service s : p.getServices()) {
571 if (s.getType().equals("SecureRandom")) {
572 return s.getAlgorithm();
573 }
574 }
575 }
576 return null;
577 }
578
579 /*
580 * Lazily initialize since Pattern.compile() is heavy.
581 * Effective Java (2nd Edition), Item 71.
582 */
583 private static final class StrongPatternHolder {
584 /*
585 * Entries are alg:prov separated by ,
586 * Allow for prepended/appended whitespace between entries.
587 *
588 * Capture groups:
589 * 1 - alg
590 * 2 - :prov (optional)
591 * 3 - prov (optional)
592 * 4 - ,nextEntry (optional)
593 * 5 - nextEntry (optional)
594 */
595 private static Pattern pattern =
596 Pattern.compile(
597 "\\s*([\\S&&[^:,]]*)(\\:([\\S&&[^,]]*))?\\s*(\\,(.*))?");
598 }
599
600 /**
601 * Returns a {@code SecureRandom} object that was selected by using
602 * the algorithms/providers specified in the {@code
603 * securerandom.strongAlgorithms} {@link Security} property.
604 * <p>
605 * Some situations require strong random values, such as when
606 * creating high-value/long-lived secrets like RSA public/private
607 * keys. To help guide applications in selecting a suitable strong
608 * {@code SecureRandom} implementation, Java distributions
609 * include a list of known strong {@code SecureRandom}
610 * implementations in the {@code securerandom.strongAlgorithms}
611 * Security property.
612 * <p>
613 * Every implementation of the Java platform is required to
614 * support at least one strong {@code SecureRandom} implementation.
615 *
616 * @return a strong {@code SecureRandom} implementation as indicated
617 * by the {@code securerandom.strongAlgorithms} Security property
618 *
619 * @throws NoSuchAlgorithmException if no algorithm is available
620 *
621 * @see Security#getProperty(String)
622 *
623 * @since 1.8
624 */
625 public static SecureRandom getInstanceStrong()
626 throws NoSuchAlgorithmException {
627
628 String property = AccessController.doPrivileged(
629 new PrivilegedAction<>() {
630 @Override
631 public String run() {
632 return Security.getProperty(
633 "securerandom.strongAlgorithms");
634 }
635 });
636
637 if ((property == null) || (property.length() == 0)) {
638 throw new NoSuchAlgorithmException(
639 "Null/empty securerandom.strongAlgorithms Security Property");
640 }
641
642 String remainder = property;
643 while (remainder != null) {
644 Matcher m;
645 if ((m = StrongPatternHolder.pattern.matcher(
646 remainder)).matches()) {
647
648 String alg = m.group(1);
649 String prov = m.group(3);
650
651 try {
652 if (prov == null) {
653 return SecureRandom.getInstance(alg);
654 } else {
655 return SecureRandom.getInstance(alg, prov);
656 }
657 } catch (NoSuchAlgorithmException |
658 NoSuchProviderException e) {
659 }
660 remainder = m.group(5);
661 } else {
662 remainder = null;
663 }
664 }
665
666 throw new NoSuchAlgorithmException(
667 "No strong SecureRandom impls available: " + property);
668 }
669
670 // Declare serialVersionUID to be compatible with JDK1.1
671 static final long serialVersionUID = 4940670005562187L;
672
673 // Retain unused values serialized from JDK1.1
674 /**
675 * @serial
676 */
677 private byte[] state;
678 /**
679 * @serial
680 */
681 private MessageDigest digest = null;
682 /**
683 * @serial
684 *
685 * We know that the MessageDigest class does not implement
686 * java.io.Serializable. However, since this field is no longer
687 * used, it will always be NULL and won't affect the serialization
688 * of the SecureRandom class itself.
689 */
690 private byte[] randomBytes;
691 /**
692 * @serial
693 */
694 private int randomBytesUsed;
695 /**
696 * @serial
697 */
698 private long counter;
699 }