Package javacard.security

Class InitializedMessageDigest.OneShot

  • Enclosing class:
    InitializedMessageDigest
    public static final class InitializedMessageDigest.OneShot
extends InitializedMessageDigest
    The OneShot class is a specialization of the InitializedMessageDigest class intended to support efficient one-shot hash operations that may avoid persistent memory writes entirely. The OneShot class uses a delegation model where calls are delegated to an instance of a InitializedMessageDigest-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. 

     ...
 InitializedMessageDigest.OneShot dig = null;
 try {
     dig = InitializedMessageDigest.OneShot.open(MessageDigest.ALG_SHA);
     dig.setInitialDigest(initialDigData, (short) 2, (short) initialDigData.length, initialDigData, (short) 0, (short) 2);
     dig.doFinal(someInData, (short) 0, (short) someInData.length, digData, (short) 0);
 } catch (CryptoException ce) {
     // Handle exception
 } finally {
     if (dig != null) {
         dig.close();
         dig = null;
     }
 }
 ...

    Since:
    3.0.5

    • Method Detail

      • open

        public static final InitializedMessageDigest.OneShot open​(byte algorithm)
                                                   throws CryptoException
        Closes and acquires a JCRE owned temporary Entry Point Object instance of OneShot with the selected algorithm.
        Parameters:
        algorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants above, for example, ALG_SHA.
        Returns:
        the InitializedMessageDigest object instance of the requested algorithm.
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode 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.

      • setInitialDigest

        public void setInitialDigest​(byte[] initialDigestBuf,
                             short initialDigestOffset,
                             short initialDigestLength,
                             byte[] digestedMsgLenBuf,
                             short digestedMsgLenOffset,
                             short digestedMsgLenLength)
                      throws CryptoException
        This method sets the state of the hash engine in place of the default value used by the MessageDigest superclass. This state is the intermediate state of the hash engine when a block-aligned portion of the message has been previously processed. The remaining bytes of the message must be presented to this InitializedMessageDigest object via the update and doFinal methods to generate the final message digest.

        Note:

        • The maximum allowed value of the byte length of the first part of the message is algorithm specific

        Specified by:
        setInitialDigest in class InitializedMessageDigest
        Parameters:
        initialDigestBuf - input buffer containing the intermediate state of the hash engine when a block-aligned portion of the message has been previously processed (using the same algorithm).
        initialDigestOffset - offset into state array where the state data begins
        initialDigestLength - the length of data in state array.
        digestedMsgLenBuf - the byte array containing the number of bytes in the first part of the message that has previously been processed to obtain the specified intermediate state. The value must be a multiple of the block size defined by the hash algorithm.
        digestedMsgLenOffset - the offset within digestedMsgLenBuf where the digested length begins (the bytes starting at this offset for digestedMsgLenLength bytes are concatenated to form the actual length of the message portion already processed)
        digestedMsgLenLength - byte length of the value stored in digestedMsgLenBuf
        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.ILLEGAL_VALUE if the parameter initialDigestLength is not equal to the intermediate hash value size of the algorithm or if the number of bytes in the first part of the message that has previously been hashed is 0 or not a multiple of the algorithm's block size or greater than the maximum length supported by the algorithm (see ALG_* algorithm descriptions ALG_SHA).

      • getAlgorithm

        public byte getAlgorithm()
        Gets the Message digest algorithm.
        Specified by:
        getAlgorithm in class MessageDigest
        Returns:
        the algorithm code defined above
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • getLength

        public byte getLength()
        Returns the byte length of the hash.
        Specified by:
        getLength in class MessageDigest
        Returns:
        hash length
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • doFinal

        public short doFinal​(byte[] inBuff,
                     short inOffset,
                     short inLength,
                     byte[] outBuff,
                     short outOffset)
              throws CryptoException
        Generates a hash of all/last input data. Completes and returns the hash computation after performing final operations such as padding. The MessageDigest object is reset to the initial state after this call is made. The data format is big-endian.

        The input and output buffer data may overlap.

        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:
        doFinal in class MessageDigest
        Parameters:
        inBuff - the input buffer of data to be hashed
        inOffset - the offset into the input buffer at which to begin hash generation
        inLength - the byte length to hash
        outBuff - the output buffer, may be the same as the input buffer
        outOffset - the offset into the output buffer where the resulting hash value begins
        Returns:
        number of bytes of hash output in outBuff
        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.ILLEGAL_USE if the accumulated message length is greater than the maximum length supported by the algorithm.

      • reset

        public void reset()
        Resets the MessageDigest object to the initial state for further use.
        Specified by:
        reset in class MessageDigest
        Throws:
        SecurityException - if this JCRE owned temporary instance of the OneShot object was opened in a context different from that of the caller.

      • update

        public void update​(byte[] inBuff,
                   short inOffset,
                   short inLength)
            throws CryptoException
        Always throws a CryptoException.This method is not supported by OneShot.
        Specified by:
        update in class MessageDigest
        Parameters:
        inBuff - the input buffer of data to be hashed
        inOffset - the offset into the input buffer at which to begin hash generation
        inLength - the byte length to hash
        Throws:
        CryptoException - with the following reason codes:
        • CryptoException.ILLEGAL_USE always.
        See Also:
        doFinal