Package javacard.security

Class RandomData.OneShot

  • Enclosing class:
    RandomData
    public static final class RandomData.OneShot
extends RandomData
    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. The OneShot class uses a delegation model where calls are delegated to an instance of a RandomData-implementing class configured for one-shot use.

    Note:

    • Instances of OneShot are JCRE owned temporary Entry Point Object instances and references to these temporary objects cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
    • The platform must support at least one instance of OneShot. Support for several OneShot instances is platform dependent. To guarantee application code portability, acquiring/opening and then releasing/closing OneShot instances should be performed within tight try-catch-finally blocks (as illustrated in the code sample below) in order to avoid unnecessarily keeping hold of instances and to prevent interleaving invocations - hence enforcing the One-Shot usage pattern. Additionally, any local variable holding a reference to a OneShot instance should be set to null once the instance is closed in order to prevent further use attempts.
    • Upon return from any Applet entry point method, back to the JCRE, and on tear or card reset events any OneShot instances in use are released back to the JCRE.
    • The internal state associated with an instance of OneShot must be bound to the initial calling context (owner context) as to preclude use/calls on that instance from other contexts.
    • Unless otherwise specified, after an instance of OneShot is released back to the JCRE, calls to any of the instance methods of the OneShot class results in an CryptoException being thrown with reason code CryptoException.ILLEGAL_USE.

    The following code shows a typical usage pattern for the OneShot class. 

     ...
 RandomData.OneShot rng = null;
 try {
     rng = RandomData.OneShot.open(RandomData.ALG_TRNG);
     rng.nextBytes(rndData, (short) 0, (short) rndData.length);
 } catch (CryptoException ce) {
     // Handle exception
 } finally {
     if (rng != null) {
        rng.close();
        rng = null;
     }
 }
 ...

    Since:
    3.0.5

    • Method Detail

      • open

        public static final RandomData.OneShot open​(byte algorithm)
                                     throws CryptoException
        Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm. The pseudo random RandomData.OneShot 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.OneShot object instance of the requested algorithm.
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.
        SystemException - with the following reason codes:
        • SystemException.NO_RESOURCE if sufficient resources are not available.

      • close

        public void close()
        Closes and releases this JCRE owned temporary instance of the OneShot object for reuse. If this method is called again this method does nothing.
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getAlgorithm

        public 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.

        Specified by:
        getAlgorithm in class RandomData
        Returns:
        the algorithm code defined above
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • generateData

        public 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.
        Specified by:
        generateData in class RandomData
        Parameters:
        buffer - the output buffer
        offset - the offset into the output buffer
        length - the length of random data to generate
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if the length parameter is zero.

      • nextBytes

        public 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.

        Specified by:
        nextBytes in class RandomData
        Parameters:
        buffer - the output buffer
        offset - the offset into the output buffer
        length - the length of random data to generate
        Returns:
        offset+length
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_VALUE if the length parameter is zero.

      • setSeed

        public 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.
        Specified by:
        setSeed in class RandomData
        Parameters:
        buffer - the input buffer
        offset - the offset into the input buffer
        length - the length of the seed data
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.