SubtleCrypto: generateKey() method
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
js
generateKey(algorithm, extractable, keyUsages)
Parameters
algorithm
-
An 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
-
A boolean value indicating whether it will be possible to export the key using
SubtleCrypto.exportKey()
orSubtleCrypto.wrapKey()
. keyUsages
-
An
Array
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
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
DOMException
-
Raised when the result is a
CryptoKey
of typesecret
orprivate
butkeyUsages
is empty. SyntaxError
DOMException
-
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.
js
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.
js
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.
js
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.
js
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