SubtleCrypto.generateKey()
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
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.
-
For RSASSA-PKCS1-v1_5, RSA-PSS, or RSA-OAEP: pass an
-
extractable
is a boolean value indicating whether it will be possible to export the key usingSubtleCrypto.exportKey()
orSubtleCrypto.wrapKey()
. -
keyUsages
is anArray
indicating what can be done with the newly generated key. Possible values for array elements are:encrypt
: The key may be used toencrypt
messages.decrypt
: The key may be used todecrypt
messages.sign
: The key may be used tosign
messages.verify
: The key may be used toverify
signatures.-
deriveKey
: The key may be used inderiving a new key
. -
deriveBits
: The key may be used inderiving bits
. wrapKey
: The key may be used towrap a key
.-
unwrapKey
: The key may be used tounwrap a key
.
Return value
-
result
is aPromise
that fulfills with aCryptoKey
(for symmetric algorithms) or aCryptoKeyPair
(for public-key algorithms).
Exceptions
The promise is rejected when the following exception is encountered:
SyntaxError
-
Raised when the result is a
CryptoKey
of typesecret
orprivate
butkeyUsages
is empty. SyntaxError
-
Raised when the result is a
CryptoKeyPair
and itsprivateKey.usages
attribute is empty.
Examples
Note: You can try the working examples on GitHub.
RSA key pair generation
This code generates an RSA-OAEP encryption key pair. See the complete code on 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"]
);
Elliptic curve key pair generation
This code generates an ECDSA signing key pair. See the complete code on GitHub.
let keyPair = await 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 = await 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 = await window.crypto.subtle.generateKey(
{
name: "AES-GCM",
length: 256
},
true,
["encrypt", "decrypt"]
);
Specifications
Specification |
---|
Web Cryptography API # SubtleCrypto-method-generateKey |
Browser compatibility
BCD tables only load in the browser