SubtleCrypto: digest() 方法

Baseline 已廣泛支援

此特性已相當成熟,可在許多裝置和瀏覽器版本上使用。自 ⁨2020 年 1 月⁩ 起,所有主流瀏覽器均已支援。

安全上下文: 此功能僅在安全上下文(HTTPS)中可用,且支援此功能的瀏覽器數量有限。

注意:此功能在 Web Workers 中可用。

digest() 方法是 SubtleCrypto 介面的一個方法,它使用指定的 雜湊函式 為給定的資料生成一個摘要。摘要是從可變長度輸入派生出的短的固定長度值。加密摘要應具有抗碰撞性,意味著很難找到兩個不同的輸入產生相同的摘要值。

它接受兩個引數:用於指定摘要演算法的識別符號和需要進行摘要的資料。它返回一個 Promise,該 Promise 將在摘要生成後解析(fulfilled)。

請注意,此 API 不支援流式輸入:在將輸入傳遞給 digest 函式之前,必須將整個輸入讀入記憶體。

語法

js
digest(algorithm, data)

引數

algorithm

這可以是一個字串,或者一個具有單個名為 name 的字串屬性的物件。該字串用於指定要使用的雜湊函式。支援的值有:

  • "SHA-1" (但在加密應用中不應使用此值)
  • "SHA-256"
  • "SHA-384"
  • "SHA-512".
data

包含要摘要的資料的 ArrayBufferTypedArrayDataView 物件。

返回值

一個 Promise,它會解析(fulfill)為一個包含摘要的 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()

示例

有關使用 digest() API 的更多示例,請參閱 SubtleCrypto 的非加密用途

基本示例

此示例對訊息進行編碼,然後計算其 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 返回,但為了進行比較和顯示,摘要通常表示為十六進位制字串。此示例計算一個摘要,然後將 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); // encode as (utf-8) Uint8Array
  const hashBuffer = await window.crypto.subtle.digest("SHA-256", msgUint8); // hash the message
  const hashArray = Array.from(new Uint8Array(hashBuffer)); // convert buffer to byte array
  const hashHex = hashArray
    .map((b) => b.toString(16).padStart(2, "0"))
    .join(""); // convert bytes to hex string
  return hashHex;
}

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

規範

規範
Web 加密級別 2
# SubtleCrypto-method-digest

瀏覽器相容性

另見