palyra-identity crate provides the security foundation for the Palyra ecosystem. It manages a private Certificate Authority (CA) for the daemon, handles the device pairing handshake (PIN/QR), and enforces mutual TLS (mTLS) for all transport layers, including gRPC and QUIC.
Certificate Authority (CA) Management
Every Palyra daemon instance initializes its own internal Root CA upon first boot. This CA is used to issue short-lived leaf certificates to the daemon itself (server-side) and to paired devices (client-side).Implementation Details
- CA Creation: The
CertificateAuthority::newfunction generates a self-signed Root CA usingrcgencrates/palyra-identity/src/ca.rs#41-62. - Server Certificates: The daemon issues itself a server certificate (supporting
localhostand custom IP SANs) for its gRPC and QUIC endpoints crates/palyra-identity/src/ca.rs#80-116. - Client Certificates: When a device successfully pairs, the CA issues a client certificate tied to the
device_idwith theClientAuthextended key usage crates/palyra-identity/src/ca.rs#64-78. - Persistence: The CA state (PEM and sequence) is stored in the identity store via
StoredCertificateAuthoritycrates/palyra-identity/src/ca.rs#27-32.
Device Pairing Handshake
Palyra uses a multi-step cryptographic handshake to pair new devices (CLI, Web, or Mobile) without pre-shared long-lived keys.The Handshake Process
- Start Session: The daemon creates an
ActivePairingSessioncontaining achallengeand an ephemeral X25519 public key crates/palyra-identity/src/pairing/handshake.rs#27-52. - Device Hello: The client generates its own
DeviceIdentity(Ed25519) and responds with aDevicePairingHellocrates/palyra-identity/src/pairing/handshake.rs#111-118. - Proof Validation: The daemon verifies the proof (e.g., a 6-digit PIN or QR secret) in constant time crates/palyra-identity/src/pairing/handshake.rs#180-183.
- Signature Verification: The client must sign the transcript (including the session challenge and its own public key) to prove possession of the private key crates/palyra-identity/src/pairing/handshake.rs#190-205.
Pairing Flow Diagram
The following diagram maps the logical handshake to the internalIdentityManager methods.
Title: Device Pairing Sequence
Sources: crates/palyra-identity/src/pairing/handshake.rs#83-148, crates/palyra-cli/src/commands/pairing.rs#159-185
Transport Security (mTLS & QUIC)
Palyra enforces mTLS across all non-public interfaces. This ensures that only devices with a certificate signed by the daemon’s internal CA can communicate with the gRPC or QUIC gateways.mTLS Configuration
- Server Side:
build_node_rpc_server_mtls_configcreates arustls::ServerConfigthat requires client certificates and validates them against the internal Root CA crates/palyra-identity/tests/mtls_pairing_flow.rs#138-143. - Client Side:
build_paired_device_client_mtls_configconfigures the client to present its issued certificate and verify the daemon’s server certificate crates/palyra-identity/tests/mtls_pairing_flow.rs#146-150.
QUIC Transport
Thequic_runtime handles low-latency, encrypted streams using the palyra-transport-quic crate.
- Binding: The endpoint is initialized with
QuicServerTlsConfigcrates/palyra-daemon/src/quic_runtime.rs#62-80. - Verification: It uses a
ClientCertVerifierto enforce identity checks on every new QUIC connection crates/palyra-daemon/src/quic_runtime.rs#19-25.
Persistence & Revocation
TheIdentityManager manages the lifecycle of paired devices, including certificate rotation and revocation.
Secret Storage
Identity materials are stored in aSecretStore. The FilesystemSecretStore implements encryption-at-rest:
- Encryption: Uses ChaCha20-Poly1305 with a locally generated master key crates/palyra-identity/src/store.rs#16-23.
- OS Hardening: On Windows, it applies ACLs to the store directory to restrict access to the current user SID crates/palyra-identity/src/store.rs#98-105.
Revocation
When a device is removed or a certificate is rotated:- The device ID is added to
revoked_devicescrates/palyra-identity/src/pairing/handshake.rs#158-160. - The certificate fingerprint is added to the
revoked_certificate_fingerprintslist crates/palyra-identity/tests/mtls_pairing_flow.rs#161-163. - The
MemoryRevocationIndexis updated, causing existing mTLS connections to be rejected upon reconnection crates/palyra-identity/tests/mtls_pairing_flow.rs#137-143.
| Entity | Code Reference | Responsibility |
|---|---|---|
IdentityManager | crates/palyra-identity/src/lib.rs | Orchestrates CA, pairing, and store. |
SecretStore | crates/palyra-identity/src/store.rs | Abstract interface for encrypted persistence. |
DeviceIdentity | crates/palyra-identity/src/device.rs | Representation of a client’s public/private keys. |
PairingCommand | crates/palyra-cli/src/commands/pairing.rs | CLI interface for managing pairing codes. |