Class DerivationFunction
- java.lang.Object
-
- javacardx.security.derivation.DerivationFunction
-
- Direct Known Subclasses:
DerivationFunction.OneShot
public abstract class DerivationFunction extends Object
TheDerivationFunction
class is the abstract class for derivation functions. This encompasses actually both Key Derivation Function (KDF) and Pseudo Random Function (PRF). Implementations of Derivation Functions must extend this class and implement all the abstract methods.A tear or card reset event resets an initialized
DerivationFunction
object to the state it was in when previously initialized via a call toinit()
.Even if a transaction is in progress, update of intermediate result state in the implementation instance shall not participate in the transaction.
- Since:
- 3.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
DerivationFunction.OneShot
TheOneShot
class is a specialization of theDerivationFunction
class intended to support efficient one-shot derivation function operations that may avoid persistent memory writes entirely.
-
Field Summary
Fields Modifier and Type Field Description static short
ALG_KDF_ANSI_X9_63
Algorithm implementing the KDF Key Derivation Function defined in the standard ANSI X9.63.static 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 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 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 short
ALG_KDF_HKDF
Algorithm implementing the HKDF Key Derivation function defined in IETF RFC 5869.static short
ALG_KDF_ICAO_MRTD
Algorithm implementing the KDF Key Derivation Function defined in the standard ICAO MRTD Doc 9303.static short
ALG_KDF_IEEE_1363
Algorithm implementing the KDF1 Key Derivation Function defined in the standard IEEE 1363-2000.static short
ALG_PRF_TLS11
Algorithm implementing the TLS version 1.1 Pseudo Random Function defined in IETF RFC 4346.static short
ALG_PRF_TLS12
Algorithm implementing the TLS version 1.2 Pseudo Random Function defined in IETF RFC 5246.
-
Constructor Summary
Constructors Modifier Constructor Description protected
DerivationFunction()
Protected constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract short
getAlgorithm()
Gets the Derivation Function algorithm.static DerivationFunction
getInstance(short algorithm, boolean externalAccess)
Creates aDerivationFunction
object instance of the selected algorithm.abstract void
init(AlgorithmParameterSpec params)
Initializes theDerivationFunction
object with the appropriate algorithm specific parameters.abstract short
lastBytes(byte[] buffer, short offset, short length)
Generates derived data as specified by the derivation function algorithm and parameters.abstract short
lastBytes(SecretKey secret)
Generates derived data as specified by the derivation function algorithm and parameters.abstract short
nextBytes(byte[] buffer, short offset, short length)
Generates derived data as specified by the derivation function algorithm and parameters.abstract short
nextBytes(SecretKey secret)
Generates derived data as specified by the derivation function algorithm and parameters.
-
-
-
Field Detail
-
ALG_KDF_COUNTER_MODE
public 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)- See Also:
- Constant Field Values
-
ALG_KDF_DPI_MODE
public 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)- See Also:
- Constant Field Values
-
ALG_KDF_FEEDBACK_MODE
public 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)- See Also:
- Constant Field Values
-
ALG_PRF_TLS11
public static final short ALG_PRF_TLS11
Algorithm implementing the TLS version 1.1 Pseudo Random Function defined in IETF RFC 4346.- See Also:
- Constant Field Values
-
ALG_PRF_TLS12
public static final short ALG_PRF_TLS12
Algorithm implementing the TLS version 1.2 Pseudo Random Function defined in IETF RFC 5246.- See Also:
- Constant Field Values
-
ALG_KDF_IEEE_1363
public static final short ALG_KDF_IEEE_1363
Algorithm implementing the KDF1 Key Derivation Function defined in the standard IEEE 1363-2000.- See Also:
- Constant Field Values
-
ALG_KDF_ICAO_MRTD
public static final short ALG_KDF_ICAO_MRTD
Algorithm implementing the KDF Key Derivation Function defined in the standard ICAO MRTD Doc 9303.- See Also:
- Constant Field Values
-
ALG_KDF_ANSI_X9_63
public static final short ALG_KDF_ANSI_X9_63
Algorithm implementing the KDF Key Derivation Function defined in the standard ANSI X9.63.- See Also:
- Constant Field Values
-
ALG_KDF_HKDF
public static final short ALG_KDF_HKDF
Algorithm implementing the HKDF Key Derivation function defined in IETF RFC 5869.- See Also:
- Constant Field Values
-
-
Method Detail
-
getInstance
public static DerivationFunction getInstance(short algorithm, boolean externalAccess) throws CryptoException
Creates aDerivationFunction
object instance of the selected algorithm.- Parameters:
algorithm
- the desired DerivationFunction algorithm. Valid codes listed inALG_*
constants above, for example,#ALG_KDF_COUNTER_MODE
.externalAccess
-true
indicates that the instance will be shared among multiple applet instances and that theDerivationFunction
instance will also be accessed (via aShareable
interface) when the owner of theDerivationFunction
instance is not the currently selected applet. Iftrue
the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.- Returns:
- the
DerivationFunction
object instance of the requested algorithm - Throws:
CryptoException
- with the following reason codes:CryptoException.NO_SUCH_ALGORITHM
if the requested algorithm is not supported or shared access mode is not supported.
- See Also:
getAlgorithm()
-
init
public abstract 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.- Parameters:
params
- the derivation function algorithm parameters.- Throws:
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 abstract short getAlgorithm()
Gets the Derivation Function algorithm.- Returns:
- the algorithm code defined above; if the algorithm is not one of
the pre-defined algorithms,
0
is returned. - See Also:
getInstance(short, boolean)
-
nextBytes
public abstract short nextBytes(byte[] buffer, short offset, short length) throws CryptoException
Generates derived data as specified by the derivation function algorithm and parameters.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 usinginit(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.- 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.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.
-
nextBytes
public abstract short nextBytes(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.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 usinginit(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.- 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.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.
-
lastBytes
public abstract 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 togetInstance(short, boolean)
. That is, the object is reset and available to be initialized again by a call toinit(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 usinginit(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.- 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.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 abstract 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 togetInstance(short, boolean)
. That is, the object is reset and available to be initialized again by a call toinit(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 usinginit(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.- 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.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.
-
-