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 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 Conn
  • func NewConn(c net.Conn, ciph Cipher) *Conn
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) ReadFrom(r io.Reader) (int64, error)
  • func (c *Conn) Write(b []byte) (int, error)
  • func (c *Conn) WriteTo(w io.Writer) (int64, error)
• type KeySizeError
  • func (e KeySizeError) Error() string
• type PacketConn
  • func NewPacketConn(c net.PacketConn, ciph Cipher) *PacketConn
  • func (c *PacketConn) ReadFrom(b []byte) (int, net.Addr, error)
  • func (c *PacketConn) WriteTo(b []byte, addr net.Addr) (int, error)
• type Reader
  • func NewReader(r io.Reader, aead cipher.AEAD) *Reader
  • func (r *Reader) Read(p []byte) (int, error)
  • func (r *Reader) WriteTo(w io.Writer) (n int64, err error)
• type Writer
  • func NewWriter(w io.Writer, aead cipher.AEAD) *Writer
  • func (w *Writer) ReadFrom(r io.Reader) (n int64, err error)
  • func (w *Writer) Write(p []byte) (n int, err error)

Variables

var ErrShortPacket = errors.New("short packet")

ErrShortPacket means that the packet is too short for a valid encrypted packet.

var (
	ErrZeroChunk = errors.New("zero chunk")
)

Functions

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 Conn

type Conn struct {
	net.Conn
	Cipher
	// contains filtered or unexported fields
}

func NewConn

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

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

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

func (*Conn) ReadFrom

func (c *Conn) ReadFrom(r io.Reader) (int64, error)

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

func (*Conn) WriteTo

func (c *Conn) WriteTo(w io.Writer) (int64, error)

type KeySizeError

type KeySizeError int

func (KeySizeError) Error

func (e KeySizeError) Error() string

type PacketConn

type PacketConn struct {
	net.PacketConn
	Cipher
}

func NewPacketConn

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

NewPacketConn wraps a net.PacketConn with cipher

func (*PacketConn) ReadFrom

func (c *PacketConn) ReadFrom(b []byte) (int, net.Addr, error)

ReadFrom reads from the embedded PacketConn and decrypts into b.

func (*PacketConn) WriteTo

func (c *PacketConn) WriteTo(b []byte, addr net.Addr) (int, error)

WriteTo encrypts b and write to addr using the embedded PacketConn.

type Reader

type Reader struct {
	io.Reader
	cipher.AEAD
	// contains filtered or unexported fields
}

func NewReader

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

NewReader wraps an io.Reader with authenticated decryption.

func (*Reader) Read

func (r *Reader) Read(p []byte) (int, error)

Read reads from the embedded io.Reader, decrypts and writes to p.

func (*Reader) WriteTo

func (r *Reader) WriteTo(w io.Writer) (n int64, err error)

WriteTo reads from the embedded io.Reader, decrypts and writes to w until there's no more data to write or when an error occurs. Return number of bytes written to w and any error encountered.

type Writer

type Writer struct {
	io.Writer
	cipher.AEAD
	// contains filtered or unexported fields
}

func NewWriter

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

NewWriter wraps an io.Writer with authenticated encryption.

func (*Writer) ReadFrom

func (w *Writer) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom reads from the given io.Reader until EOF or error, encrypts and writes to the embedded io.Writer. Returns number of bytes read from r and any error encountered.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write encrypts p and writes to the embedded io.Writer.