javacard.security
Class MessageDigest

java.lang.Object
  extended by 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:

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.



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