# pull-chacha20poly1305-stream

> Streaming encryption based on [libsodium](https://github.com/paixaop/node-sodium)'s box primitive.

Latest version **1.0.0** (published 2015-06-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install pull-chacha20poly1305-stream
pnpm add pull-chacha20poly1305-stream
yarn add pull-chacha20poly1305-stream
bun add pull-chacha20poly1305-stream
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2015-06-06 |
| First published | 2015-06-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Dominic Tarr |
| Maintainers | dominictarr |

## Links

- npm: https://www.npmjs.com/package/pull-chacha20poly1305-stream
- Repository: https://github.com/dominictarr/pull-chacha20poly1305-stream
- Issues: https://github.com/dominictarr/pull-chacha20poly1305-stream/issues
- npm.io page: https://npm.io/package/pull-chacha20poly1305-stream

## Dependencies (6)

- [sodium](https://npm.io/package/sodium.md) ^1.0.17
- [pull-reader](https://npm.io/package/pull-reader.md) ~1.0.1
- [pull-stream](https://npm.io/package/pull-stream.md) ~2.26.1
- [pull-through](https://npm.io/package/pull-through.md) ~1.0.14
- [split-buffer](https://npm.io/package/split-buffer.md) ~1.0.0
- [increment-buffer](https://npm.io/package/increment-buffer.md) ~1.0.0

## Recent versions

- 1.0.0 (latest) — 2015-06-06
- 0.0.0 — 2015-06-04

## README

# pull-box-stream

Streaming encryption based on [libsodium](https://github.com/paixaop/node-sodium)'s box primitive.

This protocol is unusually robust, there are no malleable bytes.
Even the framing is authenticated, and an attacker cannot
flip any bits without being immediately detected.

The design follows on from that used in
[pull-mac](https://github.com/dominictarr/pull-mac),
where both the framing and the framed packet are authenticated.

In `pull-mac`, the packet is hashed, and then the header hmac'd.
Since the header contains the packet hash and the packet length,
then changing a bit in the packet will produce a different hash
and thus an invalid packet. Flipping a bit in the header will
invalidate the hmac.

In `pull-boxes` a similar approach is used, but via nacl's authenticated
encryption primitive: `box`. salsa20 encryption + poly1305 mac.
The packet is boxed, then the header is constructed from the packet 
length + packet mac, then the header is boxed.

This protocol uses a 56 byte key (448 bits). The first 32 bytes
are the salsa20 key, and the last 24 bytes are the nonce. Previous
verisons of this protocol generated a nonce and transmitted it,
but it could be simplified by considering it part of the key.

Since every header and packet body are encrypted,
then every byte in the stream appears random.

The only information an evesdropper can extract is
packet timing and to guess at packet boundries
(although, sometimes packets will be appended, obscuring the true boundries)

## Example

``` js
var boxes = require('pull-box-stream')
//generate a random secret, 56 bytes long.

var key = createRandomSecret(56)

pull(
  plaintext_input,

  //encrypt every byte
  boxes.createBoxStream(key),

  //the encrypted stream
  pull.through(console.log),

  //decrypt every byte
  boxes.createUnboxStream(key),

  plaintext_output
)


```

## Protocol

```
(

  [header MAC (16)] // sends header MAC
     |
     |   .--header-box-----------------.
     \-> |length (2), [packet MAC (16)]| // sends encrypted header
         `--^------------|-------------`
            |            |
            |            |  .-packet-box-------.
            |            `->|data.. (length...)| // sends encrypted packet
            |               `-----------|------`
            \---------------------------/

) * // repeat 0-N times

[final header MAC(16)]
   |
   |  .-final-header-box-------.
   \->|length=0 (2), zeros (16)|
      `------------------------`
```

Since the packet mac is inside the header box, the packet
must be boxed first.

The last 24 bytes of the 56 byte key is used as the nonce.
When boxing, you must use a different nonce everytime a particular key is used.

The recommended way to do this is to randomly generate an initial
nonce for that key, and then increment that nonce on each boxing.
(this way security is not dependant on the random number generator)

The protocol sends zero or more {header, packet} pairs, then a final
header, that is same length, but is just boxed zeros.
 Each header is 34 bytes long (header mac + packet_length + packet mac).
Then the packet_length is length long (with a maximum length of 4096
bytes long, if the in coming packet is longer than that it is split
into 4096 byte long sections.)

Packet number P uses N+2P as the nonce on the header box,
and N+2P+1 as the nonce on the packet box.

A final packet is sent so that an incorrectly terminated session
can be detected.

## License

MIT

---
_Source: https://npm.io/package/pull-chacha20poly1305-stream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._