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