simple-hpke 0.1.2 → 0.1.5

package/README.md

@@ -14,12 +14,22 @@ Hybrid Public Key Encryption
 
 1 dependency -- `uint8arrays`.
 
+On every `create`/`seal` 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.
+
 <details><summary><h2>Contents</h2></summary>
 
 <!-- toc -->
 
 - [Install](#install)
-- [Example](#example)
+- [Examples](#examples)
   * [Key Wrapping](#key-wrapping)
   * [Hybrid Encryption](#hybrid-encryption)
     + [Encrypt / Decrypt](#encrypt--decrypt)
@@ -45,13 +55,13 @@ Hybrid Public Key Encryption
 npm i -S simple-hpke
 ```
 
-## Example
+## Examples
 
-Wrap an AES key, or encrypt a message.
+Create an AES key, or encrypt a message.
 
 ### Key Wrapping
 
-Encrypt an AES key to yourself, then recover it later.
+Encrypt an AES key, then recover it later.
 
 ```ts
 import { create, seal, open } from 'simple-hpke'
@@ -61,21 +71,23 @@ import { create, seal, open } from 'simple-hpke'
 // HPKE only needs `deriveBits`.
 const keypair = await crypto.subtle.generateKey(
     { name: 'X25519' },
-    false,  // extractable
+    false,  // not extractable
     ['deriveBits']
 )
 
 // Create a new AES key and encrypt it to your public key.
 const { enc, key } = await create(keypair)
 
+//
 // 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
+    true,  // not extractable
     ['encrypt', 'decrypt']
 )
 
-// Wrap an existing key.
+// Wrap the existing key.
 const { enc: sealedKey } = await seal(keypair, aesKey)
 
 // or pass in just a public key
@@ -86,8 +98,6 @@ const recoveredKey = await open(keypair, sealedKey)
 // `recoveredKey` is equal to `aesKey`
 ```
 
-See [docs/README.md](./docs/README.md) for the full API and rationale.
-
 
 ------------------------------------------------------
 
@@ -148,11 +158,11 @@ 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` which do the same thing.
+This package exposes functions `encrypt` and `decrypt` that do the same thing.
 
 `encrypt` seals an AES key to the recipient, encrypts the message under
 that key, and returns a single envelope:
-`wrappedLen + wrapped + iv + ciphertext`
+`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.
 
@@ -168,27 +178,42 @@ cipher text). `decrypt` reverses it, returning the plaintext bytes.
 
 
 ```ts
+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,
+    false,  // not extractable
     ['deriveBits']
 )
 
-// create a new AES key, encrypt a message, and get back one envelope
-const encryptedMessage = await encrypt(recipient, 'hello encryption')
+// create a new AES key, encrypt a message, and get back an "envelope"
+const encryptedMessage = await encrypt(recipient.publicKey, 'hello encryption')
 
-// the recipient recovers the message with their private key
-const text = await decrypt.asString(recipient, encryptedMessage)
+// encrypt to a public key as Uint8Array
+const publicBytes = new Uint8Array(
+    await subtle.exportKey('raw', recipient.publicKey)
+)
+const envelope = await encrypt(publicBytes, 'hello again')
 
-// use `decrypt` to get a Uint8Array
-const bytes = await decrypt(recipient, encryptedMessage)
+// 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')
 
 //
-// use an existing AES key
+// 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
@@ -200,8 +225,23 @@ const anotherEncryptedMsg = await encrypt(
     '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.
@@ -218,7 +258,7 @@ async function encrypt (
     message:Uint8Array|string,
     aesKey?:CryptoKey|Uint8Array|null,
     opts?:{
-        keysize?:128|256
+        size?:128|256
         info?:Uint8Array|string
     }
 ):Promise<Uint8Array>