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
Constants ¶
This section is empty.
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 ¶
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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.
Source Files
Directories