SubtleCrypto.generateKey()

Use the generateKey() method of the SubtleCrypto interface to generate a new key (for symmetric algorithms) or key pair (for public-key algorithms).

Syntax

const result = crypto.subtle.generateKey(algorithm, extractable, keyUsages);

Parameters

• algorithm is a dictionary object defining the type of key to generate and providing extra algorithm-specific parameters.
  • For RSASSA-PKCS1-v1_5, RSA-PSS, or RSA-OAEP: pass an RsaHashedKeyGenParams object.
  • For ECDSA or ECDH: pass an EcKeyGenParams object.
  • For HMAC: pass an HmacKeyGenParams object.
  • For AES-CTR, AES-CBC, AES-GCM, or AES-KW: pass an AesKeyGenParams object.
• extractable is a Boolean indicating whether it will be possible to export  the key using SubtleCrypto.exportKey() or SubtleCrypto.wrapKey().
• keyUsages  is an Array indicating what can be done with the newly generated key. Possible values for array elements are:
  • encrypt: The key may be used to encrypt messages.
  • decrypt: The key may be used to decrypt messages.
  • sign: The key may be used to sign messages.
  • verify: The key may be used to verify signatures.
  • deriveKey: The key may be used in deriving a new key.
  • deriveBits: The key may be used in deriving bits.
  • wrapKey: The key may be used to wrap a key.
  • unwrapKey: The key may be used to unwrap a key.

Return value

• result is a Promise that fulfills with a CryptoKey (for symmetric algorithms) or a CryptoKeyPair (for public-key algorithms).

Exceptions

The promise is rejected when the following exception is encountered:

SyntaxError

Raised when the result is a CryptoKey of type secret or private but keyUsages is empty.

SyntaxError

Raised when the result is a CryptoKeyPair and its privateKey.usages attribute is empty.

Examples

RSA key pair generation

This code generates an RSA-OAEP encryption key pair. See the complete code on GitHub.

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

Elliptic curve key pair generation

This code generates an ECDSA signing key pair. See the complete code on GitHub.

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

HMAC key generation

This code generates an HMAC signing key. See the complete code on GitHub.

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

AES key generation

This code generates an AES-GCM encryption key. See the complete code on GitHub.

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

Specifications

Browser compatibility

See also

• Cryptographic key length recommendations.
• NIST cryptographic algorithm and key length recommendations.