simple-hpke 0.1.2 → 0.1.3

package/README.md

@@ -68,14 +68,17 @@ const keypair = await crypto.subtle.generateKey(
 // 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
     ['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 +89,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 +149,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 +169,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,  // 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 +216,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-hpke",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Hybrid Public Key Encryption",
   "type": "module",
   "files": [