cobblestone

README

filippo.io/cobblestone

Package cobblestone implements the chunked (or streaming) encryption scheme Cobblestone-128, as described in c2sp.org/chunked-encryption.

Cobblestone-128 is based on AES-128-GCM and HKDF-SHA-512, and is designed to encrypt large messages of up to 4 PiB, allowing authenticated streaming encryption (provided as an io.Writer or io.Reader) and decryption (provided as an io.Reader), and authenticated random access (provided as an io.ReaderAt). The message is broken up into 16 KiB chunks, each of which is encrypted and authenticated separately, with protections against reordering and truncation attacks.

This scheme has a fixed overhead of 56 bytes and a marginal overhead of approximately 0.1%.

The rawchunked package implements raw mode, where key derivation is left to the application, and different AEADs can be used.

Testing

go test ./...
go run filippo.io/mostly-harmless/muzoo@latest test --memory 2GiB --timeout 2m
go run honnef.co/go/tools/cmd/staticcheck@latest ./...

Documentation

Overview

Package cobblestone implements the chunked (or streaming) encryption scheme Cobblestone-128, as described in c2sp.org/chunked-encryption.

Index

• Constants
• func CiphertextSize(plaintextSize int64) int64
• func NewDecryptReader(key []byte, context string, src io.Reader) (io.Reader, error)
• func NewDecryptReaderAt(key []byte, context string, src io.ReaderAt, size int64) (io.ReaderAt, error)
• func NewEncryptReader(key []byte, context string, src io.Reader) (io.Reader, error)
• func NewEncryptWriter(key []byte, context string, dst io.Writer) (io.WriteCloser, error)
• func PlaintextSize(ciphertextSize int64) (int64, error)

Constants

const KeySize = 16

Functions

func CiphertextSize

func CiphertextSize(plaintextSize int64) int64

CiphertextSize returns the size of the ciphertext corresponding to a given plaintext size.

func NewDecryptReader

func NewDecryptReader(key []byte, context string, src io.Reader) (io.Reader, error)

NewDecryptReader returns a Reader that decrypts ciphertext read from src and produces the plaintext.

The key must be 16 bytes long. The context is an optional string that is included in the key derivation and commitment, and can be used to bind the ciphertext to a specific context (e.g. a filename or a user ID).

func NewDecryptReaderAt

func NewDecryptReaderAt(key []byte, context string, src io.ReaderAt, size int64) (io.ReaderAt, error)

NewDecryptReaderAt returns a ReaderAt that decrypts ciphertext read from src and produces the plaintext. The size parameter is the total size of the ciphertext available through src.

The key must be 16 bytes long. The context is an optional string that is included in the key derivation and commitment, and can be used to bind the ciphertext to a specific context (e.g. a filename or a user ID).

func NewEncryptReader

func NewEncryptReader(key []byte, context string, src io.Reader) (io.Reader, error)

NewEncryptReader returns a Reader that encrypts plaintext read from src and produces the ciphertext.

The key must be 16 bytes long. The context is an optional string that is included in the key derivation and commitment, and can be used to bind the ciphertext to a specific context (e.g. a filename or a user ID).

func NewEncryptWriter

func NewEncryptWriter(key []byte, context string, dst io.Writer) (io.WriteCloser, error)

NewEncryptWriter returns a WriteCloser that encrypts data written to it and writes the ciphertext to dst.

The key must be 16 bytes long. The context is an optional string that is included in the key derivation and commitment, and can be used to bind the ciphertext to a specific context (e.g. a filename or a user ID).

The caller must always call the Close method on the returned WriteCloser to flush the final chunk.

func PlaintextSize

func PlaintextSize(ciphertextSize int64) (int64, error)

PlaintextSize returns the size of the plaintext corresponding to a given ciphertext size, or an error if the ciphertext size is invalid.