SubtleCrypto.digest()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

安全上下文: 此项功能仅在一些支持的浏览器安全上下文(HTTPS)中可用。

SubtleCrypto 接口的 digest() 方法生成给定数据的摘要。摘要是从一些可变长的输入生成的短且具有固定长度的值。密码摘要应表现出抗冲突性,这意味着很难构造出具有相同摘要值的两个不同的输入。

它以使用的摘要算法的标识符和计算摘要的数据为参数。并返回一个 Promise,会兑现数据的摘要值。

语法

js
digest(algorithm, data)

参数

algorithm

可以是一个字符串或一个仅有 name 字符串属性的对象。该字符串为使用的哈希函数的名称。支持的值有:

  • "SHA-1"(请不要在加密应用程序中使用它)
  • "SHA-256"
  • "SHA-384"
  • "SHA-512"
data

一个包含将计算摘要的数据的 ArrayBufferTypedArrayDataView 对象。

返回值

一个 Promise,会兑现一个包含摘要值的 ArrayBuffer

支持的算法

摘要算法(也称为加密哈希函数)将任意长度的数据块转换为固定长度的输出(通常比输入短得多)。其在密码学中有多种应用。

算法 输出长度(比特) 块大小(比特) 规范
SHA-1 160 512 FIPS 180-4 第 6.1 节
SHA-256 256 512 FIPS 180-4 第 6.2 节
SHA-384 384 1024 FIPS 180-4 第 6.5 节
SHA-512 512 1024 FIPS 180-4 第 6.4 节

警告: 现在,SHA-1 被认为是易受攻击的,不应将其用于加密应用程序。

备注: 如果你在寻找如何创建密钥散列消息认证码(HMAC),则需要改用 SubtleCrypto.sign() 方法。

示例

基本示例

此示例对消息进行编码,然后计算其 SHA-256 摘要,并打印摘要长度:

js
const text =
  "An obscure body in the S-K System, your majesty. The inhabitants refer to it as the planet Earth.";

async function digestMessage(message) {
  const encoder = new TextEncoder();
  const data = encoder.encode(message);
  const hash = await window.crypto.subtle.digest("SHA-256", data);
  return hash;
}

digestMessage(text).then((digestBuffer) =>
  console.log(digestBuffer.byteLength),
);

将摘要转换为十六进制字符串

摘要以 ArrayBuffer 的形式返回,但为了进行比较和显示,通常会使用十六进制(hex)字符串的形式表示。此示例计算摘要,然后将 ArrayBuffer 转换为十六进制字符串:

js
const text =
  "An obscure body in the S-K System, your majesty. The inhabitants refer to it as the planet Earth.";

async function digestMessage(message) {
  const msgUint8 = new TextEncoder().encode(message); // 编码为(utf-8)Uint8Array
  const hashBuffer = await window.crypto.subtle.digest("SHA-256", msgUint8); // 计算消息的哈希值
  const hashArray = Array.from(new Uint8Array(hashBuffer)); // 将缓冲区转换为字节数组
  const hashHex = hashArray
    .map((b) => b.toString(16).padStart(2, "0"))
    .join(""); // 将字节数组转换为十六进制字符串
  return hashHex;
}

digestMessage(text).then((digestHex) => console.log(digestHex));

规范

Specification
Web Cryptography API
# SubtleCrypto-method-digest

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
digest

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
Has more compatibility info.

备注: Chrome 60 添加了对非 TLS 连接禁用 crypto.subtle 的特性。

参见