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 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
  • func AESGCM(psk []byte) (Cipher, error)
  • func Chacha20Poly1305(psk []byte) (Cipher, error)
  • func XChacha20Poly1305(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 NewReader

func NewReader(r io.Reader, aead cipher.AEAD) io.Reader

NewReader wraps an io.Reader with AEAD decryption.

func NewWriter

func NewWriter(w io.Writer, aead cipher.AEAD) io.Writer

NewWriter wraps an io.Writer with AEAD encryption.

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.

func XChacha20Poly1305

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

XChacha20Poly1305 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