SubtleCrypto: deriveKey() 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.
The deriveKey()
method of the SubtleCrypto
interface can be used to derive a secret key from a master key.
It takes as arguments some initial key material, the derivation algorithm to use, and the desired properties for the key to derive.
It returns a Promise
which will be fulfilled with a CryptoKey
object representing the new key.
It's worth noting that the supported key derivation algorithms have quite different characteristics and are appropriate in quite different situations. See Supported algorithms for some more detail on this.
Syntax
deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)
Parameters
algorithm

An object defining the derivation algorithm to use.
 To use ECDH, pass an
EcdhKeyDeriveParams
object, specifying the stringECDH
as thename
property.  To use HKDF, pass an
HkdfParams
object.  To use X25519, pass an
EcdhKeyDeriveParams
object, specifying the stringX25519
as thename
property.
 To use ECDH, pass an
baseKey

A
CryptoKey
representing the input to the derivation algorithm. Ifalgorithm
is ECDH or X25519, then this will be the ECDH or X25519 private key. Otherwise it will be the initial key material for the derivation function: for example, for PBKDF2 it might be a password, imported as aCryptoKey
usingSubtleCrypto.importKey()
. derivedKeyAlgorithm

An object defining the algorithm the derived key will be used for:
 For HMAC pass an
HmacKeyGenParams
object.  For AESCTR, AESCBC, AESGCM, or AESKW, pass an
AesKeyGenParams
object.  For HKDF, pass an
HkdfParams
object.  For PBKDF2, pass a
Pbkdf2Params
object.
 For HMAC 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 derived key. Note that the key usages must be allowed by the algorithm set inderivedKeyAlgorithm
. Possible values of the array 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
Exceptions
The promise is rejected when one of the following exceptions are encountered:
InvalidAccessError
DOMException

Raised when the master key is not a key for the requested derivation algorithm or if the
keyUsages
value of that key doesn't containderiveKey
. NotSupported
DOMException

Raised when trying to use an algorithm that is either unknown or isn't suitable for derivation, or if the algorithm requested for the derived key doesn't define a key length.
SyntaxError
DOMException

Raised when
keyUsages
is empty but the unwrapped key is of typesecret
orprivate
.
Supported algorithms
The algorithms supported by deriveKey()
have quite different characteristics and are appropriate in different situations.
Key derivation algorithms
HKDF
HKDF is a key derivation function. It's designed to derive key material from some highentropy input, such as the output of an ECDH key agreement operation.
It's not designed to derive keys from relatively lowentropy inputs such as passwords. For that, use PBKDF2.
HKDF is specified in RFC 5869.
PBKDF2
PBKDF2 is also a key derivation function. It's designed to derive key material from some relatively lowentropy input, such as a password. It derives key material by applying a function such as HMAC to the input password along with some salt, and repeating this process many times. The more times the process is repeated, the more computationally expensive key derivation is: this makes it harder for an attacker to use bruteforce to discover the key using a dictionary attack.
PBKDF2 is specified in RFC 2898.
Key agreement algorithms
ECDH
ECDH (Elliptic Curve DiffieHellman) is a keyagreement algorithm. It enables two people who each have an ECDH public/private key pair to generate a shared secret: that is, a secret that they — and no one else — share. They can then use this shared secret as a symmetric key to secure their communication, or can use the secret as an input to derive such a key (for example, using the HKDF algorithm).
ECDH is specified in RFC 6090.
X25519
X25519 is a key agreement algorithm like ECDH, but built on the Curve25519 elliptic curve, which is part of the EdwardsCurve Digital Signature Algorithm (EdDSA) family of algorithms defined in RFC 8032.
The Curve25519 algorithms are widely used in cryptography, and are considered to be some of the most efficient/fast available. By comparison with the NIST (National Institute of Standards and Technology) curve key exchange algorithms used with ECDH, Curve25519 is simpler to implement, and its nongovernmental origin means that the decisions behind its design choices are transparent and open.
X25519 is specified in RFC 7748.
Examples
Note: You can try the working examples on GitHub.
ECDH: derive shared secret key
In this example Alice and Bob each generate an ECDH key pair, then exchange public keys.
They then use deriveKey()
to derive a shared AES key, that they could use to encrypt messages.
See the complete code on GitHub.
/*
Derive an AES key, given:
 our ECDH private key
 their ECDH public key
*/
function deriveSecretKey(privateKey, publicKey) {
return window.crypto.subtle.deriveKey(
{
name: "ECDH",
public: publicKey,
},
privateKey,
{
name: "AESGCM",
length: 256,
},
false,
["encrypt", "decrypt"],
);
}
async function agreeSharedSecretKey() {
// Generate 2 ECDH key pairs: one for Alice and one for Bob
// In more normal usage, they would generate their key pairs
// separately and exchange public keys securely
let alicesKeyPair = await window.crypto.subtle.generateKey(
{
name: "ECDH",
namedCurve: "P384",
},
false,
["deriveKey"],
);
let bobsKeyPair = await window.crypto.subtle.generateKey(
{
name: "ECDH",
namedCurve: "P384",
},
false,
["deriveKey"],
);
// Alice then generates a secret key using her private key and Bob's public key.
let alicesSecretKey = await deriveSecretKey(
alicesKeyPair.privateKey,
bobsKeyPair.publicKey,
);
// Bob generates the same secret key using his private key and Alice's public key.
let bobsSecretKey = await deriveSecretKey(
bobsKeyPair.privateKey,
alicesKeyPair.publicKey,
);
// Alice can then use her copy of the secret key to encrypt a message to Bob.
let encryptButton = document.querySelector(".ecdh .encryptbutton");
encryptButton.addEventListener("click", () => {
encrypt(alicesSecretKey);
});
// Bob can use his copy to decrypt the message.
let decryptButton = document.querySelector(".ecdh .decryptbutton");
decryptButton.addEventListener("click", () => {
decrypt(bobsSecretKey);
});
}
X25519: derive shared secret key
In this example Alice and Bob each generate an X25519 key pair, then exchange public keys.
They then each use deriveKey()
to derive a shared AES key from their own private key and each other's public key.
They can use this shared key to encrypt and decrypt messages they exchange.
HTML
First we define an HTML <input>
that you will use to enter the plaintext message that "Alice" will send, and a button that you can click to start the encryption process.
<label for="message">Plaintext message from Alice (Enter):</label>
<input
type="text"
id="message"
name="message"
size="50"
value="The lion roars near dawn" />
<input id="encryptbutton" type="button" value="Encrypt" />
This is followed by another two elements for displaying the ciphertext after Alice has encrypted the plaintext with her copy of the secret key, and for displaying the text after Bob has decrypted it with his copy of the secret key.
<div id="results">
<label for="encrypted">Encrypted (Alice)</label>
<input
type="text"
id="encrypted"
name="encrypted"
size="30"
value=""
readonly />
<label for="results">Decrypted (Bob)</label>
<input
type="text"
id="decrypted"
name="decrypted"
size="50"
value=""
readonly />
</div>
JavaScript
The code below shows how we use deriveKey()
.
We pass in the remote party's X25519 public key, the local party's X25519 private key, and specify that the derived key should be an AESGCM key.
We also set the derived key to be nonextractable, and suitable for encryption and decryption.
We use this function further down in the code to create shared keys for Bob and Alice.
/*
Derive an AESGCM key, given:
 our X25519 private key
 their X25519 public key
*/
function deriveSecretKey(privateKey, publicKey) {
return window.crypto.subtle.deriveKey(
{
name: "X25519",
public: publicKey,
},
privateKey,
{
name: "AESGCM",
length: 256,
},
false,
["encrypt", "decrypt"],
);
}
Next we define the functions that Alice will use to UTF8 encode and then encrypt her plaintext message, and that Bob will use to decrypt and then decode the message. They both take as arguments the shared AES key, an initialization vector, and the text to be encrypted or decrypted.
The same initialization vector must be used for encryption and decryption, but it does not need to be secret, so usually it is sent alongside the encrypted message. In this case, though, since we're not actually sending a message, we just make it directly available.
async function encryptMessage(key, initializationVector, message) {
try {
const encoder = new TextEncoder();
encodedMessage = encoder.encode(message);
// iv will be needed for decryption
return await window.crypto.subtle.encrypt(
{ name: "AESGCM", iv: initializationVector },
key,
encodedMessage,
);
} catch (e) {
console.log(e);
return `Encoding error`;
}
}
async function decryptMessage(key, initializationVector, ciphertext) {
try {
const decryptedText = await window.crypto.subtle.decrypt(
// The iv value must be the same as that used for encryption
{ name: "AESGCM", iv: initializationVector },
key,
ciphertext,
);
const utf8Decoder = new TextDecoder();
return utf8Decoder.decode(decryptedText);
} catch (e) {
console.log(e);
return "Decryption error";
}
}
The agreeSharedSecretKey()
function below is called on loading to generate pairs and shared keys for Alice and Bob.
It also adds a click handler for the "Encrypt" button that will trigger encryption and then decryption of the text defined in the first <input>
.
Note that all the code is inside a try...catch
handler, to ensure that we can log the case where key generation fails because the X25519 algorithm is not supported.
async function agreeSharedSecretKey() {
try {
// Generate 2 X25519 key pairs: one for Alice and one for Bob
// In more normal usage, they would generate their key pairs
// separately and exchange public keys securely
const alicesKeyPair = await window.crypto.subtle.generateKey(
{
name: "X25519",
},
false,
["deriveKey"],
);
log(
`Created Alices's key pair: (algorithm: ${JSON.stringify(
alicesKeyPair.privateKey.algorithm,
)}, usages: ${alicesKeyPair.privateKey.usages})`,
);
const bobsKeyPair = await window.crypto.subtle.generateKey(
{
name: "X25519",
},
false,
["deriveKey"],
);
log(
`Created Bob's key pair: (algorithm: ${JSON.stringify(
bobsKeyPair.privateKey.algorithm,
)}, usages: ${bobsKeyPair.privateKey.usages})`,
);
// Alice then generates a secret key using her private key and Bob's public key.
const alicesSecretKey = await deriveSecretKey(
alicesKeyPair.privateKey,
bobsKeyPair.publicKey,
);
log(
`alicesSecretKey: ${alicesSecretKey.type} (algorithm: ${JSON.stringify(
alicesSecretKey.algorithm,
)}, usages: ${alicesSecretKey.usages}), `,
);
// Bob generates the same secret key using his private key and Alice's public key.
const bobsSecretKey = await deriveSecretKey(
bobsKeyPair.privateKey,
alicesKeyPair.publicKey,
);
log(
`bobsSecretKey: ${bobsSecretKey.type} (algorithm: ${JSON.stringify(
bobsSecretKey.algorithm,
)}, usages: ${bobsSecretKey.usages}), \n`,
);
// Get access for the encrypt button and the three inputs
const encryptButton = document.querySelector("#encryptbutton");
const messageInput = document.querySelector("#message");
const encryptedInput = document.querySelector("#encrypted");
const decryptedInput = document.querySelector("#decrypted");
encryptButton.addEventListener("click", async () => {
log(`Plaintext: ${messageInput.value}`);
// Define the initialization vector used when encrypting and decrypting.
// This must be regenerated for every message!
const initializationVector = window.crypto.getRandomValues(
new Uint8Array(8),
);
// Alice can use her copy of the shared key to encrypt the message.
const encryptedMessage = await encryptMessage(
alicesSecretKey,
initializationVector,
messageInput.value,
);
// We then display part of the encrypted buffer and log the encrypted message
let buffer = new Uint8Array(encryptedMessage, 0, 5);
encryptedInput.value = `${buffer}...[${encryptedMessage.byteLength} bytes total]`;
log(
`encryptedMessage: ${buffer}...[${encryptedMessage.byteLength} bytes total]`,
);
// Bob uses his shared secret key to decrypt the message.
const decryptedCiphertext = await decryptMessage(
bobsSecretKey,
initializationVector,
encryptedMessage,
);
decryptedInput.value = decryptedCiphertext;
log(`decryptedCiphertext: ${decryptedCiphertext}\n`);
});
} catch (e) {
log(e);
}
}
// Finally we call the method to set the example running.
agreeSharedSecretKey();
Result
Press the Encrypt button to encrypt the text in the top <input>
element, displaying the encrypted ciphertext and decrypted ciphertext in the following two elements.
The log area at the bottom provides information about the keys that are generated by the code.
PBKDF2: derive AES key from password
In this example we ask the user for a password, then use it to derive an AES key using PBKDF2, then use the AES key to encrypt a message. See the complete code on GitHub.
/*
Get some key material to use as input to the deriveKey method.
The key material is a password supplied by the user.
*/
function getKeyMaterial() {
const password = window.prompt("Enter your password");
const enc = new TextEncoder();
return window.crypto.subtle.importKey(
"raw",
enc.encode(password),
"PBKDF2",
false,
["deriveBits", "deriveKey"],
);
}
async function encrypt(plaintext, salt, iv) {
const keyMaterial = await getKeyMaterial();
const key = await window.crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: 100000,
hash: "SHA256",
},
keyMaterial,
{ name: "AESGCM", length: 256 },
true,
["encrypt", "decrypt"],
);
return window.crypto.subtle.encrypt({ name: "AESGCM", iv }, key, plaintext);
}
HKDF: derive AES key from shared secret
In this example, we encrypt a message plainText
given a shared secret secret
, which might itself have been derived using an algorithm such as ECDH.
Instead of using the shared secret directly, we use it as key material for the HKDF function, to derive an AESGCM encryption key, which we then use to encrypt the message.
See the complete code on GitHub.
/*
Given some key material and some random salt,
derive an AESGCM key using HKDF.
*/
function getKey(keyMaterial, salt) {
return window.crypto.subtle.deriveKey(
{
name: "HKDF",
salt: salt,
info: new TextEncoder().encode("Encryption example"),
hash: "SHA256",
},
keyMaterial,
{ name: "AESGCM", length: 256 },
true,
["encrypt", "decrypt"],
);
}
async function encrypt(secret, plainText) {
const message = {
salt: window.crypto.getRandomValues(new Uint8Array(16)),
iv: window.crypto.getRandomValues(new Uint8Array(12)),
};
const key = await getKey(secret, message.salt);
message.ciphertext = await window.crypto.subtle.encrypt(
{
name: "AESGCM",
iv: message.iv,
},
key,
plainText,
);
return message;
}
Specifications
Specification 

Web Cryptography API # SubtleCryptomethodderiveKey 
Browser compatibility
BCD tables only load in the browser