palyra-identity crate provides the foundation for secure node-to-node communication and device authentication. It manages the lifecycle of Ed25519 keypairs, Certificate Authority (CA) operations, mTLS certificate issuance, and the Trust-On-First-Use (TOFU) pairing handshake protocol.
Device Identity and Key Management
Every Palyra node or client is identified by aDeviceIdentity. This identity is anchored by an Ed25519 keypair and a unique device_id (typically a canonical ULID).
Secret Storage
Identities and sensitive cryptographic materials are persisted using theSecretStore trait crates/palyra-identity/src/store.rs#25-31.
FilesystemSecretStore: The default implementation for production. It usesCHACHA20_POLY1305AEAD encryption to protect secrets at rest crates/palyra-identity/src/store.rs#16-22. On Windows, it leveragespalyra_common::windows_securityto harden file permissions to the current user SID crates/palyra-identity/src/store.rs#98-105.InMemorySecretStore: Used primarily for testing and ephemeral sessions crates/palyra-identity/src/store.rs#34-36.
Identity Management
TheIdentityManager serves as the high-level API for managing the local node’s credentials and CA crates/palyra-cli/src/commands/pairing.rs#168-169. It coordinates the storage and retrieval of DeviceIdentity structures, which include the public key and associated metadata.
Sources: crates/palyra-identity/src/store.rs#1-127, crates/palyra-cli/src/commands/pairing.rs#159-178
Certificate Authority and mTLS
Palyra uses a private PKI (Public Key Infrastructure) to secure gRPC and QUIC traffic between nodes. Each daemon acts as its own CA for its cluster.CA Operations
TheCertificateAuthority struct handles the generation of a self-signed root and the issuance of leaf certificates crates/palyra-identity/src/ca.rs#34-40.
- Client Certificates: Issued for paired devices with
ExtendedKeyUsagePurpose::ClientAuthcrates/palyra-identity/src/ca.rs#64-78. - Server Certificates: Issued for the daemon’s gRPC/QUIC endpoints, including Subject Alternative Names (SANs) for
localhostand specific IP addresses crates/palyra-identity/src/ca.rs#88-116.
mTLS Lifecycle
TheIssuedCertificate struct tracks the PEM-encoded certificate, private key, and validity periods (issued/expiry in unix milliseconds) crates/palyra-identity/src/ca.rs#16-25. Certificates are typically issued with a default validity period defined by DEFAULT_CERT_VALIDITY crates/palyra-cli/src/commands/pairing.rs#2.
Sources: crates/palyra-identity/src/ca.rs#1-173, crates/palyra-cli/src/commands/pairing.rs#1-5
Node Pairing Handshake (TOFU)
Pairing is the process by which a new client (e.g., a Desktop Companion or Mobile App) establishes a trusted relationship with a Palyra Daemon.The Handshake Flow
Palyra implements a Trust-On-First-Use (TOFU) model. The flow is initiated via thepalyra pairing pair command or through the Web Console.
- Initiation: The client generates a
DeviceIdentityand a pairing request. - Proof Verification: A “proof” (e.g., a 6-digit code or a QR code secret) is used to out-of-band verify the request. The CLI supports passing this via
--proofor--proof-stdincrates/palyra-cli/src/commands/pairing.rs#123-133. - Approval: Requests must be explicitly approved. The
PairingCommand::Approvehandler calls theapprove_node_pairing_requestmethod on the control plane client crates/palyra-cli/src/commands/pairing.rs#97-109. - Persistence: Upon successful pairing, the device identity is persisted in the identity store crates/palyra-cli/tests/pairing_flow.rs#111-140.
Pairing Data Flow
The following diagram illustrates the transition from the CLI command to the identity management logic. Title: Pairing Handshake Sequence Sources: crates/palyra-cli/src/commands/pairing.rs#159-182, crates/palyra-identity/src/ca.rs#64-78, crates/palyra-identity/src/store.rs#135-154QUIC Transport and mTLS Enforcement
Thepalyra-daemon utilizes quinn for its Node RPC interface, which strictly enforces mTLS.
QUIC Runtime
TheQuicRuntimeTlsMaterial struct encapsulates the CA certificate, server certificate, and private key required to bootstrap the QUIC endpoint crates/palyra-daemon/src/quic_runtime.rs#19-25.
Connection Handling
Theserve_with_connection_limit function manages incoming QUIC connections, applying a Semaphore-based concurrency limit (default 256) crates/palyra-daemon/src/quic_runtime.rs#86-102. Every connection must pass rustls client certificate verification if require_client_auth is enabled crates/palyra-daemon/src/quic_runtime.rs#23.
Title: QUIC mTLS Connection Logic
Sources: crates/palyra-daemon/src/quic_runtime.rs#62-122, crates/palyra-daemon/src/quic_runtime.rs#144-179
Persistence and Revocation
Pairing Persistence
Pairing records are stored in the identity store. On a failed pairing attempt, the system explicitly ensures that no partial identity secrets are persisted to disk crates/palyra-cli/tests/pairing_flow.rs#112-140.Revocation
Revocation is managed by removing the device’s identity from theSecretStore. Once the secret is deleted, subsequent mTLS handshakes will fail as the IdentityManager will no longer recognize the device_id during the verification phase.
Sources: crates/palyra-identity/src/store.rs#156-162, crates/palyra-cli/tests/pairing_flow.rs#112-140