Simple HPKE

Hybrid Public Key Encryption (RFC 9180)

1 dependency -- uint8arrays.

On every create/encrypt call, we generate a fresh ephemeral X25519 keypair, do Diffie-Hellman against the recipient public key, and the key schedule derives an AES-256-GCM key from that shared secret.

That DH-derived key is the wrapping key. The AES key the API hands back is a second, independently random key, and the wrapping key encrypts its raw bytes. Key wrapping here just means "HPKE seal where the plaintext happens to be 16 or 32 bytes of key material." The RFC doesn't care what the plaintext is.

• Install
• Examples
  • Key Wrapping
  • Hybrid Encryption
    • Encrypt / Decrypt
      • encrypt
      • encrypt.asString
      • decrypt
      • decrypt.asString
      • decrypt.fromString
• Extractable keys
• keyId
• Errors
• Modules
  • ESM
  • Common JS
  • pre-built JS
    • copy
    • HTML

Install

npm i -S simple-hpke

Examples

Create an AES key, or encrypt a message.

Key Wrapping

Encrypt an AES key, then recover it later.

import { create, encryptKey, open } from 'simple-hpke'

// An X25519 keypair. (asymmetric keypair).
// The private key can be non-extractable.
// HPKE only needs `deriveBits`.
const keypair = await crypto.subtle.generateKey(
    { name: 'X25519' },
    false,  // not extractable
    ['deriveBits']
)

// Create a new AES key and encrypt it to your public key.
// `key` is the unencrypted new AES key
// `wrapped` is the AES key encrypted to the given public key
const { wrapped, key } = await create(keypair.publicKey)  // or bytes or string

// `key` is non-extractable by default. It still encrypts and decrypts;
// it just cannot be exported. Pass `{ extractable: true }` if you need
// the raw bytes. See [Extractable keys](#extractable-keys).

//
// Or wrap an existing AES key. The supplied AES key must be extractable.
//
const aesKey = await crypto.subtle.generateKey(
    { name: 'AES-GCM', length: 256 },
    true,  // extractable -- its raw bytes are what get sealed
    ['encrypt', 'decrypt']
)

// Wrap the existing key.
const { wrapped: wrappedKey } = await encryptKey(keypair, aesKey)

// or pass in just a public key

// Later, recover the same key with your private key.
const recoveredKey = await open(keypair, wrappedKey)

// `recoveredKey` is equal to `aesKey`

Hybrid Encryption

Encrypt a message with AES-GCM, then encrypt the AES key to a given public key. The encrypted key is concattenated with the cipher text, along with the IV. The recipient uses their private key to open the AES key and decrypt the message.

import { create, open } from 'simple-hpke'

const recipient = await crypto.subtle.generateKey(
    { name: 'X25519' },
    false,  // not extractable
    ['deriveBits']
)

// Create a fresh AES-GCM key, and encrypt a message with it.
const { wrapped, key } = await create(recipient)
const iv = crypto.getRandomValues(new Uint8Array(12))
const ciphertextBuffer = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv },
    key,
    new TextEncoder().encode('attack at dawn')
)

// Send `wrapped`, `iv`, and `ciphertext` together. `create(...)` defaults
// to a 256-bit AES key, so `wrapped.length` is 80 bytes in this example.
//
// If your protocol allows different wrapped-key sizes, prefix
// `wrapped.length` (or otherwise transmit it) so the recipient can split
// the payload safely.
const ciphertext = new Uint8Array(ciphertextBuffer)
const wrappedLength = wrapped.length
const message = new Uint8Array(
    wrappedLength + iv.length + ciphertext.length
)
message.set(wrapped, 0)
message.set(iv, wrappedLength)
message.set(ciphertext, wrappedLength + iv.length)

// On the other side, split the payload back into its parts.
const wrapped2 = message.subarray(0, wrappedLength)
const iv2 = message.subarray(wrappedLength, wrappedLength + 12)
const ciphertext2 = message.subarray(wrappedLength + 12)

// Recover the key, then decrypt the message.
const recovered = await open(recipient, wrapped2)
const plaintext = await crypto.subtle.decrypt(
    { name: 'AES-GCM', iv: iv2 },
    recovered,
    ciphertext2
)

new TextDecoder().decode(plaintext)  // => 'attack at dawn'

Encrypt / Decrypt

So that was a lot of code to encrypt and decrypt a message... This package exposes functions encrypt and decrypt that do the same thing.

encrypt wraps an AES key to the recipient, encrypts the message under that key, and returns a single envelope: wrappedLen + wrappedKey + iv + ciphertext (a 2-byte length prefix, the wrapped key, the 12-byte AES-GCM IV, and the cipher text). decrypt reverses it, returning the plaintext bytes.

[!NOTE]
See decrypt.asString & decrypt.fromString below for a convenient way to decrypt from a string.

See encrypt.asString for encrypting and encoding to a string.

import { toString } from 'uint8arrays'
import { encrypt, decrypt } from 'simple-hpke'

// ----------------------
// Encrypt
// ----------------------

// need a public key for the recipient
const recipient = await crypto.subtle.generateKey(
    { name: 'X25519' },
    false,  // not extractable
    ['deriveBits']
)

// create a new AES key, encrypt a message, and get back an "envelope"
const encryptedMessage = await encrypt(recipient.publicKey, 'hello encryption')

// encrypt to a public key as Uint8Array
const publicBytes = new Uint8Array(
    await subtle.exportKey('raw', recipient.publicKey)
)
const envelope = await encrypt(publicBytes, 'hello again')

// encrypt to a stringified public key
// create a string with `uint8arrays.toString`
const publicString = toString(publicBytes, 'base64url')
const envelopeAgain = await encrypt({
    publicKey: publicString,
    encoding: 'base64url'  // <-- this is the default
}, 'hello again, string version')

//
// encrypt with an existing AES key
// (a key not generated by this module)
//

const existingKey = await crypto.subtle.generateKey(
    { name: 'AES-GCM', length: 256 },
    true,  // extractable
    ['encrypt', 'decrypt']
)

const anotherEncryptedMsg = await encrypt(
    recipient,
    'hello again',
    existingKey
)

// ----------------------
// Decrypt
// ----------------------

// the recipient recovers the message with their private key
const text = await decrypt.asString(recipient, encryptedMessage)

// use `decrypt` to get a Uint8Array
const bytes = await decrypt(recipient, encryptedMessage)

// get a string
const plaintext = await decrypt.asString(recipient, envelope)

encrypt

The recipient can be a crypto key, a Uint8Array, or a string public key.

type RecipientKey =
    | CryptoKey
    | CryptoKeyPair
    | Uint8Array
    | { publicKey:string; encoding?:Uint8ArrayEncodings }

async function encrypt (
    recipient:RecipientKey,
    message:Uint8Array|string,
    aesKey?:CryptoKey|Uint8Array|null,
    opts?:{
        size?:128|256
        info?:Uint8Array|string
    }
):Promise<Uint8Array>

encrypt.asString

encrypt.asString is encrypt with the envelope encoded to a string, useful for transports that carry text (JSON, URLs, headers). opts.encoding sets the string encoding. Default encoding is base64url.

import { encrypt, decrypt } from 'simple-hpke'
import { fromString } from 'uint8arrays'

// recipient is any RecipientKey; keypair holds the matching private key
const encryptedString = await encrypt.asString(
    recipient,
    'message for them',
    null,  // an AES key if you want
    { encoding: 'base64url' }
)

// Decode it back to bytes before decrypting.
const message = fromString(encryptedString, 'base64url')
const plaintext = await decrypt.asString(keypair, message)
// 'message for them'

The returned string encodes the same envelope encrypt returns, so the recipient decodes it with a matching decoder (here fromString) and passes the bytes to decrypt / decrypt.asString.

decrypt

Decrypt the given data, return a Uint8Array.

async function decrypt (
    keypair:CryptoKeyPair,
    message:Uint8Array,
    opts?:{ info?:Uint8Array|string }
):Promise<Uint8Array>

decrypt.asString

Take a Uint8Array, return a string.

decrypt.asString = async function decryptToString (
    keypair:CryptoKeyPair,
    message:Uint8Array,
    opts?:{ info?:Uint8Array|string }
):Promise<string>

decrypt.fromString

Take a string as input. Return either a string, or if opts.buffer is true, aUint8Array.

decrypt.fromString = async function decryptFromString (
    keypair:CryptoKeyPair,
    message:string,
    opts?:{ info?:Uint8Array|string, buffer?:boolean }
):Promise<string|Uint8Array>

Extractable keys

create, encryptKey, and open return a non-extractable AES-GCM CryptoKey by default. It encrypts and decrypts normally; it just cannot be exported, so its raw bytes cannot leak out of the runtime.

Opt in when you genuinely need the bytes:

const { wrapped, key } = await create(recipient, { extractable: true })
const bytes = new Uint8Array(await crypto.subtle.exportKey('raw', key))

// same option on the way back out
const recovered = await open(keypair, wrapped, { extractable: true })

This is separate from the aesKey you may pass in to encryptKey / encrypt. That one must always be extractable, because its raw bytes are what get sealed.

If you only need to tell two keys apart, you do not need the bytes -- use keyId.

keyId

A stable fingerprint for an AES-GCM key, so you can ask "is this the key I have?" without holding its bytes.

async function keyId (key:CryptoKey):Promise<string>

import { create, open, keyId } from 'simple-hpke'

const { wrapped, key } = await create(recipient)
const id = await keyId(key)     // 43-char base64url string

const recovered = await open(keypair, wrapped)
await keyId(recovered) === id   // true

It works on a non-extractable key -- including one rehydrated from IndexedDB -- which is the whole point: the obvious implementation (exportKey('raw') then SHA-256) would force every key you want to identify to be extractable.

The derivation is fixed, and is treated as wire format:

LABEL = utf8("simple-hpke/keyId/v1")
N     = SHA-256(LABEL)[0..12]        // fixed nonce
C     = AES-GCM(key, N, LABEL)       // ciphertext || 16-byte tag
keyId = base64url(SHA-256(LABEL || C))

key must be an AES-GCM key with the encrypt usage; anything else throws ERR_INVALID_AES_KEY.

Errors

Every error this package throws is an HpkeError: an ordinary Error with a stable code. Branch on the code, not on the message text -- the codes are part of the API, the prose is not. Where a WebCrypto failure is being wrapped, the original is kept on cause.

import { decrypt, HpkeError } from 'simple-hpke'

try {
    await decrypt(keypair, envelope)
} catch (err) {
    if (err instanceof HpkeError && err.code === 'ERR_DECRYPT_FAILED') {
        // wrong keypair, wrong `info`, or a tampered envelope
    }
    throw err
}

| Code | Raised when | | --- | --- | | ERR_INVALID_RECIPIENT_KEY | The recipient is not a usable X25519 public key: wrong length, a private key, the wrong algorithm, or an unrecognized form. | | ERR_INVALID_KEYPAIR | keypair.privateKey is not an X25519 private key. | | ERR_SMALL_ORDER_KEY | The X25519 shared secret came out all-zero (a small-order public key). Conforming runtimes reject this first. | | ERR_MALFORMED_ENVELOPE | An open / open.raw envelope is too short to hold enc plus an AEAD tag. | | ERR_MALFORMED_MESSAGE | A decrypt envelope is too short to hold its own declared segments. | | ERR_INVALID_KEYSIZE | opts.size is neither 128 nor 256. | | ERR_INVALID_AES_KEY | A supplied aesKey is the wrong length or non-extractable, or keyId got a key it cannot use. | | ERR_DECRYPT_FAILED | AES-GCM authentication failed: wrong keypair, wrong info, or a tampered ciphertext. |

HpkeErrorCode is exported as a type if you want to switch exhaustively.

Modules

This exposes ESM and common JS via package.json exports field.

ESM

import {
    create,
    encryptKey,
    open,
    encrypt,
    decrypt,
    keyId,
    HpkeError
} from 'simple-hpke'

Common JS

require('simple-hpke')

pre-built JS

This package exposes minified JS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/simple-hpke/dist/index.min.js ./public/hpke.min.js

HTML

<script type="module" src="./hpke.min.js"></script>