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 aBoolean
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 | Status | Comment |
---|---|---|
Web Cryptography API The definition of 'SubtleCrypto.generateKey()' in that specification. |
Recommendation | Initial definition. |
Browser compatibility
BCD tables only load in the browser