IKEv2 (RFC 7296) message + payload codec (PC_ENABLE_IKEV2) - a zero-heap builder / parser for the Internet Key Exchange v2 wire format that negotiates IPsec security associations over UDP 500 / 4500 (NAT-T). This is the "secure machine bridge over untrusted networks" southbound: the framing tier of an IKEv2/IPsec stack. More...

#include "protocore_config.h"

Detailed Description

IKEv2 (RFC 7296) message + payload codec (PC_ENABLE_IKEV2) - a zero-heap builder / parser for the Internet Key Exchange v2 wire format that negotiates IPsec security associations over UDP 500 / 4500 (NAT-T). This is the "secure machine bridge over untrusted networks" southbound: the framing tier of an IKEv2/IPsec stack.

Scope (tier 1 of the IPsec roadmap item): the pure wire codec only - build / parse into caller buffers, no sockets and no crypto. It frames the 28-octet IKE header and the generic payload chain (SA -> proposals -> transforms, KE, Ni/Nr, IDi/IDr, CERT/CERTREQ, AUTH, N notify, D delete, TSi/TSr, and the SK encrypted-payload envelope). Tier 2's crypto lives here too: the SKEYSEED / SK_* key derivation (RFC 7296 §2.13-2.14, prf+ over HMAC-SHA2-256), the SK-payload AEAD (RFC 5282 AES-256-GCM-16), the Diffie-Hellman shared secret (RFC 7296 §2.7, group 31 = X25519), PSK + ECDSA-P256 authentication (§2.15 / RFC 7427), the IKE_SA_INIT + IKE_AUTH message assembly (§1.2 / §3.14), and the SA / Child-SA key schedules (§2.14 / §2.17). On top of those sits a full stateful handshake DRIVER - both the initiator and responder complete IKE_SA_INIT + IKE_AUTH to IKE_ST_ESTABLISHED with mutual PSK auth - plus the post-auth INFORMATIONAL (DPD / Delete / Notify) and CREATE_CHILD_SA exchanges over the established SA. Remaining for tier 2: rekey/retransmit orchestration and RSA-signature auth. Tier 3 (the ESP datapath, a network-layer transform that hooks lwIP) is a separate, later track. All the crypto reuses primitives the library already ships.

Wire framing (byte-exact, network byte order): the IKE header is 8-byte Initiator SPI, 8-byte Responder SPI, 1-byte Next Payload, 1-byte Version (0x20 = MjVer 2 / MnVer 0), 1-byte Exchange Type, 1-byte Flags, 4-byte Message ID, 4-byte Length (whole message). Every payload starts with the same 4-byte generic header: Next Payload (the type of the FOLLOWING payload, so the chain is walked forward from the header's Next Payload), a Critical bit + 7 reserved bits, and a 2-byte Payload Length (this payload incl. the generic header). Multi-byte fields are big-endian throughout.

Reference: RFC 7296 (IKEv2) + the IANA "Internet Key Exchange Version 2 (IKEv2) Parameters" registry. Every structure was cross-checked byte-for-byte against scapy's IKEv2 contrib (the header, KE, Nonce, Notify, Delete, and the SA -> proposal -> transform tree, including the key-length transform attribute verified against scapy's decoder).

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file ikev2.h.