SubtleCrypto: generateKey() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Note: This feature is available in Web Workers.
The generateKey()
method of the SubtleCrypto
interface is used to generate a new key (for symmetric algorithms) or key pair (for public-key algorithms).
Syntax
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 Ed25519: pass the string
Ed25519
or an object of the form{ name: "Ed25519" }
. - For X25519: pass the string
X25519
or an object of the form{ name: "X25519" }
.
-
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
of strings 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
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, or invalid for the algorithm type. SyntaxError
DOMException
-
Raised when the result is a
CryptoKeyPair
and itsprivateKey.usages
attribute is empty, or invalid for the algorithm type.
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"],
);
Ed25519 key generation
This code generates an Ed25519 signing key pair. It is derived from this source code on GitHub, which you can run live here.
JavaScript
Code for generating a key pair using the Ed25519
algorithm and logging the information in each key is shown below.
Note that the code is run in a try..catch
block because not all browsers support this algorithm.
The JavaScript first gets the #sign-button
and #message
<input>
elements, then adds a listener for the click
event on the button.
The event handler clears the log and runs the other operations passing the content of the <input>
element.
const button = document.querySelector("#run-button");
const input = document.querySelector("#log");
button.addEventListener("click", () => {
// Clear log
logElement.innerText = "";
logElement.scrollTop = logElement.scrollHeight;
// Run test
test();
});
async function test() {
try {
// Create a key pair and use destructuring assignment to assign to variables
const { publicKey, privateKey } = await crypto.subtle.generateKey(
{
name: "Ed25519",
},
true,
["sign", "verify"],
);
// Log the properties of the keys
log(`publicKey: ${publicKey}`);
log(` type: ${publicKey.type}`);
log(` extractable: ${publicKey.extractable}`);
log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
log(` usages: ${publicKey.usages}`);
log(`privateKey: ${privateKey}`);
log(` type: ${privateKey.type}`);
log(` extractable: ${privateKey.extractable}`);
log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
log(` usages: ${privateKey.usages}`);
} catch (error) {
log(error);
}
}
Result
The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
X25519 key generation
This code generates an X25519 public and private key pair that can be used in SubtleCrypto.deriveKey()
to create a shared key, or in SubtleCrypto.deriveBits()
to create a shared secret.
JavaScript
Code for generating a key pair using the X25519
algorithm and logging the information in each key is shown below.
Note that the code is run in a try..catch
block because not all browsers support this algorithm.
The JavaScript first gets the #run-button
and #log
<input>
elements, then adds a listener for the click
event on the button.
The event handler clears the log, generates an X25519 key pair, and logs some of its properties.
const button = document.querySelector("#run-button");
const input = document.querySelector("#log");
button.addEventListener("click", () => {
// Clear log
logElement.innerText = "";
logElement.scrollTop = logElement.scrollHeight;
// Run test
test();
});
async function test() {
try {
// Create a key pair and use destructuring assignment to assign to variables
const { publicKey, privateKey } = await crypto.subtle.generateKey(
{
name: "X25519",
},
true,
["deriveKey", "deriveBits"],
);
// Log the properties of the keys
log(`publicKey: ${publicKey}`);
log(` type: ${publicKey.type}`);
log(` extractable: ${publicKey.extractable}`);
log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
log(` usages: ${publicKey.usages}`);
log(`privateKey: ${privateKey}`);
log(` type: ${privateKey.type}`);
log(` extractable: ${privateKey.extractable}`);
log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
log(` usages: ${privateKey.usages}`);
} catch (error) {
log(error);
}
}
Result
The information about the created keys is logged below (or an error string if the browser does not allow the key to be created).
Specifications
Specification |
---|
Web Cryptography API # SubtleCrypto-method-generateKey |
Browser compatibility
BCD tables only load in the browser