javacardx.security.derivation.DerivationFunction

javacardx.security.derivation.DerivationFunction.OneShot

Enclosing class:: DerivationFunction

public static final class DerivationFunction.OneShot extends DerivationFunction

The OneShot class is a specialization of the DerivationFunction class intended to support efficient one-shot derivation function operations that may avoid persistent memory writes entirely. The OneShot class uses a delegation model where calls are delegated to an instance of a DerivationFunction-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.

...
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 DerivationFunction
DerivationFunction.OneShot

Modifier and Type

Class

Description

static final class

DerivationFunction.OneShot

The OneShot class is a specialization of the DerivationFunction class intended to support efficient one-shot derivation function operations that may avoid persistent memory writes entirely.
Field Summary

Fields inherited from class DerivationFunction
ALG_HKDF_EXPAND_LABEL_TLS13, 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

Modifier and Type

Field

Description

static final short

ALG_HKDF_EXPAND_LABEL_TLS13

Algorithm implementing the HKDF-Expand-Label Key Derivation defined in TLS 1.3 - IETF RFC 8446.

static final short

ALG_KDF_ANSI_X9_63

Algorithm implementing the KDF Key Derivation Function defined in the standard ANSI X9.63.

static final short

ALG_KDF_COUNTER_MODE

Algorithm implementing KDF in Counter Mode defined in NIST SP 800-108 (Recommendation for Key Derivation Using Pseudorandom Functions)

static final short

ALG_KDF_DPI_MODE

Algorithm implementing KDF in Double Pipeline Iteration Mode defined in NIST SP 800-108 (Recommendation for Key Derivation Using Pseudorandom Functions)

static final short

ALG_KDF_FEEDBACK_MODE

Algorithm implementing KDF in Feedback Mode defined in NIST SP 800-108 (Recommendation for Key Derivation Using Pseudorandom Functions)

static final short

ALG_KDF_HKDF

Algorithm implementing the HKDF Key Derivation function defined in IETF RFC 5869.

static final short

ALG_KDF_ICAO_MRTD

Algorithm implementing the KDF Key Derivation Function defined in the standard ICAO MRTD Doc 9303.

static final short

ALG_KDF_IEEE_1363

Algorithm implementing the KDF1 Key Derivation Function defined in the standard IEEE 1363-2000.

static final short

ALG_PRF_TLS11

Algorithm implementing the TLS version 1.1 Pseudo Random Function defined in IETF RFC 4346.

static final short

ALG_PRF_TLS12

Algorithm implementing the TLS version 1.2 Pseudo Random Function defined in IETF RFC 5246.
Method Summary

Modifier and Type

Method

Description

void

close()

Closes and releases this JCRE owned temporary instance of the OneShot object for reuse.

short

getAlgorithm()

Gets the Derivation Function algorithm.

void

init(AlgorithmParameterSpec params)

Initializes the DerivationFunction 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 a CryptoException.This method is not supported by OneShot.

short

nextBytes(SecretKey secret)

Always throws a CryptoException.This method is not supported by OneShot.

static final DerivationFunction.OneShot

open(byte algorithm)

Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm.

Methods inherited from class DerivationFunction
getInstance

Modifier and Type

Method

Description

static DerivationFunction

getInstance(short algorithm, boolean externalAccess)

Creates a DerivationFunction object instance of the selected algorithm.

Methods inherited from class Object
equals

Modifier and Type

Method

Description

boolean

equals(Object obj)

Compares two Objects for equality.

Method Details
- open
  public static final DerivationFunction.OneShot open(byte algorithm) throws CryptoException
  
  Opens/acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm.
  
  Parameters:
  
  algorithm - the desired derivation function algorithm. Valid codes listed in ALG_* constants above, for example ALG_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 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.
- init
  public void init(AlgorithmParameterSpec params) throws CryptoException
  
  Initializes the DerivationFunction object with the appropriate algorithm specific parameters.
  init() must be used to update the DerivationFunction object with new parameters. A caller may not make any assumption on the params 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 the params object is modified after invoking the init() method, the behavior of the nextBytes() and lastBytes() methods is unspecified.
  The AlgorithmParameterSpec params instance type is checked for consistency with the DerivationFunction algorithm. For instance KDFCounterModeSpec matches ALG_KDF_COUNTER_MODE.
  
  Specified by:
  
  init in class DerivationFunction
  
  Parameters:
  
  params - the derivation function algorithm parameters.
  
  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.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 class DerivationFunction
  
  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 the OneShot 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 a CryptoException.This method is not supported by OneShot.
  
  Specified by:
  
  nextBytes in class DerivationFunction
  
  Parameters:
  
  buffer - the output buffer
  
  offset - the offset into the output buffer
  
  length - 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 a CryptoException.This method is not supported by OneShot.
  
  Specified by:
  
  nextBytes in class DerivationFunction
  
  Parameters:
  
  secret - the SecretKey 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 to DerivationFunction.getInstance(short, boolean). That is, the object is reset and available to be initialized again by a call to DerivationFunction.init(AlgorithmParameterSpec).
  The AlgorithmParameterSpec may define a maximum data length that can be generated. If such limitation is defined, the sum of length from all calls to this method cannot exceed the maximum length and will throw an exception. The DerivationFunction will then need to be reinitialized using DerivationFunction.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 the SensitiveResult class, if supported by the platform.
  
  Specified by:
  
  lastBytes in class DerivationFunction
  
  Parameters:
  
  buffer - the output buffer
  
  offset - the offset into the output buffer
  
  length - the length of derived 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.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 to DerivationFunction.getInstance(short, boolean). That is, the object is reset and available to be initialized again by a call to DerivationFunction.init(AlgorithmParameterSpec).
  The AlgorithmParameterSpec may define a maximum data length that can be generated. If such limitation is defined, the sum of length from all calls to this method cannot exceed the maximum length and will throw an exception. The DerivationFunction will then need to be reinitialized using DerivationFunction.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 the SensitiveResult class, if supported by the platform.
  
  Specified by:
  
  lastBytes in class DerivationFunction
  
  Parameters:
  
  secret - the SecretKey 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 the OneShot 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.

Class DerivationFunction.OneShot

Nested Class Summary

Nested classes/interfaces inherited from class DerivationFunction

Field Summary

Fields inherited from class DerivationFunction

Method Summary

Methods inherited from class DerivationFunction

Methods inherited from class Object

Method Details

open

close

init

getAlgorithm

nextBytes

nextBytes

lastBytes

lastBytes