001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019package org.apache.shiro.crypto; 020 021import org.apache.shiro.util.ByteSource; 022 023/** 024 * A component that can generate random number/byte values as needed. Useful in cryptography or security scenarios 025 * where random byte arrays are needed, such as for password salts, nonces, initialization vectors and other seeds. 026 * <p/> 027 * This is essentially the same as a {@link java.security.SecureRandom SecureRandom}, and indeed implementations 028 * of this interface will probably all use {@link java.security.SecureRandom SecureRandom} instances, but this 029 * interface provides a few additional benefits to end-users: 030 * <ul> 031 * <li>It is an interface rather than the JDK's {@code SecureRandom} concrete implementation. Implementation details 032 * can be customized as necessary based on the application's needs</li> 033 * <li>Default per-instance behavior can be customized on implementations, typically via JavaBeans mutators.</li> 034 * <li>Perhaps most important for Shiro end-users, tt can more easily be used as a source of cryptographic seed data, 035 * and the data returned is already in a more convenient {@link ByteSource ByteSource} format in case that data needs 036 * to be {@link org.apache.shiro.util.ByteSource#toHex() hex} or 037 * {@link org.apache.shiro.util.ByteSource#toBase64() base64}-encoded.</li> 038 * </ul> 039 * For example, consider the following example generating password salts for new user accounts: 040 * <pre> 041 * RandomNumberGenerator saltGenerator = new {@link org.apache.shiro.crypto.SecureRandomNumberGenerator SecureRandomNumberGenerator}(); 042 * User user = new User(); 043 * user.setPasswordSalt(saltGenerator.nextBytes().toBase64()); 044 * userDAO.save(user); 045 * </pre> 046 * 047 * @since 1.1 048 */ 049public interface RandomNumberGenerator { 050 051 /** 052 * Generates a byte array of fixed length filled with random data, often useful for generating salts, 053 * initialization vectors or other seed data. The length is specified as a configuration 054 * value on the underlying implementation. 055 * <p/> 056 * If you'd like per-invocation control the number of bytes generated, use the 057 * {@link #nextBytes(int) nextBytes(int)} method instead. 058 * 059 * @return a byte array of fixed length filled with random data. 060 * @see #nextBytes(int) 061 */ 062 ByteSource nextBytes(); 063 064 /** 065 * Generates a byte array of the specified length filled with random data. 066 * 067 * @param numBytes the number of bytes to be populated with random data. 068 * @return a byte array of the specified length filled with random data. 069 * @see #nextBytes() 070 */ 071 ByteSource nextBytes(int numBytes); 072}