gklib

Ghostkey Library (ghostkey_lib)

A Rust library for creating and managing ghost keys and certificates in the Freenet ecosystem.

Features

• Creation and verification of notary certificates (the PKI intermediate)
• Creation and verification of ghost key certificates
• RSA and Ed25519 cryptographic operations
• Serialization and deserialization of certificates

Main Components

• NotaryCertificateV1: Represents a notary certificate signed by the master key. Historically called DelegateCertificateV1; renamed in 0.2.0 to deconflict with Freenet's own Delegate (sandboxed WASM agent) concept. In particular the Ghostkey Vault (https://github.com/freenet/ghostkeys) is the delegate that holds user ghost keys on a Freenet node — "vault" is its product name. The old name is preserved as a deprecated type alias and the old module path (ghostkey_lib::delegate_certificate) continues to re-export the renamed types through a stub module. Both are slated for removal in a future release. See issue #24.
• GhostkeyCertificateV1: Represents a ghost key certificate signed by a notary key
• Armorable: Trait for serializing and deserializing objects to/from bytes and armored strings

Usage

Add this to your Cargo.toml:

[dependencies]
ghostkey_lib = "0.2" # Replace with the latest version

Example usage:

use ghostkey_lib::notary_certificate::NotaryCertificateV1;
use ghostkey_lib::ghost_key_certificate::GhostkeyCertificateV1;
use ghostkey_lib::util::create_keypair;
use rand_core::OsRng;

// Create a master key pair
let (master_signing_key, master_verifying_key) = create_keypair(&mut OsRng).unwrap();

// Create a notary certificate
let info = "Test Notary".to_string();
let (notary_certificate, notary_signing_key) =
    NotaryCertificateV1::new(&master_signing_key, &info).unwrap();

// Create a ghost key certificate
let (ghost_key_certificate, ghost_key_signing_key) =
    GhostkeyCertificateV1::new(&notary_certificate, &notary_signing_key);

// Verify the ghost key certificate
let verified_info = ghost_key_certificate
    .verify(&Some(master_verifying_key))
    .unwrap();
assert_eq!(verified_info, info);

Wire-Format Compatibility

Ghost-key certificates minted by ghostkey_lib 0.1.4 and earlier are fully interchangeable with 0.2.0. The rename is a source-API change only:

• CBOR field names in the signed payload are frozen via #[serde(rename)].
• PEM armor headers accept both BEGIN NOTARY_CERTIFICATE_V1 (new writes) and BEGIN DELEGATE_CERTIFICATE_V1 (legacy reads).
• A regression test suite in tests/legacy_v1_compat.rs loads real fixtures generated by the pre-rename code and asserts byte-identical round-trip.

License

ghostkey_lib is released under the GNU Lesser General Public License v3.0.