Struct BackendManager 

pub struct BackendManager { /* private fields */ }

Routes catalog keys to their declared backend instances.

Constructed from a validated Catalog plus a map of already-built backend instances keyed by the catalog backends names. Constructing the backends from credentials is out of scope (that is vault-vh1 / the bin); this layer only routes.

Implementations

impl BackendManager

pub fn new( catalog: Catalog, backends: BTreeMap<String, Box<dyn Backend>>, ) -> Result<Self, ManagerError>

Build a manager from a catalog + the named, already-constructed backends.

Validates that every catalog.keys[*].backend names a present backend instance, failing closed with ManagerError::UnknownBackend otherwise.

Errors

Returns ManagerError::UnknownBackend if a key references a backend name absent from backends.

pub fn catalog(&self) -> Arc<Catalog>

Shared immutable catalog this manager routes against.

pub fn resolve(&self, key_id: &str) -> Result<Routed<'_>, ManagerError>

Resolve a dotted catalog name to its backend instance + metadata.

Errors

• ManagerError::UnknownKey if key_id is not in the catalog.
• ManagerError::UnknownBackend if the key’s backend is missing (impossible after BackendManager::new validation, but checked so resolution never panics on a missing instance).

pub async fn new_key( &self, key_id: &str, key_type: KeyType, ) -> Result<NewKey, ManagerError>

new_key creates a key under catalog name key_id.

Valid for crypto keys (asymmetric / symmetric). This is the request-time op, where the backend assigns the on-backend id. Startup reconcile (crate::reconcile) instead creates a generate-policy key at its catalog path via Backend::create_named_key / Backend::create_named_aead so the named material exists before any op resolves to it.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (for a value / public key), or ManagerError::Backend.

pub async fn sign( &self, key_id: &str, message: &[u8], ) -> Result<Vec<u8>, ManagerError>

sign signs message with key_id.

Valid only for asymmetric keys. Two custody arms by effective engine:

• transit (the default): the backend signs in place; the private never leaves the vault. This is the strong key-never-leaves guarantee.
• kv2 (an explicit engine=kv2 Ed25519 signing key): the materialize- to-sign arm (design §17.7, vault-iiz): the 32-byte Ed25519 seed is materialized from KV (Zeroizing end-to-end), used for exactly one signature, then zeroized. The key-never-leaves guarantee holds for transit only; the kv2 arm is the sanctioned trade-off for a backend with no in-place sign primitive (e.g. a RAM-constrained device that can’t run transit). The seed is never returned, logged, or audited.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::Signing (a malformed materialized seed on the kv2 arm), or ManagerError::Backend.

pub async fn verify( &self, key_id: &str, message: &[u8], signature: &[u8], ) -> Result<bool, ManagerError>

verify verifies signature over message with key_id.

Valid for asymmetric and public keys (the public half verifies). For an engine=kv2 Ed25519 signing key (vault-iiz), verification is a public op: the public half is derived from the materialized seed and the signature is checked in-process (the seed is zeroized before this returns).

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::Signing (a malformed seed or signature length on the kv2 arm), or ManagerError::Backend.

pub async fn get_public_key( &self, key_id: &str, ) -> Result<PublicKey, ManagerError>

get_public_key reads the public half plus metadata (real algorithm

• current version) for key_id.

Valid for asymmetric and public keys, plus software-custody ML-KEM sealing keys (basil-4ybx): for those the public encapsulation key was derived at provisioning time and recorded in the custody record, and is returned WITHOUT materializing the decapsulation seed (the seed is touched only by unwrap). The returned PublicKey is what the handler echoes verbatim, replacing the previous hardcoded ed25519 / version 1 (vault-k3w).

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, or ManagerError::Backend.

pub fn ml_dsa_algorithm_for(&self, key_id: &str) -> Option<SignatureAlgorithm>

The provider SignatureAlgorithm for an ML-DSA signing key, or None for an unknown key or a classical signing key (which uses the in-place backend signing path).

This is the routing signal the signing service uses to choose between the classical Self::sign/Self::verify path and the provider-dispatch Self::provider_sign/Self::provider_verify path.

pub fn ml_kem_algorithm_for(&self, key_id: &str) -> Option<ProviderKemAlgorithm>

The provider ProviderKemAlgorithm for an ML-KEM sealing key, or None for an unknown key or any non-ML-KEM key (an X25519 sealing key signs through the classical sealing path, not provider provisioning).

The routing signal the signing service uses to dispatch a new_key for an ML-KEM sealing key through Self::provider_generate_sealing.

pub fn describe_provider( &self, key_id: &str, ) -> Result<KeyProviderDescriptor, ManagerError>

Describe the provider/custody/version a key is provisioned under, plus whether its backend now natively supports the key’s algorithm: the admin read seam for observing the active custody mode and whether a backend-native migration is available (basil-wuj.10).

A pure read: it resolves the key, parses its reserved catalog labels, and runs the cheap capability probe. It never performs a crypto operation, reads key material, or materializes a seed, so it needs no caller gate.

Errors

ManagerError::UnknownKey if key_id is not in the catalog.

pub async fn provider_sign( &self, key_id: &str, message: &[u8], gate: ProviderGate, ) -> Result<(Vec<u8>, ProviderDispatch), ManagerError>

sign for an ML-DSA software-custodied key, dispatched through the provider that select_provider chooses from the key’s catalog policy/custody labels and the caller’s gate.

The signature is produced by the selected CryptoProvider; the private seed is materialized inside the provider for exactly one signature and zeroized. It is never returned, logged, or audited. Returns the signature plus a ProviderDispatch describing the selected provider/algorithm for the audit trail.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-asymmetric key), ManagerError::Unsupported (not an ML-DSA key), or ManagerError::Provider (an unsupported algorithm/provider combination, a policy denial, or an opaque software-custody crypto failure).

pub async fn provider_verify( &self, key_id: &str, message: &[u8], signature: &[u8], gate: ProviderGate, ) -> Result<(bool, ProviderDispatch), ManagerError>

verify for an ML-DSA software-custodied key, dispatched through the selected provider. Verification needs only the published public key (no seed is materialized). Returns the validity plus the ProviderDispatch.

Errors

As Self::provider_sign.

pub async fn provider_generate( &self, key_id: &str, gate: ProviderGate, ) -> Result<(NewKey, ProviderDispatch), ManagerError>

new_key for an ML-DSA software-custodied key: generate a keypair, seal the private seed into an encrypted custody record, and write it to KV, all inside the selected provider, so the private is never exposed to the caller. Returns the new key (public half only) plus the ProviderDispatch.

Errors

As Self::provider_sign.

pub async fn provider_generate_sealing( &self, key_id: &str, kem: ProviderKemAlgorithm, gate: ProviderGate, ) -> Result<(NewKey, ProviderDispatch), ManagerError>

new_key for an ML-KEM software-custodied sealing key, dispatched through the crypto provider that select_provider chooses from the key’s catalog policy/custody labels and the caller’s gate.

The provider generates a fresh 64-byte ML-KEM seed, seals it under the catalog pqc_storage_key AEAD key, writes the custody record, and returns the derived encapsulation (public) key plus a ProviderDispatch for the audit trail. The seed never leaves the provider; no private material is returned. The requested kem must match the key’s catalog keyType.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-sealing key), ManagerError::KemAlgorithmMismatch (the catalog keyType is not the requested ML-KEM level), or ManagerError::Provider (a policy denial or an opaque software-custody crypto failure).

pub async fn import( &self, key_id: &str, key_type: KeyType, material: &KeyMaterial, ) -> Result<NewKey, ManagerError>

import (BYOK): provision the key key_id from caller-supplied material.

Valid for crypto keys (asymmetric / symmetric). Write-only: the reply carries only the public half; the private material is never echoed.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, or ManagerError::Backend (including an unsupported material variant).

pub async fn list( &self, prefix: Option<&str>, visible: impl Fn(&str) -> bool, ) -> Result<Vec<WireCatalogEntry>, ManagerError>

list returns value-free key metadata across the catalog (§7).

Projects the catalog (name + kind + algorithm) into the wire WireCatalogEntry shape, filtered by prefix and by the visible predicate (the handler passes a PDP-backed closure so a caller only sees keys it may list/read). The latest version is read from each key’s backend via Backend::key_metadata; a key whose backend errors is reported with latest_version = 0 rather than failing the whole list (one down backend must not blind the caller to every other key). Never returns key bytes.

Errors

Infallible at the manager layer today: per-key backend failures degrade to latest_version = 0; the Result is kept for forward-compat.

pub async fn encrypt( &self, key_id: &str, algorithm: AeadAlgorithm, plaintext: &[u8], aad: Option<&[u8]>, ) -> Result<CiphertextEnvelope, ManagerError>

encrypt AEAD-encrypts plaintext under key_id’s latest version.

Valid only for symmetric keys. algorithm must match the key’s catalog keyType (ManagerError::AlgorithmMismatch otherwise). The backend owns the nonce and returns a normalized CiphertextEnvelope.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::AlgorithmMismatch, or ManagerError::Backend.

pub async fn decrypt( &self, key_id: &str, envelope: &CiphertextEnvelope, aad: Option<&[u8]>, ) -> Result<Vec<u8>, ManagerError>

decrypt AEAD-decrypts envelope under key_id, targeting the version the envelope names (rotation grace). The envelope alg must match the key’s catalog keyType.

Valid only for symmetric keys. A tag/AAD/version mismatch surfaces as BackendError::DecryptFailed (opaque).

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::AlgorithmMismatch, or ManagerError::Backend (including the opaque BackendError::DecryptFailed).

pub async fn wrap_envelope( &self, key_id: &str, plaintext: &[u8], aad: &[u8], ) -> Result<SealedEnvelope, ManagerError>

wrap_envelope seals plaintext to a sealing key as an X25519 sealed box.

Valid only for sealing keys. Sealing needs the recipient public key, which the broker reads from the key’s out-of-band-provisioned public_path (a non-secret kv_get, basil-o86), so wrap is a pure public op that never materializes the long-lived private (that happens only on unwrap, the op that performs the ECDH). A caller can wrap without first fetching the public half. The returned SealedEnvelope carries the ephemeral public (encapsulated_key), the nonce, and the ciphertext; aad is bound as AEAD associated data.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-sealing key), ManagerError::MissingPublicPath (no public_path configured), ManagerError::Sealing (malformed stored public / crypto failure), or ManagerError::Backend.

pub async fn unwrap_envelope( &self, key_id: &str, envelope: &SealedEnvelope, aad: &[u8], ) -> Result<Zeroizing<Vec<u8>>, ManagerError>

unwrap_envelope opens an X25519 sealed box addressed to a sealing key.

Valid only for sealing keys. The X25519 private is materialized from KV by an internal read (NOT the public get op, which stays denied for a sealing key), used for exactly one ECDH, and zeroized on every path. A wrong key, tampered envelope, or mismatched aad returns the opaque SealingFailure::OpenFailed (no oracle). The recovered plaintext is returned in a zeroizing buffer.

Confidentiality only, NOT sender authentication. A sealed box is anonymous: a successful unwrap proves only that the envelope was sealed to this recipient, never who sealed it. Callers MUST NOT treat a successful unwrap as proof of sender identity. (A low-order encapsulated_key is rejected by the crypto core, but that is not authentication.)

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-sealing key), ManagerError::Sealing (malformed materialized key, malformed envelope, or AEAD authentication failure), or ManagerError::Backend.

pub async fn unseal_cose( &self, key_id: &str, cose_encrypt: &[u8], external_aad: &[u8], ) -> Result<Zeroizing<Vec<u8>>, ManagerError>

Open a strict-profile COSE_Encrypt with a custodied X25519 sealing key.

The exact tagged COSE_Encrypt bytes are passed to basil-cose verbatim. The Enc_structure AAD covers the serialized protected header bytes, so callers must not parse and re-encode before this point.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::UnsealContextNotPermitted when the key pins an allowed COSE unseal context (KDF parties / external_aad, basil-2rqj) this envelope is not bound to, ManagerError::Sealing for malformed material/profile input or AEAD authentication failure, or ManagerError::Backend.

pub async fn encrypt_nats_curve( &self, key_id: &str, recipient_public_xkey: &str, plaintext: &[u8], ) -> Result<Vec<u8>, ManagerError>

Encrypt with a custodied NATS curve xkey.

This is a materialize-to-use operation: the sender private xkey is read through the secret KV path, used for one NaCl-compatible authenticated box, then zeroized. The peer key is a public X... nkey supplied by the caller.

pub async fn decrypt_nats_curve( &self, key_id: &str, sender_public_xkey: &str, ciphertext: &[u8], ) -> Result<Zeroizing<Vec<u8>>, ManagerError>

Decrypt a NATS curve xkey authenticated box with a custodied recipient key.

A wrong key, wrong sender public key, or tampered ciphertext maps to the same opaque sealing open failure used by the envelope decrypt path.

pub async fn provider_wrap_envelope( &self, key_id: &str, kem: ProviderKemAlgorithm, envelope_algorithm: ProviderEnvelopeAlgorithm, plaintext: &[u8], aad: &[u8], gate: ProviderGate, ) -> Result<(ProviderEnvelope, ProviderDispatch), ManagerError>

wrap_envelope for an ML-KEM sealing key, dispatched through the crypto provider (software custody).

Self-sealing: the provider materializes the custodied 64-byte ML-KEM seed, derives its public encapsulation key, encapsulates to it, and AEAD-seals the plaintext under the KEM-derived key, so the broker needs no separately published encapsulation key. The requested kem must name the same ML-KEM level the key’s catalog keyType declares; the local-software provider is selectable only when gate carries the caller’s explicit op:use_software_custody grant. Returns the self-describing ProviderEnvelope (KEM/envelope algorithm, key version, encapsulated key, nonce, ciphertext) plus a ProviderDispatch for the audit trail.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-sealing key), ManagerError::KemAlgorithmMismatch (a wrong ML-KEM level), or ManagerError::Provider (a policy denial or an opaque software-custody crypto failure).

pub async fn provider_unwrap_envelope( &self, key_id: &str, kem: ProviderKemAlgorithm, envelope_algorithm: ProviderEnvelopeAlgorithm, parts: MlKemEnvelopeParts<'_>, aad: &[u8], gate: ProviderGate, ) -> Result<(Vec<u8>, ProviderDispatch), ManagerError>

unwrap_envelope for an ML-KEM sealing key, dispatched through the crypto provider (software custody).

The provider materializes the custodied 64-byte ML-KEM seed for exactly one decapsulation, derives the AEAD key, opens the envelope, and zeroizes the seed on every path. The requested kem must match the key’s catalog keyType; the local-software provider requires the caller’s explicit op:use_software_custody grant in gate. A wrong key, tampered envelope, or mismatched aad returns the opaque ProviderError::CryptoFailed (no decrypt oracle). Returns the recovered plaintext plus a ProviderDispatch for the audit trail.

Confidentiality only, NOT sender authentication. A successful unwrap proves only that the payload was sealed to this recipient, never who sealed it.

Errors

As Self::provider_wrap_envelope.

pub async fn sealing_public_key( &self, key_id: &str, ) -> Result<[u8; 32], ManagerError>

get_public_key for a sealing key: read and return the X25519 public half from the key’s out-of-band-provisioned public_path (basil-o86). A pure public op: the long-lived private is never materialized here (that happens only on unwrap). Senders use the returned public to seal enrollment payloads to this recipient.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass (a non-sealing key), ManagerError::MissingPublicPath (no public_path configured), ManagerError::Sealing (malformed stored public), or ManagerError::Backend.

pub async fn get( &self, key_id: &str, version: Option<u32>, ) -> Result<KvSecret, ManagerError>

get reads the latest (or a specific) KV-v2 value for key_id, returning the value bytes + the version they came from (§7).

Valid only for value and public keys. A crypto key (asymmetric / symmetric) is rejected with ManagerError::OpNotValidForClass before any backend call: the broker never hands out signing/encryption key material through get (that op-class gate is the security invariant here). version = None reads the latest version.

A value-class read is a SECRET: it is routed through the Zeroizing chain (Backend::kv_get_secret, like the materialize paths) so no plain copy of the cleartext is left in freed heap (the t9a leak, security review finding 17). A public-class read carries no secret and uses the plain Backend::kv_get path; its bytes are wrapped into the returned KvSecret for a uniform signature.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, or ManagerError::Backend.

pub async fn set(&self, key_id: &str, value: &[u8]) -> Result<u32, ManagerError>

set writes value as a fresh KV-v2 version of key_id, returning the new version number (never the value, §7).

Valid only for value keys (a public key is read-only material, a crypto key is import/rotate territory). Rejected with ManagerError::OpNotValidForClass otherwise, before any backend call.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, or ManagerError::Backend.

pub async fn rotate( &self, key_id: &str, limits: BrokerLimits, ) -> Result<u32, ManagerError>

rotate bumps key_id to a fresh version, returning the new version.

• Crypto (transit) keys (asymmetric/symmetric): a transit key version bump. New sign/encrypt uses the newest version; older versions stay usable within the grace window, which this method then applies via Backend::configure_versions (raising min_decryption_version to BrokerLimits::grace_floor). On compromise, set grace_versions = 0 so only the newest version is honored.
• Value keys: a key with a catalog generate recipe regenerates a fresh value as a new KV-v2 version (vault-a2p); a value key without a recipe is ManagerError::ValueRotateNeedsSet (use set).

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::ValueRotateNeedsSet, or ManagerError::Backend.

pub async fn sweep_retention( &self, key_id: &str, limits: BrokerLimits, ) -> Result<(), ManagerError>

Retention sweep for one crypto key: raise the backend’s min_available_version to BrokerLimits::retention_floor, irreversibly pruning archived key material below the retention window. A no-op when retention is disabled (retain_versions = None) or the key has too few versions to prune.

This is the sweep primitive. Call it after a rotate, or from the binary’s periodic catalog sweep task, to enforce retention.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, or ManagerError::Backend.

pub async fn sweep_all_retention( &self, limits: BrokerLimits, ) -> Result<(), ManagerError>

Apply the configured retention floor to every crypto key in catalog order.

Value/public keys have no backend key-version retention in Basil and are skipped. A disabled retention policy is a no-op.

Errors

Returns the first routing/backend error encountered while sweeping.

pub async fn issue_x509_svid( &self, key_id: &str, spiffe_id: &str, ttl_seconds: u64, ) -> Result<X509Svid, ManagerError>

Issue an X.509-SVID from a catalog engine=pki issuer key.

Valid only for asymmetric keys with the explicit PKI engine. The backend path is a Vault issue endpoint (pki/issue/<role>), and the backend returns DER-normalized certificate chain, leaf key, and bundle material.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::Unsupported for a non-PKI catalog entry, or ManagerError::Backend.

pub async fn issue_x509_cert( &self, key_id: &str, request: &X509CertRequest, ) -> Result<X509Svid, ManagerError>

Issue a DNS/IP-SAN X.509 leaf (TLS cert) from a catalog engine=pki issuer.

The same issuer-key constraints as BackendManager::issue_x509_svid (asymmetric class, explicit PKI engine), but binds DNS/IP SANs instead of a SPIFFE URI. The issuing CA key stays in the backend; the leaf private key is returned to the caller.

Errors

ManagerError::UnknownKey, ManagerError::OpNotValidForClass, ManagerError::Unsupported for a non-PKI catalog entry, or ManagerError::Backend.

impl BackendManager

pub async fn reconcile(&self) -> Result<ReconcileSummary, ReconcileError>

Reconcile every catalog key against its backend, applying the key’s MissingPolicy (§3.7).

Returns a ReconcileSummary on success. Fails closed with a ReconcileError if a backend is unreachable while probing, if any required (error) key is absent, or if generating an absent generate key fails. All required-missing keys are collected and reported together.

Errors

ReconcileError::Probe (unreachable backend), ReconcileError::RequiredMissing (one or more error-policy keys absent), or ReconcileError::Generate (a generate key could not be created).

pub async fn check(&self) -> Result<CheckReport, ReconcileError>

Read-only counterpart to reconcile: probe every catalog key and report whether it is present or absent (with its MissingPolicy), without generating or mutating anything. For CI / pre-deploy lint checks.

Reuses the same existence probe as reconcile (crypto via key_metadata, value/public via kv_get). A backend that is unreachable during the probe is not “absent”: it is a fatal ReconcileError::Probe (fail closed), exactly as in reconcile: a down backend must never be reported as a clean “missing” that a caller might act on.

Returns a CheckReport over every key in catalog name order. Use CheckReport::should_fail_required to gate a --strict CI check.

Errors

ReconcileError::Probe if any backend is unreachable (or rejecting) while probing a key’s existence.

Trait Implementations

impl Debug for BackendManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.