SubtleCrypto: phương thức generateKey()

Baseline Widely available *

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

* Some parts of this feature may have varying levels of support.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is available in Web Workers.

Phương thức generateKey() của giao diện SubtleCrypto được sử dụng để tạo một khóa mới (cho thuật toán đối xứng) hoặc cặp khóa (cho thuật toán khóa công khai).

Cú pháp

generateKey(algorithm, extractable, keyUsages)

Tham số

algorithm

Một đối tượng xác định loại khóa cần tạo và cung cấp các tham số bổ sung cụ thể cho thuật toán.

Đối với RSASSA-PKCS1-v1_5, RSA-PSS, hoặc RSA-OAEP: truyền một đối tượng RsaHashedKeyGenParams.
Đối với ECDSA hoặc ECDH: truyền một đối tượng EcKeyGenParams.
Đối với HMAC: truyền một đối tượng HmacKeyGenParams.
Đối với AES-CTR, AES-CBC, AES-GCM, hoặc AES-KW: truyền một đối tượng AesKeyGenParams.
Đối với Ed25519: truyền chuỗi Ed25519 hoặc một đối tượng có dạng { name: "Ed25519" }.
Đối với X25519: truyền chuỗi X25519 hoặc một đối tượng có dạng { name: "X25519" }.

extractable

Một giá trị boolean cho biết liệu có thể xuất khóa bằng SubtleCrypto.exportKey() hoặc SubtleCrypto.wrapKey() hay không. Lưu ý khi tạo cặp khóa bất đối xứng (chẳng hạn như RSA hoặc ECDSA), tham số extractable xác định liệu khóa riêng tư có thể xuất được hay không; khóa công khai luôn có thể xuất được.

keyUsages

Một Array các chuỗi cho biết những gì có thể thực hiện với khóa mới được tạo. Các giá trị có thể cho các phần tử mảng là:

encrypt: Khóa có thể được sử dụng để mã hóa thông báo.
decrypt: Khóa có thể được sử dụng để giải mã thông báo.
sign: Khóa có thể được sử dụng để ký thông báo.
verify: Khóa có thể được sử dụng để xác minh chữ ký.
deriveKey: Khóa có thể được sử dụng trong phái sinh khóa mới.
deriveBits: Khóa có thể được sử dụng trong phái sinh bit.
wrapKey: Khóa có thể được sử dụng để bọc khóa.
unwrapKey: Khóa có thể được sử dụng để mở bọc khóa.

Giá trị trả về

Một Promise được fulfill với một CryptoKey (cho thuật toán đối xứng) hoặc một CryptoKeyPair (cho thuật toán khóa công khai).

Ngoại lệ

Promise bị reject khi gặp ngoại lệ sau:

SyntaxError DOMException: Ném lên khi kết quả là một CryptoKey loại secret hoặc private nhưng keyUsages trống, hoặc không hợp lệ cho loại thuật toán.
SyntaxError DOMException: Ném lên khi kết quả là một CryptoKeyPair và thuộc tính privateKey.usages của nó trống, hoặc không hợp lệ cho loại thuật toán.

Ví dụ

Note: Bạn có thể thử các ví dụ hoạt động trên GitHub.

Tạo cặp khóa RSA

Đoạn mã này tạo một cặp khóa mã hóa RSA-OAEP. Xem mã đầy đủ trên 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"],
);

Tạo cặp khóa đường cong elliptic

Đoạn mã này tạo một cặp khóa ký ECDSA. Xem mã đầy đủ trên GitHub.

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

Tạo khóa HMAC

Đoạn mã này tạo một khóa ký HMAC. Xem mã đầy đủ trên GitHub.

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

Tạo khóa AES

Đoạn mã này tạo một khóa mã hóa AES-GCM. Xem mã đầy đủ trên GitHub.

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

Tạo khóa Ed25519

Đoạn mã này tạo một cặp khóa ký Ed25519. Nó được dẫn xuất từ mã nguồn này trên GitHub, mà bạn có thể chạy trực tiếp tại đây.

<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

Mã tạo cặp khóa bằng thuật toán Ed25519 và ghi log thông tin trong mỗi khóa được hiển thị bên dưới. Lưu ý rằng mã được chạy trong khối try..catch vì không phải tất cả trình duyệt đều hỗ trợ thuật toán này.

JavaScript đầu tiên lấy các phần tử <input> #sign-button và #message, sau đó thêm trình lắng nghe cho sự kiện click trên nút. Trình xử lý sự kiện xóa log và chạy các thao tác khác truyền nội dung của phần tử <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);
  }
}

Kết quả

Thông tin về các khóa được tạo được ghi log bên dưới (hoặc một chuỗi lỗi nếu trình duyệt không cho phép tạo khóa).

Tạo khóa X25519

Đoạn mã này tạo một cặp khóa công khai và khóa riêng tư X25519 có thể sử dụng trong SubtleCrypto.deriveKey() để tạo khóa chia sẻ, hoặc trong SubtleCrypto.deriveBits() để tạo bí mật chia sẻ.

<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

Mã tạo cặp khóa bằng thuật toán X25519 và ghi log thông tin trong mỗi khóa được hiển thị bên dưới. Lưu ý rằng mã được chạy trong khối try..catch vì không phải tất cả trình duyệt đều hỗ trợ thuật toán này.

JavaScript đầu tiên lấy các phần tử <input> #run-button và #log, sau đó thêm trình lắng nghe cho sự kiện click trên nút. Trình xử lý sự kiện xóa log, tạo cặp khóa X25519, và ghi log một số thuộc tính của nó.

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);
  }
}

Kết quả

Thông tin về các khóa được tạo được ghi log bên dưới (hoặc một chuỗi lỗi nếu trình duyệt không cho phép tạo khóa).

Đặc tả kỹ thuật

Thông số kỹ thuật
Web Cryptography Level 2 # SubtleCrypto-method-generateKey

Tương thích trình duyệt

Xem thêm

Help improve MDN

Tìm hiểu cách đóng góp

This page was last modified on Jan 1, 1970 by MDN contributors.

Xem trang này trên GitHub • Báo cáo sự cố với nội dung này