Struct Identity 

pub struct Identity { /* private fields */ }

Cryptographic identity based on Ed25519

Each node in the network has a unique identity represented by a key pair. The public key is the node’s identity, the private key never leaves this module.

Security

• Private keys are automatically zeroized on drop
• Uses OS-level CSPRNG for key generation
• Blake3 hashing for fast public key comparisons

Example

use core_identity::Identity;

let mut rng = rand::thread_rng();
let identity = Identity::generate(&mut rng)?;
let public_key = identity.verifying_key();
let public_key_hash = identity.public_key_hash();

assert_eq!(public_key_hash.len(), 32);

Implementations

impl Identity

pub fn generate<R>(csprng: &mut R) -> Result<Identity, IdentityError>

where R: RngCore + CryptoRng,

Generates a new identity using a provided CSPRNG.

Example

use core_identity::Identity;

let mut rng = rand::thread_rng();
let identity = Identity::generate(&mut rng).expect("Failed to generate identity");
assert_eq!(identity.public_key_hash().len(), 32);

Errors

This function is infallible in practice, but returns Result for consistency with the API.

Examples found in repository

examples/simple_auth_flow.rs (line 28)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("p47h Open Core - Simple Authorization Flow");
    println!("-------------------------------------------");
    println!();

    // -------------------------------------------------------------------------
    // Step 1: Create Identities
    // -------------------------------------------------------------------------
    // Each user or device in the network has a unique cryptographic identity.
    // The identity is an Ed25519 keypair. We use the public key hash as the
    // peer identifier for policy rules.

    let mut rng = rand::thread_rng();

    let alice = Identity::generate(&mut rng)?;
    let alice_id = format!("alice-{}", hex::encode(&alice.public_key_hash()[..4]));

    let bob = Identity::generate(&mut rng)?;
    let bob_id = format!("bob-{}", hex::encode(&bob.public_key_hash()[..4]));

    println!("Created identities:");
    println!("  Alice: {}", alice_id);
    println!("  Bob:   {}", bob_id);
    println!();

    // -------------------------------------------------------------------------
    // Step 2: Define a Policy
    // -------------------------------------------------------------------------
    // A policy is a collection of rules that define who can do what on which
    // resources. Each rule specifies:
    //   - peer_id: The identity this rule applies to
    //   - action: What operation is allowed (Read, Write, Execute, Delete, All)
    //   - resource: What resource pattern this applies to (supports wildcards)

    // Policy parameters:
    //   - name: Human-readable identifier
    //   - valid_duration: How long the policy is valid (in seconds)
    //   - current_time: Unix timestamp when the policy was created
    let current_time = 1700000000; // Fixed timestamp for reproducibility
    let valid_duration = 86400; // 24 hours

    let policy = Policy::new("file-access-policy", valid_duration, current_time)?
        // Rule 1: Alice can read any file under /data/
        .add_rule(PolicyRule::new(
            alice_id.clone(),
            Action::Read,
            Resource::File("/data/*".into()),
        ))?
        // Rule 2: Alice can write to her personal directory
        .add_rule(PolicyRule::new(
            alice_id.clone(),
            Action::Write,
            Resource::File("/home/alice/*".into()),
        ))?
        // Rule 3: Bob has full access to the /shared/ directory
        .add_rule(PolicyRule::new(
            bob_id.clone(),
            Action::All,
            Resource::File("/shared/*".into()),
        ))?;

    println!("Created policy: {}", policy.name());
    println!("  Rules: {}", policy.rules().len());
    println!("  Valid until: {} (Unix timestamp)", policy.valid_until());
    println!();

    // -------------------------------------------------------------------------
    // Step 3: Evaluate Access Requests
    // -------------------------------------------------------------------------
    // The PolicyAuthorizer evaluates whether a specific peer can perform a
    // specific action on a specific resource. It checks all rules and returns
    // true if at least one rule allows the access.

    let authorizer = PolicyAuthorizer::new(policy.rules());

    // Define test cases: (peer, action, resource, expected_result)
    let test_cases = [
        // Alice reading from /data/ - should be ALLOWED (Rule 1)
        (&alice_id, Action::Read, "/data/report.txt", true),
        // Alice writing to /data/ - should be DENIED (no rule allows this)
        (&alice_id, Action::Write, "/data/report.txt", false),
        // Alice writing to her home - should be ALLOWED (Rule 2)
        (&alice_id, Action::Write, "/home/alice/notes.txt", true),
        // Bob reading from /data/ - should be DENIED (no rule for Bob on /data/)
        (&bob_id, Action::Read, "/data/report.txt", false),
        // Bob writing to /shared/ - should be ALLOWED (Rule 3, Action::All)
        (&bob_id, Action::Write, "/shared/document.pdf", true),
        // Bob deleting from /shared/ - should be ALLOWED (Rule 3, Action::All)
        (&bob_id, Action::Delete, "/shared/old-file.txt", true),
        // Unknown user - should be DENIED (no rules match)
        (
            &"unknown-user".to_string(),
            Action::Read,
            "/data/file.txt",
            false,
        ),
    ];

    println!("Evaluating access requests:");
    println!();

    for (peer_id, action, resource_path, expected) in test_cases {
        let resource = Resource::File(resource_path.into());
        let allowed = authorizer.is_allowed(peer_id, &action, &resource);

        // Verify our expectations match the actual result
        let status = if allowed { "ALLOWED" } else { "DENIED" };
        let check = if allowed == expected {
            "OK"
        } else {
            "MISMATCH"
        };

        println!(
            "  {} {:?} {} -> {} [{}]",
            peer_id, action, resource_path, status, check
        );
    }

    println!();
    println!("-------------------------------------------");
    println!("Authorization flow completed successfully.");

    Ok(())
}

pub fn from_seed(seed: &[u8; 32]) -> Result<Identity, IdentityError>

Creates an identity from a 32-byte seed

Useful for testing or deriving identities deterministically

Example

use core_identity::Identity;

let seed = [42u8; 32];
let identity1 = Identity::from_seed(&seed).unwrap();
let identity2 = Identity::from_seed(&seed).unwrap();

// Same seed produces same identity
assert_eq!(
    identity1.verifying_key().as_bytes(),
    identity2.verifying_key().as_bytes()
);

pub fn from_bytes(bytes: &[u8; 32]) -> Result<Identity, IdentityError>

Creates an identity from raw signing key bytes

Security

This method should only be used for deserialization from secure storage (e.g., encrypted keystore).

Errors

Currently infallible, but returns Result for API consistency.

pub fn verifying_key(&self) -> VerifyingKey

Returns the public key

This is the identity shared with other nodes

Example

use core_identity::Identity;

let mut rng = rand::thread_rng();
let identity = Identity::generate(&mut rng)?;
let public_key = identity.verifying_key();

// Public key is 32 bytes
assert_eq!(public_key.as_bytes().len(), 32);

pub fn public_key_hash(&self) -> [u8; 32]

Returns the hash of the public key

Uses the configured hash provider (default: Blake3) for efficient lookups.

Examples found in repository

examples/simple_auth_flow.rs (line 29)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("p47h Open Core - Simple Authorization Flow");
    println!("-------------------------------------------");
    println!();

    // -------------------------------------------------------------------------
    // Step 1: Create Identities
    // -------------------------------------------------------------------------
    // Each user or device in the network has a unique cryptographic identity.
    // The identity is an Ed25519 keypair. We use the public key hash as the
    // peer identifier for policy rules.

    let mut rng = rand::thread_rng();

    let alice = Identity::generate(&mut rng)?;
    let alice_id = format!("alice-{}", hex::encode(&alice.public_key_hash()[..4]));

    let bob = Identity::generate(&mut rng)?;
    let bob_id = format!("bob-{}", hex::encode(&bob.public_key_hash()[..4]));

    println!("Created identities:");
    println!("  Alice: {}", alice_id);
    println!("  Bob:   {}", bob_id);
    println!();

    // -------------------------------------------------------------------------
    // Step 2: Define a Policy
    // -------------------------------------------------------------------------
    // A policy is a collection of rules that define who can do what on which
    // resources. Each rule specifies:
    //   - peer_id: The identity this rule applies to
    //   - action: What operation is allowed (Read, Write, Execute, Delete, All)
    //   - resource: What resource pattern this applies to (supports wildcards)

    // Policy parameters:
    //   - name: Human-readable identifier
    //   - valid_duration: How long the policy is valid (in seconds)
    //   - current_time: Unix timestamp when the policy was created
    let current_time = 1700000000; // Fixed timestamp for reproducibility
    let valid_duration = 86400; // 24 hours

    let policy = Policy::new("file-access-policy", valid_duration, current_time)?
        // Rule 1: Alice can read any file under /data/
        .add_rule(PolicyRule::new(
            alice_id.clone(),
            Action::Read,
            Resource::File("/data/*".into()),
        ))?
        // Rule 2: Alice can write to her personal directory
        .add_rule(PolicyRule::new(
            alice_id.clone(),
            Action::Write,
            Resource::File("/home/alice/*".into()),
        ))?
        // Rule 3: Bob has full access to the /shared/ directory
        .add_rule(PolicyRule::new(
            bob_id.clone(),
            Action::All,
            Resource::File("/shared/*".into()),
        ))?;

    println!("Created policy: {}", policy.name());
    println!("  Rules: {}", policy.rules().len());
    println!("  Valid until: {} (Unix timestamp)", policy.valid_until());
    println!();

    // -------------------------------------------------------------------------
    // Step 3: Evaluate Access Requests
    // -------------------------------------------------------------------------
    // The PolicyAuthorizer evaluates whether a specific peer can perform a
    // specific action on a specific resource. It checks all rules and returns
    // true if at least one rule allows the access.

    let authorizer = PolicyAuthorizer::new(policy.rules());

    // Define test cases: (peer, action, resource, expected_result)
    let test_cases = [
        // Alice reading from /data/ - should be ALLOWED (Rule 1)
        (&alice_id, Action::Read, "/data/report.txt", true),
        // Alice writing to /data/ - should be DENIED (no rule allows this)
        (&alice_id, Action::Write, "/data/report.txt", false),
        // Alice writing to her home - should be ALLOWED (Rule 2)
        (&alice_id, Action::Write, "/home/alice/notes.txt", true),
        // Bob reading from /data/ - should be DENIED (no rule for Bob on /data/)
        (&bob_id, Action::Read, "/data/report.txt", false),
        // Bob writing to /shared/ - should be ALLOWED (Rule 3, Action::All)
        (&bob_id, Action::Write, "/shared/document.pdf", true),
        // Bob deleting from /shared/ - should be ALLOWED (Rule 3, Action::All)
        (&bob_id, Action::Delete, "/shared/old-file.txt", true),
        // Unknown user - should be DENIED (no rules match)
        (
            &"unknown-user".to_string(),
            Action::Read,
            "/data/file.txt",
            false,
        ),
    ];

    println!("Evaluating access requests:");
    println!();

    for (peer_id, action, resource_path, expected) in test_cases {
        let resource = Resource::File(resource_path.into());
        let allowed = authorizer.is_allowed(peer_id, &action, &resource);

        // Verify our expectations match the actual result
        let status = if allowed { "ALLOWED" } else { "DENIED" };
        let check = if allowed == expected {
            "OK"
        } else {
            "MISMATCH"
        };

        println!(
            "  {} {:?} {} -> {} [{}]",
            peer_id, action, resource_path, status, check
        );
    }

    println!();
    println!("-------------------------------------------");
    println!("Authorization flow completed successfully.");

    Ok(())
}

pub fn sign(&self, message: &[u8]) -> Signature

Signs a message with the private key

Arguments

• message - The bytes to sign

Returns

A signature that can be verified with the public key

Example

use core_identity::{Identity, verify_signature};

let mut rng = rand::thread_rng();
let identity = Identity::generate(&mut rng)?;
let message = b"Important message";

let signature = identity.sign(message);
verify_signature(&identity.verifying_key(), message, &signature)?;

pub fn signing_key_bytes(&self) -> Secret<Vec<u8>>

Returns the signing key bytes for serialization

Security

This method returns a Secret<Vec<u8>> that prevents accidental exposure:

• Cannot be printed with Debug/Display
• Will not appear in logs automatically
• Requires explicit .expose_secret() to access

Should only be used for:

• Secure serialization (encrypted keystore)
• Conversion to libp2p keypair
• Low-level cryptographic operations

WARNING: Use .expose_secret() only when absolutely necessary. The exposed bytes should be:

• Encrypted immediately if stored
• Zeroized after use
• Never logged or transmitted unencrypted

Example

use core_identity::Identity;
use secrecy::ExposeSecret;

let mut rng = rand::thread_rng();
let identity = Identity::generate(&mut rng)?;

// Get the secret bytes
let secret_bytes = identity.signing_key_bytes();

// Only expose when needed for cryptographic operations
let raw_bytes = secret_bytes.expose_secret();
// Use raw_bytes for signing, serialization, etc.

Trait Implementations

impl Drop for Identity

fn drop(&mut self)

Executes the destructor for this type.