palyra-identity crate provides the foundation for secure communication and device trust within the Palyra ecosystem. It manages Ed25519 keypairs for device identification, handles X.509 certificate generation via an internal Certificate Authority (CA), and implements a multi-step pairing handshake for new nodes. Security is enforced through Mutual TLS (mTLS) for all node-to-node and node-to-daemon RPC communications.
Identity Core Entities
Palyra uses a tiered identity model where the daemon acts as a Root of Trust for its connected nodes.- DeviceIdentity: Represents a specific hardware/software instance. It contains an Ed25519 signing keypair used to prove identity during handshakes and sign CSRs crates/palyra-identity/src/device.rs#1-50.
- CertificateAuthority (CA): The daemon maintains an internal CA. It generates a self-signed root certificate and issues short-lived leaf certificates to paired devices crates/palyra-identity/src/ca.rs#10-100.
- IdentityManager: The central orchestrator in
palyra-identitythat manages pairing sessions, certificate issuance, and the revocation list crates/palyra-identity/src/pairing/manager.rs#20-80.
Identity Data Flow
The following diagram illustrates how identity materials are generated and stored. Identity Generation & Storage Flow Sources: crates/palyra-identity/src/pairing/manager.rs#20-80, crates/palyra-identity/src/store.rs#87-115, crates/palyra-identity/src/device.rs#1-20Device Pairing Handshake (TOFU)
Pairing is a Trust-On-First-Use (TOFU) mechanism that upgrades an unauthenticated connection to a trusted, mTLS-secured session. It involves a cryptographic exchange (Device Hello) verified against a pre-shared secret (PIN or QR token).- Start Pairing: The daemon creates an
ActivePairingSessionwith a challenge and an ephemeral X25519 public key crates/palyra-identity/src/pairing/handshake.rs#27-52. - Device Hello: The connecting node generates a
DevicePairingHellocontaining itsdevice_id, public signing key, and a signature over the transcript crates/palyra-identity/src/pairing/handshake.rs#111-118. - Verification: The
IdentityManagerverifies the signature using the device’s public key and checks the proof (e.g., PIN) crates/palyra-identity/src/pairing/handshake.rs#150-190. - Finalization: Upon success, the device is added to
paired_devicesand issued its first mTLS certificate crates/palyra-identity/src/pairing/handshake.rs#120-127.
mTLS Configuration & Enforcement
Palyra enforces mTLS for all Node RPC communication. The daemon requires a valid client certificate issued by its internal CA for any request to theNodeService.
Server-Side Enforcement
TheQuicRuntime and gRPC server use a ClientCertVerifier to validate incoming certificates against the daemon’s Root CA crates/palyra-daemon/src/quic_runtime.rs#19-25.
| Feature | Implementation | File Reference |
|---|---|---|
| CA Validation | rustls RootCertStore | crates/palyra-identity/src/mtls.rs#10-30 |
| Revocation Check | Fingerprint-based CRL in IdentityManager | crates/palyra-identity/src/pairing/revocation.rs#5-40 |
| Enforcement Toggle | node_rpc_mtls_required flag | crates/palyra-daemon/src/quic_runtime.rs#82-90 |
Node RPC Test Patterns
Integration tests innode_rpc_mtls.rs verify that:
- Clients without certificates are rejected with
Unauthenticatedcrates/palyra-daemon/tests/node_rpc_mtls.rs#45-69. - Clients with valid certificates are accepted crates/palyra-daemon/tests/node_rpc_mtls.rs#72-92.
- Revoked certificates result in
PermissionDeniedcrates/palyra-daemon/tests/node_rpc_mtls.rs#95-118.
Secret Store & Persistence
Thepalyra-identity crate provides a SecretStore trait to abstract the storage of sensitive identity materials (CA keys, device keys, and state bundles).
FilesystemSecretStore
TheFilesystemSecretStore implements encrypted storage using ChaCha20-Poly1305 crates/palyra-identity/src/store.rs#16-23.
- Encryption Key: Stored in
.store-key.v1within the identity directory crates/palyra-identity/src/store.rs#23. - Platform Hardening: On Windows, it uses
palyra_common::windows_securityto restrict file access to the current user SID crates/palyra-identity/src/store.rs#98-105. On Unix, it enforces0o700permissions crates/palyra-identity/src/store.rs#108-114. - Atomic Writes: Uses temporary files and
fs::renameto prevent state corruption during writes crates/palyra-identity/src/store.rs#177-198.
State Concurrency
To prevent multiple processes (e.g., CLI and Daemon) from corrupting the identity state, a file-based lock mechanism is used.- Lock File:
.identity-state.lockcrates/palyra-identity/src/pairing/persistence.rs#34. - Stale Lock Reclamation: If a process crashes, the lock is reclaimed after 30 seconds if the owner PID is no longer active crates/palyra-identity/src/pairing/persistence.rs#184-210.
Certificate Rotation & Revocation
Certificates in Palyra are designed to be short-lived (DEFAULT_CERT_VALIDITY).
Rotation
TheIdentityManager provides issue_gateway_server_certificate to rotate the daemon’s own transport certificates. Nodes are expected to re-pair or use a refresh protocol (managed via the Control Plane) when their leaf certificates approach expiry.
Revocation
Revocation is handled via therevocation.rs module. The daemon maintains:
- revoked_devices: A map of Device IDs that are no longer allowed to connect crates/palyra-identity/src/pairing/revocation.rs#10-25.
- revoked_certificate_fingerprints: A set of SHA-256 fingerprints for specific certificates that have been invalidated crates/palyra-identity/src/pairing/revocation.rs#27-45.
ClientCertVerifier checks the presented certificate’s fingerprint against this list.
Sources: crates/palyra-identity/src/pairing/revocation.rs#1-50, crates/palyra-identity/src/mtls.rs#5-35