pub struct KeyChain { /* private fields */ }Expand description
A named NDN identity with an associated signing key and trust anchors.
KeyChain is the single entry point for NDN security in both applications
and the forwarder. It owns a signing key, a certificate cache, and a set of
trust anchors, and exposes methods for signing packets and building validators.
§Constructors
KeyChain::ephemeral— in-memory, self-signed; ideal for tests and short-lived producers.KeyChain::open_or_create— file-backed PIB; generates a key on first run and reloads it on subsequent runs.KeyChain::from_parts— construct from a pre-builtSecurityManager; intended for framework code (NDNCERT enrollment, device provisioning).
§Examples
use ndn_security::KeyChain;
// Ephemeral identity (testing / short-lived producers)
let kc = KeyChain::ephemeral("/com/example/alice")?;
let signer = kc.signer()?;
// Persistent identity
let kc = KeyChain::open_or_create(
std::path::Path::new("/var/lib/ndn"),
"/com/example/alice",
)?;Implementations§
Source§impl KeyChain
impl KeyChain
Sourcepub fn ephemeral(name: impl AsRef<str>) -> Result<Self, TrustError>
pub fn ephemeral(name: impl AsRef<str>) -> Result<Self, TrustError>
Create an ephemeral, in-memory identity with a freshly generated Ed25519 key.
The key is self-signed with a 365-day certificate and registered as a
trust anchor. Keys are not persisted — use open_or_create for
long-lived identities.
Sourcepub fn open_or_create(
path: &Path,
name: impl AsRef<str>,
) -> Result<Self, TrustError>
pub fn open_or_create( path: &Path, name: impl AsRef<str>, ) -> Result<Self, TrustError>
Open a persistent identity from a PIB directory, creating it if absent.
On first run, generates an Ed25519 key and self-signed certificate. On subsequent runs, loads the existing key and certificate from disk.
Sourcepub fn from_parts(mgr: Arc<SecurityManager>, name: Name, key_name: Name) -> Self
pub fn from_parts(mgr: Arc<SecurityManager>, name: Name, key_name: Name) -> Self
Construct a KeyChain from a pre-built SecurityManager.
This is an escape hatch for framework code (NDNCERT enrollment, device
provisioning) that needs to build a SecurityManager before wrapping it.
Prefer ephemeral or open_or_create for application code.
Sourcepub fn key_name(&self) -> &Name
pub fn key_name(&self) -> &Name
The name of the active signing key (e.g. /com/acme/alice/KEY/v=0).
Sourcepub fn validator(&self) -> Validator
pub fn validator(&self) -> Validator
Build a Validator pre-configured with this identity’s trust anchors.
Uses TrustSchema::accept_all by default (any correctly-signed packet
whose certificate chain terminates in a known anchor is accepted). For
stricter namespace-based policy, call
Validator::set_schema on the result or
use TrustSchema::hierarchical.
Sourcepub fn add_trust_anchor(&self, cert: Certificate)
pub fn add_trust_anchor(&self, cert: Certificate)
Add an external trust anchor certificate.
Use this to accept data signed by a CA that was not issued by this identity (e.g., a network-wide trust anchor discovered via NDNCERT).
Sourcepub fn cert_cache(&self) -> &CertCache
pub fn cert_cache(&self) -> &CertCache
Access the certificate cache.
Useful for pre-populating the cache with known intermediate certificates before validation.
Sourcepub fn trust_only(
anchor_prefix: impl AsRef<str>,
) -> Result<Validator, TrustError>
pub fn trust_only( anchor_prefix: impl AsRef<str>, ) -> Result<Validator, TrustError>
Build a Validator that trusts only certificates issued under anchor_prefix.
Shorthand for creating a consumer-side validator when you know the
trust-anchor prefix and don’t need a full KeyChain. For example, to
accept Data signed by any certificate under /ndn/testbed:
use ndn_security::KeyChain;
let validator = KeyChain::trust_only("/ndn/testbed").unwrap();Uses TrustSchema::hierarchical so the Data name must be a sub-name
of the signing certificate prefix.
Sourcepub fn sign_data(&self, builder: DataBuilder) -> Result<Bytes, TrustError>
pub fn sign_data(&self, builder: DataBuilder) -> Result<Bytes, TrustError>
Sign a Data packet using this KeyChain’s signing key.
Returns the encoded, signed Data wire bytes. Uses Ed25519 with the key locator set to this identity’s key name.
§Errors
Returns TrustError if the signing key is not available.
Sourcepub fn sign_interest(
&self,
builder: InterestBuilder,
) -> Result<Bytes, TrustError>
pub fn sign_interest( &self, builder: InterestBuilder, ) -> Result<Bytes, TrustError>
Sign an Interest using this KeyChain’s signing key.
Returns the encoded, signed Interest wire bytes. Uses Ed25519 with the key locator set to this identity’s key name.
§Errors
Returns TrustError if the signing key is not available.
Sourcepub fn build_validator(&self) -> Validator
pub fn build_validator(&self) -> Validator
Sourcepub fn manager_arc(&self) -> Arc<SecurityManager>
pub fn manager_arc(&self) -> Arc<SecurityManager>
The Arc-wrapped SecurityManager backing this keychain.
Intended for framework code (e.g., background renewal tasks) that needs to share the manager across async tasks. Prefer the higher-level methods for application code.