saf.h

Go to the documentation of this file.

#ifndef SAFECOMM_SAF_H
#define SAFECOMM_SAF_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "safecomm/status.h"
#include "safecomm/mac/mac.h"
#include "safecomm/transport/transport.h"
 
#ifdef __cplusplus
extern "C" {
#endif

#define SAFECOMM_SAF_MAX_PDU 1024U

#define SAFECOMM_SAF_AU1_LEN 13U
#define SAFECOMM_SAF_AU2_LEN 21U
#define SAFECOMM_SAF_AU3_LEN 9U
#define SAFECOMM_SAF_AR_LEN  9U
#define SAFECOMM_SAF_DATA_OVERHEAD 13U

typedef enum
{
    SAFECOMM_SAF_FRAME_UNKNOWN = 0,
    SAFECOMM_SAF_FRAME_AU1,
    SAFECOMM_SAF_FRAME_AU2,
    SAFECOMM_SAF_FRAME_AU3,
    SAFECOMM_SAF_FRAME_DATA,
    SAFECOMM_SAF_FRAME_DISCONNECT,
    SAFECOMM_SAF_FRAME_AR
} safecomm_saf_frame_kind_t;

typedef enum
{
    SAFECOMM_SAF_ROLE_INITIATOR = 0, 
    SAFECOMM_SAF_ROLE_RESPONDER      
} safecomm_saf_role_t;

typedef enum
{
    SAFECOMM_SAF_STATE_IDLE = 0,
    SAFECOMM_SAF_STATE_WAIT_AU2,
    SAFECOMM_SAF_STATE_WAIT_AU3,
    SAFECOMM_SAF_STATE_DATA,
    SAFECOMM_SAF_STATE_DISCONNECTING
} safecomm_saf_state_t;

typedef struct
{
    safecomm_saf_role_t role;
    uint8_t  kmac[SAFECOMM_MAC_KEY_LEN]; 
    uint32_t etcs_id_self;               
    uint32_t etcs_id_peer;               
    uint8_t  ety;                        
    uint32_t t_connect_ms;               
    uint32_t t_supervision_ms;           
} safecomm_saf_config_t;

typedef struct
{
    safecomm_saf_config_t   cfg;
    safecomm_transport_t    transport;
    safecomm_mac_ctx_t      mac;
    safecomm_saf_state_t    state;
    uint32_t                seq_tx;
    uint32_t                seq_rx;
    uint8_t                 ra[SAFECOMM_MAC_RAND_LEN];
    uint8_t                 rb[SAFECOMM_MAC_RAND_LEN];
    uint32_t                now_ms;               
    uint32_t                last_rx_ms;           
    bool                    supervision_armed;
    uint32_t                connect_start_ms;     
} safecomm_saf_conn_t;

safecomm_status_t safecomm_saf_init(safecomm_saf_conn_t *conn,
                                    const safecomm_saf_config_t *cfg,
                                    const safecomm_transport_t *transport);

safecomm_status_t safecomm_saf_connect(safecomm_saf_conn_t *conn);

safecomm_status_t safecomm_saf_send(safecomm_saf_conn_t *conn,
                                    const uint8_t *pdu, size_t pdu_len);

safecomm_status_t safecomm_saf_recv(safecomm_saf_conn_t *conn,
                                    uint8_t *out, size_t out_cap, size_t *out_len);
 
/*
 * Frame-driven responder API (REQ-SC-SAF-040..045).
 *
 * For a caller that owns its own I/O and cannot block, e.g. a cyclic executive where the peer's next frame arrives one
 * or more cycles later over a relay shared by many connections. Each call consumes one already-received frame and
 * produces at most one frame for the caller to transmit; none of them touches conn->transport. The same MAC and state
 * checks as the blocking safecomm_saf_connect() / safecomm_saf_recv() apply (they share the implementation).
 *
 * The responder random RB is supplied by the caller: it must come from a cryptographically secure source, and in a
 * 2oo2 system both channels must be given the same RB so they derive the same session key and emit identical frames.
 */

safecomm_saf_frame_kind_t safecomm_saf_frame_kind(const uint8_t *frame, size_t frame_len);

safecomm_status_t safecomm_saf_au1_fields(const uint8_t *au1, size_t au1_len, uint32_t *out_peer_id,
                                          uint8_t out_ra[SAFECOMM_MAC_RAND_LEN]);

safecomm_status_t safecomm_saf_responder_on_au1(safecomm_saf_conn_t *conn, const uint8_t *au1, size_t au1_len,
                                                const uint8_t rb[SAFECOMM_MAC_RAND_LEN],
                                                uint8_t *out_au2, size_t out_cap, size_t *out_len);

safecomm_status_t safecomm_saf_responder_on_au3(safecomm_saf_conn_t *conn, const uint8_t *au3, size_t au3_len,
                                                uint8_t *out_ar, size_t out_cap, size_t *out_len);

safecomm_status_t safecomm_saf_accept_frame(safecomm_saf_conn_t *conn, const uint8_t *frame, size_t frame_len,
                                            uint8_t *out, size_t out_cap, size_t *out_len);

safecomm_status_t safecomm_saf_frame_sent(safecomm_saf_conn_t *conn);

#define SAFECOMM_SAF_DI_LEN 3U

safecomm_status_t safecomm_saf_disconnect_frame(safecomm_saf_role_t role, uint8_t *out, size_t out_cap,
                                                size_t *out_len);

void safecomm_saf_set_time(safecomm_saf_conn_t *conn, uint32_t now_ms);

safecomm_status_t safecomm_saf_supervise(safecomm_saf_conn_t *conn);
 
safecomm_status_t safecomm_saf_disconnect(safecomm_saf_conn_t *conn);

safecomm_saf_state_t safecomm_saf_state(const safecomm_saf_conn_t *conn);

typedef struct
{
    safecomm_saf_state_t state;
    uint32_t             seq_tx;
    uint32_t             seq_rx;
    uint32_t             seq_rx_last_accepted;
    uint8_t              ksmac[SAFECOMM_MAC_KEY_LEN];
    uint8_t              ra[SAFECOMM_MAC_RAND_LEN];
    uint8_t              rb[SAFECOMM_MAC_RAND_LEN];
    uint32_t             etcs_id_self;
    uint32_t             etcs_id_peer;
} safecomm_session_vital_state_t;

safecomm_status_t safecomm_saf_export_session_state(const safecomm_saf_conn_t *conn,
                                                    safecomm_session_vital_state_t *out_state);

safecomm_status_t safecomm_saf_import_session_state(safecomm_saf_conn_t *conn,
                                                    const safecomm_session_vital_state_t *in_state);

safecomm_status_t safecomm_saf_prepare_send(safecomm_saf_conn_t *conn,
                                            const uint8_t *pdu, size_t pdu_len,
                                            uint8_t *out_frame, size_t out_frame_cap,
                                            size_t *out_frame_len);

safecomm_status_t safecomm_saf_commit_send(safecomm_saf_conn_t *conn,
                                           const uint8_t *frame, size_t frame_len);
 
#ifdef __cplusplus
}
#endif
 
#endif /* SAFECOMM_SAF_H */