SubtleCrypto: метод generateKey()

Метод generateKey() интерфейса SubtleCrypto используется для генерации нового ключа (для симметричных алгоритмов) или пары ключей (для алгоритмов с открытым ключом).

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

Массив строк, указывающих, что можно сделать с новым сгенерированным ключом. Возможные значения элементов массива:

encrypt

Ключ может быть использован для шифрования сообщений.

decrypt

Ключ может быть использован для дешифрования сообщений.

sign

Ключ может быть использован для подписи сообщений.

verify

Ключ может быть использован для проверки подписей.

deriveKey

Ключ может быть использован для вывода нового ключа.

deriveBits

Ключ может быть использован для вывода битов.

wrapKey

Ключ может быть использован для обертывания ключа.

unwrapKey

Ключ может быть использован для развертывания ключа.

Объект Promise, который возвращает CryptoKey (для симметричных алгоритмов) или CryptoKeyPair (для алгоритмов с открытым ключом).

Обещание отклоняется, когда возникает следующая ошибка:

SyntaxError DOMException

Возникает, когда результатом является CryptoKey типа secret или private, но keyUsages пусто или неверно для типа алгоритма.

SyntaxError DOMException

Возникает, когда результатом является CryptoKeyPair, и его атрибут privateKey.usages пуст или неверен для типа алгоритма.

Этот код генерирует пару ключей для шифрования 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. Посмотрите полный код на GitHub.

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

Этот код генерирует ключ для шифрования AES-GCM. Посмотрите полный код на GitHub.

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

Этот код генерирует пару ключей для подписи Ed25519. Он взят из исходного кода на GitHub, который можно запустить онлайн.

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, которые могут быть использованы в SubtleCrypto.deriveKey() для создания общего ключа или в SubtleCrypto.deriveBits() для создания общего секрета.

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

Результат

Информация о созданных ключах будет выведена ниже (или строка ошибки, если браузер не разрешает создание ключа).

• Рекомендации по длине криптографических ключей.
• Переход NIST к использованию криптографических алгоритмов и длин ключей.