SubtleCrypto: generateKey() 方法

Baseline 廣泛可用 *

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

* 此特性的某些部分可能存在不同級別的支援。

安全上下文： 此功能僅在安全上下文（HTTPS）中可用，且支援此功能的瀏覽器數量有限。

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

SubtleCrypto 介面的 generateKey() 方法用於生成一個新的金鑰（用於對稱演算法）或金鑰對（用於公鑰演算法）。

語法

generateKey(algorithm, extractable, keyUsages)

引數

algorithm

一個定義要生成的金鑰型別並提供額外的演算法特定引數的物件。

對於 RSASSA-PKCS1-v1_5、RSA-PSS 或 RSA-OAEP：傳遞一個 RsaHashedKeyGenParams 物件。
對於 ECDSA 或 ECDH：傳遞一個 EcKeyGenParams 物件。
對於 HMAC：傳遞一個 HmacKeyGenParams 物件。
對於 AES-CTR、AES-CBC、AES-GCM 或 AES-KW：傳遞一個 AesKeyGenParams 物件。
對於 Ed25519：傳遞字串 Ed25519 或形式為 { name: "Ed25519" } 的物件。
對於 X25519：傳遞字串 X25519 或形式為 { name: "X25519" } 的物件。

extractable

一個布林值，指示是否可以使用 SubtleCrypto.exportKey() 或 SubtleCrypto.wrapKey() 匯出金鑰。

keyUsages

一個 Array，其中包含指示新生成的金鑰可以執行的操作的字串。陣列元素的可能值為

encrypt: 金鑰可用於加密訊息。
decrypt: 金鑰可用於解密訊息。
符號: 金鑰可用於簽名訊息。
verify: 金鑰可用於驗證簽名。
deriveKey: 金鑰可用於派生新金鑰。
deriveBits: 金鑰可用於派生位。
wrapKey: 金鑰可用於包裝金鑰。
unwrapKey: 金鑰可用於解包裝金鑰。

返回值

一個 Promise，它將以 CryptoKey（用於對稱演算法）或 CryptoKeyPair（用於公鑰演算法）進行解析。

異常

當遇到以下異常時，Promise 將被拒絕

SyntaxError DOMException: 當結果是型別為 secret 或 private 的 CryptoKey，但 keyUsages 為空或對於演算法型別無效時，將丟擲此異常。
SyntaxError DOMException: 當結果是 CryptoKeyPair 且其 privateKey.usages 屬性為空或對於演算法型別無效時，將丟擲此異常。

示例

注意：您可以在 GitHub 上嘗試工作示例。

RSA 金鑰對生成

此程式碼生成一個 RSA-OAEP 加密金鑰對。在 GitHub 上檢視完整程式碼。

let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "RSA-OAEP",
    modulusLength: 4096,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["encrypt", "decrypt"],
);

橢圓曲線金鑰對生成

此程式碼生成一個 ECDSA 簽名金鑰對。在 GitHub 上檢視完整程式碼。

let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "ECDSA",
    namedCurve: "P-384",
  },
  true,
  ["sign", "verify"],
);

HMAC 金鑰生成

此程式碼生成一個 HMAC 簽名金鑰。在 GitHub 上檢視完整程式碼。

let key = await window.crypto.subtle.generateKey(
  {
    name: "HMAC",
    hash: { name: "SHA-512" },
  },
  true,
  ["sign", "verify"],
);

AES 金鑰生成

此程式碼生成一個 AES-GCM 加密金鑰。在 GitHub 上檢視完整程式碼。

let key = await window.crypto.subtle.generateKey(
  {
    name: "AES-GCM",
    length: 256,
  },
  true,
  ["encrypt", "decrypt"],
);

Ed25519 金鑰生成

此程式碼生成一個 Ed25519 簽名金鑰對。它源自 GitHub 上的此原始碼，您可以在此處即時執行。

<input id="run-button" type="button" value="Run" />
<pre id="log">Click "Run" button</pre>

#log {
  height: 170px;
  white-space: pre-wrap; /* wrap pre blocks */
  overflow-wrap: break-word; /* break on words */
  overflow-y: auto;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

下面顯示了使用 Ed25519 演算法生成金鑰對並記錄每個金鑰資訊的程式碼。請注意，程式碼執行在 try..catch 塊中，因為並非所有瀏覽器都支援此演算法。

JavaScript 首先獲取 #sign-button 和 #message <input> 元素，然後為按鈕的 click 事件新增一個監聽器。事件處理程式會清除日誌並執行其他操作，傳遞 <input> 元素的內容。

const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "Ed25519",
      },
      true,
      ["sign", "verify"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

結果

有關建立的金鑰的資訊將記錄在下方（如果瀏覽器不允許建立金鑰，則顯示錯誤字串）。

X25519 金鑰生成

此程式碼生成一個 X25519 公鑰和私鑰對，可用於 SubtleCrypto.deriveKey() 建立共享金鑰，或用於 SubtleCrypto.deriveBits() 建立共享金鑰。

<input id="run-button" type="button" value="Run" />
<pre id="log">Click "Run" button</pre>

#log {
  height: 170px;
  white-space: pre-wrap; /* wrap pre blocks */
  overflow-wrap: break-word; /* break on words */
  overflow-y: auto;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

下面顯示了使用 X25519 演算法生成金鑰對並記錄每個金鑰資訊的程式碼。請注意，程式碼執行在 try..catch 塊中，因為並非所有瀏覽器都支援此演算法。

JavaScript 首先獲取 #run-button 和 #log <input> 元素，然後為按鈕的 click 事件新增一個監聽器。事件處理程式會清除日誌，生成一個 X25519 金鑰對，並記錄其一些屬性。

const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "X25519",
      },
      true,
      ["deriveKey", "deriveBits"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

結果

有關建立的金鑰的資訊將記錄在下方（如果瀏覽器不允許建立金鑰，則顯示錯誤字串）。

規範

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

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ⁨2025 年 6 月 23 日⁩，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的某個問題