diff --git a/MIGRATE.md b/MIGRATE.md index 86c9e306..0f09a3a7 100644 --- a/MIGRATE.md +++ b/MIGRATE.md @@ -131,8 +131,7 @@ For each way the survey found: [rind-ring's README] leaves out: stop, and report it as a rind gap. rind panics on a CPU missing a feature it requires. At the start of each -binary's `main`, refuse one by exiting with the error from an adapter's -`default_provider()` or `rind::cpu::check()`. +binary's `main`, refuse one by exiting with the error from `rind::cpu::check()`. A library leaves this to the binaries that use it, and says so in its docs. Commit as you go, with messages in the project's style. diff --git a/MIGRATING.md b/MIGRATING.md index 1b54527c..93ba9799 100644 --- a/MIGRATING.md +++ b/MIGRATING.md @@ -350,13 +350,10 @@ ring has none. ## Adapter crates -Each `rind-*` crate stands in for a crate's aws-lc-rs or ring backend. rind -panics on a CPU missing a feature it requires, so every adapter function -that returns a provider refuses one with the adapter's own -`MissingFeature` instead, which displays rind's message. rind-rustls, whose -signatures are rustls's provider's, does not. rind-ring, whose signatures -are ring's, and rind-rcgen's `KeyPair`, whose errors are rcgen's, cannot. -Call `rind::cpu::check()` before using them. +Each `rind-*` crate stands in for a crate's aws-lc-rs or ring backend and +offers that crate's signatures, so none returns an error for a CPU it lacks. +Call `rind::cpu::check()` at startup to get that error, as the [cpu](#cpu) +section describes. ### rind-ring diff --git a/quest/m0/adapters/README.md b/quest/m0/adapters/README.md deleted file mode 100644 index 92f967f0..00000000 --- a/quest/m0/adapters/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# [XS] Adapters offer exactly their upstream's API - -## Goal - -Each published `rind-` adapter offers exactly the API of the provider its upstream ships, so swapping one for the other changes no other code. Each README lists only what rind cannot back. - -## Plan - -A 2026-11-08 comparison of each adapter's rustdoc surface against its upstream found additions, changed signatures, and renamed items. Decided with the maintainer on 2026-11-08: - -- Adapters must have identical APIs, with no exceptions ✅ (rejected: a carve-out for additions that replace what upstream's built-in provider does implicitly). A divergence is a bug: fix it in a patch release with the version set by hand, and yank the divergent releases if needed. AGENTS.md and CONTRIBUTING.md now say so. -- Milestone: now, m0 ✅ (rejected: m2 beside the API epic, m3 beside the parity epic). -- Every adapter's `MissingFeature`, and the `Result` it puts on `default_provider()` and its kin, diverges from upstream. Each child removes it from its adapters by no longer calling `rind::cpu::check()`, which can't fail on any target rind builds for. rind's own `check()` goes in [rind needs no runtime CPU check](/quest/m2/api/cpu-check.md). Until it lands, a debug or `--cfg rind_cpu_disable` aarch64 build run with `RIND_CPU_DISABLE_neon` panics in `verify_cpu_features` on the first operation instead of erroring at `default_provider()`; that test-only toggle needs no handling here, and that quest deletes both. -- rind-object-store and rind-instant-acme have no upstream provider shape to copy: object_store's are `pub(crate)`, and instant-acme's are associated functions. rind-object-store keeps its `default_provider()`, which MoQ's moq-cli uses; rind-instant-acme was deleted in [moq-dev/rind#510](https://github.com/moq-dev/rind/pull/510), since it had no consumer. -- Behavior that isn't API stays where rind has a reason, documented in each README: rind-rustls and rind-dimpl put ChaCha20-Poly1305 first on CPUs without AES instructions, and rind-rustls lists AES-128-GCM before AES-256-GCM, for speed. -- Each child ends with its adapter's README and MIGRATING.md section listing only the remaining omissions. - -Decided with the maintainer on 2026-11-09: - -- Releases: one rind 0.4 that carries all three breaking changes, and a MoQ-side PR ready before the adapter patch releases publish ✅ (rejected: the 0.4 quest alone, accepting that MoQ's build breaks until fixed; leaving both to release-plz). rind 0.4 is in [rind 0.4 ships once](/quest/m2/api/release-0.4.md). -- The children change calls MoQ's `main` makes: `default_provider()` in rind-rustls, rind-jsonwebtoken, and rind-object-store, and `KeyPair::generate` and `to_pkcs8` in rind-rcgen. MoQ requires those adapters by caret (moq-dev/moq's `Cargo.toml:218-221`), so its first lockfile update after the patch releases stops building until its calls change. No crate MoQ has published names a rind adapter yet, so only `main` and its next cut are exposed. -- The adapter patch releases therefore publish only once MoQ's PR adapting those calls is ready to merge. Publishing happens only when a release PR merges (`CONTRIBUTING.md:138`), so the maintainer leaves the release PR that carries them unmerged until then, and MoQ's PR merges the day they publish. That PR is a quest in moq-dev/moq's own tree. -- Since rind 0.4 is pending on `main` ([moq-dev/rind#548](https://github.com/moq-dev/rind/pull/548) leaves release-plz to propose it), these fixes publish in the same release as rind 0.4, each adapter requiring it, so MoQ's PR moves to both at once. diff --git a/quest/m2/api/cpu-check.md b/quest/m2/api/cpu-check.md index cde353f8..25ab11ab 100644 --- a/quest/m2/api/cpu-check.md +++ b/quest/m2/api/cpu-check.md @@ -13,10 +13,6 @@ Decided with the maintainer on 2026-11-08: - Delete the runtime check and make requirements compile-time ✅ (rejected: keep `check()` documented as never failing; leave it). rind's removal ships in 0.4. - `rind/build.rs` selects the aarch64 backend only when `CARGO_CFG_TARGET_FEATURE` has `neon`, and the portable backend otherwise, which is one backend per target, chosen at build time. - AGENTS.md's Required rule changes from "a CPU missing a required feature fails with an error naming it" to say a backend requires only its target's compile-time features. The maintainer asked for this edit; follow `quest guide prompting`. -- The adapters stop calling `check()` and drop their `MissingFeature` in [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md), since their upstreams have no such error. That epic also replaces this quest's earlier decision to break the adapters in patch releases for this quest alone. +- The adapters no longer call `check()` or have a `MissingFeature`, since their upstreams have no such error. Their fixes ship with rind 0.4 in [rind 0.4 ships once](/quest/m2/api/release-0.4.md), so this quest removes only rind's own check. - Delete what only existed for the check: `verify_cpu_features` and its per-operation atomic load in `low::entry`, `rind/tests/cpu.rs`'s per-feature panic test, and `RIND_CPU_DISABLE_neon` if nothing else uses it. Keep the optional-feature toggles that select tiers. -- Update README, PLATFORMS.md, MIGRATING.md, and ARCHITECTURE.md's `cpu` line, which tell callers to check first. Keep `cpu::has_aes_hardware` and `cpu::Dit`. - -## Required - -- [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md) - the adapters stop calling `check()` first +- Update README, PLATFORMS.md, MIGRATING.md, MIGRATE.md, TESTING.md, and ARCHITECTURE.md's `cpu` line, which tell callers to check first. Keep `cpu::has_aes_hardware` and `cpu::Dit`. diff --git a/quest/m2/api/release-0.4.md b/quest/m2/api/release-0.4.md index 10842e1d..45b1825b 100644 --- a/quest/m2/api/release-0.4.md +++ b/quest/m2/api/release-0.4.md @@ -10,9 +10,9 @@ Decided with the maintainer on 2026-11-09: - Releases: one rind 0.4 that carries all three breaking changes, and a MoQ-side PR ready before the adapter fixes publish ✅ (rejected: the 0.4 quest alone, accepting that MoQ's build breaks until fixed; leaving both to release-plz). Three breaking releases would re-pin every adapter three times, and each would leave a consumer that pins rind 0.3 with two copies of rind until it follows. - Two of the three merged the same day, while rind's version was hand-set to 0.3.3 and unpublished: the typed CBC IV ([moq-dev/rind#530](https://github.com/moq-dev/rind/pull/530)) and the agreement keys ([moq-dev/rind#529](https://github.com/moq-dev/rind/pull/529)). A version set by hand ahead of the published one is kept as is (`CONTRIBUTING.md:146`), so release PR [moq-dev/rind#511](https://github.com/moq-dev/rind/pull/511) proposed publishing both as rind 0.3.3. On 2026-11-10 the maintainer chose ✅ to return rind's manifest to the published 0.3.2, so release-plz proposes 0.4.0 itself from the `!` commits, and hold the release for the last change (rejected: hand-set 0.4.0; set 0.4.0 and ship it now, with the CPU-check removal as 0.5; revert both and release 0.3.3). [moq-dev/rind#548](https://github.com/moq-dev/rind/pull/548) sets it; any later `!` change to rind then lands inside the same 0.4.0. -- So the adapter fixes of [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md) publish in the same release as rind 0.4, not before it, and MoQ's PR moves to both at once. +- So the adapter fixes publish in the same release as rind 0.4, not before it, and MoQ's PR moves to both at once. -What remains is [rind needs no runtime CPU check](/quest/m2/api/cpu-check.md), which waits on that epic. +What remains is [rind needs no runtime CPU check](/quest/m2/api/cpu-check.md). The hold uses only what the release tooling has. Publishing happens only when a release PR merges (`CONTRIBUTING.md:138`, `.release-plz.toml:6`), and one release PR covers every crate. So the hold is the maintainer leaving the release PR unmerged, and while it lasts no adapter fix and no pyrind release publishes either. @@ -34,7 +34,3 @@ The benchmark report is refreshed once before each minor release (maintainer, 20 - [Benchmark report refresh, before rind 0.4](/quest/m2/bench/report-refresh.md) - the report and the README's claims, current for the release - [rind needs no runtime CPU check](/quest/m2/api/cpu-check.md) - `cpu::check` and `MissingFeature` removed, the last of the three - -## Related - -- [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md) - its fixes publish in this release diff --git a/quest/m2/confidence/adapter-api-diff.md b/quest/m2/confidence/adapter-api-diff.md index fef5e295..bf985eff 100644 --- a/quest/m2/confidence/adapter-api-diff.md +++ b/quest/m2/confidence/adapter-api-diff.md @@ -8,7 +8,7 @@ Planned from the 2026-11-09 tooling audit. The exact-API rule has no machine check: -- A one-off comparison of rustdoc surfaces on 2026-11-08 found additions, changed signatures, and renamed items in every adapter ([the adapters epic](/quest/m0/adapters/README.md) records it). The PRs that fix them add no check, so the next drift is found by the next hand audit. +- A one-off comparison of rustdoc surfaces on 2026-11-08 found additions, changed signatures, and renamed items in every adapter. The PRs that fix them add no check, so the next drift is found by the next hand audit. - `sh/adapter-versions.sh` checks only that an adapter's version begins with its upstream's breaking part. - cargo-semver-checks, through release-plz, compares an adapter with its own last release, not with upstream. - No job builds an adapter's features one at a time: rind-aws-lc-rs declares 13 and rind-ring 3, and only the default set, `--no-default-features`, and `wipe` are built. @@ -22,7 +22,3 @@ Guidance: - rustdoc's JSON output is unstable. Pin the toolchain that writes it in the flake, so a new release cannot fail the gate. - Scope it in `sh/dispatch.sh` to an adapter's sources, its manifest, and `Cargo.lock`, as the `versions` module is scoped (`sh/dispatch.sh:57`). An upstream release reaches rind only through a lockfile change, so no nightly run is needed. - If the doc builds make it too slow for the gate, run it in `lints.yml` nightly and on pull requests that touch an adapter. - -## Required - -- [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md) - every adapter matches its upstream, so the diff starts green diff --git a/quest/m2/confidence/mutants-adapters.md b/quest/m2/confidence/mutants-adapters.md index 182cd75e..6e7457fb 100644 --- a/quest/m2/confidence/mutants-adapters.md +++ b/quest/m2/confidence/mutants-adapters.md @@ -8,8 +8,4 @@ The 103 mutants in the `rind-` adapters that no test catches are kille - Where the upstream crate has the same value, such as ring's or rustls' aws-lc-rs provider's, test against it rather than a literal. - Run `admin/mutants -p ` on each adapter to confirm none survive. -- Start from the list as the adapters epic leaves it. Its PRs rewrite the adapters to their upstreams' exact APIs, and [moq-dev/rind#521](https://github.com/moq-dev/rind/pull/521) and [moq-dev/rind#515](https://github.com/moq-dev/rind/pull/515) already edit this block of `exclude_re`, so recount the survivors, and drop each entry that no longer matches a mutant, before writing tests. - -## Required - -- [Adapters offer exactly their upstream's API](/quest/m0/adapters/README.md) - the adapters' final code, so no test is written for a mutant its rewrite removes +- Start from the list as the adapter PRs leave it. Those PRs rewrite the adapters to their upstreams' exact APIs, and [moq-dev/rind#521](https://github.com/moq-dev/rind/pull/521) and [moq-dev/rind#515](https://github.com/moq-dev/rind/pull/515) already edit this block of `exclude_re`, so recount the survivors, and drop each entry that no longer matches a mutant, before writing tests. diff --git a/quest/m4/pq/rustls-p384-mlkem1024.md b/quest/m4/pq/rustls-p384-mlkem1024.md index c8a75e2b..ff6899c1 100644 --- a/quest/m4/pq/rustls-p384-mlkem1024.md +++ b/quest/m4/pq/rustls-p384-mlkem1024.md @@ -9,7 +9,7 @@ rind-rustls offers RFC 10024's `SecP384r1MLKEM1024` key exchange group (`0x11ED` From [the scope](/quest/m4/pq/README.md), 2026-11-06. - It's an RFC 10024 hybrid like the two rind-rustls already composes in `kx_group/hybrid.rs`: ECDH share first, then ML-KEM-1024, and an 80-byte secret. -- Waits for rustls ✅ (rejected: offering it now by its raw codepoint, `NamedGroup::Unknown(0x11ED)`, as rind-rustls's own addition, which the maintainer chose on 2026-11-07). The adapter rule the maintainer set a day later wins: `AGENTS.md` has an adapter offer exactly the API of the provider its upstream ships, adding nothing, and [the adapters epic](/quest/m0/adapters/README.md) decided that with no exceptions, removing `kx_group::SECP521R1` from rind-rustls for the same reason. rustls 0.23.46's provider has `MLKEM768`, `MLKEM1024`, `SECP256R1MLKEM768`, and `X25519MLKEM768` (`src/crypto/aws_lc_rs/mod.rs:247`) and its `NamedGroup` has no variant for this group. +- Waits for rustls ✅ (rejected: offering it now by its raw codepoint, `NamedGroup::Unknown(0x11ED)`, as rind-rustls's own addition, which the maintainer chose on 2026-11-07). The adapter rule the maintainer set a day later wins: `AGENTS.md` has an adapter offer exactly the API of the provider its upstream ships, adding nothing, and the maintainer decided that with no exceptions on 2026-11-08, removing `kx_group::SECP521R1` from rind-rustls for the same reason. rustls 0.23.46's provider has `MLKEM768`, `MLKEM1024`, `SECP256R1MLKEM768`, and `X25519MLKEM768` (`src/crypto/aws_lc_rs/mod.rs:247`) and its `NamedGroup` has no variant for this group. - Mirror upstream when it lands: the same static name in `kx_group`, in or out of the default groups as upstream has it (RFC 10024 marks the group not recommended), and no exclusion in `aws_lc_rs_parity`. - Test it in `tests/pair.rs` against itself and against rustls's own provider. diff --git a/quest/m4/protocols/rind-openmls.md b/quest/m4/protocols/rind-openmls.md index e6d4162a..2a06de26 100644 --- a/quest/m4/protocols/rind-openmls.md +++ b/quest/m4/protocols/rind-openmls.md @@ -9,7 +9,7 @@ A published `rind-openmls` adapter implements openmls's `OpenMlsCrypto` provider Decided with the maintainer on 2026-11-07, as a follow-up from [moq-dev/rind#449](https://github.com/moq-dev/rind/pull/449). openmls needs HPKE with the exporter, which `rind::hpke` offers, plus AEADs, HKDF, and signatures rind already has. - Follow the adapter rules: its own crate, a version matching openmls's breaking version (CONTRIBUTING.md's Releases), no re-exported rind types, and exactly the API of the openmls provider it replaces, adding nothing (`AGENTS.md`). Say in the PR which of openmls's providers, `openmls_rust_crypto` or `openmls_libcrux_crypto`, it mirrors item for item. -- No `MissingFeature` and no `Result` on its constructor, which an earlier plan here had: [the adapters epic](/quest/m0/adapters/README.md) removes both from every adapter. +- No `MissingFeature` and no `Result` on its constructor, which an earlier plan here had: no adapter has either. - Run openmls's provider test suite and its interop tests against the RustCrypto provider. Document unsupported ciphersuites, such as X448 and Ed448, in the README. ## Related diff --git a/rind-dimpl/README.md b/rind-dimpl/README.md index 4d7f8751..c9e2fed7 100644 --- a/rind-dimpl/README.md +++ b/rind-dimpl/README.md @@ -18,6 +18,7 @@ let config = dimpl::Config::builder() Or install it for the process with `dimpl::crypto::CryptoProvider::install_default`. It negotiates DTLS 1.2 ECDHE-ECDSA and DTLS 1.3 with AES-128-GCM, AES-256-GCM, and ChaCha20-Poly1305, over X25519, P-256, and P-384, and signs with ECDSA P-256 or P-384 keys in PKCS#8 or SEC1, as DER or PEM. +On a CPU where rind runs AES without CPU instructions, it puts ChaCha20-Poly1305 first, for speed. dimpl's PSK suite, AES-128-CCM-8, is not offered. A PEM key whose preamble starts with `0` is refused: that byte is the tag every DER key starts with, and a DER key's later bytes are secret, so rind never searches them for PEM.