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 connection lifecycle as USB bulk transfers deliver none. Empty frames are used to mark session resets.
• 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. A develop envelope carries unreleased messages opaquely; only development firmware serves it, production Arks refuse it.

The wire keeps trust policy at its edges. The server takes an Attester producing the attestation to present to the client; the client 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.

Test vectors

The vectors directory holds golden test vectors for implementing (or rather validating) 3rd party clients. These are scenario transcripts that can be replayed to confirm expected behaviors and nuances. There are no server test vectors published as the Ark (genuine or emulated) is the single server.

Disclaimer

The Ark’s wire protocol is still heavily evolving, including the Rust API, low level transport and high level protobuf messages too. This crate is published for interoperability reasons, but it will undergo aggressive updates, possibly forced through by the Dark Bio cloud, hub and tools.

Re-exports

pub use protocol::ArkToHost;

pub use protocol::HostToArk;

Modules

protocol

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

Structs

Attestation

Device attestation a server 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 client’s decision.

Client

Client side of the wire, an encrypted transport for issuing protobuf requests to a connected server. 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 are accepted 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.

Server

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

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 server 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 a server 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.