/* | |
* Licensed to the Apache Software Foundation (ASF) under one | |
* or more contributor license agreements. See the NOTICE file | |
* distributed with this work for additional information | |
* regarding copyright ownership. The ASF licenses this file | |
* to you under the Apache License, Version 2.0 (the | |
* "License"); you may not use this file except in compliance | |
* with the License. You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* Unless required by applicable law or agreed to in writing, | |
* software distributed under the License is distributed on an | |
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
* KIND, either express or implied. See the License for the | |
* specific language governing permissions and limitations | |
* under the License. | |
*/ | |
package org.apache.shiro.crypto; | |
import org.apache.shiro.util.ByteSource; | |
/** | |
* A component that can generate random number/byte values as needed. Useful in cryptography or security scenarios | |
* where random byte arrays are needed, such as for password salts, nonces, initialization vectors and other seeds. | |
* <p/> | |
* This is essentially the same as a {@link java.security.SecureRandom SecureRandom}, and indeed implementations | |
* of this interface will probably all use {@link java.security.SecureRandom SecureRandom} instances, but this | |
* interface provides a few additional benefits to end-users: | |
* <ul> | |
* <li>It is an interface rather than the JDK's {@code SecureRandom} concrete implementation. Implementation details | |
* can be customized as necessary based on the application's needs</li> | |
* <li>Default per-instance behavior can be customized on implementations, typically via JavaBeans mutators.</li> | |
* <li>Perhaps most important for Shiro end-users, tt can more easily be used as a source of cryptographic seed data, | |
* and the data returned is already in a more {@link ByteSource ByteSource} format in case that data needs to be | |
* {@link org.apache.shiro.util.ByteSource#toHex() hex} or | |
* {@link org.apache.shiro.util.ByteSource#toBase64() base64}-encoded.</li> | |
* </ul> | |
* For example, consider the following example generating password salts for new user accounts: | |
* | |
* <pre> | |
* RandomNumberGenerator saltGenerator = new {@link org.apache.shiro.crypto.SecureRandomNumberGenerator SecureRandomNumberGenerator}(); | |
* User user = new User(); | |
* user.setPasswordSalt(saltGenerator.nextBytes().toBase64()); | |
* userDAO.save(user); | |
* </pre> | |
* | |
* @since 1.1 | |
*/ | |
public interface RandomNumberGenerator { | |
/** | |
* Generates a byte array of fixed length filled with random data, often useful for generating salts, | |
* initialization vectors or other seed data. The length is specified as a configuration | |
* value on the underlying implementation. | |
* | |
* @return a byte array of fixed length filled with random data. | |
*/ | |
ByteSource nextBytes(); | |
/** | |
* Generates a byte array of the specified length filled with random data. | |
* @param numBytes the number of bytes to be populated with random data. | |
* @return a byte array of the specified length filled with random data. | |
*/ | |
ByteSource nextBytes(int numBytes); | |
} |