feat!: sign and verify data as first-class ceremony steps

.cargo/audit.toml

@@ -10,18 +10,23 @@ ignore = [
     # timing sidechannels in the `rsa` crate. No fixed version is available
     # upstream.
     #
-    # Why it does not apply here: the `rsa` crate is pulled in only for
-    # *public-key* operations — verifying the self-signature on an incoming
-    # CSR (`rsa::RsaPublicKey::verify` in
-    # `crates/rite-stdlib/src/pki/issue_certificate.rs`). The Marvin attack
-    # targets RSA *private-key* decryption/signing (PKCS#1 v1.5 unpadding),
-    # which is never performed: Rite holds no RSA private keys in this crate
-    # and never decrypts or signs with `rsa`. All private-key crypto lives in
-    # the OpenSSL backend (`rite-openssl`), not in the `rsa` crate.
+    # Why it does not apply here: `rsa` is not a dependency of this workspace.
+    # It arrives only transitively through the `yubikey` crate, and so only in
+    # builds with the `piv` or `yubikey` feature enabled. The default build and
+    # the static musl release artifacts do not contain it at all. Software RSA
+    # in Rite is performed by OpenSSL, through `rite-openssl`.
+    #
+    # Where it does appear, the attack still does not reach: Marvin targets RSA
+    # *private-key* operations (PKCS#1 v1.5 decryption and signing), and
+    # `yubikey` performs none. It uses `rsa` only to rebuild an `RsaPublicKey`
+    # from the modulus and exponent a card reports and re-encode it as SPKI
+    # (`yubikey::piv`). The private key never leaves the card, which is the
+    # reason for using one.
     #
     # Revisit if any of the following becomes true:
-    #   - `rsa` gains a private-key code path here (decryption, signing, or
-    #     key import) — grep for `RsaPrivateKey`, `decrypt`, `sign`;
+    #   - `rsa` returns as a direct dependency of a crate in this workspace;
+    #   - `yubikey` gains an RSA private-key code path — grep the dependency
+    #     for `RsaPrivateKey`, `decrypt`, and `sign`;
     #   - a fixed release of `rsa` ships (drop this entry and upgrade).
     "RUSTSEC-2023-0071",
 ]

CONTRIBUTING.md

@@ -5,7 +5,8 @@ Pull requests are welcome, but opening an issue to discuss the change first is s
 
 CLI behavior conventions are documented in `docs/development/cli-conventions.md`.
 Runtime and frontend architecture is documented in `docs/development/runtime-and-frontend.md`,
-crate layout in `docs/development/crate-layout.md`, and the testing strategy in
+crate layout in `docs/development/crate-layout.md`, the crypto stack in
+`docs/development/cryptographic-dependencies.md`, and the testing strategy in
 `docs/development/testing.md`.
 
 ## AI-assisted contributions
@@ -22,6 +23,12 @@ datapoint for any contribution, not as a compliance step.
 
 Requires Rust 1.88+ and `libssl-dev` (OpenSSL headers).
 
+The post-quantum algorithms (ML-DSA) additionally need **OpenSSL 3.5 or
+newer**. Building against an older one succeeds, with those algorithms absent
+from the binary and their tests and examples skipped; see
+`docs/development/cryptographic-dependencies.md`. `--features openssl-vendored`
+bundles a current OpenSSL and sidesteps the question.
+
 ```sh
 cargo build -p rite --features openssl-vendored
 cargo run -p rite -- check examples/showcase/demo.rite.yaml