shadowaead

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 Pack(dst, plaintext []byte, ciph Cipher) ([]byte, error)
• func Unpack(dst, pkt []byte, ciph Cipher) ([]byte, error)
• type Cipher
  • func AESGCM(psk []byte) (Cipher, error)
  • func Chacha20Poly1305(psk []byte) (Cipher, error)
• type KeySizeError
  • func (e KeySizeError) Error() string

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 NewConn

func NewConn(c net.Conn, ciph Cipher) net.Conn

NewConn wraps a stream-oriented net.Conn with cipher.

func NewPacketConn

func NewPacketConn(c net.PacketConn, ciph Cipher) net.PacketConn

NewPacketConn wraps a net.PacketConn with cipher

func Pack

func Pack(dst, plaintext []byte, ciph Cipher) ([]byte, error)

Pack encrypts plaintext using Cipher with a randomly generated salt and returns a slice of dst containing the encrypted packet and any error occurred. Ensure len(dst) >= ciph.SaltSize() + len(plaintext) + aead.Overhead().

func Unpack

func Unpack(dst, pkt []byte, ciph Cipher) ([]byte, error)

Unpack decrypts pkt using Cipher and returns a slice of dst containing the decrypted payload and any error occurred. Ensure len(dst) >= len(pkt) - aead.SaltSize() - aead.Overhead().

Types

type Cipher

type Cipher interface {
	KeySize() int
	SaltSize() int
	Encrypter(salt []byte) (cipher.AEAD, error)
	Decrypter(salt []byte) (cipher.AEAD, error)
}

func AESGCM

func AESGCM(psk []byte) (Cipher, error)

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

func Chacha20Poly1305(psk []byte) (Cipher, error)

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