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 package org.apache.shiro.crypto;
20
21 import org.apache.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 org.apache.shiro.util.ByteSource#toHex() hex} or
37 * {@link org.apache.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 org.apache.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 public 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 }