pull-secret-channel

Streaming authenticated encryption using ChaCha20-Poly1305 (RFC 8439) (or other AEAD constructions).

See project README.md for more information.

Install

npm install --save pull-secret-channel

Example

const { randomBytes } = require('crypto')
const pull = require('pull-stream')
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, nonce),

  // the encrypted stream
  pull.through((ciphertext) => {
    console.log('Encrypted: ', ciphertext)
  }),

  // decrypt every byte
  pullDecrypter(key, nonce),

  pull.concat((err, plaintext2) => {
    if (err) throw err
    console.log('Decrypted: ', plaintext2)
  }),
)

API

pullEncrypter(key, nonce)

Returns a "through" pull-stream.

For every plaintext content item in stream:

• Constructs and encrypts content length
• Encrypts content

And when stream done, constructs and encrypts an end-of-stream message.

pullDecrypter(key, nonce)

Returns a "through" pull-stream.

First reads and decrypts either a length or end-of-stream message.

If end-of-stream message, gracefully ends the stream.

Otherwise length message, so reads and decrypts the specified content.

If stream ends without end-of-stream message, aborts with an error.

KEY_SIZE

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.

The size of encrypted ciphertext is plaintext.length + TAG_SIZE.

The size of decrypted plaintext is ciphertext.length - TAG_SIZE.

License

Copyright 2023 Michael Williams

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.