Internal Certificate Authority (CA)
Palyra implements a built-in Certificate Authority to manage the lifecycle of identities without external dependencies. TheCertificateAuthority class handles the generation of self-signed root certificates and the issuance of short-lived leaf certificates for both clients and servers.
Key Components
CertificateAuthority: The core engine for signing. It usesrcgento generate X.509 certificates and manages a sequence counter for issued artifacts crates/palyra-identity/src/ca.rs#34-38.IssuedCertificate: A container for the PEM-encoded certificate, private key, and validity metadata crates/palyra-identity/src/ca.rs#17-25.StoredCertificateAuthority: A serializable representation of the CA state, including the private key, used for persistence in the secret store crates/palyra-identity/src/ca.rs#27-32.
Issuance Logic
The CA supports three primary issuance flows:- Client Certificates: Issued for devices with the
ClientAuthextended key usage crates/palyra-identity/src/ca.rs#64-78. - Server Certificates: Issued for the daemon’s RPC surfaces with
ServerAuthcrates/palyra-identity/src/ca.rs#80-86. - SAN-Enabled Certificates: Supports Subject Alternative Names (SANs) for both DNS names and IP addresses, essential for multi-node networking where nodes are addressed by IP crates/palyra-identity/src/ca.rs#88-116.
Identity Management and Persistence
TheIdentityManager orchestrates the CA, device pairing, and revocation state. It relies on a SecretStore for secure persistence of the CA private key and the identity state bundle.
The Secret Store Layer
Palyra provides two primary implementations of theSecretStore trait:
FilesystemSecretStore: Encrypts secrets at rest using ChaCha20-Poly1305. On Windows, it further hardens file permissions using SIDs to ensure only the owner can access the identity directory crates/palyra-identity/src/store.rs#87-115.InMemorySecretStore: Used for testing and volatile sessions crates/palyra-identity/src/store.rs#34-36.
State Concurrency
To prevent state corruption during concurrent mutations (e.g., multiple CLI commands or daemon tasks), theIdentityManager implements a two-tier locking mechanism:
IDENTITY_STATE_PROCESS_LOCK: A standard RustMutexfor intra-process synchronization crates/palyra-identity/src/pairing/persistence.rs#39.- Filesystem Lock: A file-based lock (
.identity-state.lock) containing PID and timestamp metadata to synchronize across different processes crates/palyra-identity/src/pairing/persistence.rs#80-96.
Device Pairing Flow
The pairing flow establishes trust between an unauthenticated client and the Palyra gateway. It uses a challenge-response mechanism involving ephemeral X25519 keys.Pairing Sequence Diagram
Title: Device Pairing Handshake Flow Sources: crates/palyra-identity/src/pairing/handshake.rs#27-148, crates/palyra-identity/src/pairing/persistence.rs#56-66Key Functions
start_pairing: Initializes the session and enforces rate limits (default 1024 starts per 60s window) crates/palyra-identity/src/pairing/handshake.rs#83-109.verify_pairing: Validates theDevicePairingHello. It performs constant-time comparison of the pairing proof to prevent timing attacks crates/palyra-identity/src/pairing/handshake.rs#129-137, crates/palyra-identity/src/pairing/handshake.rs#180-183.complete_pairing: Orchestrates verification and persistence in a single atomic operation crates/palyra-identity/src/pairing/handshake.rs#120-127.
mTLS Enforcement and Revocation
Once paired, all node communication is protected by mTLS. Palyra implements aRevocationAwareClientVerifier (conceptually managed via MemoryRevocationIndex) to handle real-time certificate invalidation.
Revocation Logic
revoked_certificate_fingerprints: TheIdentityManagermaintains a list of SHA-256 fingerprints of certificates that have been superseded or manually revoked crates/palyra-identity/src/pairing/persistence.rs#132.MemoryRevocationIndex: AnArc-wrapped shared state used by the TLS stack to reject connections from revoked devices crates/palyra-identity/tests/mtls_pairing_flow.rs#137-143.
Configuration Helpers
build_node_rpc_server_mtls_config: Configures arustls::ServerConfigthat requires client certificates and validates them against the internal CA and revocation index crates/palyra-identity/tests/mtls_pairing_flow.rs#138-142.build_paired_device_client_mtls_config: Configures arustls::ClientConfigusing the device’s issued certificate for outbound mTLS crates/palyra-identity/tests/mtls_pairing_flow.rs#146-150.
QUIC Transport Layer
Palyra uses thequinn implementation of QUIC for its framed I/O layer (palyra-transport-quic). This provides multiplexed, reliable, and encrypted streams.
Transport Runtime Architecture
Title: QUIC Runtime and Framed I/O Sources: crates/palyra-daemon/src/quic_runtime.rs#1-122, crates/palyra-transport-quic/src/lib.rsImplementation Details
- Concurrency Control: The
serve_with_connection_limitfunction uses atokio::sync::Semaphoreto enforceMAX_CONCURRENT_CONNECTIONS(default 256) crates/palyra-daemon/src/quic_runtime.rs#86-102. - Framed I/O: Since QUIC streams are byte-oriented,
palyra-transport-quicprovidesread_frameandwrite_frameto handle length-prefixed messages crates/palyra-daemon/src/quic_runtime.rs#149-152. - Protocol Versioning: Every request and response frame includes a
protocol_version(currentlyu16). The runtime rejects frames where the version does not matchpalyra_transport_quic::PROTOCOL_VERSIONcrates/palyra-daemon/src/quic_runtime.rs#160-163.
Supported Methods
The QUIC runtime currently handles:node.health: Returns the health status and whether mTLS is required for gRPC RPCs crates/palyra-daemon/src/quic_runtime.rs#166-179.node.stream_events: Supports event streaming with resumption viaresume_fromsequence numbers crates/palyra-daemon/src/quic_runtime.rs#180-197.