framing

Documentation

Overview

Package framing implements the obfs4 link framing and cryptography.

The ObfsEncoder/ObfsDecoder shared secret format is:

uint8_t[32] NaCl secretbox key
uint8_t[16] NaCl Nonce prefix
uint8_t[16] SipHash-2-4 key (used to obfsucate length)
uint8_t[8]  SipHash-2-4 IV

The frame format is:

uint16_t length (obfsucated, big endian)
NaCl secretbox (Poly1305/XSalsa20) containing:
  uint8_t[16] tag (Part of the secretbox construct)
  uint8_t[]   payload

The length field is length of the NaCl secretbox XORed with the truncated SipHash-2-4 digest ran in OFB mode.

Initialize K, IV[0] with values from the shared secret.
On each packet, IV[n] = H(K, IV[n - 1])
mask[n] = IV[n][0:2]
obfsLen = length ^ mask[n]

The NaCl secretbox (Poly1305/XSalsa20) nonce format is:

uint8_t[24] prefix (Fixed)
uint64_t    counter (Big endian)

The counter is initialized to 1, and is incremented on each frame. Since the protocol is designed to be used over a reliable medium, the nonce is not transmitted over the wire as both sides of the conversation know the prefix and the initial counter value. It is imperative that the counter does not wrap, and sessions MUST terminate before 2^64 frames are sent.

Index

• Constants
• Variables
• type ObfsDecoder
  • func NewObfsDecoder(key []byte) *ObfsDecoder
• type ObfsEncoder
  • func NewObfsEncoder(key []byte) *ObfsEncoder

Constants

const (

	// FrameOverhead is the length of the framing overhead.
	FrameOverhead = f.LengthLength + secretbox.Overhead

	// MaximumFramePayloadLength is the length of the maximum allowed payload
	// per frame.
	MaximumFramePayloadLength = f.MaximumSegmentLength - FrameOverhead

	// KeyLength is the length of the ObfsEncoder/ObfsDecoder secret key.
	KeyLength = keyLength + noncePrefixLength + drbg.SeedLength
)

const (
	PacketTypePayload = iota
	PacketTypePrngSeed
)

Variables

var ErrNonceCounterWrapped = errors.New("framing: Nonce counter wrapped")

Error returned when the NaCl secretbox nonce's counter wraps (FATAL).

Types

type ObfsDecoder

type ObfsDecoder struct {
	f.BaseDecoder

	PacketOverhead int
	PrngRegen      prngRegenFunc
	// contains filtered or unexported fields
}

ObfsDecoder is a BaseDecoder instance.

func NewObfsDecoder

func NewObfsDecoder(key []byte) *ObfsDecoder

NewObfsDecoder creates a new ObfsDecoder instance. It must be supplied a slice containing exactly KeyLength bytes of keying material.

type ObfsEncoder

type ObfsEncoder struct {
	f.BaseEncoder

	PacketOverhead int
	// contains filtered or unexported fields
}

ObfsEncoder is a frame encoder instance.

func NewObfsEncoder

func NewObfsEncoder(key []byte) *ObfsEncoder

NewObfsEncoder creates a new ObfsEncoder instance. It must be supplied a slice containing exactly KeyLength bytes of keying material.