tentp

Documentation

Overview

Package tentp implements the framing layer portion of the Trivial Encrypted Network Transport Protocol, a lightweight XChaCha20 + Poly1305 based authentication/encryption protocol for streams with reliable-in-order delivery semantics.

All security properties are lost if multiple sessions re-use the Encoder/Decoder keys, so don't do that.

This implementation is somewhat different from the draft that Nick M. and I worked on a while ago but the basic ideas and concepts are the same.

Index

• Constants
• Variables
• type Decoder
  • func NewDecoder(key []byte) (*Decoder, error)
  • func NewDecoderFromKDF(kdf io.Reader) (*Decoder, error)
  • func (d *Decoder) DecodeRecordBody(encMsg []byte) (buf []byte, err error)
  • func (d *Decoder) DecodeRecordHdr(encHdr []byte) (cmd byte, want int, err error)
  • func (d *Decoder) Reset()
• type Encoder
  • func NewEncoder(key []byte) (*Encoder, error)
  • func NewEncoderFromKDF(kdf io.Reader) (*Encoder, error)
  • func (e *Encoder) EncodeRecord(cmd byte, msg []byte, padLen int) ([]byte, error)
  • func (e *Encoder) Reset()

Constants

const (
	// KeySize is the size of a Encoder/Decoder key in bytes (56 bytes).
	KeySize = chacha20.KeySize + chacha20.XNonceSize

	// MaxPlaintextRecordSize is the maximum length of a message payload that
	// can be sent per record.  (The length of payload + padding is also
	// limited to this maximum value).
	MaxPlaintextRecordSize = 65535

	// MaxPaddingSize is the maximum length of padding that can be sent per
	// record.  (The length of payload + padding is also limited to this
	// maximum value).
	MaxPaddingSize = 65535

	// FramingOverhead is the amount of constant overhead incurred regardless
	// of payload/padding length (24 bytes).
	FramingOverhead = poly1305.TagSize + recordHeaderSize

	// PayloadOverhead is the amount of *additional* overhead incurred when
	// sending any payload/padding (16 bytes).
	PayloadOverhead = poly1305.TagSize

	// MaxIdealIPv4Size is the "ideal" maximum payload + padding for a single
	// record for an IPv4 connection over Ethernet (1420 bytes).
	MaxIdealIPv4Size = framing.MaxIPv4TcpSize - (FramingOverhead + PayloadOverhead)

	// MaxIdealIPv6Size is the "ideal" maximum payload + padding for a single
	// record for an IPv6 connection over Ethernet (1400 bytes).
	MaxIdealIPv6Size = framing.MaxIPv6TcpSize - (FramingOverhead + PayloadOverhead)
)

Variables

var (
	// ErrInvalidKeySize is the error returned when the key size is invalid.
	ErrInvalidKeySize = errors.New("tentp: invalid key size")

	// ErrMsgSize is the error returned when the message/pad size is invalid.
	ErrMsgSize = errors.New("tentp: invalid msg/pad size")

	// ErrSendSeqNr is the error returned when NSEND is exhausted.
	ErrSendSeqNr = errors.New("tentp: out of send sequence space")

	// ErrHdrSize is the error returned when the header size is invalid.
	ErrHdrSize = errors.New("tentp: invalid hdr size")

	// ErrDecoderState is the error returned when the decoder calls are made
	// in the wrong order (caller bug).
	ErrDecoderState = errors.New("tentp: decoder in invalid state")

	// ErrInvalidTag is the error returned when the MAC verification fails.
	ErrInvalidTag = errors.New("tentp: invalid tag")

	// ErrProtocol is the error returned when the protocol invariants are
	// violated by the peer. (Invalid version, invalid reserved fields).
	ErrProtocol = errors.New("tentp: protocol invariant violation")

	// ErrRecvSeqNr is the error returned when NRECV is exhausted.
	ErrRecvSeqNr = errors.New("tentp: out of recv sequence space")

	// ErrWasReset is the error returned when the Encoder/Decoder are called
	// after the internal state has been obliterated.
	ErrWasReset = errors.New("tentp: attempted encode/decode after Reset")
)

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder is a TENTP frame decoder instance.

func NewDecoder

func NewDecoder(key []byte) (*Decoder, error)

NewDecoder creates a new Decoder instance with the specificed key.

func NewDecoderFromKDF

func NewDecoderFromKDF(kdf io.Reader) (*Decoder, error)

NewDecoderFromKDF creates a new Dcoder instance with material read from a KDF. This is intended to be used with the golang.org/x/crypto SHAKE implementation.

func (*Decoder) DecodeRecordBody

func (d *Decoder) DecodeRecordBody(encMsg []byte) (buf []byte, err error)

DecodeRecordBody decodes a encrypted/authenticated record payload + padding message and returns the payload plaintext. It is possible, and perfectly valid for buf to be nil.

func (*Decoder) DecodeRecordHdr

func (d *Decoder) DecodeRecordHdr(encHdr []byte) (cmd byte, want int, err error)

DecodeRecordHdr decodes a given FramingOverhead length byte slice, and returns the command, and expected payload/padding ciphertext length (including overhead) that must be passed to DecodeRecordBody. If want is 0, the call to DecodeRecordBody may be omitted.

func (*Decoder) Reset

func (d *Decoder) Reset()

Reset clears sensitive data from the Decoder's internal state and irreversably invalidates the instance.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is a TENTP frame encoder instance.

func NewEncoder

func NewEncoder(key []byte) (*Encoder, error)

NewEncoder creates a new Encoder instance with the specificed key.

func NewEncoderFromKDF

func NewEncoderFromKDF(kdf io.Reader) (*Encoder, error)

NewEncoderFromKDF creates a new Encoder instance with material read from a KDF. This is intended to be used with the golang.org/x/crypto SHAKE implementation.

func (*Encoder) EncodeRecord

func (e *Encoder) EncodeRecord(cmd byte, msg []byte, padLen int) ([]byte, error)

EncodeRecord encodes a message with command cmd, message msg, and padLen bytes of padding, and returns the encrypted/authenticated ciphertext.

func (*Encoder) Reset

func (e *Encoder) Reset()

Reset clears sensitive data from the Encoder's internal state and irreversably invalidates the instance.