| Frames | No Frames |
1: /* IRandom.java -- 2: Copyright (C) 2001, 2002, 2003, 2006 Free Software Foundation, Inc. 3: 4: This file is a part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2 of the License, or (at 9: your option) any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; if not, write to the Free Software 18: Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 19: USA 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package gnu.java.security.prng; 40: 41: import java.util.Map; 42: 43: /** 44: * The basic visible methods of any pseudo-random number generator. 45: * <p> 46: * The [HAC] defines a PRNG (as implemented in this library) as follows: 47: * <ul> 48: * <li>"5.6 Definition: A pseudorandom bit generator (PRBG) is said to pass the 49: * <em>next-bit test</em> if there is no polynomial-time algorithm which, on 50: * input of the first <code>L</code> bits of an output sequence <code>S</code>, 51: * can predict the <code>(L+1)</code><sup>st</sup> bit of <code>S</code> with a 52: * probability significantly greater than <code>1/2</code>."</li> 53: * <li>"5.8 Definition: A PRBG that passes the <em>next-bit test</em> 54: * (possibly under some plausible but unproved mathematical assumption such as 55: * the intractability of factoring integers) is called a <em>cryptographically 56: * secure pseudorandom bit generator</em> (CSPRBG)."</li> 57: * </ul> 58: * <p> 59: * <b>IMPLEMENTATION NOTE</b>: Although all the concrete classes in this 60: * package implement the {@link Cloneable} interface, it is important to note 61: * here that such an operation, for those algorithms that use an underlying 62: * symmetric key block cipher, <b>DOES NOT</b> clone any session key material 63: * that may have been used in initialising the source PRNG (the instance to be 64: * cloned). Instead a clone of an already initialised PRNG, that uses an 65: * underlying symmetric key block cipher, is another instance with a clone of 66: * the same cipher that operates with the <b>same block size</b> but without 67: * any knowledge of neither key material nor key size. 68: * <p> 69: * References: 70: * <ol> 71: * <li><a href="http://www.cacr.math.uwaterloo.ca/hac">[HAC]</a>: Handbook of 72: * Applied Cryptography.<br> 73: * CRC Press, Inc. ISBN 0-8493-8523-7, 1997<br> 74: * Menezes, A., van Oorschot, P. and S. Vanstone.</li> 75: * </ol> 76: */ 77: public interface IRandom 78: extends Cloneable 79: { 80: /** 81: * Returns the canonical name of this instance. 82: * 83: * @return the canonical name of this instance. 84: */ 85: String name(); 86: 87: /** 88: * Initialises the pseudo-random number generator scheme with the appropriate 89: * attributes. 90: * 91: * @param attributes a set of name-value pairs that describe the desired 92: * future instance behaviour. 93: * @exception IllegalArgumentException if at least one of the defined name/ 94: * value pairs contains invalid data. 95: */ 96: void init(Map attributes); 97: 98: /** 99: * Returns the next 8 bits of random data generated from this instance. 100: * 101: * @return the next 8 bits of random data generated from this instance. 102: * @exception IllegalStateException if the instance is not yet initialised. 103: * @exception LimitReachedException if this instance has reached its 104: * theoretical limit for generating non-repetitive pseudo-random 105: * data. 106: */ 107: byte nextByte() throws IllegalStateException, LimitReachedException; 108: 109: /** 110: * Fills the designated byte array, starting from byte at index 111: * <code>offset</code>, for a maximum of <code>length</code> bytes with 112: * the output of this generator instance. 113: * 114: * @param out the placeholder to contain the generated random bytes. 115: * @param offset the starting index in <i>out</i> to consider. This method 116: * does nothing if this parameter is not within <code>0</code> and 117: * <code>out.length</code>. 118: * @param length the maximum number of required random bytes. This method does 119: * nothing if this parameter is less than <code>1</code>. 120: * @exception IllegalStateException if the instance is not yet initialised. 121: * @exception LimitReachedException if this instance has reached its 122: * theoretical limit for generating non-repetitive pseudo-random 123: * data. 124: */ 125: void nextBytes(byte[] out, int offset, int length) 126: throws IllegalStateException, LimitReachedException; 127: 128: /** 129: * Supplement, or possibly replace, the random state of this PRNG with a 130: * random byte. 131: * <p> 132: * Implementations are not required to implement this method in any meaningful 133: * way; this may be a no-operation, and implementations may throw an 134: * {@link UnsupportedOperationException}. 135: * 136: * @param b The byte to add. 137: */ 138: void addRandomByte(byte b); 139: 140: /** 141: * Supplement, or possibly replace, the random state of this PRNG with a 142: * sequence of new random bytes. 143: * <p> 144: * Implementations are not required to implement this method in any meaningful 145: * way; this may be a no-operation, and implementations may throw an 146: * {@link UnsupportedOperationException}. 147: * 148: * @param in The buffer of new random bytes to add. 149: */ 150: void addRandomBytes(byte[] in); 151: 152: /** 153: * Supplement, or possibly replace, the random state of this PRNG with a 154: * sequence of new random bytes. 155: * <p> 156: * Implementations are not required to implement this method in any meaningful 157: * way; this may be a no-operation, and implementations may throw an 158: * {@link UnsupportedOperationException}. 159: * 160: * @param in The buffer of new random bytes to add. 161: * @param offset The offset from whence to begin reading random bytes. 162: * @param length The number of random bytes to add. 163: * @exception IndexOutOfBoundsException If <i>offset</i>, <i>length</i>, or 164: * <i>offset</i>+<i>length</i> is out of bounds. 165: */ 166: void addRandomBytes(byte[] in, int offset, int length); 167: 168: /** 169: * Returns a clone copy of this instance. 170: * 171: * @return a clone copy of this instance. 172: */ 173: Object clone() throws CloneNotSupportedException; 174: }