Documentation ¶
Overview ¶
Package sio implements a provable secure authenticated encryption scheme for continuous byte streams.
Index ¶
- Constants
- type Algorithm
- type DecReader
- type DecReaderAt
- type DecWriter
- type EncReader
- type EncWriter
- type Stream
- func (s *Stream) DecryptReader(r io.Reader, nonce, associatedData []byte) *DecReader
- func (s *Stream) DecryptReaderAt(r io.ReaderAt, nonce, associatedData []byte) *DecReaderAt
- func (s *Stream) DecryptWriter(w io.Writer, nonce, associatedData []byte) *DecWriter
- func (s *Stream) EncryptReader(r io.Reader, nonce, associatedData []byte) *EncReader
- func (s *Stream) EncryptWriter(w io.Writer, nonce, associatedData []byte) *EncWriter
- func (s *Stream) NonceSize() int
- func (s *Stream) Overhead(size int64) int64
Examples ¶
Constants ¶
const ( // MaxBufSize is the maximum buffer size for streams. MaxBufSize = (1 << 24) - 1 // BufSize is the recommended buffer size for streams. BufSize = 1 << 14 )
const ( // NotAuthentic is returned when the decryption of a data stream fails. // It indicates that the encrypted data is invalid - i.e. it has been // (maliciously) modified. NotAuthentic errorType = "sio: data is not authentic" // ErrExceeded is returned when no more data can be encrypted / // decrypted securely. It indicates that the data stream is too // large to be encrypted / decrypted with a single key-nonce // combination. // // It depends on the buffer size how many bytes can be // encrypted / decrypted securely using the same key-nonce // combination. For BufSize the limit is ~64 TiB. ErrExceeded errorType = "sio: data limit exceeded" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Algorithm ¶ added in v0.3.0
type Algorithm string
Algorithm specifies an AEAD algorithm that can be used to en/decrypt data streams.
Its main purpose is to simplify code that wants to use commonly used AEAD algorithms, like AES-GCM, by providing a way to directly create Streams from secret keys.
const ( AES_128_GCM Algorithm = "AES-128-GCM" // The secret key must be 16 bytes long. See: https://golang.org/pkg/crypto/cipher/#NewGCM AES_256_GCM Algorithm = "AES-256-GCM" // The secret key must be 32 bytes long. See: https://golang.org/pkg/crypto/cipher/#NewGCM ChaCha20Poly1305 Algorithm = "ChaCha20-Poly1305" // The secret key must be 32 bytes long. See: https://godoc.org/golang.org/x/crypto/chacha20poly1305#New XChaCha20Poly1305 Algorithm = "XChaCha20-Poly1305" // The secret key must be 32 bytes long. See: https://godoc.org/golang.org/x/crypto/chacha20poly1305#NewX )
The constants above specify concrete AEAD algorithms that can be used to encrypt and decrypt data streams.
For example, you can create a new Stream using AES-GCM like this:
stream, err := sio.AES_128_GCM.Stream(key)
type DecReader ¶
type DecReader struct {
// contains filtered or unexported fields
}
A DecReader decrypts and verifies everything it reads from an underlying io.Reader. A DecReader never returns invalid (i.e. not authentic) data.
Example ¶
// Use the key used to encrypt the data. (See e.g. the EncReader example). // Obviously don't use this example key for anything real. key, _ := hex.DecodeString("ffb0823fcab82a983e1725e003c702252ef4fc7054796b3c23d08aa189f662c9") block, _ := aes.NewCipher(key) gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) var ( // Use the nonce value using during encryption. // (See e.g. the EncWriter example). nonce []byte = make([]byte, stream.NonceSize()) // Use the associated data using during encryption. // (See e.g. the EncWriter example). associatedData []byte = nil ) ciphertext := hex.NewDecoder(strings.NewReader("9f54ed8df9cffaff02eddb479b95fd3bed9391758a4f81376cfadd7f8c00")) r := stream.DecryptReader(ciphertext, nonce, associatedData) // Reading from r returns the original plaintext (or an error). if _, err := ioutil.ReadAll(r); err != nil { if err == sio.NotAuthentic { // Read data is not authentic -> ciphertext has been modified. // TODO: error handling panic(err) } }
Output:
func (*DecReader) Read ¶
Read behaves like specified by the io.Reader interface. In particular, Read reads up to len(p) decrypted bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered while reading from the underlying io.Reader.
When Read fails to decrypt some data returned by the underlying io.Reader it returns NotAuthentic. This error indicates that the encrypted data has been (maliciously) modified.
When Read cannot decrypt more bytes securely it returns ErrExceeded. However, this can only happen when the underlying io.Reader returns valid but too many encrypted bytes. Therefore, ErrExceeded indicates a misbehaving producer of encrypted data.
func (*DecReader) ReadByte ¶
ReadByte behaves as specified by the io.ByteReader interface. In particular, ReadByte returns the next decrypted byte or any error encountered.
When ReadByte fails to decrypt the next byte returned by the underlying io.Reader it returns NotAuthentic. This error indicates that the encrypted byte has been (maliciously) modified.
When Read cannot decrypt one more byte securely it returns ErrExceeded. However, this can only happen when the underlying io.Reader returns valid but too many encrypted bytes. Therefore, ErrExceeded indicates a misbehaving producer of encrypted data.
func (*DecReader) WriteTo ¶
WriteTo behaves as specified by the io.WriterTo interface. In particular, WriteTo writes decrypted data to w until either there's no more data to write, an error occurs or the encrypted data is invalid.
When WriteTo fails to decrypt some data it returns NotAuthentic. This error indicates that the encrypted bytes has been (maliciously) modified.
When WriteTo cannot decrypt any more bytes securely it returns ErrExceeded. However, this can only happen when the underlying io.Reader returns valid but too many encrypted bytes. Therefore, ErrExceeded indicates a misbehaving producer of encrypted data.
type DecReaderAt ¶
type DecReaderAt struct {
// contains filtered or unexported fields
}
A DecReaderAt decrypts and verifies everything it reads from an underlying io.ReaderAt. A DecReaderAt never returns invalid (i.e. not authentic) data.
Example ¶
// Use the key used to encrypt the data. (See e.g. the EncReader example). // Obviously don't use this example key for anything real. key, _ := hex.DecodeString("ffb0823fcab82a983e1725e003c702252ef4fc7054796b3c23d08aa189f662c9") block, _ := aes.NewCipher(key) gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) var ( // Use the nonce value using during encryption. // (See e.g. the EncWriter example). nonce []byte = make([]byte, stream.NonceSize()) // Use the associated data using during encryption. // (See e.g. the EncWriter example). associatedData []byte = nil ) rawBytes, _ := hex.DecodeString("9f54ed8df9cffaff02eddb479b95fd3bed9391758a4f81376cfadd7f8c00") ciphertext := bytes.NewReader(rawBytes) r := stream.DecryptReaderAt(ciphertext, nonce, associatedData) section := io.NewSectionReader(r, 5, 9) // Read the 'plaintext' substring from 'some plaintext' // Reading from section returns the original plaintext (or an error). if _, err := ioutil.ReadAll(section); err != nil { if err == sio.NotAuthentic { // Read data is not authentic -> ciphertext has been modified. // TODO: error handling panic(err) } }
Output:
func (*DecReaderAt) ReadAt ¶
func (r *DecReaderAt) ReadAt(p []byte, offset int64) (int, error)
ReadAt behaves like specified by the io.ReaderAt interface. In particular, ReadAt reads len(p) decrypted bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered while reading from the underlying io.Reader. When ReadAt returns n < len(p), it returns a non-nil error explaining why more bytes were not returned.
When ReadAt fails to decrypt some data returned by the underlying io.ReaderAt it returns NotAuthentic. This error indicates that the encrypted data has been (maliciously) modified.
When ReadAt cannot decrypt more bytes securely it returns ErrExceeded. However, this can only happen when the underlying io.ReaderAt returns valid but too many encrypted bytes. Therefore, ErrExceeded indicates a misbehaving producer of encrypted data.
type DecWriter ¶
type DecWriter struct {
// contains filtered or unexported fields
}
A DecWriter decrypts and verifies everything it writes to an underlying io.Writer. It never writes invalid (i.e. not authentic) data to the underlying data stream.
A DecWriter must always be closed and the returned error must be checked. Otherwise, the decrypted data written to the underlying io.Writer would be incomplete. Also, no more data must be written to a closed DecWriter.
Closing a DecWriter also closes the underlying io.Writer if it implements io.Closer.
Example ¶
// Use the key used to encrypt the data. (See e.g. the EncWriter example). // Obviously don't use this example key for anything real. key, _ := hex.DecodeString("ffb0823fcab82a983e1725e003c702252ef4fc7054796b3c23d08aa189f662c9") block, _ := aes.NewCipher(key) gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) var ( // Use the nonce value using during encryption. // (See e.g. the EncWriter example). nonce []byte = make([]byte, stream.NonceSize()) // Use the associated data using during encryption. // (See e.g. the EncWriter example). associatedData []byte = nil ) plaintext := bytes.NewBuffer(nil) w := stream.DecryptWriter(plaintext, nonce, associatedData) defer func() { if err := w.Close(); err != nil { if err == sio.NotAuthentic { // During Close() the DecWriter may detect unauthentic data -> decryption error. panic(err) // TODO: error handling } panic(err) // TODO: error handling } }() ciphertext, _ := hex.DecodeString("9f54ed8df9cffaff02eddb479b95fd3bed9391758a4f81376cfadd7f8c00") // Writing ciphertext to w writes decrypted and verified data to // the underlying io.Writer (i.e. the plaintext *bytes.Buffer) or // returns an error. if _, err := w.Write(ciphertext); err != nil { if err == sio.NotAuthentic { // Read data is not authentic -> ciphertext has been modified. // TODO: error handling panic(err) } }
Output:
func (*DecWriter) Close ¶
Close writes any remaining decrypted bytes to the underlying io.Writer and returns any error encountered. If the underlying io.Writer implements Close it closes the underlying data stream as well.
It is important to check the returned error since Close may return NotAuthentic indicating that some remaining bytes are invalid encrypted data.
It safe to call close multiple times.
func (*DecWriter) ReadFrom ¶
ReadFrom behaves as specified by the io.ReadFrom interface. In particular, ReadFrom reads data from r until io.EOF or any error occurs, decrypts the data and writes the decrypted data to the underlying io.Writer. ReadFrom does not close the DecWriter nor the underlying data stream.
ReadFrom returns the number of bytes read and any error except io.EOF. When ReadFrom fails to decrypt some data it returns NotAuthentic. This error indicates that some encrypted bytes have been (maliciously) modified.
When ReadFrom cannot decrypt any more data securely it returns ErrExceeded. However, the DecWriter must still be closed to complete the decryption and flush any remaining data to the underlying data stream.
ReadFrom must not be called once the DecWriter has been closed.
func (*DecWriter) Write ¶
Write behaves as specified by the io.Writer interface. In particular, Write decrypts len(p) bytes from p and writes the decrypted bytes to the underlying data stream. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early.
When Write fails to decrypt some data it returns NotAuthentic. This error indicates that the encrypted bytes have been (maliciously) modified.
When Write cannot decrypt any more bytes securely it returns ErrExceeded. However, the DecWriter must still be closed to complete the decryption and flush any remaining data to the underlying data stream.
Write must not be called once the DecWriter has been closed.
func (*DecWriter) WriteByte ¶
WriteByte behaves as specified by the io.ByteWriter interface. In particular, WriteByte decrypts b and writes the decrypted byte to the underlying data stream.
When WriteByte fails to decrypt b it returns NotAuthentic. This error indicates that some encrypted bytes have been (maliciously) modified.
When WriteByte cannot decrypt one more byte securely it returns ErrExceeded. However, the DecWriter must still be closed to complete the decryption and flush any remaining data to the underlying data stream.
WriteByte must not be called once the DecWriter has been closed.
type EncReader ¶
type EncReader struct {
// contains filtered or unexported fields
}
An EncReader encrypts and authenticates everything it reads from an underlying io.Reader.
Example ¶
// Use an unique key per data stream. For example derive one // from a password using a suitable package like argon2 or // from a master key using e.g. HKDF. // Obviously don't use this example key for anything real. key, _ := hex.DecodeString("ffb0823fcab82a983e1725e003c702252ef4fc7054796b3c23d08aa189f662c9") block, _ := aes.NewCipher(key) gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) var ( // Use a unique nonce per key. If you choose an unique key // you can also set the nonce to all zeros. (What to prefer // depends on the application). nonce []byte = make([]byte, stream.NonceSize()) // If you want to bind additional data to the ciphertext // (e.g. a file name to prevent renaming / moving the file) // set the associated data. But be aware that the associated // data is not encrypted (only authenticated) and must be // available when decrypting the ciphertext again. associatedData []byte = nil ) plaintext := strings.NewReader("some plaintext") r := stream.EncryptReader(plaintext, nonce, associatedData) // Reading from r returns encrypted and authenticated data. ioutil.ReadAll(r)
Output:
func (*EncReader) Read ¶
Read behaves as specified by the io.Reader interface. In particular, Read reads up to len(p) encrypted bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered while reading from the underlying io.Reader.
When Read cannot encrypt any more bytes securely it returns ErrExceeded.
func (*EncReader) ReadByte ¶
ReadByte behaves as specified by the io.ByteReader interface. In particular, ReadByte returns the next encrypted byte or any error encountered.
When ReadByte cannot encrypt one more byte securely it returns ErrExceeded.
func (*EncReader) WriteTo ¶
WriteTo behaves as specified by the io.WriterTo interface. In particular, WriteTo writes encrypted data to w until either there's no more data to write, an error occurs or no more data can be encrypted securely. When WriteTo cannot encrypt more data securely it returns ErrExceeded.
type EncWriter ¶
type EncWriter struct {
// contains filtered or unexported fields
}
An EncWriter encrypts and authenticates everything it writes to an underlying io.Writer.
An EncWriter must always be closed successfully. Otherwise, the encrypted data written to the underlying io.Writer would be incomplete. Also, no more data must be written to a closed EncWriter.
Closing an EncWriter also closes the underlying io.Writer if it implements io.Closer.
Example ¶
// Use an unique key per data stream. For example derive one // from a password using a suitable package like argon2 or // from a master key using e.g. HKDF. // Obviously don't use this example key for anything real. key, _ := hex.DecodeString("ffb0823fcab82a983e1725e003c702252ef4fc7054796b3c23d08aa189f662c9") block, _ := aes.NewCipher(key) gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) var ( // Use a unique nonce per key. If you choose an unique key // you can also set the nonce to all zeros. (What to prefer // depends on the application). nonce []byte = make([]byte, stream.NonceSize()) // If you want to bind additional data to the ciphertext // (e.g. a file name to prevent renaming / moving the file) // set the associated data. But be aware that the associated // data is not encrypted (only authenticated) and must be // available when decrypting the ciphertext again. associatedData []byte = nil ) ciphertext := bytes.NewBuffer(nil) // You can also use the plaintext size and stream.Overhead() to avoid re-allocation. w := stream.EncryptWriter(ciphertext, nonce, associatedData) defer func() { if err := w.Close(); err != nil { // The EncWriter must be closed to complete the encryption. panic(err) // TODO: error handling } }() // Writing plaintext to w writes encrypted and authenticated data to // the underlying io.Writer (i.e. the ciphertext *bytes.Buffer) if _, err := io.WriteString(w, "some plaintext"); err != nil { // TODO: error handling }
Output:
func (*EncWriter) Close ¶
Close writes any remaining encrypted bytes to the underlying io.Writer and returns any error encountered. If the underlying io.Writer implements Close it closes the underlying data stream as well.
It safe to call close multiple times.
func (*EncWriter) ReadFrom ¶
ReadFrom behaves as specified by the io.ReadFrom interface. In particular, ReadFrom reads data from r until io.EOF or any error occurs, encrypts the data and writes the encrypted data to the underlying io.Writer. ReadFrom does not close the EncWriter nor the underlying data stream.
ReadFrom returns the number of bytes read and any error except io.EOF.
When ReadFrom cannot encrypt any more data securely it returns ErrExceeded. However, the EncWriter must still be closed to complete the encryption and flush any remaining data to the underlying data stream.
ReadFrom must not be called once the EncWriter has been closed.
func (*EncWriter) Write ¶
Write behaves as specified by the io.Writer interface. In particular, Write encrypts len(p) bytes from p and writes the encrypted bytes to the underlying data stream. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early.
When Write cannot encrypt any more bytes securely it returns ErrExceeded. However, the EncWriter must still be closed to complete the encryption and flush any remaining data to the underlying data stream.
Write must not be called once the EncWriter has been closed.
func (*EncWriter) WriteByte ¶
WriteByte behaves as specified by the io.ByteWriter interface. In particular, WriteByte encrypts b and writes the encrypted byte to the underlying data stream.
When WriteByte cannot encrypt one more byte securely it returns ErrExceeded. However, the EncWriter must still be closed to complete the encryption and flush any remaining data to the underlying data stream.
WriteByte must not be called once the EncWriter has been closed.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
A Stream encrypts or decrypts continuous byte streams.
func NewStream ¶
NewStream creates a new Stream that encrypts or decrypts data streams with the cipher using bufSize large chunks. Therefore, the bufSize must be the same for encryption and decryption. If you don't have special requirements just use the default BufSize.
The cipher must support a NonceSize() >= 4 and the bufSize must be between 1 (inclusive) and MaxBufSize (inclusive).
Example (AES128GCM) ¶
// Load your secret key from a safe place. You should use a unique key // per data stream since the nonce size of `Stream` (with AES-128-GCM) is // to short for chosing a nonce at random (risk of repeating the // nonce is too high). // Obviously don't use this example key for anything real. // If you want to convert a passphrase to a key, use a suitable // package like argon2 or scrypt. key, _ := hex.DecodeString("4c4d737f2199f3ccb13d2c81dfe38eb8") stream, err := sio.AES_128_GCM.Stream(key) if err != nil { panic(err) // TODO: error handling } // Print the nonce size for Stream (with AES-128-GCM) and the overhead added // when encrypting a 1 MiB data stream. fmt.Printf("NonceSize: %d, Overhead: %d", stream.NonceSize(), stream.Overhead(1024*1024))
Output: NonceSize: 8, Overhead: 1024
Example (AES192GCM) ¶
// Load your secret key from a safe place. You should use a unique key // per data stream since the nonce size of `Stream` (with AES-192-GCM) is // to short for chosing a nonce at random (risk of repeating the // nonce is too high). // Obviously don't use this example key for anything real. // If you want to convert a passphrase to a key, use a suitable // package like argon2 or scrypt. key, _ := hex.DecodeString("fe6165e714125dc3d84d3349f9e3020430ce9d77e0a1f2c0") block, err := aes.NewCipher(key) if err != nil { panic(err) // TODO: error handling } gcm, _ := cipher.NewGCM(block) stream := sio.NewStream(gcm, sio.BufSize) // Print the nonce size for Stream (with AES-192-GCM) and the overhead added // when encrypting a 1 MiB data stream. fmt.Printf("NonceSize: %d, Overhead: %d", stream.NonceSize(), stream.Overhead(1024*1024))
Output: NonceSize: 8, Overhead: 1024
Example (AES256GCM) ¶
// Load your secret key from a safe place. You should use a unique key // per data stream since the nonce size of `Stream` (with AES-256-GCM) is // to short for chosing a nonce at random (risk of repeating the // nonce is too high). // Obviously don't use this example key for anything real. // If you want to convert a passphrase to a key, use a suitable // package like argon2 or scrypt. key, _ := hex.DecodeString("5b48c6945ae03a93ecc20e38305d2cbe4a177133d83bf4773f1f3be636e2cc4b") stream, err := sio.AES_256_GCM.Stream(key) if err != nil { panic(err) // TODO: error handling } // Print the nonce size for Stream (with AES-256-GCM) and the overhead added // when encrypting a 1 MiB data stream. fmt.Printf("NonceSize: %d, Overhead: %d", stream.NonceSize(), stream.Overhead(1024*1024))
Output: NonceSize: 8, Overhead: 1024
Example (XChaCha20Poly1305) ¶
// Load your secret key from a safe place. You may reuse it for // en/decrypting multiple data streams. (XChaCha20-Poly1305 nonce // values are large enough to be chosen at random without risking // to select a nonce twice - probability is negligible). // // Obviously don't use this example key for anything real. // If you want to convert a passphrase to a key, use a suitable // package like argon2 or scrypt - or take a look at the sio/sioutil // package. key, _ := hex.DecodeString("f230e700c4f120b623b84ac26cbcb5ae926f44f36589e63745a46ae0ca47137d") stream, err := sio.XChaCha20Poly1305.Stream(key) if err != nil { panic(err) // TODO: error handling } // Print the nonce size for Stream (with XChaCha20-Poly1305) and the // overhead added when encrypting a 1 MiB data stream. fmt.Printf("NonceSize: %d, Overhead: %d", stream.NonceSize(), stream.Overhead(1024*1024))
Output: NonceSize: 20, Overhead: 1024
func (*Stream) DecryptReader ¶
DecryptReader returns a new DecReader that wraps r and decrypts and verifies everything it reads from r.
The nonce must be Stream.NonceSize() bytes long and must match the value used when encrypting the data stream.
The associatedData must match the value used when encrypting the data stream.
func (*Stream) DecryptReaderAt ¶
func (s *Stream) DecryptReaderAt(r io.ReaderAt, nonce, associatedData []byte) *DecReaderAt
DecryptReaderAt returns a new DecReaderAt that wraps r and decrypts and verifies everything it reads from r.
The nonce must be Stream.NonceSize() bytes long and must match the value used when encrypting the data stream.
The associatedData must match the value used when encrypting the data stream.
func (*Stream) DecryptWriter ¶
DecryptWriter returns a new DecWriter that wraps w and decrypts and verifies everything before writing it to w.
The nonce must be Stream.NonceSize() bytes long and must match the value used when encrypting the data stream.
The associatedData must match the value used when encrypting the data stream.
func (*Stream) EncryptReader ¶
EncryptReader returns a new EncReader that wraps r and encrypts and authenticates it reads from r.
The nonce must be Stream.NonceSize() bytes long and unique for the same key. The same nonce must be provided when decrypting the data stream.
The associatedData is only authenticated but not encrypted and not written to w. Instead, the same associatedData must be provided when decrypting the data stream again. It is safe to set:
associatedData = nil
func (*Stream) EncryptWriter ¶
EncryptWriter returns a new EncWriter that wraps w and encrypts and authenticates everything before writing it to w.
The nonce must be Stream.NonceSize() bytes long and unique for the same key. The same nonce must be provided when decrypting the data stream.
The associatedData is only authenticated but not encrypted and not written to w. Instead, the same associatedData must be provided when decrypting the data stream again. It is safe to set:
associatedData = nil
func (*Stream) NonceSize ¶
NonceSize returns the size of the unique nonce that must be provided when encrypting or decrypting a data stream.
func (*Stream) Overhead ¶
Overhead returns the overhead added when encrypting a data stream. For a plaintext stream of a non-negative size, the size of an encrypted data stream will be:
encSize = size + stream.Overhead(size) // 0 <= size <= (2³² - 1) * bufSize 0 = stream.Overhead(size) // size > (2³² - 1) * bufSize -1 = stream.Overhead(size) // size < 0
In general, the size of an encrypted data stream is always greater than the size of the corresponding plaintext stream. If size is too large (i.e. greater than (2³² - 1) * bufSize) then Overhead returns 0. If size is negative Overhead returns -1.