hunt.shiro.crypto.RandomNumberGenerator source code

1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied.  See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  */
19 module hunt.shiro.crypto.RandomNumberGenerator;
20 
21 import hunt.shiro.util.ByteSource;
22 
23 /**
24  * A component that can generate random number/byte values as needed.  Useful in cryptography or security scenarios
25  * where random byte arrays are needed, such as for password salts, nonces, initialization vectors and other seeds.
26  * <p/>
27  * This is essentially the same as a {@link java.security.SecureRandom SecureRandom}, and indeed implementations
28  * of this interface will probably all use {@link java.security.SecureRandom SecureRandom} instances, but this
29  * interface provides a few additional benefits to end-users:
30  * <ul>
31  * <li>It is an interface rather than the JDK's {@code SecureRandom} concrete implementation.  Implementation details
32  * can be customized as necessary based on the application's needs</li>
33  * <li>Default per-instance behavior can be customized on implementations, typically via JavaBeans mutators.</li>
34  * <li>Perhaps most important for Shiro end-users, tt can more easily be used as a source of cryptographic seed data,
35  * and the data returned is already in a more convenient {@link ByteSource ByteSource} format in case that data needs
36  * to be {@link hunt.shiro.util.ByteSource#toHex() hex} or
37  * {@link hunt.shiro.util.ByteSource#toBase64() base64}-encoded.</li>
38  * </ul>
39  * For example, consider the following example generating password salts for new user accounts:
40  * <pre>
41  * RandomNumberGenerator saltGenerator = new {@link hunt.shiro.crypto.SecureRandomNumberGenerator SecureRandomNumberGenerator}();
42  * User user = new User();
43  * user.setPasswordSalt(saltGenerator.nextBytes().toBase64());
44  * userDAO.save(user);
45  * </pre>
46  *
47  * @since 1.1
48  */
49 interface RandomNumberGenerator {
50 
51     /**
52      * Generates a byte array of fixed length filled with random data, often useful for generating salts,
53      * initialization vectors or other seed data.  The length is specified as a configuration
54      * value on the underlying implementation.
55      * <p/>
56      * If you'd like per-invocation control the number of bytes generated, use the
57      * {@link #nextBytes(int) nextBytes(int)} method instead.
58      *
59      * @return a byte array of fixed length filled with random data.
60      * @see #nextBytes(int)
61      */
62     ByteSource nextBytes();
63 
64     /**
65      * Generates a byte array of the specified length filled with random data.
66      *
67      * @param numBytes the number of bytes to be populated with random data.
68      * @return a byte array of the specified length filled with random data.
69      * @see #nextBytes()
70      */
71     ByteSource nextBytes(int numBytes);
72 }