JavaTM Platform
Standard Ed. 6

java.security
类 MessageDigest

java.lang.Object
  继承者 java.security.MessageDigestSpi
      继承者 java.security.MessageDigest

public abstract class MessageDigest
extends MessageDigestSpi

此 MessageDigest 类为应用程序提供信息摘要算法的功能,如 MD5 或 SHA 算法。信息摘要是安全的单向哈希函数,它接收任意大小的数据,并输出固定长度的哈希值。

MessageDigest 对象开始被初始化。该对象通过使用 update 方法处理数据。任何时候都可以调用 reset 方法重置摘要。一旦所有需要更新的数据都已经被更新了,应该调用 digest 方法之一完成哈希计算。

对于给定数量的更新数据,digest 方法只能被调用一次。在调用 digest 之后,MessageDigest 对象被重新设置成其初始状态。

该实现可随意选择是否实现 Cloneable 接口。客户端应用程可以通过尝试复制和捕获 CloneNotSupportedException 来测试可复制性:

 MessageDigest md = MessageDigest.getInstance("SHA");

 try {
     md.update(toChapter1);
     MessageDigest tc1 = md.clone();
     byte[] toChapter1Digest = tc1.digest();
     md.update(toChapter2);
     ...etc.
 } catch (CloneNotSupportedException cnse) {
     throw new DigestException("couldn't make digest of partial content");
 }
 

注意,如果给定的实现是不可复制的,而事先已经知道摘要的数目,则仍然能够通过实例化几个实例计算中间摘要。

注意,由于历史原因,此类是抽象类,是从 MessageDigestSpi 扩展的。应用程序开发人员只需注意在此 MessageDigest 类中定义的方法;超类中的所有方法是供希望提供自己的信息摘要算法实现的加密服务提供者使用的。

另请参见:
DigestInputStream, DigestOutputStream

构造方法摘要
protected MessageDigest(String algorithm)
          创建具有指定算法名称的信息摘要。
 
方法摘要
 Object clone()
          如果实现是可复制的,则返回一个副本。
 byte[] digest()
          通过执行诸如填充之类的最终操作完成哈希计算。
 byte[] digest(byte[] input)
          使用指定的 byte 数组对摘要进行最后更新,然后完成摘要计算。
 int digest(byte[] buf, int offset, int len)
          通过执行诸如填充之类的最终操作完成哈希计算。
 String getAlgorithm()
          返回标识算法的独立于实现细节的字符串。
 int getDigestLength()
          返回以字节为单位的摘要长度,如果提供者不支持此操作并且实现是不可复制的,则返回 0。
static MessageDigest getInstance(String algorithm)
          返回实现指定摘要算法的 MessageDigest 对象。
static MessageDigest getInstance(String algorithm, Provider provider)
          返回实现指定摘要算法的 MessageDigest 对象。
static MessageDigest getInstance(String algorithm, String provider)
          返回实现指定摘要算法的 MessageDigest 对象。
 Provider getProvider()
          返回此信息摘要对象的提供者。
static boolean isEqual(byte[] digesta, byte[] digestb)
          比较两个摘要的相等性。
 void reset()
          重置摘要以供再次使用。
 String toString()
          返回此信息摘要对象的字符串表示形式。
 void update(byte input)
          使用指定的字节更新摘要。
 void update(byte[] input)
          使用指定的 byte 数组更新摘要。
 void update(byte[] input, int offset, int len)
          使用指定的 byte 数组,从指定的偏移量开始更新摘要。
 void update(ByteBuffer input)
          使用指定的 ByteBuffer 更新摘要。
 
从类 java.security.MessageDigestSpi 继承的方法
engineDigest, engineDigest, engineGetDigestLength, engineReset, engineUpdate, engineUpdate, engineUpdate
 
从类 java.lang.Object 继承的方法
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

构造方法详细信息

MessageDigest

protected MessageDigest(String algorithm)
创建具有指定算法名称的信息摘要。

参数:
algorithm - 摘要算法的标准名称。有关标准算法名称的信息,请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。
方法详细信息

getInstance

public static MessageDigest getInstance(String algorithm)
                                 throws NoSuchAlgorithmException
返回实现指定摘要算法的 MessageDigest 对象。

此方法从首选 Provider 开始遍历已注册安全提供者列表。返回封装取自第一个 Provider 的 MessageDigestSpi 实现的新 MessageDigest 对象,第一个 Provider 支持指定算法。

注意,可以通过 Security.getProviders() 方法获取已注册提供者列表。

参数:
algorithm - 所请求算法的名称。有关标准算法名称的信息,请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。
返回:
实现指定算法的 Message Digest 对象。
抛出:
NoSuchAlgorithmException - 如果没有 Provider 支持指定算法的 MessageDigestSpi 实现
另请参见:
Provider

getInstance

public static MessageDigest getInstance(String algorithm,
                                        String provider)
                                 throws NoSuchAlgorithmException,
                                        NoSuchProviderException
返回实现指定摘要算法的 MessageDigest 对象。

返回封装 MessageDigestSpi 实现的新 MessageDigest 对象,该实现取自指定提供者。指定提供者必须在安全提供者列表中注册。

注意,可以通过 Security.getProviders() 方法获取已注册提供者列表。

参数:
algorithm - 所请求算法的名称。有关标准算法名称的信息,请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。
provider - 提供者的名称。
返回:
实现指定算法的 MessageDigest 对象。
抛出:
NoSuchAlgorithmException - 如果指定算法的 MessageDigestSpi 实现不能从指定提供者获得。
NoSuchProviderException - 如果指定提供者未在安全提供者列表中注册。
IllegalArgumentException - 如果提供者的名称为 null 或空。
另请参见:
Provider

getInstance

public static MessageDigest getInstance(String algorithm,
                                        Provider provider)
                                 throws NoSuchAlgorithmException
返回实现指定摘要算法的 MessageDigest 对象。

返回封装 MessageDigestSpi 实现的新 MessageDigest 对象,该实现取自指定 Provider 对象。注意,指定 Provider 对象无需在提供者列表中注册。

参数:
algorithm - 所请求算法的名称。有关标准算法名称的信息,请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。
provider - 提供者。
返回:
实现指定算法的 MessageDigest 对象。
抛出:
NoSuchAlgorithmException - 如果指定算法的 MessageDigestSpi 实现不能从指定的提供者对象获得。
IllegalArgumentException - 如果指定的提供者为 null。
从以下版本开始:
1.4
另请参见:
Provider

getProvider

public final Provider getProvider()
返回此信息摘要对象的提供者。

返回:
此信息摘要对象的提供者。

update

public void update(byte input)
使用指定的字节更新摘要。

参数:
input - 用于更新摘要的字节。

update

public void update(byte[] input,
                   int offset,
                   int len)
使用指定的 byte 数组,从指定的偏移量开始更新摘要。

参数:
input - byte 数组。
offset - byte 数组中的偏移量,操作从此处开始。
len - 要使用的字节数,始于 offset

update

public void update(byte[] input)
使用指定的 byte 数组更新摘要。

参数:
input - byte 数组。

update

public final void update(ByteBuffer input)
使用指定的 ByteBuffer 更新摘要。使用始于 input.position() 处的 input.remaining() 个字节更新摘要。一旦返回,该缓冲区的位置将等于它的界限;它的界限将不会更改。

参数:
input - ByteBuffer
从以下版本开始:
1.5

digest

public byte[] digest()
通过执行诸如填充之类的最终操作完成哈希计算。在调用此方法之后,摘要被重置。

返回:
存放哈希值结果的 byte 数组。

digest

public int digest(byte[] buf,
                  int offset,
                  int len)
           throws DigestException
通过执行诸如填充之类的最终操作完成哈希计算。在调用此方法之后,摘要被重置。

参数:
buf - 存放计算摘要的输出缓冲区
offset - 输出缓冲区中的偏移量,从此处开始存储摘要。
len - 在 buf 中分配给摘要的字节数
返回:
放到 buf 中的字节数
抛出:
DigestException - 如果发生错误。

digest

public byte[] digest(byte[] input)
使用指定的 byte 数组对摘要进行最后更新,然后完成摘要计算。也就是说,此方法首先调用 update(input),向 update 方法传递 input 数组,然后调用 digest()

参数:
input - 在完成摘要计算前要更新的输入。
返回:
存放哈希值结果的 byte 数组。

toString

public String toString()
返回此信息摘要对象的字符串表示形式。

覆盖:
Object 中的 toString
返回:
该对象的字符串表示形式。

isEqual

public static boolean isEqual(byte[] digesta,
                              byte[] digestb)
比较两个摘要的相等性。做简单的字节比较。

参数:
digesta - 要比较的摘要之一。
digestb - 要比较的另一个摘要。
返回:
如果摘要相等,则返回 true;否则返回 false

reset

public void reset()
重置摘要以供再次使用。


getAlgorithm

public final String getAlgorithm()
返回标识算法的独立于实现细节的字符串。此名称应该是标准的 Java 安全名称(如 "SHA"、"MD5" 等等)。有关标准算法名称的信息,请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。

返回:
算法的名称

getDigestLength

public final int getDigestLength()
返回以字节为单位的摘要长度,如果提供者不支持此操作并且实现是不可复制的,则返回 0。

返回:
以字节为单位的摘要长度,如果提供者不支持此操作并且实现是不可复制的,则返回 0。
从以下版本开始:
1.2

clone

public Object clone()
             throws CloneNotSupportedException
如果实现是可复制的,则返回一个副本。

覆盖:
MessageDigestSpi 中的 clone
返回:
如果实现是可复制的,则返回一个副本。
抛出:
CloneNotSupportedException - 如果对一个不支持 Cloneable 的实现调用此方法。
另请参见:
Cloneable

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策