Documentation
¶
Overview ¶
Package ciphersuite defines cipher-suite descriptors, immutable record metadata, protection capabilities, and DTLS record-protection contracts.
Index ¶
- Variables
- type AuthenticationType
- type Capabilities
- func (c Capabilities) MaskLen() int
- func (c Capabilities) PlaintextLenUpperBound(protectedLen int) (int, error)
- func (c Capabilities) ProtectedLen(plaintextLen int) (int, error)
- func (c Capabilities) SupportsVersion(version protocol.Version) bool
- func (c Capabilities) ValidatePlaintextLen(protectedLen, plaintextLen int) error
- func (c Capabilities) Version() protocol.Version
- type ConnectionSuite
- type EndpointRole
- type ID
- type KeyExchangeAlgorithm
- type KeyMaterial
- type Protection
- type Record
- type Suite
- type TrafficProtection
- type TrafficSecret
- type TrafficSuite
- type UsageLimitProvider
- type UsageLimits
Constants ¶
This section is empty.
Variables ¶
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 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.
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 ¶
func (a KeyExchangeAlgorithm) Has(v KeyExchangeAlgorithm) bool
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 ¶
UsageLimits describes advisory per-key recommendations for DTLS. Zero means unspecified.