Crate void_crypto 

void-crypto: Cryptographic primitives and key management for void.

This crate is the sole custodian of repository encryption key material. It provides:

• AES-256-GCM authenticated encryption with AAD
• HKDF-SHA256 key derivation with purpose separation
• Per-commit envelope encryption (VD01 format)
• KeyVault: an opaque vault that holds the root key and provides operations
• CommitReader: a per-commit handle for decrypting metadata and shards
• Scoped access tokens for limited read access

Security Architecture

The root key never leaves this crate. External crates interact with key material only through:

• KeyVault methods (open_commit, seal_commit, derived key accessors)
• CommitReader methods (decrypt_metadata, decrypt_shard)
• SecretKey references (derived keys for index/stash/staged)

Raw [u8; 32] key parameters are pub(crate) only — the crate boundary is the enforcement mechanism.

Re-exports

pub use reader::decrypt_object;

pub use reader::decrypt_object_parse;

pub use reader::decrypt_object_raw;

pub use reader::decrypt_shard_data;

pub use reader::CommitReader;

pub use identity::derive_repo_owner_signing_key;

pub use identity::ecies_unwrap_key;

pub use identity::ecies_wrap_key;

pub use identity::Identity;

pub use identity::IdentityError;

pub use identity::ParsedIdentity;

pub use ecies::EciesError;

pub use seed::derive_nostr_key;

pub use seed::derive_recipient_key;

pub use seed::derive_repo_owner_key;

pub use seed::derive_signing_key;

pub use seed::generate_mnemonic;

pub use seed::mnemonic_to_seed;

pub use seed::SeedError;

pub use pin::decrypt_identity_keys;

pub use pin::encrypt_identity_keys;

pub use pin::PinError;

pub use vault::KeyVault;

Modules

ecies

Shared ECIES (Elliptic Curve Integrated Encryption Scheme) operations.

identity

Identity management for void collaboration.

pin

PIN-based encryption for identity keys.

reader

CommitReader: encapsulates the commit→metadata→shard key derivation chain.

seed

BIP-39 mnemonic and deterministic key derivation for void identities.

vault

KeyVault: opaque custodian of repository key material.

Structs

CommitCid

CID pointing to an envelope-encrypted commit blob (AAD_COMMIT).

CommitSignature

Ed25519 signature over commit signable bytes (64 bytes).

ContentKey

A 32-byte content key derived from a commit’s envelope nonce.

ContributorId

Full contributor identity combining signing and recipient public keys.

EncryptedCommit

Encrypted commit blob (AAD_COMMIT).

EncryptedIndex

Encrypted workspace index blob (AAD_INDEX).

EncryptedManifest

Encrypted tree manifest blob (AAD_MANIFEST).

EncryptedMetadata

Encrypted metadata bundle blob (AAD_METADATA).

EncryptedRepoManifest

Encrypted repo manifest blob (AAD_REPO_MANIFEST).

EncryptedShard

Encrypted content shard blob (AAD_SHARD).

EncryptedStaged

Encrypted staged file content blob (AAD_STAGED).

EncryptedStash

Encrypted stash stack metadata blob (AAD_STASH).

IdentitySeed

BIP-39 seed bytes (64 bytes). Zeroed on drop.

KeyRing

Key ring holding all derived keys - zeroed on drop.

ManifestCid

CID pointing to an AEAD-encrypted tree manifest (AAD_MANIFEST).

MetadataCid

CID pointing to an AEAD-encrypted metadata bundle (AAD_METADATA).

Nonce

A fixed-size cryptographic nonce.

NostrPubKey

Secp256k1 x-only (schnorr) public key for Nostr transport (32 bytes).

NostrSecretKey

Secp256k1 secret key for Nostr transport (32 bytes). Zeroed on drop.

RecipientPubKey

X25519 public key for ECIES encryption (32 bytes).

RecipientSecretKey

X25519 secret key for ECIES decryption (32 bytes). Zeroed on drop.

RepoKey

Thin wrapper for repository encryption keys (AES-256, 32 bytes).

RepoManifestCid

CID pointing to an AEAD-encrypted repo manifest (AAD_REPO_MANIFEST).

RepoSecret

A 32-byte random secret used for shard path hashing (NOT an encryption key).

ScopedAccessToken

A token granting scoped read access to specific paths or branches.

ScopedKeyRing

A key ring holding scoped access tokens.

SecretKey

A 32-byte derived key that is zeroed on drop.

ShardCid

CID pointing to an encrypted shard blob (AAD_SHARD).

ShareKey

A derived key from share-based unseal.

SigningPubKey

Ed25519 public key for verifying signatures (32 bytes).

SigningSecretKey

Ed25519 secret key for signing (32 bytes). Zeroed on drop.

WrappedKey

ECIES-wrapped key blob (variable length).

Enums

CryptoError

Errors that can occur in void-crypto.

KeyPurpose

Key purposes for derivation.

ParseError

Error parsing key types from strings.

Constants

AAD_COMMIT

AAD for commit objects.

AAD_INDEX

AAD for index objects.

AAD_MANIFEST

AAD for tree manifest objects.

AAD_METADATA

AAD for metadata bundle objects.

AAD_REPO_MANIFEST

AAD for repo manifest (collaboration manifest JSON).

AAD_SHARD

AAD for shard objects.

AAD_SHARD_KEY

AAD for shard key wrapping (content_key wraps shard_key).

AAD_STAGED

AAD for staged content blobs.

AAD_STASH

AAD for stash objects.

MAGIC_V1

Magic bytes identifying envelope format version 1.

Traits

EncryptedBlob

Common interface for typed encrypted blob newtypes.

Functions

decrypt

Decrypts ciphertext using AES-256-GCM with Additional Authenticated Data (AAD).

decrypt_and_parse

Decrypt and parse a CBOR-encoded type.

decrypt_envelope

Decrypts a blob with envelope format (VD01 header required).

decrypt_to_vec

Decrypts ciphertext into a byte buffer.

derive_key

Derives a 32-byte key from the root key using HKDF-SHA256.

derive_key_for_purpose

Derive a purpose-specific key from the root key.

derive_scoped_key

Derive a scoped read key from a root key.

encrypt

Encrypts plaintext using AES-256-GCM with Additional Authenticated Data (AAD).

encrypt_with_envelope

Encrypts plaintext using a derived key and wraps it in an envelope.

generate_key

Generates a cryptographically secure random 32-byte key.

generate_key_nonce

Generates a cryptographically secure random key nonce.

unwrap_shard_key

Unwrap a shard key that was wrapped under a content key.

wrap_shard_key

Wrap a shard key under a content key using AES-256-GCM.

Type Aliases

AeadNonce

12-byte nonce for AES-256-GCM authenticated encryption.

CryptoResult

Result type for void-crypto operations.

KeyNonce

16-byte nonce for VD01 envelope key derivation.