palyra-identity crate is the foundational security layer for the Palyra ecosystem. It manages the cryptographic lifecycle of devices, including Ed25519 signing keys, X25519 exchange keys, and X.509 certificates used for mutual TLS (mTLS) in QUIC and gRPC communications. It also orchestrates the multi-step pairing handshake required to onboard new nodes and clients into a trusted mesh.
Secret Storage and Persistence
Palyra uses a tiered storage model for sensitive identity material. TheSecretStore trait provides an abstraction for reading, writing, and deleting secrets.
FilesystemSecretStore
TheFilesystemSecretStore is the primary implementation for persistent storage on disk. It enforces strict OS-level permissions and uses authenticated encryption for all stored values.
- Encryption: Data is encrypted using
CHACHA20_POLY1305crates/palyra-identity/src/store.rs#16. A master store key is maintained in.store-key.v1crates/palyra-identity/src/store.rs#23. - Linux/macOS Security: Directories are created with
0o700permissions, and files are restricted to the owner crates/palyra-identity/src/store.rs#110-111. - Windows Security: Uses DPAPI (Data Protection API) via
palyra_common::windows_securityto protect the store key and enforces NTFS ACLs crates/palyra-identity/src/store.rs#100-104. - Key Derivation: Secret keys are hex-encoded to form filenames within the store root crates/palyra-identity/src/store.rs#126.
Vault Backends
Whilepalyra-identity handles the core device keys, the palyra-vault crate provides higher-level blob storage for application secrets using BackendKind crates/palyra-vault/src/backend.rs#41:
EncryptedFile: Standard encrypted file storage.MacosKeychain: Integration with Apple’s Keychain crates/palyra-vault/src/backend.rs#44.LinuxSecretService: Integration with libsecret/dbus crates/palyra-vault/src/backend.rs#46.WindowsDpapi: Integration with Windows Data Protection API crates/palyra-vault/src/backend.rs#48.
Device Identity and Keys
Every participant in the Palyra network is identified by aDeviceIdentity. This identity consists of a canonical ULID device_id and a set of cryptographic key pairs.
Key Types
- Ed25519: Used for signing pairing requests and authenticating control plane messages.
- X25519: Used for Diffie-Hellman key exchange during the pairing handshake to establish a shared secret without exposing it to the transport layer.
Identity Management
TheIdentityManager acts as the orchestrator for the local device’s identity and the registry of known PairedDevice entities crates/palyra-identity/src/pairing/handshake.rs#58. It manages:
- Rotation: Support for rotating signing keys.
- Revocation: Maintaining a list of
revoked_devicesto prevent compromised nodes from reconnecting crates/palyra-identity/src/pairing/handshake.rs#158.
Pairing Handshake
The pairing process is a cryptographic handshake that upgrades an out-of-band “proof” (like a QR code or numeric PIN) into a permanent mTLS trust relationship.Handshake Flow
TheIdentityManager implements the start_pairing, verify_pairing, and finalize_verified_pairing sequence.
1. Initiation
The gateway generates aPairingSession containing an ephemeral X25519 public key and a random challenge crates/palyra-identity/src/pairing/handshake.rs#41-49.
2. Device Hello
The joining device responds with aDevicePairingHello. This structure includes its own ephemeral X25519 key, its permanent Ed25519 public key, and a signature over the transcript crates/palyra-identity/src/pairing/handshake.rs#111-118.
3. Verification
TheIdentityManager verifies:
- Proof Match: The out-of-band proof must match exactly crates/palyra-identity/src/pairing/handshake.rs#180.
- Signature: The device’s signature over the handshake transcript (including challenges and ephemeral keys) must be valid crates/palyra-identity/src/pairing/handshake.rs#190-195.
- Expiration: The session must not have timed out crates/palyra-identity/src/pairing/handshake.rs#167.
Pairing Handshake Logic
Title: Pairing Handshake Sequence Sources: crates/palyra-identity/src/pairing/handshake.rs#27-109, crates/palyra-identity/src/pairing/handshake.rs#150-195mTLS and Transport Security
Once paired, nodes communicate using mTLS. Thepalyra-identity crate facilitates this by managing the X.509 certificates used by the QUIC and gRPC transport layers.
Certificate Management
- Generation: Certificates are generated with a default validity period (
DEFAULT_CERT_VALIDITY) crates/palyra-cli/src/commands/pairing.rs#2. - Fingerprinting: Certificates are identified and validated via SHA-256 fingerprints crates/palyra-identity/src/pairing/handshake.rs#17.
- Verification: During the TLS handshake, the peer’s certificate fingerprint is checked against the
PairedDeviceregistry stored in theIdentityManager.
Code Entity Mapping
Title: Identity Code Entities and Roles Sources: crates/palyra-identity/src/store.rs#25-31, crates/palyra-identity/src/store.rs#87-92, crates/palyra-identity/src/pairing/handshake.rs#27-52Revocation and Safety
The system includes mechanisms to protect against brute-force attacks and compromised devices.- Rate Limiting:
IdentityManagertracksrecent_pairing_startsand enforces a maximum number of pairing attempts per time window crates/palyra-identity/src/pairing/handshake.rs#92-97. - Session Pruning: Expired pairing sessions are automatically removed from memory during initiation or completion of new sessions crates/palyra-identity/src/pairing/handshake.rs#59-70.
- Revocation List: Devices can be explicitly revoked. Any pairing attempt or connection from a
device_idpresent in therevoked_devicesmap is immediately rejected crates/palyra-identity/src/pairing/handshake.rs#158-160. - Constant-Time Comparisons: Proof verification uses
constant_time_eqto prevent timing attacks that could leak pairing codes crates/palyra-identity/src/pairing/handshake.rs#180.