Package javacard.security

Class MessageDigest.OneShot

  • Enclosing class:
    MessageDigest
    public static final class MessageDigest.OneShot
extends MessageDigest
    The OneShot class is a specialization of the MessageDigest 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 MessageDigest-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. 

     ...
 MessageDigest.OneShot dig = null;
 try {
     dig = MessageDigest.OneShot.open(MessageDigest.ALG_SHA);
     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 MessageDigest.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 message digest algorithm. Valid codes listed in ALG_* constants above, for example, ALG_SHA.
        Returns:
        the MessageDigest 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.

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

      • 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

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