MessageDigest (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.security
Class MessageDigest

    java.lang.Object
      javacard.security.MessageDigest

Direct Known Subclasses:
  InitializedMessageDigest

    @TransactionType(value=SUPPORTS)
    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.

Since:
  Java Card 2.x, Java Card 3.0

Field Summary
`static byte` | `ALG_MD5` Message Digest algorithm MD5.
`static byte` | `ALG_RIPEMD160` Message Digest algorithm RIPE MD-160.
`static byte` | `ALG_SHA` Message Digest algorithm SHA.
`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` | `LENGTH_MD5` Length of digest in bytes for SHA
`static byte` | `LENGTH_RIPEMD160` Length of digest in bytes for RIPE MD-160
`static byte` | `LENGTH_SHA` Length of digest in bytes for SHA-256
`static byte` | `LENGTH_SHA_256` Length of digest in bytes for MD5
`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 String` | `SERVICE_NAME` This cryptographic service name, as used to lookup implemented algorithms.

Constructor Summary
`protected` | `MessageDigest()` Protected Constructor

Method Summary
`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.
`abstract String` | `getAlgorithmName()` Gets the Message digest algorithm name.
`static InitializedMessageDigest` | `getInitializedMessageDigestInstance(byte algorithm, boolean externalAccess)` Creates a `InitializedMessageDigest` object instance of the selected algorithm.
`static InitializedMessageDigest` | `getInitializedMessageDigestInstance(String algorithm, boolean externalAccess)` Creates a `InitializedMessageDigest` object instance of the selected algorithm.
`static InitializedMessageDigest` | `getInitializedMessageDigestInstance(String algorithm, String provider, 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.
`static MessageDigest` | `getInstance(String algorithm, boolean externalAccess)` Creates a `MessageDigest` object instance of the selected algorithm.
`static MessageDigest` | `getInstance(String algorithm, String provider, 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.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SERVICE_NAME

    public static final String SERVICE_NAME

  This cryptographic service name, as used to lookup implemented algorithms.

  Since:
    Java Card 3.0
  See Also:
    Constant Field Values

### ALG_SHA

    public static final byte ALG_SHA

  Message Digest algorithm SHA. The block size used by this algorithm is 64 bytes. The intermediate hash value size used by this algorithm is 20 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"SHA"`

  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 hash value size used by this algorithm is 16 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"MD5"`

  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 hash value size used by this algorithm is 20 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"RIPEMD160"`

  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 hash value size used by this algorithm is 32 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"SHA_256"`

  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 hash value size used by this algorithm is 64 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"SHA_384"`

  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 hash value size used by this algorithm is 64 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"SHA_512"`

  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 hash value size used by this algorithm is 32 bytes.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"SHA_224"`

  See Also:
    Constant Field Values

### LENGTH_MD5

    public static final byte LENGTH_MD5

  Length of digest in bytes for SHA

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

  See Also:
    Constant Field Values

### LENGTH_SHA_256

    public static final byte LENGTH_SHA_256

  Length of digest in bytes for MD5

  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

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.

  This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the `CryptoServices.getProviders()` method.

  A call to this method is equivalent to a call to `getInstance(java.lang.String, boolean)` with the `algorithm` parameter set to the equivalent `String` algorithm name - as listed in the `ALG_*` constants above.

  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` or if called from a web application 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.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.

### getInstance

    public static final MessageDigest getInstance(String algorithm,
                                                  boolean externalAccess)
                                           throws CryptoException

  Creates a `MessageDigest` object instance of the selected algorithm.

  This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the `CryptoServices.getProviders()` method.

  Parameters:
    `algorithm` - the desired message digest algorithm name. Valid names 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` or if called from a web application 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.
    `NullPointerException` - if `algorithm` is null.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### getInstance

    public static final MessageDigest getInstance(String algorithm,
                                                  String provider,
                                                  boolean externalAccess)
                                           throws CryptoException

  Creates a `MessageDigest` object instance of the selected algorithm.

  Parameters:
    `algorithm` - the desired message digest algorithm name. Valid names listed in `ALG_*` constants above, for example, `ALG_SHA`.
    `provider` - the desired message digest algorithm provider.
    `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` or if called from a web application 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.
    `NullPointerException` - if `algorithm` or `provider` is null.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### 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` or if called from a web application 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.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    2.2.2

### getInitializedMessageDigestInstance

    public static final InitializedMessageDigest getInitializedMessageDigestInstance(String algorithm,
                                                                                     boolean externalAccess)
                                                                              throws CryptoException

  Creates a `InitializedMessageDigest` object instance of the selected algorithm.

  Parameters:
    `algorithm` - the desired message digest algorithm names. Valid names 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` or if called from a web application 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.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### getInitializedMessageDigestInstance

    public static final InitializedMessageDigest getInitializedMessageDigestInstance(String algorithm,
                                                                                     String provider,
                                                                                     boolean externalAccess)
                                                                              throws CryptoException

  Creates a `InitializedMessageDigest` object instance of the selected algorithm.

  Parameters:
    `algorithm` - the desired message digest algorithm names. Valid names listed in `ALG_*` constants above, for example, `ALG_SHA`.
    `provider` - the desired message digest algorithm provider.
    `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` or if called from a web application 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.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### getAlgorithm

    public abstract byte getAlgorithm()

  Gets the Message digest algorithm. Pre-defined codes listed in `ALG_*` constants above, for example, `ALG_SHA`.

  Returns:
    the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, `0` is returned.

### getAlgorithmName

    public abstract String getAlgorithmName()

  Gets the Message digest algorithm name. Pre-defined names listed for each of the `ALG_*` constants above, for example, `ALG_SHA`.

  New algorithms may be defined through the Extensible Cryptography Framework.

  Returns:
    the algorithm name.
  Since:
    Java Card 3.0

### 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 input and output buffer data may overlap.

  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.

  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.