simple-hpke 0.2.0 → 0.3.1

package/README.md

@@ -38,6 +38,9 @@ the plaintext is.
       - [`decrypt`](#decrypt)
       - [`decrypt.asString`](#decryptasstring)
       - [`decrypt.fromString`](#decryptfromstring)
+- [Extractable keys](#extractable-keys)
+- [`keyId`](#keyid)
+- [Errors](#errors)
 - [Modules](#modules)
   * [ESM](#esm)
   * [Common JS](#common-js)
@@ -77,20 +80,24 @@ const keypair = await crypto.subtle.generateKey(
 
 // Create a new AES key and encrypt it to your public key.
 // `key` is the unencrypted new AES key
-// `enc` is the AES key encrypted to the given public key
-const { enc, key } = await create(keypair.publicKey)  // or a buffer or string
+// `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,  // not extractable
+    true,  // extractable -- its raw bytes are what get sealed
     ['encrypt', 'decrypt']
 )
 
 // Wrap the existing key.
-const { enc: wrappedKey } = await encryptKey(keypair, aesKey)
+const { wrapped: wrappedKey } = await encryptKey(keypair, aesKey)
 
 // or pass in just a public key
 
@@ -121,7 +128,7 @@ const recipient = await crypto.subtle.generateKey(
 )
 
 // Create a fresh AES-GCM key, and encrypt a message with it.
-const { enc, key } = await create(recipient)
+const { wrapped, key } = await create(recipient)
 const iv = crypto.getRandomValues(new Uint8Array(12))
 const ciphertextBuffer = await crypto.subtle.encrypt(
     { name: 'AES-GCM', iv },
@@ -129,25 +136,28 @@ const ciphertextBuffer = await crypto.subtle.encrypt(
     new TextEncoder().encode('attack at dawn')
 )
 
-// Send `enc`, `iv`, and `ciphertext` together. `create(...)` defaults to a
-// 256-bit AES key, so `enc.length` is 80 bytes in this example.
+// 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 `enc.length`
-// (or otherwise transmit it) so the recipient can split the payload safely.
+// 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 encLength = enc.length
-const message = new Uint8Array(encLength + iv.length + ciphertext.length)
-message.set(enc, 0)
-message.set(iv, encLength)
-message.set(ciphertext, encLength + iv.length)
+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 enc2 = message.subarray(0, encLength)
-const iv2 = message.subarray(encLength, encLength + 12)
-const ciphertext2 = message.subarray(encLength + 12)
+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, enc2)
+const recovered = await open(recipient, wrapped2)
 const plaintext = await crypto.subtle.decrypt(
     { name: 'AES-GCM', iv: iv2 },
     recovered,
@@ -334,6 +344,100 @@ decrypt.fromString = async function decryptFromString (
 
 ---------------------------------------------------------------
 
+## 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:
+
+```ts
+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).
+
+## `keyId`
+
+A stable fingerprint for an AES-GCM key, so you can ask "is this the key I
+have?" without holding its bytes.
+
+```ts
+async function keyId (key:CryptoKey):Promise<string>
+```
+
+```ts
+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).
+
+## 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`.
+
+```ts
+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
@@ -341,7 +445,15 @@ This exposes ESM and common JS via
 
 ### ESM
 ```js
-import { create, encryptKey, open, encrypt, decrypt } from 'simple-hpke'
+import {
+    create,
+    encryptKey,
+    open,
+    encrypt,
+    decrypt,
+    keyId,
+    HpkeError
+} from 'simple-hpke'
 ```
 
 ### Common JS

package/dist/constants.cjs

@@ -29,6 +29,8 @@ __export(constants_exports, {
   KDF_ID: () => KDF_ID,
   KEM_ID: () => KEM_ID,
   KEM_SUITE_ID: () => KEM_SUITE_ID,
+  KEY_ID_LABEL: () => KEY_ID_LABEL,
+  KEY_ID_NONCE_LENGTH: () => KEY_ID_NONCE_LENGTH,
   MODE_BASE: () => MODE_BASE,
   NK: () => NK,
   NN: () => NN,
@@ -1315,6 +1317,19 @@ function toString2(array, encoding = "utf8") {
 }
 __name(toString2, "toString");
 
+// src/errors.ts
+var HpkeError = class extends Error {
+  static {
+    __name(this, "HpkeError");
+  }
+  code;
+  constructor(code2, message, opts) {
+    super(message, opts);
+    this.name = "HpkeError";
+    this.code = code2;
+  }
+};
+
 // src/index.ts
 var subtle = globalThis.crypto.subtle;
 var open = Object.assign(openBytes, {
@@ -1329,13 +1344,19 @@ var decrypt = Object.assign(decryptBytes, {
 });
 async function decryptBytes(keypair, message, opts) {
   if (message.byteLength < WRAPPED_LEN_PREFIX) {
-    throw new Error("malformed message: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: too short"
+    );
   }
   const wrappedLen = message[0] << 8 | message[1];
   const ivStart = WRAPPED_LEN_PREFIX + wrappedLen;
   const ctStart = ivStart + NN;
   if (message.byteLength < ctStart + AEAD_TAG_LENGTH) {
-    throw new Error("malformed message: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: too short"
+    );
   }
   const wrapped = message.slice(WRAPPED_LEN_PREFIX, ivStart);
   const iv = message.slice(ivStart, ctStart);
@@ -1346,11 +1367,20 @@ async function decryptBytes(keypair, message, opts) {
     opts?.info !== void 0 ? { info: opts.info } : void 0
   );
   const key = await importAesKeyDecryptOnly(keyBytes);
-  const pt = await subtle.decrypt(
-    { name: "AES-GCM", iv },
-    key,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      ciphertext
+    );
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_DECRYPT_FAILED",
+      "failed to decrypt the message: tampered ciphertext",
+      { cause: err }
+    );
+  }
   return new Uint8Array(pt);
 }
 __name(decryptBytes, "decryptBytes");
@@ -1371,7 +1401,8 @@ async function decryptFromString(keypair, message, opts) {
 __name(decryptFromString, "decryptFromString");
 function validateKeysize(keysize) {
   if (keysize !== 128 && keysize !== 256) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_KEYSIZE",
       `invalid keysize: ${keysize} (expected 128 or 256)`
     );
   }
@@ -1379,7 +1410,8 @@ function validateKeysize(keysize) {
 __name(validateKeysize, "validateKeysize");
 function validateRawKeyBytes(raw) {
   if (raw.length !== 16 && raw.length !== 32) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
       `invalid aesKey length: ${raw.length} bytes (expected 16 or 32)`
     );
   }
@@ -1393,19 +1425,20 @@ function normalizeInfo(info) {
 __name(normalizeInfo, "normalizeInfo");
 async function exportAesKeyBytes(key) {
   if (!key.extractable) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
       "aesKey must be extractable: its raw bytes are what get sealed"
     );
   }
   return new Uint8Array(await subtle.exportKey("raw", key));
 }
 __name(exportAesKeyBytes, "exportAesKeyBytes");
-async function importAesKey(raw) {
+async function importAesKey(raw, extractable) {
   return subtle.importKey(
     "raw",
     raw,
     { name: "AES-GCM" },
-    true,
+    extractable,
     ["encrypt", "decrypt"]
   );
 }
@@ -1460,7 +1493,10 @@ async function keySchedule(sharedSecret, info) {
 __name(keySchedule, "keySchedule");
 async function openRawBytes(keypair, wrapped, opts) {
   if (wrapped.byteLength < ENC_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("malformed envelope: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_ENVELOPE",
+      "malformed envelope: too short"
+    );
   }
   const info = normalizeInfo(opts?.info);
   const enc = wrapped.slice(0, ENC_LENGTH);
@@ -1472,7 +1508,7 @@ async function openRawBytes(keypair, wrapped, opts) {
 __name(openRawBytes, "openRawBytes");
 async function openBytes(keypair, wrapped, opts) {
   const keyBytes = await openRawBytes(keypair, wrapped, opts);
-  return importAesKey(keyBytes);
+  return importAesKey(keyBytes, opts?.extractable ?? false);
 }
 __name(openBytes, "openBytes");
 async function encryptKey(recipient, aesKey, opts) {
@@ -1496,8 +1532,11 @@ async function encryptKey(recipient, aesKey, opts) {
   const { key, baseNonce } = await keySchedule(sharedSecret, info);
   const ciphertext = await aeadSeal(key, baseNonce, keyBytes);
   const wrapped = concat2(enc, ciphertext);
-  const aesGcmKey = await importAesKey(keyBytes);
-  return { enc: wrapped, key: aesGcmKey };
+  const aesGcmKey = await importAesKey(
+    keyBytes,
+    opts?.extractable ?? false
+  );
+  return { wrapped, key: aesGcmKey };
 }
 __name(encryptKey, "encryptKey");
 
@@ -1527,24 +1566,38 @@ async function aeadOpen(key, nonce, ciphertext) {
     false,
     ["decrypt"]
   );
-  const pt = await subtle2.decrypt(
-    { name: "AES-GCM", iv: nonce },
-    k,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle2.decrypt(
+      { name: "AES-GCM", iv: nonce },
+      k,
+      ciphertext
+    );
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_DECRYPT_FAILED",
+      "failed to decrypt the wrapped key: wrong keypair, wrong info, or a tampered envelope",
+      { cause: err }
+    );
+  }
   return new Uint8Array(pt);
 }
 __name(aeadOpen, "aeadOpen");
 async function encryptBytes(recipient, message, aesKey, opts) {
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
-  const { enc, key } = await encryptKey(recipient, aesKey, opts);
+  const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
   const ct = new Uint8Array(await subtle2.encrypt(
     { name: "AES-GCM", iv },
     key,
     plaintext
   ));
-  return concat2(i2osp(enc.length, WRAPPED_LEN_PREFIX), enc, iv, ct);
+  return concat2(
+    i2osp(wrapped.length, WRAPPED_LEN_PREFIX),
+    wrapped,
+    iv,
+    ct
+  );
 }
 __name(encryptBytes, "encryptBytes");
 async function encryptToString(recipient, message, aesKey, opts) {
@@ -1610,7 +1663,8 @@ async function exportRawPublic(key) {
 __name(exportRawPublic, "exportRawPublic");
 async function importRawPublic(raw) {
   if (raw.length !== ENC_LENGTH) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
       `invalid public key length: ${raw.length} bytes (expected ${ENC_LENGTH})`
     );
   }
@@ -1629,9 +1683,16 @@ async function resolveRecipientPublicKey(recipient) {
   }
   if (recipient instanceof CryptoKey) {
     if (recipient.type !== "public") {
-      throw new Error("recipient CryptoKey must be a public key");
+      throw new HpkeError(
+        "ERR_INVALID_RECIPIENT_KEY",
+        "recipient CryptoKey must be a public key"
+      );
     }
-    assertX25519Algorithm(recipient, "recipient CryptoKey");
+    assertX25519Algorithm(
+      recipient,
+      "recipient CryptoKey",
+      "ERR_INVALID_RECIPIENT_KEY"
+    );
     return recipient;
   }
   if (typeof recipient.publicKey === "string") {
@@ -1641,17 +1702,28 @@ async function resolveRecipientPublicKey(recipient) {
   const pair = recipient;
   if (pair.publicKey instanceof CryptoKey) {
     if (pair.publicKey.type !== "public") {
-      throw new Error("recipient keypair publicKey must be a public key");
+      throw new HpkeError(
+        "ERR_INVALID_RECIPIENT_KEY",
+        "recipient keypair publicKey must be a public key"
+      );
     }
-    assertX25519Algorithm(pair.publicKey, "recipient keypair publicKey");
+    assertX25519Algorithm(
+      pair.publicKey,
+      "recipient keypair publicKey",
+      "ERR_INVALID_RECIPIENT_KEY"
+    );
     return pair.publicKey;
   }
-  throw new Error("unrecognized recipient key form");
+  throw new HpkeError(
+    "ERR_INVALID_RECIPIENT_KEY",
+    "unrecognized recipient key form"
+  );
 }
 __name(resolveRecipientPublicKey, "resolveRecipientPublicKey");
-function assertX25519Algorithm(key, context) {
+function assertX25519Algorithm(key, context, code2) {
   if (key.algorithm.name !== "X25519") {
-    throw new Error(
+    throw new HpkeError(
+      code2,
       `${context} must be an X25519 key (got ${key.algorithm.name})`
     );
   }
@@ -1665,7 +1737,8 @@ async function dh(priv, pub) {
   );
   const bytes = new Uint8Array(bits);
   if (bytes.every((b) => b === 0)) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_SMALL_ORDER_KEY",
       "X25519 shared secret is all-zero (small-order public key?)"
     );
   }
@@ -1704,9 +1777,16 @@ async function encap(pkR) {
 __name(encap, "encap");
 async function decap(enc, keypair) {
   if (keypair.privateKey.type !== "private") {
-    throw new Error("keypair.privateKey must be a private key");
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.privateKey must be a private key"
+    );
   }
-  assertX25519Algorithm(keypair.privateKey, "keypair.privateKey");
+  assertX25519Algorithm(
+    keypair.privateKey,
+    "keypair.privateKey",
+    "ERR_INVALID_KEYPAIR"
+  );
   const pkE = await subtle2.importKey(
     "raw",
     enc,
@@ -1765,4 +1845,6 @@ var HPKE_SUITE_ID = concat2(
   i2osp(KDF_ID, 2),
   i2osp(AEAD_ID, 2)
 );
+var KEY_ID_LABEL = new TextEncoder().encode("simple-hpke/keyId/v1");
+var KEY_ID_NONCE_LENGTH = 12;
 //# sourceMappingURL=constants.cjs.map