Package javacardx.security.derivation

Class DerivationFunction

  • Direct Known Subclasses:
    DerivationFunction.OneShot
    public abstract class DerivationFunction
extends Object
    The DerivationFunction 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 to init().

    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
      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 
      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 a DerivationFunction object instance of the selected algorithm.
      abstract void init​(AlgorithmParameterSpec params)
      Initializes the DerivationFunction 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

    • Constructor Detail

      • DerivationFunction

        protected DerivationFunction()
        Protected constructor.

    • Method Detail

      • getInstance

        public static DerivationFunction getInstance​(short algorithm,
                                             boolean externalAccess)
                                      throws CryptoException
        Creates a DerivationFunction object instance of the selected algorithm.
        Parameters:
        algorithm - the desired DerivationFunction algorithm. Valid codes listed in ALG_* constants above, for example, #ALG_KDF_COUNTER_MODE.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the DerivationFunction instance will also be accessed (via a Shareable interface) when the owner of the DerivationFunction instance is not the currently selected applet. If true 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 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.

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

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

        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.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 to getInstance(short, boolean). That is, the object is reset and available to be initialized again by a call to 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 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.

        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.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 to getInstance(short, boolean). That is, the object is reset and available to be initialized again by a call to 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 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.

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