Struct Session 

pub struct Session {

    pub session_id: [u8; 16],
    pub client_addr: SocketAddr,
    pub state: SessionState,
    pub keys: SessionKeys,
    pub eph_pub: [u8; 32],
    pub counter: u64,
    pub last_seen: Instant,
    pub created_at: Instant,
    pub last_server_send: Instant,
    pub mask: Option<MaskProfile>,
    pub pending_mask: Option<(MaskProfile, Instant)>,
    pub fsm_state: u16,
    pub fsm_packets: u32,
    pub fsm_state_start: Instant,
    pub send_seq: u32,
    pub recv_seq: u32,
    pub send_counter: u64,
    pub expected_tags: HashMap<u64, [u8; 8]>,
    pub tag_window_base: u64,
    pub received_bitmap: u256,
    pub pending_bytes_in: u64,
    pub pending_bytes_out: u64,
    pub server_eph_pub: Option<[u8; 32]>,
    pub server_hello_signature: Option<[u8; 64]>,
    pub ratcheted_keys: Option<SessionKeys>,
    pub ratcheted_expected_tags: HashMap<u64, [u8; 8]>,
    pub is_ratcheted: bool,
    pub vpn_ip: Option<Ipv4Addr>,
    pub client_id: Option<String>,
    pub pre_ratchet_tags: HashMap<u64, [u8; 8]>,
    pub pre_ratchet_expire: Option<Instant>,
}

Session information

Fields

session_id: [u8; 16]

client_addr: SocketAddr

state: SessionState

keys: SessionKeys

eph_pub: [u8; 32]

counter: u64

Packet counter for tag generation

last_seen: Instant

Last seen timestamp

created_at: Instant

Created timestamp

last_server_send: Instant

Last server-to-client packet timestamp (for downlink recording IAT)

mask: Option<MaskProfile>

Current mask profile

pending_mask: Option<(MaskProfile, Instant)>

Pending mask awaiting grace period before activation. Stored as (new_mask, timestamp_when_MaskUpdate_was_sent).

fsm_state: u16

Current FSM state

fsm_packets: u32

Packets in current FSM state

fsm_state_start: Instant

Duration in current FSM state

send_seq: u32

Sequence number for outgoing packets

recv_seq: u32

Last received sequence (for ACK)

send_counter: u64

Send counter for nonce generation (u64, same space as tags)

expected_tags: HashMap<u64, [u8; 8]>

Expected tags (counter -> tag)

tag_window_base: u64

Counter value used as the base for the currently precomputed tag window.

received_bitmap: u256

Received tag bitmap (for anti-replay)

pending_bytes_in: u64

Accumulated inbound bytes to flush into client_db in batches.

pending_bytes_out: u64

Accumulated outbound (downlink) bytes to flush into client_db in batches.

server_eph_pub: Option<[u8; 32]>

Server’s ephemeral public key for this session

server_hello_signature: Option<[u8; 64]>

Ed25519 signature for ServerHello

ratcheted_keys: Option<SessionKeys>

Ratcheted session keys (PFS)

ratcheted_expected_tags: HashMap<u64, [u8; 8]>

Ratcheted tags for validation (counter -> tag)

is_ratcheted: bool

Whether session has completed PFS ratchet

vpn_ip: Option<Ipv4Addr>

Assigned VPN IP (e.g. 10.0.0.2)

client_id: Option<String>

Registered client ID (from client_db) for traffic accounting

pre_ratchet_tags: HashMap<u64, [u8; 8]>

Pre-ratchet expected tags preserved for a 2-second grace window after complete_ratchet() so client packets that were already in-flight with the old keys are not silently dropped as unrecognised.

pre_ratchet_expire: Option<Instant>

Deadline until which pre_ratchet_tags are still accepted.

Implementations

impl Session

pub fn new( session_id: [u8; 16], client_addr: SocketAddr, keys: SessionKeys, eph_pub: [u8; 32], ) -> Self

pub fn next_send_nonce(&mut self) -> ([u8; 12], u64)

Compute next nonce for encryption from send_counter (u64) Uses the same counter space as tag generation for consistency

pub fn update_tag_window(&mut self)

Update expected tags for validation window

pub fn validate_tag(&self, tag: &[u8; 8]) -> Option<(u64, bool)>

Validate received tag (constant-time) Returns (counter, is_ratcheted_tag) if valid. Checks the current time window first, then adjacent windows (±1) for clock skew tolerance.

pub fn mark_tag_received(&mut self, counter: u64)

Mark tag as received

pub fn next_seq(&mut self) -> u32

Get next sequence number for inner header

pub fn update_fsm(&mut self)

Update FSM state

pub fn is_idle(&self) -> bool

Check if session is idle

pub fn is_expired(&self) -> bool

Check if session is expired

pub fn update_ratcheted_tag_window(&mut self)

Pre-compute tags for ratcheted keys

pub fn complete_ratchet(&mut self)

Complete PFS ratchet: switch to ratcheted keys, zeroize old ones

pub fn commit_pending_mask(&mut self) -> bool

Check and commit a pending mask if the grace period has elapsed. Returns true if a mask was committed. Grace period = 500ms — enough for the MaskUpdate packet to reach the client.