com.novell.java.security
Class MessageDigest

java.lang.Object
  |
  +--com.novell.java.security.MessageDigestSpi
        |
        +--com.novell.java.security.MessageDigest

public abstract class MessageDigest

extends MessageDigestSpi

Provides applications with the functionality of a message digest algorithm, such as MD5 or SHA. Message digests are secure one-way hash functions that take arbitrary-sized data and output a fixed-length hash value.

A MessageDigest object starts out initialized. The data is processed through it using the update() methods. At any point the reset() method can be called to reset the digest. Once all the data has been updated, one of the digest() methods should be called to complete the hash computation. The digest() method can be called once for a given number of updates. After digest() has been called, the MessageDigest object is reset to its initialized state.

Implementations of the MessageDigest class can be used by implementing the Cloneable interface. Such an implementation will let client applications test cloneability using instanceof Cloneable before cloning. Following is such an example:

MessageDigest md = MessageDigest.getInstance("SHA");
 if (md instanceof Cloneable) {
     md.update(toChapter1);
     MessageDigest tc1 = md.clone();
     byte[] toChapter1Digest = tc1.digest;
     md.update(toChapter2);
     ...etc.
 } else {
     throw new DigestException("couldn't make digest of partial content");
 }

If a given implementation is not cloneable, but the number of digests is known in advance, it is still possible to compute intermediate digests by instantiating several instances.

The MessageDigest class is abstract and extends from the MessageDigestSpi class for historical reasons. Application developers should only take notice of the methods defined in this MessageDigest class, and ignore all the methods in the superclass.

See Also:

DigestInputStream, DigestOutputStream, MessageDigestSpi

Method Summary

java.lang.Object	clone() Creates a new message digest object of the same class as this message digest object.
byte[]	digest() Completes the hash computation by performing final operations such as padding.
byte[]	digest(byte[] input) Performs a final update and digest computation on the digest using the specified array of bytes.
int	digest(byte[] buf, int offset, int len) Completes the hash computation by performing final operations such as padding.
java.lang.String	getAlgorithm() Returns a string that identifies the algorithm, independent of implementation details.
int	getDigestLength() Returns the length of the digest in bytes.
static MessageDigest	getInstance(java.lang.String algorithm) Generates a MessageDigest object that implements the specified digest algorithm.
static MessageDigest	getInstance(java.lang.String algorithm, java.lang.String provider) Generates a MessageDigest object implementing the specified algorithm as supplied from the specified provider.
Provider	getProvider() Returns the Provider of this message digest object.
static boolean	isEqual(byte[] digesta, byte[] digestb) Compares two digests for equality using a simple byte compare.
void	reset() Resets the digest for further use.
java.lang.String	toString() Returns a string representation of this message digest object.
void	update(byte input) Updates the message digest using the specified byte.
void	update(byte[] input) Updates the message digest using the specified array of bytes.
void	update(byte[] input, int offset, int len) Updates the message digest using the specified array of bytes, starting at the specified offset.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getInstance

public static MessageDigest getInstance(java.lang.String algorithm)
                                 throws NoSuchAlgorithmException

Generates a MessageDigest object that implements the specified digest algorithm. If the default provider package contains a MessageDigest subclass implementing the algorithm, an instance of that subclass is returned. If the algorithm is not available in the default package, other packages are searched. See Appendix A in Sun's Java Cryptography Architecture API Specification & Reference documentation for information about standard algorithm names.

Parameters:

algorithm - The name of the algorithm requested.

Returns:

A Message Digest object implementing the specified algorithm.

Throws:

NoSuchAlgorithmException - Thrown if the algorithm is not available in the caller's environment.

getInstance

public static MessageDigest getInstance(java.lang.String algorithm,
                                        java.lang.String provider)
                                 throws NoSuchAlgorithmException,
                                        NoSuchProviderException

Generates a MessageDigest object implementing the specified algorithm as supplied from the specified provider. The MessageDigest is generated if an algorithm is available from the provider. See Appendix A in Sun's Java Cryptography Architecture API Specification & Reference documentation for information about standard algorithm names.

Parameters:

algorithm - The name of the algorithm requested.

provider - The name of the provider.

Returns:

A Message Digest object implementing the specified algorithm.

Throws:

NoSuchAlgorithmException - Thrown if the algorithm is not available in the package supplied by the requested provider.

NoSuchProviderException - Thrown if the provider is not available in the environment.

See Also:

Provider

getProvider

public final Provider getProvider()

Returns the Provider of this message digest object.

Returns:

The Provider of this message digest object

update

public void update(byte input)

Updates the message digest using the specified byte.

Parameters:

input - The byte with which to update the digest.

update

public void update(byte[] input,
                   int offset,
                   int len)

Updates the message digest using the specified array of bytes, starting at the specified offset.

Parameters:

input - The array of bytes.

offset - The offset in the array of bytes from which to start.

len - The number of bytes to use, starting at the offset.

update

public void update(byte[] input)

Updates the message digest using the specified array of bytes.

Parameters:

input - The array of bytes.

digest

public byte[] digest()

Completes the hash computation by performing final operations such as padding. The digest is reset after this call is made.

Returns:

The array of bytes for the resulting hash value.

digest

public int digest(byte[] buf,
                  int offset,
                  int len)
           throws DigestException

Completes the hash computation by performing final operations such as padding. The digest is reset after this call is made.

Parameters:

buf - The output buffer for the computed digest.

offset - The offset into the output buffer at which to begin storing the digest.

len - The number of bytes within the output buffer (buf) allotted for the digest.

Returns:

The length of the digest.

Throws:

DigestException - Thrown if an error occurs.

digest

public byte[] digest(byte[] input)

Performs a final update and digest computation on the digest using the specified array of bytes. That is, this digest() method first calls update() on the array, then calls this digest() method.

Parameters:

input - The input to be updated before the digest is completed.

Returns:

The array of bytes for the resulting hash value.

toString

public java.lang.String toString()

Returns a string representation of this message digest object. In general, the toString() method returns a string that textually represents the object. The result should be a concise but informative representation that is easy for a person to read.

Returns:

A string representation of the message digest object.

Overrides:

toString in class java.lang.Object

isEqual

public static boolean isEqual(byte[] digesta,
                              byte[] digestb)

Compares two digests for equality using a simple byte compare.

Parameters:

digesta - One of the digests to compare.

digestb - The other digest to compare.

Returns:

A boolean set to TRUE if the digests are equal, otherwise FALSE.

reset

public void reset()

Resets the digest for further use.

getAlgorithm

public final java.lang.String getAlgorithm()

Returns a string that identifies the algorithm, independent of implementation details. The name should be a standard Java Security name, such as SHA, MD5, and so forth. See Appendix A in Sun's Java Cryptography Architecture API Specification & Reference documentation for information about standard algorithm names.

getDigestLength

public final int getDigestLength()

Returns the length of the digest in bytes. Zero (0) is returned if this operation is not supported by the provider and the implementation is not cloneable.

Returns:

The digest length in bytes, or 0 if this operation is not supported by the provider and the implementation is not cloneable.

Since:

JDK1.2

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Creates a new message digest object of the same class as this message digest object. It then initializes each of the new object's fields by assigning it the same value as the corresponding field in this object. The clone() method will only clone a message digest object if the implementation is Cloneable. A class indicates that its instances can be cloned by declaring that it implements the Cloneable interface.

Returns:

a clone if the implementation is cloneable.

Throws:

java.lang.CloneNotSupportedException - Thrown if the clone() method is called on an implementation that does not support Cloneable.

Overrides:

clone in class MessageDigestSpi