Deployment forms compared

The service comes in two deployment forms, l4re and win. Each is a standalone Rust package; they share no source code. They offer the same algorithms but differ in transport, message format, set of operations, and error codes. This page helps you choose and shows where an integration with one form doesn't carry over to the other.

Terms

Deployment form: one of the two packages, l4re-crypto-service in l4re/ or wvds-crypto-service-win in win/.
Dataspace: an L4Re memory region that two tasks map at the same time.
DataspaceEndpoint: the platform vendor's component that connects two tasks through dataspaces. It isn't part of the service; the service calls it through a C interface.
Named pipe: a named Windows communication channel, used here line by line: one JSON line per request, one JSON line per response.

Side by side

	`l4re`	`win`
Target system	L4Re on x86_64 and aarch64	Windows x86_64
Version	0.2.0	0.3.0
Transport	`DataspaceEndpoint`, shared memory	named pipes, default name `\\.\pipe\wvds_crypto`
Message format	binary, 16-byte header, little-endian	one JSON line, binary data Base64-encoded
Largest message	64 KiB payload	no limit
Operations	10 served request types, 12 with ChaCha20; 5 reserved	10 named operations
Key generation	ML-DSA, ML-KEM	AES-256, ML-DSA, ML-KEM
AES-GCM nonce	supplied by the caller	generated by the service
Error codes	numbers, 32-bit	names such as `KEY_NOT_FOUND`
Binding description	`l4re/pub/include/wvds_crypto.h`	`win/src/protocol.rs`
User interface	none	terminal UI, can be turned off

For the details behind each row, see L4Re binary protocol and Windows JSON protocol.

Which form to use

l4re is meant for systems in which security-critical parts run as separate tasks on the L4Re microkernel. The crypto service is then a task of its own; a fault in the calling task can't reach the keys because the microkernel isolates the address spaces.

win is meant for development, demonstrations, and Windows gateways. Any tool that can open a named pipe can read and write the JSON format. A configuration file can open several pipes (“gateways”), each with its own statistics; see Build features and configuration.

How the L4Re form is built today

The build targets in l4re/.cargo/config.toml are x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu. A dedicated Rust target for L4Re is prepared but commented out, because it requires the L4Re SDK.

As a result:

The code path that accepts requests through DataspaceEndpoint is compiled only when the target system is L4Re (target_os = "l4re").
A program built for a Linux target runs a demonstration instead: it performs AES-256-GCM, ML-DSA-65, ML-KEM-768, and HKDF-SHA256 once each, prints the results, and exits.
On Windows, the l4re package replaces the DataspaceEndpoint functions with stand-ins that always fail. That lets you compile and test the library without L4Re.

To run the service as a real L4Re task, you need the L4Re SDK, a Rust target for L4Re, and your platform vendor's DataspaceEndpoint library.

Out of scope

The layout of individual messages; see the two protocol references.
The build itself; see Build and test.