support new key derivations, add new preferred versions using such

[squeep-mystery-box] / README.md

diff --git a/README.md b/README.md
index e070bb24d4f31dc58f743b93fb4bdfc3f2e161c4..b7ad9d4fd0ac5dbff6aa89260295c221fc23113d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -6,5 +6,30 @@ In our case, this results in a Base64URL encoded string containing a bespoke pac
 
 ## API
 
-- pack(contents, version, flags)
-- unpack(box)
+- `async pack(contents, version, flags)`
+- `async unpack(box)`
+
+## Example
+
+```js
+const { MysteryBox } = require('@squeep/mystery-box');
+const assert = require('assert');
+
+const mb = new MysteryBox(console, {
+  encryptionSecret: 'very secret',
+});
+
+(async () => {
+  const data = { important: 'to keep secret' };
+  const encrypted = await mb.pack(data);
+  const decrypted = await mb.unpack(encrypted);
+  assert.deepStrictEqual(decrypted, data);
+})()
+  .then(() => console.log('data retrieved!'));
+```
+
+## Details
+
+This relies on AEAD ciphers, such as `aes-256-gcm` and `chacha20-poly1305`, to encrypt the payload and authenticate the additional metadata (version identifier, flags indicating payload details, the iv of the cipher, and the salt used to create the key) needed to decrypt the payload.
+
+For each box, a new key is generated using the stored secret and a securely-random salt by way of a mechanism such as an XOF such as `shake256`, a hash such as `blake2b512`, or a more time-consuming multi-round hash such as `scrypt`.  This key is used to encrypt and authenticate the data and metadata, which is then encoded as a base64url string.