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 = 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
Specification |
---|
Web Cryptography API # SubtleCrypto-method-generateKey |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
generateKey |
37 |
12
["Not supported: RSA-PSS, ECDSA, ECDH.", "Not supported: AES-CTR."]
|
34 |
11
Returns
KeyOperation instead of Promise
|
24 |
7 |
37 |
37 |
34 |
24 |
7 |
6.0 |
See also
- Cryptographic key length recommendations.
- NIST cryptographic algorithm and key length recommendations.
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey