simple-hpke 0.1.3 → 0.2.0

package/README.md

@@ -14,12 +14,22 @@ Hybrid Public Key Encryption
 
 1 dependency -- `uint8arrays`.
 
+On every `create`/`encrypt` 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,46 +55,47 @@ 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'
+import { create, encryptKey, open } from 'simple-hpke'
 
 // An X25519 keypair. (asymmetric keypair).
 // The private key can be non-extractable.
 // 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)
+// `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
 
 //
 // 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 the existing key.
-const { enc: sealedKey } = await seal(keypair, aesKey)
+const { enc: wrappedKey } = 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, sealedKey)
+const recoveredKey = await open(keypair, wrappedKey)
 
 // `recoveredKey` is equal to `aesKey`
 ```
@@ -96,7 +107,7 @@ const recoveredKey = await open(keypair, sealedKey)
 ### Hybrid Encryption
 
 Encrypt a message with AES-GCM, then encrypt the AES key to a given
-public key. The wrapped key is concattenated with the cipher text,
+public key. The encrypted key is concattenated with the cipher text,
 along with the IV. The recipient uses their private key to open the AES key and
 decrypt the message.
 
@@ -151,7 +162,7 @@ new TextDecoder().decode(plaintext)  // => 'attack at dawn'
 So that was a lot of code to encrypt and decrypt a message...
 This package exposes functions `encrypt` and `decrypt` that do the same thing.
 
-`encrypt` seals an AES key to the recipient, encrypts the message under
+`encrypt` wraps an AES key to the recipient, encrypts the message under
 that key, and returns a single envelope:
 `wrappedLen + wrappedKey + iv + ciphertext`
 (a 2-byte length prefix, the wrapped key, the 12-byte AES-GCM IV, and the
@@ -179,7 +190,7 @@ import { encrypt, decrypt } from 'simple-hpke'
 // need a public key for the recipient
 const recipient = await crypto.subtle.generateKey(
     { name: 'X25519' },
-    false,  // extractable
+    false,  // not extractable
     ['deriveBits']
 )
 
@@ -249,7 +260,7 @@ async function encrypt (
     message:Uint8Array|string,
     aesKey?:CryptoKey|Uint8Array|null,
     opts?:{
-        keysize?:128|256
+        size?:128|256
         info?:Uint8Array|string
     }
 ):Promise<Uint8Array>
@@ -330,7 +341,7 @@ This exposes ESM and common JS via
 
 ### ESM
 ```js
-import { create, seal, open, encrypt, decrypt } from 'simple-hpke'
+import { create, encryptKey, open, encrypt, decrypt } from 'simple-hpke'
 ```
 
 ### Common JS

package/dist/constants.cjs

@@ -1317,16 +1317,6 @@ __name(toString2, "toString");
 
 // src/index.ts
 var subtle = globalThis.crypto.subtle;
-async function create2(recipient, opts) {
-  const { wrapped, key } = await encryptKey(recipient, null, opts);
-  return { enc: wrapped, key };
-}
-__name(create2, "create");
-async function seal(recipient, aesKey, opts) {
-  const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
-  return { enc: wrapped, key };
-}
-__name(seal, "seal");
 var open = Object.assign(openBytes, {
   raw: openRawBytes
 });
@@ -1507,7 +1497,7 @@ async function encryptKey(recipient, aesKey, opts) {
   const ciphertext = await aeadSeal(key, baseNonce, keyBytes);
   const wrapped = concat2(enc, ciphertext);
   const aesGcmKey = await importAesKey(keyBytes);
-  return { wrapped, key: aesGcmKey };
+  return { enc: wrapped, key: aesGcmKey };
 }
 __name(encryptKey, "encryptKey");
 
@@ -1547,17 +1537,7 @@ async function aeadOpen(key, nonce, ciphertext) {
 __name(aeadOpen, "aeadOpen");
 async function encryptBytes(recipient, message, aesKey, opts) {
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
-  let enc;
-  let key;
-  if (!aesKey) {
-    const keys = await create2(recipient, opts);
-    enc = keys.enc;
-    key = keys.key;
-  } else {
-    const keys = await seal(recipient, aesKey, opts);
-    enc = keys.enc;
-    key = keys.key;
-  }
+  const { enc, 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 },