Documentation ¶
Overview ¶
Package shadowaead implements a simple AEAD-protected secure protocol.
In general, there are two types of connections: stream-oriented and packet-oriented. Stream-oriented connections (e.g. TCP) assume reliable and orderly delivery of bytes. Packet-oriented connections (e.g. UDP) assume unreliable and out-of-order delivery of packets, where each packet is either delivered intact or lost.
An encrypted stream starts with a random salt to derive a session key, followed by any number of encrypted records. Each encrypted record has the following structure:
[encrypted payload length] [payload length tag] [encrypted payload] [payload tag]
Payload length is 2-byte unsigned big-endian integer capped at 0x3FFF (16383). The higher 2 bits are reserved and must be set to zero. The first AEAD encrypt/decrypt operation uses a counting nonce starting from 0. After each encrypt/decrypt operation, the nonce is incremented by one as if it were an unsigned little-endian integer.
Each encrypted packet transmitted on a packet-oriented connection has the following structure:
[random salt] [encrypted payload] [payload tag]
The salt is used to derive a subkey to initiate an AEAD. Packets are encrypted/decrypted independently using zero nonce.
In both stream-oriented and packet-oriented connections, length of nonce and tag varies depending on which AEAD is used. Salt should be at least 16-byte long.
Index ¶
- Variables
- func NewConn(c net.Conn, ciph Cipher) net.Conn
- func NewPacketConn(c net.PacketConn, ciph Cipher) net.PacketConn
- func NewReader(r io.Reader, aead cipher.AEAD) io.Reader
- func NewWriter(w io.Writer, aead cipher.AEAD) io.Writer
- func Pack(dst, plaintext []byte, ciph Cipher) ([]byte, error)
- func Unpack(dst, pkt []byte, ciph Cipher) ([]byte, error)
- type Cipher
- type KeySizeError
Constants ¶
This section is empty.
Variables ¶
var ErrRepeatedSalt = errors.New("repeated salt detected")
ErrRepeatedSalt means detected a reused salt
var ErrShortPacket = errors.New("short packet")
ErrShortPacket means that the packet is too short for a valid encrypted packet.
Functions ¶
func NewPacketConn ¶
func NewPacketConn(c net.PacketConn, ciph Cipher) net.PacketConn
NewPacketConn wraps a net.PacketConn with cipher
Types ¶
type Cipher ¶
type Cipher interface { KeySize() int SaltSize() int Encrypter(salt []byte) (cipher.AEAD, error) Decrypter(salt []byte) (cipher.AEAD, error) }
func AESGCM ¶
AESGCM creates a new Cipher with a pre-shared key. len(psk) must be one of 16, 24, or 32 to select AES-128/196/256-GCM.
func Chacha20Poly1305 ¶
Chacha20Poly1305 creates a new Cipher with a pre-shared key. len(psk) must be 32.
type KeySizeError ¶
type KeySizeError int
func (KeySizeError) Error ¶
func (e KeySizeError) Error() string