Skip to content

Signing back ends

Task-oriented guide: Signing.

Algorithm registry

approvo.crypto.algorithms

Signature-scheme registry.

Every place approvo verifies a signature dispatches through here on a scheme string, so adding a new algorithm (for a KMS that only offers P-384, say) is a registry entry, not a change to the verifier, the checkpoint code, or the service.

A scheme entry knows three things:

  • public_raw(key) — the canonical wire bytes for a public key of this scheme. Ed25519 uses the 32-byte raw form (so historical key ids do not change); everything else uses DER SubjectPublicKeyInfo.
  • load_public(raw) — reconstruct a cryptography public-key object from those bytes.
  • verify(raw, signature, message) — raise :class:cryptography.exceptions.InvalidSignature on failure.

Signature encodings match what mainstream KMS/HSM back ends emit: raw 64-byte for Ed25519, ASN.1/DER for ECDSA, PKCS#1 v1.5 / PSS octet strings for RSA.

Scheme dataclass

get_scheme

get_scheme(name: str) -> Scheme

register_scheme

register_scheme(scheme: Scheme) -> None

Add or replace a scheme. For niche KMS curves not shipped by default.

known_schemes

known_schemes() -> tuple[str, ...]

keyid_for

keyid_for(public_raw: bytes) -> str

Key id = SHA-256 of the scheme's canonical public bytes.

Signers

approvo.crypto.signer.sign_with async

sign_with(signer: Signer, data: bytes) -> tuple[bytes, str]

Sign data, awaiting the result if the signer is async.

Returns (signature, keyid) — the keyid is captured here so an envelope records exactly which key/version produced the signature, which keeps historical signatures verifiable across key rotation.

approvo.crypto.signer.public_key_ref

public_key_ref(signer: Signer, owner_id: str, *, not_before: str, not_after: str | None = None, key_use: str = 'approver', log_ids: tuple[str, ...] | None = None) -> KeyRef

Convenience: a KeyRef for signer's public half.

approvo.crypto.signer.PublicKeyMaterial dataclass

A public key ready to drop into a :class:~approvo.crypto.keys.KeyRef.

KeyProvider

approvo.crypto.keyprovider.KeyProvider

Bases: Protocol

Resolves logical key refs to signers and public keys.

get_signer async

get_signer(key_ref: str) -> Signer

A primed signer (key_id() / algorithm usable synchronously).

list_keys async

list_keys() -> list[KeyDescriptor]

Optional. Providers that cannot enumerate raise NotImplementedError.

self_test async

self_test(key_ref: str) -> None

Sign + verify a nonce, so a bad grant fails at startup not first use.

approvo.crypto.keyprovider.parse_key_ref

parse_key_ref(key_ref: str) -> tuple[str, str]

"gcpkms://projects/..." -> ("gcpkms", "projects/...").

approvo.crypto.keyprovider.InMemoryKeyProvider

Bases: _BaseProvider

memory://<name> -> a generated Ed25519 key. Tests and local dev.

approvo.crypto.keyprovider.LocalFileKeyProvider

Bases: _BaseProvider

file:///abs/path -> an Ed25519 seed (hex). Optionally rooted.

With root set, file://name resolves to root/name.key and :meth:ensure will generate a missing key (0600) — handy for a single-node deployment that wants a persistent org key without a KMS.

approvo.crypto.keyprovider.EnvKeyProvider

Bases: _BaseProvider

env://VARNAME -> an Ed25519 seed (hex) from the environment.

approvo.crypto.keyprovider.CompositeKeyProvider

Bases: _BaseProvider

Routes a key ref to the sub-provider that handles its scheme.

approvo.crypto.keyprovider.KeyDescriptor dataclass

KeyResolver

approvo.crypto.resolver.SigningPurpose

Bases: str, Enum

approvo.crypto.resolver.SigningContext dataclass

approvo.crypto.resolver.KeyResolver

Bases: Protocol

approvo.crypto.resolver.StaticKeyResolver

One key reference per :class:SigningPurpose.

approvo.crypto.resolver.TemplateKeyResolver

Format a reference template per purpose with fields from the context.

::

TemplateKeyResolver({
    SigningPurpose.DECISION:
        "gcpkms://.../cryptoKeys/{log_id}-approvals/cryptoKeyVersions/1",
    SigningPurpose.CHECKPOINT:
        "gcpkms://.../cryptoKeys/{log_id}-log/cryptoKeyVersions/1",
})

SigningService

approvo.crypto.signing.SigningService

trust async

trust(specs: list[TrustSpec]) -> list[KeyRef]

Resolve each spec's public key into a :class:KeyRef.

trust_from_static async

trust_from_static(*, issuer_owner_id: str, log_owner_id: str, not_before: str, log_ids: tuple[str, ...] | None = None) -> list[KeyRef]

Shortcut when the resolver is a :class:StaticKeyResolver: publish its DECISION key as decision_issuer and its CHECKPOINT key as log.

approvo.crypto.signing.TrustSpec dataclass

How to publish one signing key into the trust root.

Cloud providers (optional extras)

approvo.providers.gcpkms.GcpKmsKeyProvider

Bases: _BaseProvider

approvo.providers.awskms.AwsKmsKeyProvider

Bases: _BaseProvider

approvo.providers.vault.VaultTransitKeyProvider

Bases: _BaseProvider