simple-hpke 0.3.1 → 0.3.3

package/README.md

@@ -31,6 +31,7 @@ the plaintext is.
 - [Install](#install)
 - [Examples](#examples)
   * [Key Wrapping](#key-wrapping)
+    + [`open.raw`](#openraw)
   * [Hybrid Encryption](#hybrid-encryption)
     + [Encrypt / Decrypt](#encrypt--decrypt)
       - [`encrypt`](#encrypt)
@@ -40,6 +41,7 @@ the plaintext is.
       - [`decrypt.fromString`](#decryptfromstring)
 - [Extractable keys](#extractable-keys)
 - [`keyId`](#keyid)
+  * [`verifyKeyId`](#verifykeyid)
 - [Errors](#errors)
 - [Modules](#modules)
   * [ESM](#esm)
@@ -96,15 +98,29 @@ const aesKey = await crypto.subtle.generateKey(
     ['encrypt', 'decrypt']
 )
 
-// Wrap the existing key.
-const { wrapped: wrappedKey } = await encryptKey(keypair, aesKey)
+// Wrap the existing key. The returned key is your own `aesKey` object,
+// untouched (`sameKey === aesKey`): same `extractable`, same usages.
+const { wrapped: wrappedKey, key: sameKey } = 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`
+// `recoveredKey` holds the same key material as `aesKey`
+```
+
+#### `open.raw`
+
+Recover the wrapped key as raw bytes instead of a `CryptoKey`. Returns a
+`Uint8Array` of 16 or 32 bytes, matching the key that was wrapped. It
+takes the same `info` option as `open`, and no `extractable` option.
+
+```ts
+const keyBytes = await open.raw(keypair, wrappedKey)
 ```
 
 
@@ -114,7 +130,7 @@ const recoveredKey = await open(keypair, wrappedKey)
 ### 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,
+public key. The encrypted key is concatenated with the cipher text,
 along with the IV. The recipient uses their private key to open the AES key and
 decrypt the message.
 
@@ -209,7 +225,7 @@ 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)
+    await crypto.subtle.exportKey('raw', recipient.publicKey)
 )
 const envelope = await encrypt(publicBytes, 'hello again')
 
@@ -256,14 +272,16 @@ const plaintext = await decrypt.asString(recipient, envelope)
 
 ##### `encrypt`
 
-The recipient can be a crypto key, a Uint8Array, or a string public key.
+The recipient can be a public crypto key, a keypair (only its public key
+is used), a Uint8Array, or a string public key. `SupportedEncodings` is
+the encoding type from `uint8arrays`.
 
 ```ts
 type RecipientKey =
     | CryptoKey
     | CryptoKeyPair
     | Uint8Array
-    | { publicKey:string; encoding?:Uint8ArrayEncodings }
+    | { publicKey:string; encoding?:SupportedEncodings }
 
 async function encrypt (
     recipient:RecipientKey,
@@ -276,6 +294,11 @@ async function encrypt (
 ):Promise<Uint8Array>
 ```
 
+A supplied `aesKey` `CryptoKey` must be extractable and must have the
+`encrypt` usage, because the message is encrypted under that key directly.
+A key without it rejects with `ERR_INVALID_AES_KEY` before any work is
+done. The key is used as-is, never re-imported.
+
 ##### `encrypt.asString`
 
 `encrypt.asString` is `encrypt` with the envelope encoded to a string, useful
@@ -331,8 +354,9 @@ decrypt.asString = async function decryptToString (
 
 ##### `decrypt.fromString`
 
-Take a `string` as input. Return either a string, or if `opts.buffer` is true,
-a`Uint8Array`.
+Take a `base64url` string as input (as returned by `encrypt.asString` with
+the default encoding). Return either a string, or if `opts.buffer` is true,
+a `Uint8Array`.
 
 ```ts
 decrypt.fromString = async function decryptFromString (
@@ -364,6 +388,23 @@ 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.
 
+A supplied `CryptoKey` is returned **as-is**: `encryptKey` gives back the
+same object you passed in, with its own `extractable` flag and usages.
+`opts.extractable` does not apply to it; it only governs a key the library
+imports (a generated key, or raw `Uint8Array` bytes). Because the library
+does not re-import your key, it does not add usages either. `encryptKey`
+will wrap a decrypt-only key, but `encrypt` needs the `encrypt` usage.
+
+```ts
+const myKey = await crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true,
+    ['encrypt', 'decrypt']
+)
+const { key } = await encryptKey(recipient, myKey, { extractable: false })
+key === myKey  // true, and still extractable
+```
+
 If you only need to tell two keys apart, you do not need the bytes --
 use [`keyId`](#keyid).
 
@@ -403,6 +444,32 @@ 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).
 
+### `verifyKeyId`
+
+Check a key against a `keyId` you stored earlier.
+
+```ts
+async function verifyKeyId (
+    key:CryptoKey,
+    expected:string
+):Promise<boolean>
+```
+
+```ts
+import { open, verifyKeyId } from 'simple-hpke'
+
+const recovered = await open(keypair, wrapped)
+if (!(await verifyKeyId(recovered, storedId))) {
+    // not the key you expected
+}
+```
+
+It resolves `true` or `false`, comparing in constant time. A key that
+`keyId` cannot fingerprint (not AES-GCM, or no `encrypt` usage) rejects
+with [`ERR_INVALID_AES_KEY`](#errors) rather than resolving `false`, so
+"cannot check this key" is never confused with "wrong key". Do not catch
+that error and return `false`.
+
 ## Errors
 
 Every error this package throws is an `HpkeError`: an ordinary `Error`
@@ -425,13 +492,13 @@ try {
 
 | 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_INVALID_RECIPIENT_KEY` | The recipient is not a usable X25519 public key: wrong length, a private key, the wrong algorithm, a non-extractable public key, a string that does not decode, or an unrecognized form. |
+| `ERR_INVALID_KEYPAIR` | `keypair.privateKey` is not an X25519 private key or lacks the `deriveBits` usage, or `keypair.publicKey` is not an extractable X25519 public key. |
+| `ERR_SMALL_ORDER_KEY` | A small-order X25519 public key (for example all zeros), as the recipient or as the `enc` in a tampered envelope. Raised on conforming runtimes, which reject it inside `deriveBits`, and on nonconforming ones, where the shared secret comes out all-zero. |
 | `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_MALFORMED_MESSAGE` | A `decrypt` envelope is too short to hold its own declared segments, or a `decrypt.fromString` input is not valid `base64url`. |
 | `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_INVALID_AES_KEY` | A supplied `aesKey` is the wrong length, non-extractable, or not an AES-GCM key, `encrypt` got an `aesKey` without the `encrypt` usage, or `keyId` / `verifyKeyId` 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.
@@ -452,6 +519,7 @@ import {
     encrypt,
     decrypt,
     keyId,
+    verifyKeyId,
     HpkeError
 } from 'simple-hpke'
 ```

package/dist/constants.cjs

@@ -1390,7 +1390,16 @@ async function decryptToString(keypair, message, opts) {
 }
 __name(decryptToString, "decryptToString");
 async function decryptFromString(keypair, message, opts) {
-  const bytes = fromString2(message, "base64url");
+  let bytes;
+  try {
+    bytes = fromString2(message, "base64url");
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: not base64url",
+      { cause: err }
+    );
+  }
   const plaintext = await decryptBytes(
     keypair,
     bytes,
@@ -1518,6 +1527,12 @@ async function encryptKey(recipient, aesKey, opts) {
     validateRawKeyBytes(aesKey);
     keyBytes = aesKey;
   } else if (aesKey) {
+    if (aesKey.algorithm.name !== "AES-GCM") {
+      throw new HpkeError(
+        "ERR_INVALID_AES_KEY",
+        "aesKey must be an AES-GCM key, got " + aesKey.algorithm.name
+      );
+    }
     keyBytes = await exportAesKeyBytes(aesKey);
     validateRawKeyBytes(keyBytes);
   } else {
@@ -1532,6 +1547,7 @@ 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);
+  if (aesKey instanceof CryptoKey) return { wrapped, key: aesKey };
   const aesGcmKey = await importAesKey(
     keyBytes,
     opts?.extractable ?? false
@@ -1584,6 +1600,12 @@ async function aeadOpen(key, nonce, ciphertext) {
 }
 __name(aeadOpen, "aeadOpen");
 async function encryptBytes(recipient, message, aesKey, opts) {
+  if (aesKey instanceof CryptoKey && !aesKey.usages.includes("encrypt")) {
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
+      'aesKey is missing the "encrypt" usage, which encrypt needs to encrypt the message'
+    );
+  }
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
   const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
@@ -1682,37 +1704,28 @@ async function resolveRecipientPublicKey(recipient) {
     return importRawPublic(recipient);
   }
   if (recipient instanceof CryptoKey) {
-    if (recipient.type !== "public") {
-      throw new HpkeError(
-        "ERR_INVALID_RECIPIENT_KEY",
-        "recipient CryptoKey must be a public key"
-      );
-    }
-    assertX25519Algorithm(
-      recipient,
-      "recipient CryptoKey",
-      "ERR_INVALID_RECIPIENT_KEY"
-    );
-    return recipient;
+    return assertRecipientPublicKey(recipient, "recipient CryptoKey");
   }
   if (typeof recipient.publicKey === "string") {
     const { publicKey, encoding } = recipient;
-    return importRawPublic(fromString2(publicKey, encoding ?? "base64url"));
-  }
-  const pair = recipient;
-  if (pair.publicKey instanceof CryptoKey) {
-    if (pair.publicKey.type !== "public") {
+    let decoded;
+    try {
+      decoded = fromString2(publicKey, encoding ?? "base64url");
+    } catch (err) {
       throw new HpkeError(
         "ERR_INVALID_RECIPIENT_KEY",
-        "recipient keypair publicKey must be a public key"
+        `recipient publicKey string does not decode as ${encoding ?? "base64url"}`,
+        { cause: err }
       );
     }
-    assertX25519Algorithm(
+    return importRawPublic(decoded);
+  }
+  const pair = recipient;
+  if (pair.publicKey instanceof CryptoKey) {
+    return assertRecipientPublicKey(
       pair.publicKey,
-      "recipient keypair publicKey",
-      "ERR_INVALID_RECIPIENT_KEY"
+      "recipient keypair publicKey"
     );
-    return pair.publicKey;
   }
   throw new HpkeError(
     "ERR_INVALID_RECIPIENT_KEY",
@@ -1720,6 +1733,23 @@ async function resolveRecipientPublicKey(recipient) {
   );
 }
 __name(resolveRecipientPublicKey, "resolveRecipientPublicKey");
+function assertRecipientPublicKey(key, context) {
+  if (key.type !== "public") {
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
+      `${context} must be a public key`
+    );
+  }
+  assertX25519Algorithm(key, context, "ERR_INVALID_RECIPIENT_KEY");
+  if (!key.extractable) {
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
+      `${context} must be extractable (the KEM exports it)`
+    );
+  }
+  return key;
+}
+__name(assertRecipientPublicKey, "assertRecipientPublicKey");
 function assertX25519Algorithm(key, context, code2) {
   if (key.algorithm.name !== "X25519") {
     throw new HpkeError(
@@ -1730,11 +1760,23 @@ function assertX25519Algorithm(key, context, code2) {
 }
 __name(assertX25519Algorithm, "assertX25519Algorithm");
 async function dh(priv, pub) {
-  const bits = await subtle2.deriveBits(
-    { name: "X25519", public: pub },
-    priv,
-    256
-  );
+  let bits;
+  try {
+    bits = await subtle2.deriveBits(
+      { name: "X25519", public: pub },
+      priv,
+      256
+    );
+  } catch (err) {
+    if (err?.name === "OperationError") {
+      throw new HpkeError(
+        "ERR_SMALL_ORDER_KEY",
+        "X25519 deriveBits rejected a small-order public key",
+        { cause: err }
+      );
+    }
+    throw err;
+  }
   const bytes = new Uint8Array(bits);
   if (bytes.every((b) => b === 0)) {
     throw new HpkeError(
@@ -1787,6 +1829,23 @@ async function decap(enc, keypair) {
     "keypair.privateKey",
     "ERR_INVALID_KEYPAIR"
   );
+  if (!keypair.privateKey.usages.includes("deriveBits")) {
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.privateKey must have the deriveBits usage"
+    );
+  }
+  if (keypair.publicKey.type !== "public" || !keypair.publicKey.extractable) {
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.publicKey must be an extractable public key"
+    );
+  }
+  assertX25519Algorithm(
+    keypair.publicKey,
+    "keypair.publicKey",
+    "ERR_INVALID_KEYPAIR"
+  );
   const pkE = await subtle2.importKey(
     "raw",
     enc,