update docs

README.md

@@ -1,22 +1,22 @@
-# secret-channel 🤫
+# "Secret Channel" 🤫
 
-Streaming authenticated encryption using ChaCha20-Poly1305 ([RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439)) (or other [AEADs](https://libsodium.gitbook.io/doc/secret-key_cryptography/aead)).
+> Streaming authenticated encryption using ChaCha20-Poly1305 ([RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439)) (or other [AEADs](https://libsodium.gitbook.io/doc/secret-key_cryptography/aead)).
 
-`secret-channel` is designed to be easy to implement and provide [security guarantees](#security-guarantees) (if you abide by the [pre-requisites](#pre-requisites)).
+A protocol for a secure peer-to-peer message stream, after you've done a secure peer-to-peer key exchange.
 
-(Note: This has not been audited to be safe. Use at your own risk.)
+(Note: This protocol has not been audited to be safe. Use at your own risk.)
 
 ## Pre-requisites
 
 - The channel must be reliable and ordered: i.e. TCP.
 - Each channel key must be an ephemeral key for a single channel and discarded when the channel ends.
-    - To get an ephemeral key for a session, you should do a secure key exchange, such as [Secret Handshake](https://dominictarr.github.io/secret-handshake-paper/shs.pdf).
-- For a duplex (bi-directional) connection between peers, you should create two secret channels (with separate keys), one in each direction.
+  - To get an ephemeral key for a session, you should do a secure key exchange, such as [Noise](https://noiseprotocol.org/noise.html) or [Secret Handshake](https://dominictarr.github.io/secret-handshake-paper/shs.pdf).
+  - For a duplex (bi-directional) connection between peers, you should create two secret channels (with separate keys), one in each direction.
 - A (key, nonce) pair must NEVER be re-used.
 
 ## Security Guarantees
 
-`secret-channel` protects the stream from:
+Secret Channel protects the stream from:
 
 - Stream truncation: avoided by checking for "end-of-stream" as the final chunk.
 - Chunk removal: the wrong nonce would be used, producing an AEAD decryption error.

SPEC.md

@@ -6,8 +6,8 @@ Streaming authenticated encryption using ChaCha20-Poly1305 ([RFC 8439](https://d
 
 - The channel must be reliable and ordered: i.e. TCP.
 - Each channel key must be an ephemeral key for a single channel and discarded when the channel ends.
-    - To get an ephemeral key for a session, do a secure key exchange, such as [Noise](https://noiseprotocol.org/noise.html) or [Secret Handshake](https://dominictarr.github.io/secret-handshake-paper/shs.pdf) first.
-- For a duplex (bi-directional) connection between peers, create two secret channels (with separate keys), one in each direction.
+  - To get an ephemeral key for a session, do a secure key exchange, such as [Noise](https://noiseprotocol.org/noise.html) or [Secret Handshake](https://dominictarr.github.io/secret-handshake-paper/shs.pdf) first.
+  - For a duplex (bi-directional) connection between peers, create two secret channels (with separate keys), one in each direction.
 - A (key, nonce) pair must NEVER be re-used.
 
 ## Security Guarantees

js/pull-secret-channel/README.md

@@ -17,26 +17,28 @@ npm install --save pull-secret-channel
 ```js
 const { randomBytes } = require('crypto')
 const pull = require('pull-stream')
-const { KEY_SIZE, pullEncrypter, pullDecrypter } = require('pull-secret-channel')
+const { pullEncrypter, pullDecrypter, KEY_SIZE, NONCE_SIZE } = require('pull-secret-channel')
 
 // generate a random secret, `KEY_SIZE` bytes long.
 const key = randomBytes(KEY_SIZE)
+// generate a random nonce, `NONCE_SIZE` bytes long.
+const nonce = randomBytes(NONCE_SIZE)
 
 const plaintext1 = Buffer.from('hello world')
 
 pull(
   pull.values([plaintext1]),
 
   // encrypt every byte
-  pullEncrypter(key),
+  pullEncrypter(key, nonce),
 
   // the encrypted stream
   pull.through((ciphertext) => {
     console.log('Encrypted: ', ciphertext)
   }),
 
   // decrypt every byte
-  pullDecrypter(key),
+  pullDecrypter(key, nonce),
 
   pull.concat((err, plaintext2) => {
     if (err) throw err
@@ -47,7 +49,7 @@ pull(
 
 ## API
 
-### `pullEncrypter(key)`
+### `pullEncrypter(key, nonce)`
 
 Returns a "through" pull-stream.
 
@@ -58,7 +60,7 @@ For every plaintext content item in stream:
 
 And when stream done, constructs and encrypts an end-of-stream message.
 
-### `pullDecrypter(key)`
+### `pullDecrypter(key, nonce)`
 
 Returns a "through" pull-stream.
 
@@ -74,6 +76,10 @@ If stream ends without end-of-stream message, aborts with an error.
 
 The size of a ChaCha20-Poly1305 key: 32 bytes
 
+### `NONCE_SIZE`
+
+The size of a ChaCha20-Poly1305 nonce: 12 bytes
+
 ### `TAG_SIZE`
 
 The size of ChaCha20-Poly1305 authentication tag: 16 bytes.