Crate foctet_core 

Foctet Core (Draft v0)

• Fixed-width frame header encoding
• Profile 0x01 crypto primitives
• Native handshake key schedule helpers
• Replay window enforcement
• Runtime-agnostic streaming adapters

foctet-core is the low-level protocol crate for applications that need to drive Foctet sessions directly. If you already have a split stream transport such as QUIC, WebTransport, WebSocket multiplexing, or another byte-stream abstraction, prefer foctet-transport for the recommended handshake and channel builders.

Main Modules

• body: application/foctet one-shot encrypted body envelope
• frame: wire frame structures, parser/encoder, framed transport types
• crypto: key schedule and frame AEAD helpers
• control: control message wire payloads
• session: handshake/rekey state machine
• payload: encrypted payload TLV schema
• io: runtime adapters and blocking SyncIo

Typical Flow

1. Build/derive TrafficKeys via handshake/session.
2. Send/receive via frame::FoctetFramed or io::SyncIo.
3. Use Session to process control frames and rotate keys.
4. Encode application bytes as TLV (APPLICATION_DATA) via payload.

Authentication Guidance

• For production use, prefer SessionAuthConfig with local identity keys, pinned PeerIdentity values, and SessionAuthConfig::require_peer_authentication(true).
• If Foctet runs inside an already-authenticated outer channel, you may use the native handshake without identity signatures, but the outer channel then carries the peer-authentication responsibility.
• Sequence numbers and rekey identifiers fail closed on exhaustion; callers should treat those errors as terminal and establish a fresh session.

Typical Native Handshake

use foctet_core::{
    IdentityKeyPair, PeerIdentity, RekeyThresholds, Session, SessionAuthConfig,
};

let auth = SessionAuthConfig::new()
    .with_local_identity(IdentityKeyPair::generate())
    .with_peer_identity(PeerIdentity::new(peer_identity_public_key))
    .require_peer_authentication(true);

let mut initiator = Session::new_initiator_with_auth(RekeyThresholds::default(), auth);
let client_hello = initiator.start_handshake()?;

Re-exports

pub use auth::HANDSHAKE_AUTH_ED25519;

pub use auth::HANDSHAKE_AUTH_NONE;

pub use auth::HandshakeAuth;

pub use auth::IdentityKeyPair;

pub use auth::PeerIdentity;

pub use auth::SessionAuthConfig;

pub use body::BODY_MAGIC;

pub use body::BODY_PROFILE_V0;

pub use body::BODY_VERSION_V0;

pub use body::BodyEnvelopeError;

pub use body::BodyEnvelopeLimits;

pub use body::open_body;

pub use body::open_body_for_key_id;

pub use body::open_body_for_key_id_with_limits;

pub use body::open_body_with_limits;

pub use body::seal_body;

pub use body::seal_body_with_limits;

pub use control::ControlMessage;

pub use control::ControlMessageKind;

pub use crypto::Direction;

pub use crypto::EphemeralKeyPair;

pub use crypto::TrafficKeys;

pub use crypto::decrypt_frame;

pub use crypto::decrypt_frame_with_key;

pub use crypto::derive_rekey_traffic_keys;

pub use crypto::derive_traffic_keys;

pub use crypto::encrypt_frame;

pub use crypto::make_nonce;

pub use crypto::random_session_salt;

pub use frame::DRAFT_MAGIC;

pub use frame::FRAME_HEADER_LEN;

pub use frame::FoctetFramed;

pub use frame::FoctetStream;

pub use frame::Frame;

pub use frame::FrameHeader;

pub use frame::PROFILE_X25519_HKDF_XCHACHA20POLY1305;

pub use frame::WIRE_VERSION_V0;

pub use payload::Tlv;

pub use payload::decode_tlvs;

pub use payload::encode_tlvs;

pub use payload::tlv_type;

pub use replay::DEFAULT_REPLAY_WINDOW;

pub use replay::ReplayProtector;

pub use replay::ReplayWindow;

pub use secure_channel::AsyncSecureChannel;

pub use secure_channel::SecureChannel;

pub use session::HandshakeRole;

pub use session::RekeyThresholds;

pub use session::Session;

pub use session::SessionState;

Modules

auth

Handshake authentication helpers and identity-key types.

body

One-shot body-complete encrypted envelope (application/foctet) helpers.

control

Control-plane message types used inside encrypted control frames.

crypto

Cryptographic primitives and key-derivation helpers.

frame

Frame wire format, parser/encoder, and framed transport adapters.

io

Runtime adapters and blocking I/O wrappers.

payload

TLV payload encoding/decoding helpers for encrypted application bytes. Encrypted payload TLV support (Draft v0). TLV wire format (fixed-width):

replay

Replay-window tracking and duplicate-frame protection.

secure_channel

High-level blocking facade combining session/rekey and TLV application flow.

session

Session handshake/rekey state and key lifecycle handling.

Enums

CoreError

Core protocol error type.