CryptoKey

The CryptoKey interface of Azion Runtime: the key object that SubtleCrypto methods return, how a function obtains one, and its properties.

Last updated

View as Markdown Agent setup

The CryptoKey interface represents a cryptographic key that one of the SubtleCrypto methods returns. In an Azion function, a CryptoKey is the object you pass to SubtleCrypto when you encrypt, decrypt, sign, or verify data. For more information, refer to CryptoKey on MDN Web Docs.

Use a CryptoKey to hold an imported secret key that verifies signed tokens or HMAC signatures. A generated key pair can sign or encrypt payloads before they leave the function. Its usages restrict how the key applies, so a key can sign but not decrypt, for example. The function handles the key as an opaque object: the raw key material stays out of the code unless the key is extractable and you export it.

Constructor

CryptoKey has no public constructor: new CryptoKey() throws TypeError: Illegal constructor. A function obtains a key from these SubtleCrypto methods:

MethodReturns
crypto.subtle.generateKey()A new CryptoKey for a symmetric algorithm, such as AES-GCM or AES-KW. For an asymmetric algorithm, such as ECDSA, an object with a privateKey and a publicKey.
crypto.subtle.importKey()A CryptoKey built from key data you supply, such as the raw bytes of a secret.
crypto.subtle.deriveKey()A CryptoKey derived from a base key, such as an AES-GCM key derived with PBKDF2.
crypto.subtle.unwrapKey()A CryptoKey decrypted from a wrapped key, such as one wrapped with AES-KW.

Properties

The properties are read-only. They describe what the key is and which operations it may be applied to, so the runtime applies a key only to the operations it was created for:

PropertyTypeDescription
typeStringKind of key: secret for a symmetric key, private or public for one half of a key pair.
extractableBooleantrue when crypto.subtle.exportKey() or crypto.subtle.wrapKey() may export the key. The method that creates the key sets it. Exporting a key whose value is false rejects with InvalidAccessError: Key is not extractable.
algorithmObjectAlgorithm the key is used with, in name, and its parameters, such as length and hash.
usagesArray of stringsOperations the key may perform: encrypt, decrypt, sign, verify, deriveKey, deriveBits, wrapKey, and unwrapKey. The method that creates the key sets them.

Example

This handler imports a secret as an HMAC key and signs a message. It checks the signature against the message and a tampered one, then returns the results and the key properties:

JavaScript
01const enc = new TextEncoder();
02const hex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');
03
04export default {
05 async fetch(request, env, ctx) {
06 const key = await crypto.subtle.importKey('raw', enc.encode('a secret'), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
07 const sig = await crypto.subtle.sign('HMAC', key, enc.encode('Azion Functions'));
08 const ok = await crypto.subtle.verify('HMAC', key, sig, enc.encode('Azion Functions'));
09 const bad = await crypto.subtle.verify('HMAC', key, sig, enc.encode('tampered'));
10 return Response.json({
11 signatureHex: hex(sig),
12 verifies: ok,
13 rejectsTampered: !bad,
14 key: { type: key.type, extractable: key.extractable, algorithm: key.algorithm, usages: key.usages, ctor: key.constructor.name },
15 });
16 },
17};

The function returns these values. The key is a CryptoKey of type secret, and it is not extractable because importKey() received false:

JSON
01{
02 "signatureHex": "86fec9e22ad82998c7007d637f61a5206e2b64ee2a8ac2ed12f1f359e3d14bc6",
03 "verifies": true,
04 "rejectsTampered": true,
05 "key": {
06 "type": "secret",
07 "extractable": false,
08 "algorithm": {
09 "name": "HMAC",
10 "length": 64,
11 "hash": {
12 "name": "SHA-256"
13 }
14 },
15 "usages": [
16 "sign",
17 "verify"
18 ],
19 "ctor": "CryptoKey"
20 }
21}
SubtleCrypto

The methods that create a CryptoKey and the operations that use it.

Crypto

The global crypto object that gives access to SubtleCrypto.

node:crypto

The Node.js crypto module, for code written against Node.js.

Web APIs

The other Web APIs that Azion Runtime supports.