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     */
019    package org.apache.shiro.crypto;
020    
021    import 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     */
049    public 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    }