cipherio

README

cipherio

This Golang package allows to use block ciphers with io.Reader and io.Writer.

Golang already provides io.Reader and io.Writer implementations for cipher.Stream, but not for cipher.BlockMode (such as AES-CBC). The purpose of this package is to fill the gap.

Block ciphers require data size to be a multiple of the block size. The io.Reader and io.Writer implementations found here can either enforce this requirement or automatically apply a user-defined padding.

This package has been written with performance in mind: buffering and copies are avoided as much as possible.

Documentation

Overview

Package cipherio allows to use block ciphers with io.Reader and io.Writer.

Golang already provides io.Reader and io.Writer implementations for cipher.Stream, but not for cipher.BlockMode (such as AES-CBC). The purpose of this package is to fill the gap.

Block ciphers require data size to be a multiple of the block size. The io.Reader and io.Writer implementations found here can either enforce this requirement or automatically apply a user-defined padding.

This package has been written with performance in mind: buffering and copies are avoided as much as possible.

Index

• Variables
• func NewBlockReader(src io.Reader, blockMode cipher.BlockMode) io.Reader
• func NewBlockReaderWithPadding(src io.Reader, blockMode cipher.BlockMode, padding Padding) io.Reader
• func NewBlockWriter(dst io.Writer, blockMode cipher.BlockMode) io.WriteCloser
• func NewBlockWriterWithPadding(dst io.Writer, blockMode cipher.BlockMode, padding Padding) io.WriteCloser
• type Padding
• type PaddingFunc
  • func (p PaddingFunc) Fill(dst []byte)

Variables

var BitPadding = PaddingFunc(bitPadding)

BitPadding fills an incomplete block with 0x80 followed by zeroes.

This is defined by ISO/IEC 9797-1 as Padding Method 2 and is also known as ISO padding.

var PKCS7Padding = PaddingFunc(pkcs7Padding)

PKCS7Padding fills an incomplete block by repeating the total number of padding bytes.

PKCS#7 is described by RFC 5652.

WARNING: this padding method MUST NOT be used with a block size larger than 256 bytes.

var ZeroPadding = PaddingFunc(zeroPadding)

ZeroPadding fills an incomplete block with zeroes.

Functions

func NewBlockReader

func NewBlockReader(src io.Reader, blockMode cipher.BlockMode) io.Reader

NewBlockReader wraps the given Reader to add on-the-fly encryption or decryption using the given BlockMode.

Data must be aligned to the cipher block size: ErrUnexpectedEOF is returned if EOF is reached in the middle of a block.

This Reader avoids buffering and copies as much as possible. A call to Read leads to at most one Read from the wrapped Reader. Unless the destination buffer is smaller than BlockSize, (en|de)cryption happens inplace within it.

There is no dynamic allocation: an internal buffer of BlockSize bytes is used to store both incomplete blocks (not yet (en|de)crypted) and partially read blocks (already (en|de)crypted).

The wrapped Reader is guaranteed to never be consumed beyond the last requested block. This means that it is safe to stop reading from this Reader at a block boundary and then resume reading from the wrapped Reader for another purpose.

func NewBlockReaderWithPadding

func NewBlockReaderWithPadding(src io.Reader, blockMode cipher.BlockMode, padding Padding) io.Reader

NewBlockReaderWithPadding is similar to NewBlockReader, except that any incomplete block is filled with the given padding instead of returning ErrUnexpectedEOF.

func NewBlockWriter

func NewBlockWriter(dst io.Writer, blockMode cipher.BlockMode) io.WriteCloser

NewBlockWriter wraps the given Writer to add on-the-fly encryption or decryption using the given BlockMode.

Data must be aligned to the cipher block size: ErrUnexpectedEOF is returned if Close is called in the middle of a block.

This Writer allocates an internal buffer of 1024 blocks, which is freed when an error is encountered or when Close is called. Other than that, there is no dynamic allocation.

Close must be called at least once. After that, Close becomes a no-op and Write must not be called anymore.

func NewBlockWriterWithPadding

func NewBlockWriterWithPadding(dst io.Writer, blockMode cipher.BlockMode, padding Padding) io.WriteCloser

NewBlockWriterWithPadding is similar to NewBlockWriter, except that Close fills any incomplete block with the given padding instead of returning ErrUnexpectedEOF.

Types

type Padding

type Padding interface {
	Fill(dst []byte)
}

Padding defines how to fill an incomplete block.

type PaddingFunc

type PaddingFunc func(dst []byte)

PaddingFunc allows to implement the Padding interface with a padding function.

func (PaddingFunc) Fill

func (p PaddingFunc) Fill(dst []byte)

Fill an incomplete block.