public static final class RandomData.OneShot extends RandomData
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:
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.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.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.
OneShot must be bound to the initial calling context
(owner context) as to preclude use/calls on that instance from other
contexts.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;
}
}
...
RandomData.OneShotALG_FAST, ALG_KEYGENERATION, ALG_PRESEEDED_DRBG, ALG_PSEUDO_RANDOM, ALG_SECURE_RANDOM, ALG_TRNG| Modifier and Type | Method and Description |
|---|---|
void |
close()
Closes and releases this JCRE owned temporary instance of the
OneShot object for reuse. |
void |
generateData(byte[] buffer,
short offset,
short length)
Deprecated.
As of release 3.0.5, replaced by
nextBytes(byte[], short, short). |
byte |
getAlgorithm()
Gets the random number generation algorithm.
|
short |
nextBytes(byte[] buffer,
short offset,
short length)
Generates random data.
|
static RandomData.OneShot |
open(byte algorithm)
Opens/acquires a JCRE owned temporary Entry Point Object instance of
OneShot with the selected algorithm. |
void |
setSeed(byte[] buffer,
short offset,
short length)
Seeds the random data generator.
|
getInstancepublic static final RandomData.OneShot open(byte algorithm) throws CryptoException
OneShot with the selected algorithm. The pseudo random
RandomData.OneShot instance's seed is initialized to a internal
default value.algorithm - the desired random number algorithm. Valid codes listed
in ALG_* constants above, for example
ALG_PRESEEDED_DRBG.RandomData.OneShot object instance of the requested
algorithm.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.public void close()
OneShot object for reuse. If this method is called again this
method does nothing.SecurityException - if this JCRE owned temporary instance of the
OneShot object was opened in a context different from that of the
caller.public byte getAlgorithm()
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.getAlgorithm in class RandomDataSecurityException - if this JCRE owned temporary instance of the
OneShot object was opened in a context different from that of the
caller.public void generateData(byte[] buffer,
short offset,
short length)
throws CryptoException
nextBytes(byte[], short, short).generateData in class RandomDatabuffer - the output bufferoffset - the offset into the output bufferlength - the length of random data to generateSecurityException - 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.
public short nextBytes(byte[] buffer,
short offset,
short length)
throws CryptoException
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.nextBytes in class RandomDatabuffer - the output bufferoffset - the offset into the output bufferlength - the length of random data to generateoffset+lengthSecurityException - 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.
public void setSeed(byte[] buffer,
short offset,
short length)
setSeed in class RandomDatabuffer - the input bufferoffset - the offset into the input bufferlength - the length of the seed dataSecurityException - if this JCRE owned temporary instance of the
OneShot object was opened in a context different from that of the
caller.Copyright © 1998, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms