mac.h File Reference

Message Authentication Code and session-key derivation (ERTMS/ETCS Subset-037-2 §6.2.2 / §6.2.3.2.3). More...

#include <stddef.h>
#include <stdint.h>
#include "safecomm/status.h"

Include dependency graph for mac.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	safecomm_mac_ctx_t
	Immutable session-key material for one SaF connection. More...

Macros
#define	SAFECOMM_MAC_KEY_LEN   24U
#define	SAFECOMM_MAC_LEN   8U
#define	SAFECOMM_MAC_RAND_LEN   8U

Enumerations
enum	safecomm_mac_alg_t { SAFECOMM_MAC_ALG_3DES_SS037 = 0 }
	MAC algorithm selector (only 3DES today; reserved for growth). More...

Functions
safecomm_status_t	safecomm_mac_derive_ksmac (const uint8_t kmac[SAFECOMM_MAC_KEY_LEN], const uint8_t ra[SAFECOMM_MAC_RAND_LEN], const uint8_t rb[SAFECOMM_MAC_RAND_LEN], safecomm_mac_ctx_t *out_ctx)
	Derive the session key KSMAC from KMAC and the AU random values.
safecomm_status_t	safecomm_mac_compute (const safecomm_mac_ctx_t *ctx, const uint8_t *msg, size_t msg_len, uint8_t out_mac[SAFECOMM_MAC_LEN])
	Compute the 8-byte EuroRadio MAC over msg.
safecomm_status_t	safecomm_mac_verify (const safecomm_mac_ctx_t *ctx, const uint8_t *msg, size_t msg_len, const uint8_t rx_mac[SAFECOMM_MAC_LEN])
	Constant-time verify of a received MAC against a freshly computed one.

Detailed Description

Message Authentication Code and session-key derivation (ERTMS/ETCS Subset-037-2 §6.2.2 / §6.2.3.2.3).

The EuroRadio MAC is a CBC-MAC ("single DES with modified MAC algorithm 3": every block but the last is single-DES under K1, the last is E(K3,D(K2,E(K1,.)))) computed with the session key KSMAC, which is itself derived during the AU1/AU2/AU3 handshake from the pre-shared KMAC and the two exchanged random values (RA split left/right, RB split left/right; the third block reverses the key order). Verified against the official worked example in Subset-037-2 Annex B; see tests/test_mac_kat.c.

SAFETY / SECURITY NOTE: DES/3DES are cryptographically dated. This module implements the algorithm the currently deployed trackside requires; a future AES-based EuroRadio MAC (Subset-037-3) would be an additional safecomm_mac_alg_t, not a replacement. See docs/safety/SUBSET_MAPPING.md.

REQ-SC-MAC-001..010 — see docs/requirements/SRS.md.

Definition in file mac.h.

Macro Definition Documentation

SAFECOMM_MAC_KEY_LEN

#define SAFECOMM_MAC_KEY_LEN   24U

Length in bytes of a KMAC / KSMAC key (3 x 8-byte DES keys).

Definition at line 34 of file mac.h.

SAFECOMM_MAC_LEN

#define SAFECOMM_MAC_LEN   8U

Length in bytes of an 8-byte EuroRadio MAC.

Definition at line 36 of file mac.h.

SAFECOMM_MAC_RAND_LEN

#define SAFECOMM_MAC_RAND_LEN   8U

Length in bytes of an AU random value (RA / RB).

Definition at line 38 of file mac.h.

Enumeration Type Documentation

safecomm_mac_alg_t

enum safecomm_mac_alg_t

MAC algorithm selector (only 3DES today; reserved for growth).

Enumerator
SAFECOMM_MAC_ALG_3DES_SS037	Subset-037 §7.3 3DES CBC-MAC.

Definition at line 41 of file mac.h.

Function Documentation

safecomm_mac_derive_ksmac()

safecomm_status_t safecomm_mac_derive_ksmac	(	const uint8_t	kmac[SAFECOMM_MAC_KEY_LEN],
		const uint8_t	ra[SAFECOMM_MAC_RAND_LEN],
		const uint8_t	rb[SAFECOMM_MAC_RAND_LEN],
		safecomm_mac_ctx_t *	out_ctx )

Derive the session key KSMAC from KMAC and the AU random values.

Implements the Subset-037 §7.3 key-derivation: the two 64-bit random numbers exchanged in AU1 (RA, sent by the caller / initiator) and AU2 (RB, sent by the responder) are combined with KMAC to produce KSMAC.

Parameters

kmac	pre-shared 24-byte KMAC for this peer pair. Non-NULL.
ra	8-byte random value from AU1. Non-NULL.
rb	8-byte random value from AU2. Non-NULL.
out_ctx	receives the derived session context. Non-NULL.

Returns

SAFECOMM_STATUS_OK, SAFECOMM_STATUS_INVALID_PARAM, or SAFECOMM_STATUS_NOT_IMPLEMENTED while this is a skeleton.

Note

REQ-SC-MAC-003.

Definition at line 267 of file mac.c.

safecomm_mac_compute()

safecomm_status_t safecomm_mac_compute	(	const safecomm_mac_ctx_t *	ctx,
		const uint8_t *	msg,
		size_t	msg_len,
		uint8_t	out_mac[SAFECOMM_MAC_LEN] )

Compute the 8-byte EuroRadio MAC over msg.

Parameters

ctx	session context from safecomm_mac_derive_ksmac(). Non-NULL.
msg	the safe PDU bytes the MAC covers. Non-NULL if msg_len > 0.
msg_len	number of bytes in msg.
out_mac	receives the 8-byte MAC. Non-NULL.

Returns

SAFECOMM_STATUS_OK / _INVALID_PARAM / _NOT_INITIALISED / _NOT_IMPLEMENTED.

Note

REQ-SC-MAC-005.

Definition at line 300 of file mac.c.

safecomm_mac_verify()

safecomm_status_t safecomm_mac_verify	(	const safecomm_mac_ctx_t *	ctx,
		const uint8_t *	msg,
		size_t	msg_len,
		const uint8_t	rx_mac[SAFECOMM_MAC_LEN] )

Constant-time verify of a received MAC against a freshly computed one.

Parameters

ctx	session context. Non-NULL.
msg	PDU bytes the MAC covers. Non-NULL if msg_len > 0.
msg_len	number of bytes in msg.
rx_mac	the 8-byte MAC received on the wire. Non-NULL.

Returns

SAFECOMM_STATUS_OK on match, SAFECOMM_STATUS_MAC_MISMATCH on mismatch, or _INVALID_PARAM / _NOT_IMPLEMENTED.

Note

REQ-SC-MAC-006. Comparison must not short-circuit on the first differing byte.

Definition at line 355 of file mac.c.