Package javacard.security

Class RandomData

  • Direct Known Subclasses:
    RandomData.OneShot
    public abstract class RandomData
extends Object
    The RandomData abstract class is the base class for random number generation. Implementations of RandomData algorithms must extend this class and implement all the abstract methods.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  RandomData.OneShot
      The OneShot class is a specialization of the RandomData class intended to support efficient one-shot random data generation operations that may avoid persistent memory writes entirely.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static byte ALG_FAST
      Utility random number generation algorithm.
      static byte ALG_KEYGENERATION
      This algorithm creates random numbers suitable to be used for key and nonce generation.
      static byte ALG_PRESEEDED_DRBG
      Deterministic Random Bit Generator (DRBG) algorithm.
      static byte ALG_PSEUDO_RANDOM
      Deprecated.
      As of release 3.0.5.
      static byte ALG_SECURE_RANDOM
      Deprecated.
      As of release 3.0.5.
      static byte ALG_TRNG
      True Random Number Generation (TRNG) algorithm.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected RandomData()
      Protected constructor for subclassing.

    • Field Detail

      • ALG_PSEUDO_RANDOM

        @Deprecated
public static final byte ALG_PSEUDO_RANDOM
        Deprecated.
        As of release 3.0.5.
        Utility pseudo-random number generation algorithms. The random number sequence generated by this algorithm need not be the same even if seeded with the same seed data.

        Even if a transaction is in progress, the update of the internal state shall not participate in the transaction.

        The security level and the standards conformance of the pseudo random number algorithm is implementation dependant

        See Also:
        Constant Field Values

      • ALG_SECURE_RANDOM

        @Deprecated
public static final byte ALG_SECURE_RANDOM
        Deprecated.
        As of release 3.0.5.
        Cryptographically secure random number generation algorithms.
        See Also:
        Constant Field Values

      • ALG_TRNG

        public static final byte ALG_TRNG
        True Random Number Generation (TRNG) algorithm. The random number sequence generated by this algorithm MUST not be the same even if seeded with the same seed data.

        The security level and the standards conformance of the TRNG algorithm is implementation dependant.

        Since:
        3.0.5
        See Also:
        Constant Field Values

      • ALG_PRESEEDED_DRBG

        public static final byte ALG_PRESEEDED_DRBG
        Deterministic Random Bit Generator (DRBG) algorithm. The algorithm is pre-seeded by an entropy source yet may by re-seeded using setSeed method.

        The security level and the standards conformance of the DRBG algorithm is implementation dependant.

        Since:
        3.0.5
        See Also:
        Constant Field Values

      • ALG_FAST

        public static final byte ALG_FAST
        Utility random number generation algorithm. Random number generated by this algorithm are not suitable for key and nonce generation. The security level of this algorithm is implementation dependant.
        Since:
        3.0.5
        See Also:
        Constant Field Values

      • ALG_KEYGENERATION

        public static final byte ALG_KEYGENERATION
        This algorithm creates random numbers suitable to be used for key and nonce generation.

        The security level and the standards conformance of the this algorithm is implementation dependant.

        Since:
        3.0.5
        See Also:
        Constant Field Values

    • Constructor Detail

      • RandomData

        protected RandomData()
        Protected constructor for subclassing.

    • Method Detail

      • getInstance

        @Deprecated
public static final RandomData getInstance​(byte algorithm)
                                    throws CryptoException
        Deprecated.
        As of release 3.2, replaced by getInstance(byte,boolean).
        Creates a RandomData instance of the selected algorithm. The pseudo random RandomData instance's seed is initialized to a internal default value.
        Parameters:
        algorithm - the desired random number algorithm. Valid codes listed in ALG_* constants above, for example ALG_PRESEEDED_DRBG.
        Returns:
        the RandomData object instance of the requested algorithm
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.

      • getInstance

        public static final RandomData getInstance​(byte algorithm,
                                           boolean externalAccess)
                                    throws CryptoException
        Creates a RandomData instance of the selected algorithm. The pseudo random RandomData instance's seed is initialized to a internal default value.
        Parameters:
        algorithm - the desired random number algorithm. Valid codes listed in ALG_* constants above, for example ALG_PRESEEDED_DRBG.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the RandomData instance will also be accessed (via a Shareable interface) when the owner of the RandomData instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
        Returns:
        the RandomData object instance of the requested algorithm
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.
        Since:
        3.2

      • generateData

        @Deprecated
public abstract void generateData​(byte[] buffer,
                                  short offset,
                                  short length)
                           throws CryptoException
        Deprecated.
        As of release 3.0.5, replaced by nextBytes(byte[], short, short).
        Generates random data.
        Parameters:
        buffer - the output buffer
        offset - the offset into the output buffer
        length - the length of random data to generate
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if the length parameter is zero.

      • nextBytes

        public abstract short nextBytes​(byte[] buffer,
                                short offset,
                                short length)
                         throws CryptoException
        Generates random data.

        In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        buffer - the output buffer
        offset - the offset into the output buffer
        length - the length of random data to generate
        Returns:
        offset+length
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if the length parameter is zero.
        Since:
        3.0.5

      • setSeed

        public abstract void setSeed​(byte[] buffer,
                             short offset,
                             short length)
        Seeds the random data generator. This method alters the state of this random number generator so as to be in exactly the same state as if it had just been created with the seed provided as argument to this method.
        Parameters:
        buffer - the input buffer
        offset - the offset into the input buffer
        length - the length of the seed data

      • getAlgorithm

        public abstract byte getAlgorithm()
        Gets the random number generation algorithm. Valid codes listed in ALG_* constants above, for example, ALG_PRESEEDED_DRBG.

        In addition to returning a byte result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Returns:
        the algorithm code defined above
        Since:
        3.0.5