pub struct EntityKeypair { /* private fields */ }Expand description
Entity keypair — ed25519 signing key + public identity.
This is the root of trust for a node. The signing key must be
kept secret. The EntityId (public key) is freely shareable.
§Full vs. public-only
Most keypairs carry both halves: a SigningKey (32-byte secret
seed) plus the derived EntityId. The migration-target path
may instead receive a public-only keypair — same entity_id
and origin_hash, but with the signing half absent. Public-only
keypairs satisfy every entity_id / origin_hash / node_id
query the mesh does routinely, but refuse to sign. This exists
because a daemon that migrated under “transport_identity = false”
(see DAEMON_IDENTITY_MIGRATION_PLAN.md) reaches the target with
its public identity intact but no private material — the plan’s
deliberate trade-off for workloads that don’t need post-migration
signing capability.
Callers that may receive a public-only keypair should use
Self::try_sign / Self::is_read_only; Self::sign
panics on a public-only keypair because most call sites own a
freshly generated keypair and a silent “signed with zeros”
fallback would be worse than a panic.
Implementations§
Source§impl EntityKeypair
impl EntityKeypair
Sourcepub fn generate() -> Self
pub fn generate() -> Self
Generate a new random keypair.
getrandom::fill failure is a fatal condition for an
identity layer that issues secret keys (predictable bytes
produce a forgeable ed25519 secret), so the safe response
is to terminate the process rather than unwind. We use
std::process::abort() instead of expect/panic! because
abort does not unwind and is extern "C"-safe — these
helpers are reachable from the FFI bindings under
ffi/mesh.rs, where unwinding through an extern "C" frame
is undefined behaviour.
Sourcepub fn from_signing_key(signing_key: SigningKey) -> Self
pub fn from_signing_key(signing_key: SigningKey) -> Self
Create from an existing ed25519 signing key.
Sourcepub fn from_bytes(secret: [u8; 32]) -> Self
pub fn from_bytes(secret: [u8; 32]) -> Self
Create from raw secret key bytes (32 bytes).
Sourcepub fn public_only(entity_id: EntityId) -> Self
pub fn public_only(entity_id: EntityId) -> Self
Create a public-only keypair — an EntityId without its
signing half. Sign attempts return EntityError::ReadOnly
(via Self::try_sign) or panic (via Self::sign).
Used by the migration-target path when a caller opts out of
private-key transport; the daemon keeps its public identity
(so origin_hash stays stable and the causal chain continues)
but cannot sign new capability announcements or mint new
permission tokens from the target.
Sourcepub fn origin_hash(&self) -> u64
pub fn origin_hash(&self) -> u64
Get the cached origin hash. The per-packet
NetHeader::origin_hash callers downcast via as u32.
Sourcepub fn is_read_only(&self) -> bool
pub fn is_read_only(&self) -> bool
true iff this keypair has no signing half. Public-only
keypairs survive every entity_id / origin_hash query but
return EntityError::ReadOnly from Self::try_sign and
Self::try_secret_bytes.
Sourcepub fn sign(&self, message: &[u8]) -> Signature
pub fn sign(&self, message: &[u8]) -> Signature
Sign a message. Panics on a public-only keypair; callers
that might hold one must use Self::try_sign instead.
§Panics
If this keypair is public-only (see Self::is_read_only).
Sourcepub fn try_sign(&self, message: &[u8]) -> Result<Signature, EntityError>
pub fn try_sign(&self, message: &[u8]) -> Result<Signature, EntityError>
Fallible sign. Returns EntityError::ReadOnly when this
keypair is public-only; otherwise delegates to the ed25519
signing path.
Sourcepub fn secret_bytes(&self) -> &[u8; 32]
pub fn secret_bytes(&self) -> &[u8; 32]
Get the raw secret key bytes. Panics on a public-only
keypair; callers that might hold one must use
Self::try_secret_bytes.
Handle with care — this is the root secret.
§Panics
If this keypair is public-only (see Self::is_read_only).
Sourcepub fn try_secret_bytes(&self) -> Result<&[u8; 32], EntityError>
pub fn try_secret_bytes(&self) -> Result<&[u8; 32], EntityError>
Fallible secret_bytes. Returns EntityError::ReadOnly
for public-only keypairs.
Sourcepub fn zeroize(&mut self)
pub fn zeroize(&mut self)
Zeroize the signing half in place, converting this keypair
into public-only. The entity_id / origin_hash / node_id
remain available; further sign / secret_bytes calls go
down the try_* / read-only path.
Called by the migration-source handler after
ActivateAck arrives from the target — the source no longer
needs to sign on behalf of this daemon, and holding the key
longer than necessary widens the dual-custody window beyond
the plan’s invariant. Idempotent; second call is a no-op.