Package javacard.security

Class MessageDigest

  • Direct Known Subclasses:
    InitializedMessageDigest, MessageDigest.OneShot
    public abstract class MessageDigest
extends Object
    The MessageDigest class is the base class for hashing algorithms. Implementations of MessageDigest algorithms must extend this class and implement all the abstract methods.

    A tear or card reset event resets a MessageDigest object to the initial state (state upon construction).

    Even if a transaction is in progress, update of intermediate result state in the implementation instance shall not participate in the transaction.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  MessageDigest.OneShot
      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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static byte ALG_MD5
      Message Digest algorithm MD5.
      static byte ALG_NULL
      This constant indicates that there is no discrete message digest algorithm.
      static byte ALG_RIPEMD160
      Message Digest algorithm RIPE MD-160.
      static byte ALG_SHA
      Message Digest algorithm SHA-1.
      static byte ALG_SHA_224
      Message Digest algorithm SHA-224.
      static byte ALG_SHA_256
      Message Digest algorithm SHA-256.
      static byte ALG_SHA_384
      Message Digest algorithm SHA-384.
      static byte ALG_SHA_512
      Message Digest algorithm SHA-512.
      static byte ALG_SHA3_224
      Message Digest algorithm SHA3-224.
      static byte ALG_SHA3_256
      Message Digest algorithm SHA3-256.
      static byte ALG_SHA3_384
      Message Digest algorithm SHA3-384.
      static byte ALG_SHA3_512
      Message Digest algorithm SHA3-512.
      static byte ALG_SM3
      Message Digest algorithm SM3.
      static byte LENGTH_MD5
      Length of digest in bytes for MD5
      static byte LENGTH_RIPEMD160
      Length of digest in bytes for RIPE MD-160
      static byte LENGTH_SHA
      Length of digest in bytes for SHA-1
      static byte LENGTH_SHA_224
      Length of digest in bytes for SHA-224
      static byte LENGTH_SHA_256
      Length of digest in bytes for SHA-256
      static byte LENGTH_SHA_384
      Length of digest in bytes for SHA-384
      static byte LENGTH_SHA_512
      Length of digest in bytes for SHA-512
      static byte LENGTH_SHA3_224
      Length of digest in bytes for SHA3-224
      static byte LENGTH_SHA3_256
      Length of digest in bytes for SHA3-256
      static byte LENGTH_SHA3_384
      Length of digest in bytes for SHA3-384
      static byte LENGTH_SHA3_512
      Length of digest in bytes for SHA3-512
      static byte LENGTH_SM3
      Length of digest in bytes for SM3

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected MessageDigest()
      Protected Constructor

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract short doFinal​(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)
      Generates a hash of all/last input data.
      abstract byte getAlgorithm()
      Gets the Message digest algorithm.
      static InitializedMessageDigest getInitializedMessageDigestInstance​(byte algorithm, boolean externalAccess)
      Creates a InitializedMessageDigest object instance of the selected algorithm.
      static MessageDigest getInstance​(byte algorithm, boolean externalAccess)
      Creates a MessageDigest object instance of the selected algorithm.
      abstract byte getLength()
      Returns the byte length of the hash.
      abstract void reset()
      Resets the MessageDigest object to the initial state for further use.
      abstract void update​(byte[] inBuff, short inOffset, short inLength)
      Accumulates a hash of the input data.

    • Field Detail

      • ALG_SHA

        public static final byte ALG_SHA
        Message Digest algorithm SHA-1. The block size used by this algorithm is 64 bytes. The intermediate state of a SHA-1 hash is a sequence of 20 bytes representing the concatenation of the five 32-bit words of the intermediate hash value H(i) (section 6.1.2 of FIPS180-4) converted to a hex string (section 3.1 of FIPS180-4).
        See Also:
        Constant Field Values

      • ALG_MD5

        public static final byte ALG_MD5
        Message Digest algorithm MD5. The block size used by this algorithm is 64 bytes. The intermediate state size used by this algorithm is 16 bytes.
        See Also:
        Constant Field Values

      • ALG_RIPEMD160

        public static final byte ALG_RIPEMD160
        Message Digest algorithm RIPE MD-160. The block size used by this algorithm is 64 bytes. The intermediate state size used by this algorithm is 20 bytes.
        See Also:
        Constant Field Values

      • ALG_SHA_256

        public static final byte ALG_SHA_256
        Message Digest algorithm SHA-256. The block size used by this algorithm is 64 bytes. The intermediate state of a SHA-256 hash is a sequence of 32 bytes representing the concatenation of the 8 words of 32-bit of the intermediate hash value H(i) (section 6.2.2 of FIPS180-4) converted to a hex string (section 3.1 of FIPS180-4).
        See Also:
        Constant Field Values

      • ALG_SHA_384

        public static final byte ALG_SHA_384
        Message Digest algorithm SHA-384. The block size used by this algorithm is 128 bytes. The intermediate state of a SHA-384 hash is a sequence of 64 bytes representing the concatenation of the 8 words of 64-bit of the intermediate hash value H(i) (section 6.4.2 of FIPS180-4) converted to a hex string (section 3.1 of FIPS180-4).
        See Also:
        Constant Field Values

      • ALG_SHA_512

        public static final byte ALG_SHA_512
        Message Digest algorithm SHA-512. The block size used by this algorithm is 128 bytes. The intermediate state of a SHA-512 hash is a sequence of 64 bytes representing the concatenation of the 8 words of 64-bit of the intermediate hash value H(i) (section 6.4.2 of FIPS180-4) converted to a hex string (section 3.1 of FIPS180-4).
        See Also:
        Constant Field Values

      • ALG_SHA_224

        public static final byte ALG_SHA_224
        Message Digest algorithm SHA-224. The block size used by this algorithm is 64 bytes. The intermediate state of a SHA-224 hash is a sequence of 32 bytes representing the concatenation of the 8 words of 32-bit of the intermediate hash value H(i) (section 6.2.2 of FIPS180-4) converted to a hex string (section 3.1 of FIPS180-4).
        See Also:
        Constant Field Values

      • ALG_SHA3_224

        public static final byte ALG_SHA3_224
        Message Digest algorithm SHA3-224. The block size used by this algorithm is 144 bytes. The intermediate state size used by this algorithm is 200 bytes.
        See Also:
        Constant Field Values

      • ALG_SHA3_256

        public static final byte ALG_SHA3_256
        Message Digest algorithm SHA3-256. The block size used by this algorithm is 136 bytes. The intermediate state size used by this algorithm is 200 bytes.
        See Also:
        Constant Field Values

      • ALG_SHA3_384

        public static final byte ALG_SHA3_384
        Message Digest algorithm SHA3-384. The block size used by this algorithm is 104 bytes. The intermediate state size used by this algorithm is 200 bytes.
        See Also:
        Constant Field Values

      • ALG_SHA3_512

        public static final byte ALG_SHA3_512
        Message Digest algorithm SHA3-512. The block size used by this algorithm is 72 bytes. The intermediate state size used by this algorithm is 200 bytes.
        See Also:
        Constant Field Values

      • ALG_SM3

        public static final byte ALG_SM3
        Message Digest algorithm SM3. The block size used by this algorithm is 64 bytes (512-bit). The intermediate state size used by this algorithm is 32 bytes.
        Since:
        3.1
        See Also:
        Constant Field Values

      • LENGTH_MD5

        public static final byte LENGTH_MD5
        Length of digest in bytes for MD5
        See Also:
        Constant Field Values

      • LENGTH_RIPEMD160

        public static final byte LENGTH_RIPEMD160
        Length of digest in bytes for RIPE MD-160
        See Also:
        Constant Field Values

      • LENGTH_SHA

        public static final byte LENGTH_SHA
        Length of digest in bytes for SHA-1
        See Also:
        Constant Field Values

      • LENGTH_SHA_224

        public static final byte LENGTH_SHA_224
        Length of digest in bytes for SHA-224
        See Also:
        Constant Field Values

      • LENGTH_SHA_256

        public static final byte LENGTH_SHA_256
        Length of digest in bytes for SHA-256
        See Also:
        Constant Field Values

      • LENGTH_SHA_384

        public static final byte LENGTH_SHA_384
        Length of digest in bytes for SHA-384
        See Also:
        Constant Field Values

      • LENGTH_SHA_512

        public static final byte LENGTH_SHA_512
        Length of digest in bytes for SHA-512
        See Also:
        Constant Field Values

      • LENGTH_SHA3_224

        public static final byte LENGTH_SHA3_224
        Length of digest in bytes for SHA3-224
        See Also:
        Constant Field Values

      • LENGTH_SHA3_256

        public static final byte LENGTH_SHA3_256
        Length of digest in bytes for SHA3-256
        See Also:
        Constant Field Values

      • LENGTH_SHA3_384

        public static final byte LENGTH_SHA3_384
        Length of digest in bytes for SHA3-384
        See Also:
        Constant Field Values

      • LENGTH_SHA3_512

        public static final byte LENGTH_SHA3_512
        Length of digest in bytes for SHA3-512
        See Also:
        Constant Field Values

      • LENGTH_SM3

        public static final byte LENGTH_SM3
        Length of digest in bytes for SM3
        Since:
        3.1
        See Also:
        Constant Field Values

    • Constructor Detail

      • MessageDigest

        protected MessageDigest()
        Protected Constructor

    • Method Detail

      • getInstance

        public static final MessageDigest getInstance​(byte algorithm,
                                              boolean externalAccess)
                                       throws CryptoException
        Creates a MessageDigest object instance of the selected algorithm.

        Note:

        Parameters:
        algorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants above, for example, ALG_SHA.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the MessageDigest instance will also be accessed (via a Shareable. interface) when the owner of the MessageDigest instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
        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.

      • getInitializedMessageDigestInstance

        public static final InitializedMessageDigest getInitializedMessageDigestInstance​(byte algorithm,
                                                                                 boolean externalAccess)
                                                                          throws CryptoException
        Creates a InitializedMessageDigest object instance of the selected algorithm.
        Parameters:
        algorithm - the desired message digest algorithm. Valid codes listed in ALG_* constants above, for example, ALG_SHA.
        externalAccess - true indicates that the instance will be shared among multiple applet instances and that the InitializedMessageDigest instance will also be accessed (via a Shareable. interface) when the owner of the InitializedMessageDigest instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.
        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.
        Since:
        2.2.2

      • getAlgorithm

        public abstract byte getAlgorithm()
        Gets the Message digest algorithm.
        Returns:
        the algorithm code defined above

      • getLength

        public abstract byte getLength()
        Returns the byte length of the hash.
        Returns:
        hash length

      • doFinal

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

        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:
        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 abstract void update​(byte[] inBuff,
                            short inOffset,
                            short inLength)
                     throws CryptoException
        Accumulates a hash of the input data. This method requires temporary storage of intermediate results. In addition, if the input data length is not block aligned (multiple of block size) then additional internal storage may be allocated at this time to store a partial input data block. This may result in additional resource consumption and/or slow performance. This method should only be used if all the input data required for the hash is not available in one byte array. If all of the input data required for the hash is located in a single byte array, use of the doFinal() method is recommended. The doFinal() method must be called to complete processing of input data accumulated by one or more calls to the update() method. The data format is big-endian.

        Note:

        • If inLength is 0 this method does nothing.

        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 if the accumulated message length is greater than the maximum length supported by the algorithm.
        See Also:
        doFinal

      • reset

        public abstract void reset()
        Resets the MessageDigest object to the initial state for further use.