transform

README

internal/ikev2/transform

The seam between IKEv2's wire protocol and the algorithm implementations. It maps IANA transform IDs onto concrete cryptoutil primitives.

Three packages, three responsibilities:

flowchart LR
    P["ikev2/payload<br/>owns the transform-ID registry (numbers)"]
    T["ikev2/transform<br/>translates ID → primitive"]
    C["cryptoutil<br/>owns the primitives, knows no IKEv2"]
    P -->|uint16 IDs| T -->|constructor call| C

Keeping the lookup here is what lets cryptoutil stay reusable by other VPN protocols, whose registries number the same algorithms differently.

API surface

• Cipher(encrID, keyBits) (SKCipher, error) — handshake cipher for an ENCR_* ID.
• ESPCrypter(encrID, keyBits, encKey, integID, integKey) (ESPCrypter, error) — the data-path cipher for a Child SA (AES-GCM ignores the integ args; AES-CBC pairs them into an encrypt-then-MAC crypter).
• PRF(id) (*PRF, error) — a PRF_* ID → keyed PRF.
• Integrity(id) (*Integrity, error) — an AUTH_* ID → truncated-HMAC ICV.
• DH(id) (DHGroup, error) — a DH_* ID → Diffie-Hellman group.

Each returns an error for an ID this build does not implement, which is how a proposal offering something unsupported is rejected rather than mis-keyed.

Implementation notes & caveats

• Adding an algorithm is a two-file change: a case here and a constructor in cryptoutil. If you add one without the other, this package won't compile against the missing constructor — by design.
• This is the only place IKEv2 transform-ID knowledge meets the primitives. Do not teach cryptoutil any IANA numbers, and do not construct ciphers directly from a protocol package — go through here so the supported-algorithm set stays in one auditable spot.

Documentation

Overview

Package transform maps IKEv2 IANA transform IDs onto concrete cryptographic primitives.

It is the seam between the wire protocol and the algorithm implementations: internal/payload owns the transform-ID registry, internal/cryptoutil owns the primitives and knows nothing about IKEv2, and this package is the only place that translates between them. Keeping the lookup here is what lets cryptoutil stay reusable by other VPN protocols, whose registries number the same algorithms differently.

Adding an algorithm means adding a case here plus a constructor in cryptoutil.

Index

• func Cipher(encrID uint16, keyBits int) (cryptoutil.SKCipher, error)
• func DH(id uint16) (cryptoutil.DHGroup, error)
• func ESPCrypter(encrID uint16, keyBits int, encKey []byte, integID uint16, integKey []byte) (cryptoutil.ESPCrypter, error)
• func Integrity(id uint16) (*cryptoutil.Integrity, error)
• func PRF(id uint16) (*cryptoutil.PRF, error)

Functions

func Cipher

func Cipher(encrID uint16, keyBits int) (cryptoutil.SKCipher, error)

Cipher returns the SK (handshake) cipher for an ENCR transform ID and key length in bits; 0 bits selects the algorithm's default.

func DH

func DH(id uint16) (cryptoutil.DHGroup, error)

DH returns the Diffie-Hellman group for a DH transform ID. The NIST curves transmit bare X||Y on the wire (RFC 5903), so their point prefix is stripped; Curve25519 has no such prefix.

func ESPCrypter

func ESPCrypter(encrID uint16, keyBits int, encKey []byte, integID uint16, integKey []byte) (cryptoutil.ESPCrypter, error)

ESPCrypter returns a prepared data-path crypter for an ESP transform. encKey carries the 4-octet GCM salt for AEAD suites; integID/integKey are used only by non-AEAD (CBC) suites.

func Integrity

func Integrity(id uint16) (*cryptoutil.Integrity, error)

Integrity returns the integrity transform for an AUTH transform ID. The key length is the hash output size and the ICV is truncated per RFC 4868.

func PRF

func PRF(id uint16) (*cryptoutil.PRF, error)

PRF returns the pseudorandom function for a PRF transform ID.