ciphersuite

package
v4.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 6 Imported by: 4

README

Ciphersuite Package

This package defines the public contracts and negotiation metadata for DTLS cipher suites. Built-in record-protection implementations are private to DTLS and live in internal/ciphersuite.

Benchmarking

Implementation benchmarks are excluded from regular test runs. Run all DTLS 1.2 record-protection benchmarks from the repository root with:

go test -tags=bench ./internal/ciphersuite -bench=BenchmarkRecordProtection12 -benchmem

Select an algorithm and operation through the benchmark path, for example:

go test -tags=bench ./internal/ciphersuite \
  -bench='BenchmarkRecordProtection12/GCM/Seal' -benchmem

Standard Go benchmark flags such as -benchtime, -count, -cpuprofile, and -memprofile are supported.

Documentation

Overview

Package ciphersuite defines cipher-suite descriptors, immutable record metadata, protection capabilities, and DTLS record-protection contracts.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidCapabilities reports a malformed cipher suite capabilities.
	ErrInvalidCapabilities = errors.New("invalid cipher suite capabilities")
	// ErrAuthenticationFailed reports that a protected record could not be
	// authenticated.
	ErrAuthenticationFailed = errors.New("record authentication failed")
)

Functions

This section is empty.

Types

type AuthenticationType

type AuthenticationType uint8

AuthenticationType controls the authentication method used by a cipher suite.

const (
	AuthenticationTypeCertificate AuthenticationType = iota + 1
	AuthenticationTypePreSharedKey
	AuthenticationTypeAnonymous
)

AuthenticationType values.

type Capabilities

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

Capabilities is protection metadata for one protocol version.

func NewAEADCapabilities

func NewAEADCapabilities(version protocol.Version, maxPlaintextLen, explicitNonceLen, tagLen, maskSampleLen int) (Capabilities, error)

NewAEADCapabilities constructs capabilities for an AEAD suite.

func NewCBCCapabilities

func NewCBCCapabilities(maxPlaintextLen, macLen, blockLen int) (Capabilities, error)

NewCBCCapabilities constructs capabilities for a MAC-then-encrypt CBC suite.

func (Capabilities) MaskLen

func (c Capabilities) MaskLen() int

MaskLen returns the required ciphertext sample length for record-number masking. It is zero when masking is not applicable.

func (Capabilities) PlaintextLenUpperBound

func (c Capabilities) PlaintextLenUpperBound(protectedLen int) (int, error)

PlaintextLenUpperBound validates protectedLen and returns a checked allocation bound.

func (Capabilities) ProtectedLen

func (c Capabilities) ProtectedLen(plaintextLen int) (int, error)

ProtectedLen returns the exact protected payload length for plaintextLen.

func (Capabilities) SupportsVersion

func (c Capabilities) SupportsVersion(version protocol.Version) bool

SupportsVersion reports whether these capabilities describe version.

func (Capabilities) ValidatePlaintextLen

func (c Capabilities) ValidatePlaintextLen(protectedLen, plaintextLen int) error

ValidatePlaintextLen checks the actual plaintext length returned by a successful Open against the protected length.

func (Capabilities) Version

func (c Capabilities) Version() protocol.Version

Version returns the protocol version supported by the suite.

type ConnectionSuite

type ConnectionSuite interface {
	Suite
	NewConnectionProtection(KeyMaterial) (Protection, error)
}

ConnectionSuite derives protection bound to both directions of a connection.

type EndpointRole

type EndpointRole uint8

EndpointRole identifies the local endpoint for DTLS 1.2 key derivation.

const (
	// EndpointRoleClient derives client write and server read keys.
	EndpointRoleClient EndpointRole = iota + 1
	// EndpointRoleServer derives server write and client read keys.
	EndpointRoleServer
)

type ID

type ID uint16

ID is a registered TLS cipher-suite identifier.

const (
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM              ID = 0xc0ac // nolint: revive,staticcheck
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8            ID = 0xc0ae // nolint: revive,staticcheck
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       ID = 0xc02b // nolint: revive,staticcheck
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         ID = 0xc02f // nolint: revive,staticcheck
	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       ID = 0xc02c // nolint: revive,staticcheck
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         ID = 0xc030 // nolint: revive,staticcheck
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA          ID = 0xc00a // nolint: revive,staticcheck
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            ID = 0xc014 // nolint: revive,staticcheck
	TLS_PSK_WITH_AES_128_CCM                      ID = 0xc0a4 // nolint: revive,staticcheck
	TLS_PSK_WITH_AES_128_CCM_8                    ID = 0xc0a8 // nolint: revive,staticcheck
	TLS_PSK_WITH_AES_256_CCM_8                    ID = 0xc0a9 // nolint: revive,staticcheck
	TLS_PSK_WITH_AES_128_GCM_SHA256               ID = 0x00a8 // nolint: revive,staticcheck
	TLS_PSK_WITH_AES_128_CBC_SHA256               ID = 0x00ae // nolint: revive,staticcheck
	TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256         ID = 0xc037 // nolint: revive,staticcheck
	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ID = 0xcca9 // nolint: revive,staticcheck
	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   ID = 0xcca8 // nolint: revive,staticcheck
	TLS_PSK_WITH_CHACHA20_POLY1305_SHA256         ID = 0xccab // nolint: revive,staticcheck
	TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256   ID = 0xccac // nolint: revive,staticcheck
	TLS_AES_128_GCM_SHA256                        ID = 0x1301 // nolint: revive,staticcheck
	TLS_AES_256_GCM_SHA384                        ID = 0x1302 // nolint: revive,staticcheck
	TLS_CHACHA20_POLY1305_SHA256                  ID = 0x1303 // nolint: revive,staticcheck
)

Supported cipher-suite identifiers.

func (ID) String

func (i ID) String() string

type KeyExchangeAlgorithm

type KeyExchangeAlgorithm uint8

KeyExchangeAlgorithm identifies cipher-suite key exchange requirements.

const (
	KeyExchangeAlgorithmNone KeyExchangeAlgorithm = 0
	KeyExchangeAlgorithmPsk  KeyExchangeAlgorithm = 1 << iota
	KeyExchangeAlgorithmEcdhe
)

KeyExchangeAlgorithm values form a bitmask.

func (KeyExchangeAlgorithm) Has

Has reports whether all bits in v are set.

type KeyMaterial

type KeyMaterial interface {
	MasterSecret() []byte
	ClientRandom() []byte
	ServerRandom() []byte
	Role() EndpointRole
}

KeyMaterial is borrowed while deriving connection-bound protection. Implementations must not modify or retain returned slices.

type Protection

type Protection interface {
	Seal(record Record, plaintext []byte) ([]byte, error)
	// Open authenticates and decrypts protected. It returns
	// ErrAuthenticationFailed for peer-controlled authentication failures.
	// for operational / provider failures it should pick other errors.
	Open(record Record, protected []byte) ([]byte, error)
}

Protection seals and opens records. Implementations treat inputs as read-only and return caller-owned bytes.

type Record

type Record interface {
	// Number returns the version-appropriate nonce number.
	RecordNumber() uint64
	// Data returns owned authentication bytes and validates the supplied record length.
	AuthenticationData(recordLen int) ([]byte, error)
}

Record is the read-only protection view of one record.

type Suite

type Suite interface {
	String() string
	ID() ID
	CertificateType() clientcertificate.Type
	HashFunc() func() hash.Hash
	AuthenticationType() AuthenticationType
	KeyExchangeAlgorithm() KeyExchangeAlgorithm
	ECC() bool
	Capabilities() Capabilities
}

Suite describes a cipher suite without connection-specific key material.

type TrafficProtection

type TrafficProtection interface {
	Protection
	// Mask treats sample as read-only and returns caller-owned bytes.
	Mask(sample []byte) ([]byte, error)
}

TrafficProtection adds record-number masking for generation-bound traffic.

type TrafficSecret

type TrafficSecret interface {
	// Bytes returns the borrowed secret. Implementations must not modify or retain it.
	Bytes() []byte
}

TrafficSecret is borrowed while deriving generation-bound traffic protection.

type TrafficSuite

type TrafficSuite interface {
	Suite
	NewTrafficProtection(TrafficSecret) (TrafficProtection, error)
}

TrafficSuite derives directional, generation-bound traffic protection.

type UsageLimitProvider

type UsageLimitProvider interface {
	UsageLimits() UsageLimits
}

UsageLimitProvider is optional metadata for cipher suites that report recommended key-usage limits in connection statistics.

type UsageLimits

type UsageLimits struct {
	MaxSealedRecords          uint64
	MaxAuthenticationFailures uint64
}

UsageLimits describes advisory per-key recommendations for DTLS. Zero means unspecified.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL