Module crypto 

Signing and verification primitives for Chio artifacts.

Purpose and FIPS Posture

Chio artifacts (capability tokens, receipts, DPoP proofs, governed approval tokens) are signed with a cryptographic algorithm negotiated between the kernel operator and its counterparties. The default algorithm is Ed25519 via ed25519-dalek, which matches the historical behaviour of every Chio deployment and every on-wire artifact produced to date. To unblock enterprise procurement in FIPS-constrained environments, this module also exposes a SigningBackend abstraction with pluggable implementations for NIST P-256 (secp256r1) and P-384 (secp384r1) ECDSA signatures.

The FIPS backends are gated behind the fips Cargo feature and link to aws-lc-rs, a FIPS 140-3 validated module. When the feature is disabled the only available backend is pure Ed25519, and the crate has no extra transitive dependencies. When enabled, callers may construct a [P256Backend] or [P384Backend] and pass it to any Chio signing helper that accepts &dyn SigningBackend.

Backward Compatibility

Ed25519 artifacts serialize byte-for-byte identically to the historical format: a 64-character lowercase hex string for the public key and a 128-character hex string for the signature. FIPS-algorithm artifacts use a self-describing hex prefix (e.g. p256: or p384:) so older verifiers that only understand bare hex recognise that the material is non-Ed25519 and can reject with a clear error rather than misinterpreting bytes.

Safety Notes

• Private key material held by Keypair is zeroed on drop via ed25519-dalek’s ZeroizeOnDrop implementation.
• FIPS-backend private keys are held by aws-lc-rs owned types which zero their own key material.
• No unsafe code is introduced by this module.

Structs

Ed25519Backend

Ed25519 SigningBackend wrapping the historical Keypair.

Keypair

Ed25519 keypair for signing.

PublicKey

Public key for verifying Chio signatures.

Signature

Signature produced by an Chio SigningBackend.

Enums

SigningAlgorithm

Enumerates the signature algorithms Chio knows how to produce and verify.

Traits

SigningBackend

Abstraction over Chio signing algorithms.

Functions

canonical_json_bytes

Serialize a value to canonical JSON bytes (RFC 8785 / JCS).

canonical_json_string

Serialize a value to a canonical JSON string (RFC 8785 / JCS).

is_default_algorithm

Returns true when alg equals the default algorithm. Free function so it can be referenced from #[serde(skip_serializing_if = "...")].

is_default_optional_algorithm

Returns true when the optional algorithm is either absent or equal to the default (Ed25519). Used by #[serde(skip_serializing_if)] on envelope fields so that legacy Ed25519 artifacts remain byte-identical on the wire.

sha256_hex

Compute SHA-256 of the given bytes, returning the hash as lowercase hex.

sign_canonical_with_backend

Sign the canonical JSON form of value with the given backend.