simple-hpke 0.2.0 → 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)
@@ -38,6 +39,10 @@ the plaintext is.
       - [`decrypt`](#decrypt)
       - [`decrypt.asString`](#decryptasstring)
       - [`decrypt.fromString`](#decryptfromstring)
+- [Extractable keys](#extractable-keys)
+- [`keyId`](#keyid)
+  * [`verifyKeyId`](#verifykeyid)
+- [Errors](#errors)
 - [Modules](#modules)
   * [ESM](#esm)
   * [Common JS](#common-js)
@@ -77,27 +82,45 @@ 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)
+// 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)
 ```
 
 
@@ -107,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.
 
@@ -121,7 +144,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 +152,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,
@@ -199,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')
 
@@ -246,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,
@@ -266,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
@@ -321,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 (
@@ -334,6 +368,143 @@ 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.
+
+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).
+
+## `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).
+
+### `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`
+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, 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, 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, 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.
+
+---------------------------------------------------------------
+
 ## Modules
 
 This exposes ESM and common JS via
@@ -341,7 +512,16 @@ 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,
+    verifyKeyId,
+    HpkeError
+} from 'simple-hpke'
 ```
 
 ### Common JS