Crate darkbio_wire 

Ark encrypted wire protocol

This repository implements the wire protocol between an Ark enclave and the host machine it is plugged into.

The wire wraps an arbitrary byte stream into an encrypted, request oriented transport:

• Framing: Consistent Overhead Byte Stuffing (COBS) encoded frames delimited by zero bytes, with oversized frames silently discarded.
• Sessions: The wire assumes its stream carries no client lifecycle as USB bulk transfers deliver none. Empty frames are used to mark session resets and cryptography renegotiations.
• Handshake: Three message exchange of ephemeral signing and encryption keys, authenticated by the device attestation. It establishes independent encrypted contexts per direction.
• Messages: Protobuf encoded requests and responses, individually sealed by the session encryption contexts.

The wire keeps trust policy at its edges. The Ark side takes an Attester producing the attestation to present to the host; the host side takes a Verifier checking the attestation it received. A Roots verifier built on darkbio-trust accepts the Arks attested under a given set of hardware and emulator roots; which roots to trust, self-signing rules and recovery overrides stay with the consumer.

This package does not concern itself with the underlying transport. Genuine Ark devices use USB bulk endpoints, emulators use websockets and tests use Unix sockets. Creating the underlying data-stream is the caller’s task.

Re-exports

pub use protocol::ArkToHost;

pub use protocol::HostToArk;

Modules

protocol

Protobuf messages, generated from proto/wire.proto at build time.

Structs

ArkSide

Ark side of the wire, an encrypted transport for serving protobuf requests from a connected host. It waits for session resets (empty frames), responds to handshake and afterward decrypts inbound and encrypts outbound messages.

Attestation

Device attestation an Ark presents in the handshake, a CWT in one of the shapes darkbio-trust defines (hardware or emulator claims). Only the shape is checked, so an obviously wrong blob is refused up front; whether it is accepted is the host’s decision.

HostSide

Host side of the wire, an encrypted transport for issuing protobuf requests to a connected Ark. It initiates sessions by signaling a transport reset and driving the handshake, afterward encrypting outbound and decrypting inbound messages.

Roots

Roots of trust, accepting the Arks attested under them: hardware Arks by the hardware roots and emulated Arks by the emulator roots, the attestation having to be valid at the current time. An Ark that was never onboarded is rejected, its self-signed attestation being an onboarding decision rather than one of trust.

Enums

Error

Things that can go wrong in the wire transport.

Constants

MAX_FRAME_SIZE

Maximum limit for a frame size, above which it will be discarded from the wire protocol.

MAX_MESSAGE_SIZE

Largest protobuf message the wire carries, being what still fits a frame after the session’s sealing and the COBS framing overheads are added.

Traits

Attester

Source of the device attestation the Ark presents in the handshake; queried on every handshake, so a freshly onboarded attestation can be picked up without recreating the wire.

Verifier

Trust policy for the device attestation an Ark presents in the handshake. It owns everything the wire deliberately does not (which roots to trust, self-signing rules, recovery overrides) and decides which Arks a session is opened with.