Class DerivationFunction.OneShot
- java.lang.Object
-
- javacardx.security.derivation.DerivationFunction
-
- javacardx.security.derivation.DerivationFunction.OneShot
-
- Enclosing class:
- DerivationFunction
public static final class DerivationFunction.OneShot extends DerivationFunction
TheOneShot
class is a specialization of theDerivationFunction
class intended to support efficient one-shot derivation function operations that may avoid persistent memory writes entirely. TheOneShot
class uses a delegation model where calls are delegated to an instance of aDerivationFunction
-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 severalOneShot
instances is platform dependent. To guarantee application code portability, acquiring/opening and then releasing/closingOneShot
instances should be performed within tighttry-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 aOneShot
instance should be set tonull
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 anyOneShot
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 theOneShot
class results in anCryptoException
being thrown with reason codeCryptoException.ILLEGAL_USE
.
The following code shows a typical usage pattern for the
OneShot
class.... DerivationFunction.OneShot kdf = null; try { kdf = DerivationFunction.OneShot.open(DerivationFunction.ALG_KDF_COUNTER_MODE); kdf = DerivationFunction.init(myKdfCounterModeParameters); kdf.lastBytes(kdfData, (short) 0, (short) kdfData.length); } catch (CryptoException ce) { // Handle exception } finally { if (kdf != null) { kdf.close(); kdf = null; } } ...
- Since:
- 3.1
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class javacardx.security.derivation.DerivationFunction
DerivationFunction.OneShot
-
-
Field Summary
-
Fields inherited from class javacardx.security.derivation.DerivationFunction
ALG_KDF_ANSI_X9_63, ALG_KDF_COUNTER_MODE, ALG_KDF_DPI_MODE, ALG_KDF_FEEDBACK_MODE, ALG_KDF_HKDF, ALG_KDF_ICAO_MRTD, ALG_KDF_IEEE_1363, ALG_PRF_TLS11, ALG_PRF_TLS12
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
Closes and releases this JCRE owned temporary instance of theOneShot
object for reuse.short
getAlgorithm()
Gets the Derivation Function algorithm.void
init(AlgorithmParameterSpec params)
Initializes theDerivationFunction
object with the appropriate algorithm specific parameters.short
lastBytes(byte[] buffer, short offset, short length)
Generates derived data as specified by the derivation function algorithm and parameters.short
lastBytes(SecretKey secret)
Generates derived data as specified by the derivation function algorithm and parameters.short
nextBytes(byte[] buffer, short offset, short length)
Always throws aCryptoException
.This method is not supported byOneShot
.short
nextBytes(SecretKey secret)
Always throws aCryptoException
.This method is not supported byOneShot
.static DerivationFunction.OneShot
open(byte algorithm)
Opens/acquires a JCRE owned temporary Entry Point Object instance ofOneShot
with the selected algorithm.-
Methods inherited from class javacardx.security.derivation.DerivationFunction
getInstance
-
-
-
-
Method Detail
-
open
public static final DerivationFunction.OneShot open(byte algorithm) throws CryptoException
Opens/acquires a JCRE owned temporary Entry Point Object instance ofOneShot
with the selected algorithm.- Parameters:
algorithm
- the desired derivation function algorithm. Valid codes listed inALG_*
constants above, for exampleALG_KDF_COUNTER_MODE
.- Returns:
- the
DerivationFunction.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 theOneShot
object for reuse. If this method is called again this method does nothing.- Throws:
SecurityException
- if this JCRE owned temporary instance of theOneShot
object was opened in a context different from that of the caller.
-
init
public void init(AlgorithmParameterSpec params) throws CryptoException
Initializes theDerivationFunction
object with the appropriate algorithm specific parameters.init()
must be used to update theDerivationFunction
object with new parameters. A caller may not make any assumption on theparams
object usage by an implementation i.e either a reference is kept or not, either the fields are used or will be consumed later on. If theparams
object is modified after invoking theinit()
method, the behavior of thenextBytes()
andlastBytes()
methods is unspecified.The
AlgorithmParameterSpec
params
instance type is checked for consistency with theDerivationFunction
algorithm. For instanceKDFCounterModeSpec
matches ALG_KDF_COUNTER_MODE.- Specified by:
init
in classDerivationFunction
- Parameters:
params
- the derivation function algorithm parameters.- Throws:
SecurityException
- if this JCRE owned temporary instance of theOneShot
object was opened in a context different from that of the caller.CryptoException
- with the following reason codes:CryptoException.NO_SUCH_ALGORITHM
if the algorithm parameter instance or any of the specified parameter is not supported.
-
getAlgorithm
public short getAlgorithm()
Gets the Derivation Function algorithm.- Specified by:
getAlgorithm
in classDerivationFunction
- Returns:
- the algorithm code defined above; if the algorithm is not one of
the pre-defined algorithms,
0
is returned. - Throws:
SecurityException
- if this JCRE owned temporary instance of theOneShot
object was opened in a context different from that of the caller.- See Also:
DerivationFunction.getInstance(short, boolean)
-
nextBytes
public short nextBytes(byte[] buffer, short offset, short length) throws CryptoException
Always throws aCryptoException
.This method is not supported byOneShot
.- Specified by:
nextBytes
in classDerivationFunction
- Parameters:
buffer
- the output bufferoffset
- the offset into the output bufferlength
- the length of derived data to generate- Returns:
offset+length
- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_USE
always.
-
nextBytes
public short nextBytes(SecretKey secret) throws CryptoException
Always throws aCryptoException
.This method is not supported byOneShot
.- Specified by:
nextBytes
in classDerivationFunction
- Parameters:
secret
- theSecretKey
instance which value has to be set with derived data.- Returns:
length
of the key in bytes- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_USE
always.
-
lastBytes
public short lastBytes(byte[] buffer, short offset, short length) throws CryptoException
Generates derived data as specified by the derivation function algorithm and parameters.A call to this method also resets this
DerivationFunction
object to the state it was in when previously instantiated via a call toDerivationFunction.getInstance(short, boolean)
. That is, the object is reset and available to be initialized again by a call toDerivationFunction.init(AlgorithmParameterSpec)
.The
AlgorithmParameterSpec
may define a maximum data length that can be generated. If such limitation is defined, the sum oflength
from all calls to this method cannot exceed the maximum length and will throw an exception. TheDerivationFunction
will then need to be reinitialized usingDerivationFunction.init(AlgorithmParameterSpec)
method.In addition to returning a
short
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Specified by:
lastBytes
in classDerivationFunction
- Parameters:
buffer
- the output bufferoffset
- the offset into the output bufferlength
- the length of derived data to generate- Returns:
offset+length
- Throws:
SecurityException
- if this JCRE owned temporary instance of theOneShot
object was opened in a context different from that of the caller.CryptoException
- with the following reason codes:CryptoException.INVALID_INIT
if at least one of the derivation function parameter has not been initialized.CryptoException.ILLEGAL_VALUE
if it is not possible to generate the requested data due to a total generated length exceeding the maximum length defined by algorithm parameter.
-
lastBytes
public short lastBytes(SecretKey secret) throws CryptoException
Generates derived data as specified by the derivation function algorithm and parameters. The length of derived data to generate is equal to the length of the secret key passed in parameter.A call to this method also resets this
DerivationFunction
object to the state it was in when previously instantiated via a call toDerivationFunction.getInstance(short, boolean)
. That is, the object is reset and available to be initialized again by a call toDerivationFunction.init(AlgorithmParameterSpec)
.The
AlgorithmParameterSpec
may define a maximum data length that can be generated. If such limitation is defined, the sum oflength
from all calls to this method cannot exceed the maximum length and will throw an exception. TheDerivationFunction
will then need to be reinitialized usingDerivationFunction.init(AlgorithmParameterSpec)
method.In addition to returning a
short
result, this method sets the result in an internal state which can be rechecked using assertion methods of theSensitiveResult
class, if supported by the platform.- Specified by:
lastBytes
in classDerivationFunction
- Parameters:
secret
- theSecretKey
instance which value has to be set with derived data.- Returns:
length
of the key in bytes- Throws:
SecurityException
- if this JCRE owned temporary instance of theOneShot
object was opened in a context different from that of the caller.CryptoException
- with the following reason codes:CryptoException.INVALID_INIT
if at least one of the derivation function parameter has not been initialized.CryptoException.ILLEGAL_VALUE
if it is not possible to generate the requested data to fully initialize the key value because generated length would exceed the maximum length defined by algorithm parameter.
-
-