X-Git-Url: http://git.squeep.com/?p=squeep-mystery-box;a=blobdiff_plain;f=README.md;h=b7ad9d4fd0ac5dbff6aa89260295c221fc23113d;hp=e070bb24d4f31dc58f743b93fb4bdfc3f2e161c4;hb=HEAD;hpb=044615f53bacdc366b44941218d808c549607469

diff --git a/README.md b/README.md
index e070bb2..3104107 100644
--- a/README.md
+++ b/README.md
@@ -6,5 +6,34 @@ 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({
+  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, 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.
+
+## Statistics
+
+A `statistics` event is emitted for every pack or unpack, containing timing and other information.