Class SecureRandomWithCache

  • All Implemented Interfaces:
    java.io.Serializable

    public final class SecureRandomWithCache
    extends java.security.SecureRandomSpi

    This class provides a crytpographically strong true random number generated based on cryptographic hardware. In this implementation of the SecureRandom class bytes are prefetched from cryptographic hardware to create a cache of random numbers available for a caller. This implementation of the SecureRandom class can be leveraged by setting the ibm.hwrandom.useicsfcache Java environment variable to true. If the ibm.hwrandom.useicsfcache Java environment variable is set to true when the IBMJCECCA provider is loaded then all subsequent calls to the SecureRandom class in the IBMJCECCA provider will be routed to this caching implementation. An additional environment variable of ibm.hwrandom.cachesize may also be specified to set the size of the cache to be used. Note a seed is not necessary for hardware random number generation and if one is passed it is not used. (Allowing the passing of a seed is to allow backwards compatibility with software generated random numbers)

    See Also:
    Serialized Form
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      byte[] engineGenerateSeed​(int numBytes)
      As hardware crypto does not need a seed value this method has no purpose, but is defined in SecureRandomSpi.
      void engineNextBytes​(byte[] bytes)
      Generates a user-specified number of random bytes.
      void engineSetSeed​(byte[] seed)
      As hardware crypto does not need a seed value this method has no purpose, but is defined in SecureRandomSpi.
      • Methods inherited from class java.security.SecureRandomSpi

        engineGetParameters, engineNextBytes, engineReseed, toString
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • SecureRandomWithCache

        public SecureRandomWithCache()
        Constructs a new instance of this class. The Java envionrment variable ibm.hwrandom.cachesize will be used to set the size of the cache to be used. If not specified the default size of 14400 bytes will be used.
      • SecureRandomWithCache

        public SecureRandomWithCache​(byte[] seed)
        Constructor that requires a seed. Note: The seed has no real meaning in hardware and this constructor only exists for compatibility with SecureRandomSpi.
        Parameters:
        seed - a series of bytes used as seed. This value will be ignored.
    • Method Detail

      • engineSetSeed

        public void engineSetSeed​(byte[] seed)
        As hardware crypto does not need a seed value this method has no purpose, but is defined in SecureRandomSpi. This method is a no-op whenever called.
        Specified by:
        engineSetSeed in class java.security.SecureRandomSpi
        Parameters:
        seed - a series of bytes used as seed. This parameter is ignored.
      • engineNextBytes

        public void engineNextBytes​(byte[] bytes)
                             throws java.lang.InternalError,
                                    java.nio.BufferUnderflowException
        Generates a user-specified number of random bytes. A cache is used to cache the bytes fetched from the underlying hardware implementation.
        Specified by:
        engineNextBytes in class java.security.SecureRandomSpi
        Parameters:
        bytes - the array to be filled in with random bytes.
        Throws:
        java.lang.InternalError - is thrown when an unexpected error occurs or bytes is equal to null.
        java.nio.BufferUnderflowException - is thrown when an unexpected internal error occurs while fetching bytes from the cache.
      • engineGenerateSeed

        public byte[] engineGenerateSeed​(int numBytes)
                                  throws java.lang.UnsupportedOperationException
        As hardware crypto does not need a seed value this method has no purpose, but is defined in SecureRandomSpi.
        Specified by:
        engineGenerateSeed in class java.security.SecureRandomSpi
        Throws:
        java.lang.UnsupportedOperationException - is always thrown if this method is invoked.