Security Model

Production configuration requires authentication by default. Tests and debug builds may explicitly disable it, but release profiles should enable auth_required.

auth_required=false means unauthenticated frames are allowed. It does not mean authenticated frames are ignored: any frame carrying AUTHENTICATED/SECURITY_EXT must verify successfully before delivery.

Auth Provider

xgl_auth_provider_t provides:

• sign
• verify
• tag_len, capped by XGL_AUTH_TAG_MAX_LEN
• user_data

Initialization must fail when auth_required=true and the provider is missing, tag_len == 0, or tag_len > XGL_AUTH_TAG_MAX_LEN. Authenticated configurations must also provide memory.allocator with both malloc and free; xgl_config_validate() rejects production auth when that allocator contract is missing.

AAD and Payload

The base header and extensions are authenticated as AAD after applying the authentication-mode canonicalization rules below. Payload is authenticated but not encrypted. CRC provides fast error detection; the authentication tag prevents forgery, tampering, and replay.

Authentication Modes

XGL distinguishes two security models:

Mode	Verifier	Forwarding behavior	Authentication domain
Hop-by-hop authentication	Every hop	Each forwarding node verifies and re-signs	May include the current wire header, including ttl and header_crc16
End-to-end authentication	Final destination, after datalink checks	Forwarding nodes must not re-sign	Must exclude hop-mutable and link-check fields

Current XGL uses end-to-end authentication for authenticated frames. The source signs, the destination verifies, and intermediate nodes only update forwarding metadata and CRCs.

End-to-End Canonical AAD

End-to-end authentication signs a canonical view of the wire AAD:

• ttl is treated as zero because it is decremented on every forwarded hop.
• header_crc16 is treated as zero because it is recomputed whenever hop-mutable header bytes change.
• frame_crc16 is not part of the authentication input because it is placed after the authentication trailer.
• Stable base-header fields, stable TLV extensions, and payload bytes remain authenticated.

Field/material	Auth input treatment	Reason	Evidence
Base header bytes	Included as AAD	Binds stable routing/session/packet identity	src/wire/xgl_wire.c
ttl	Included as zero	Forwarding decrements TTL per hop	src/wire/xgl_wire.c, src/network/xgl_network_receive.c
header_crc16	Included as zero	Header CRC is recomputed when TTL changes	src/wire/xgl_wire.c
TLV extensions	Included as AAD	Binds session, security, fragment, route, and data-type metadata	src/wire/xgl_wire.c, src/wire/xgl_wire_ext.c
Payload	Included as payload input	Protects application/fragment data	src/wire/xgl_wire.c
Authentication tag	Not included in its own input	It is generated by the provider	src/wire/xgl_wire.c
Frame CRC16	Not included	It is serialized after the auth trailer	src/wire/xgl_wire.c, src/wire/xgl_frame_auth.c

Any future extension whose value changes at each hop must either be excluded by the same canonicalization rule or be protected by a separate hop-by-hop authentication mechanism. Do not silently add hop-mutable fields to the end-to-end AAD.

Decision: End-to-End Auth

The protocol chooses end-to-end authentication for the current AUTHENTICATED/SECURITY_EXT path.

Reasons:

• Intermediate nodes can forward without access to the originator's signing key.
• The authentication tag continues to protect payload and stable routing/session identity across multiple hops.
• TTL and CRC remain datalink/network maintenance fields rather than application-security fields.

Consequences:

• Forwarding must recompute header CRC and frame CRC after TTL changes.
• Forwarding must preserve the original authentication tag.
• A separate hop-by-hop tag would be needed if a deployment requires each link to authenticate the immediate previous hop.

Authentication Trailer

The authentication trailer is placed after payload and before frame CRC. SECURITY_EXT records key_id, nonce_id, and tag_len. The provider declares a fixed tag length so the signing path does not need a trial signature followed by a second signature.

Verification Order

1. Check magic, version, header_len, and payload_len.
2. Verify header CRC.
3. Parse SECURITY_EXT.
4. Verify authentication trailer when authentication is required or when the frame declares authentication.
5. Check replay window for verified authenticated frames.
6. Enter network/transport semantic handling.

Any failure prevents payload delivery.

Replay Window

Anti-replay key:

source_id + connection_id + session_epoch + packet_number

Replay results are tri-state:

• new authenticated packets enter network/transport handling;
• duplicate ACK-eliciting reliable packets may enter transport so the receiver can regenerate ACK/SACK after a lost ACK, but transport duplicate detection must not deliver payload again;
• non-reliable duplicates, old-session packets, wrong-connection packets, and packets older than the replay window are dropped before network/transport.

Multi-Hop Forwarding

TTL is a hop-mutable field. After forwarding changes TTL, the implementation recomputes header_crc16 and frame_crc16 and preserves the original authentication tag. Verification remains valid because the end-to-end AAD canonicalizes TTL and header CRC before calling the provider.

Reserved

Encryption is reserved. Do not treat enable_encryption as an available production encryption path.

Key Boundary

XGL does not persist keys or define key derivation. Production applications implement key storage, rotation, key id mapping, and hardware security module integration inside the auth provider.

Traceability

Rule	Source	Tests
Auth provider validation and tag length bounds	src/api/xgl_config.c	test/test_config.cpp
SECURITY_EXT encoding and auth trailer placement	src/wire/xgl_frame_auth.c, src/wire/xgl_wire_ext.c	test/test_wire.cpp, test/test_frame.cpp
Canonical AAD with TTL/header CRC zeroed	src/wire/xgl_wire.c	test/test_datalink.cpp, test/test_network.cpp
Datalink auth verification and replay classification	src/datalink/xgl_datalink_receive.c, src/security/xgl_security.c	test/test_datalink.cpp, test/test_security.cpp