Package javacardx.security.derivation

Class 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

    • Method Detail

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

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