Skip to content

feat(core)!: resolve CryptoProvider through Context - #970

Open
Xuanwo wants to merge 13 commits into
mainfrom
xuanwo/crypto-provider-breaking-change
Open

Xuanwo wants to merge 13 commits into
mainfrom
xuanwo/crypto-provider-breaking-change

Conversation

@Xuanwo

@Xuanwo Xuanwo commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Problem

Reqsign currently bundles cryptographic implementations into reqsign-core and several service crates. Applications cannot choose a single crypto stack, and the public jwt API exposes rsa::RsaPrivateKey in its surface. This is the breaking-change implementation of the approved CryptoProvider design, with Context-owned provider selection and a facade default that works without startup boilerplate.

Final behavior

reqsign-core and every services/* crate carry zero production dependencies on sha1, sha2, hmac, rsa, p256, or aes-gcm. Crypto operations resolve through Context in this order:

  1. Context::with_crypto(provider) (explicit, highest priority);
  2. the process-wide reqsign_core::crypto::install_default(provider) registration;
  3. otherwise ErrorKind::ConfigInvalid at the point of use.

Context::new() starts unbound. Creating, using, or cloning a context never installs or freezes the process-wide slot. An explicitly bound context keeps its provider; an unbound context observes the current global registration. Distinct contexts can use independent providers.

The reqsign facade adds default-crypto (included in default). When enabled, default_context() checks the process-wide registration at construction: it binds RustCryptoProvider only when the slot is empty, and leaves the context unbound when a global provider is already installed. It never writes the global slot. Per-service default_signer(...) and examples therefore work without startup boilerplate. Applications choosing a global provider install it before constructing facade contexts; contexts already bound to RustCrypto keep that binding, and an explicit with_crypto binding always wins. Without default-crypto, default_context() has no implicit binding. Middleware such as OpenDAL must not install a global provider.

Standalone crypto entry points take an explicit provider: hash::* and Azure's ServiceSharedAccessSignature::token. Callers with a context pass ctx.crypto_provider()?. Pure base64 encoders/decoders stay unchanged. The public reqsign_core::jwt module and jwt feature are removed; Azure client-certificate and Google service-account flows format RS256 JWS in private service helpers using the selected provider.

Error semantics remain: missing/unsupported provider operation is non-retryable ConfigInvalid; malformed key material is CredentialInvalid; backend failures are Unexpected.

Two provider crates ship:

  • reqsign-crypto-rustcrypto (crypto/rustcrypto) is a workspace member and implements all eight operations natively; on wasm32-unknown-unknown it provides SHA-1, SHA-256, HMAC-SHA-1/256, and P-256 ECDSA, reporting RSA/AES-GCM/random as unsupported.
  • reqsign-crypto-boring (crypto/boring) is excluded from the main workspace, native-only, independently versioned, and verified by a focused Linux workflow. It implements all eight operations through safe, stateless BoringSSL APIs and forwards an optional fips feature.

The authoritative contract, resolution and ownership rules, migration guidance, error boundaries, and provider manifests are in docs/crypto-provider.md.

Migration

  • Facade users can keep using default_context() / default_signer(...) without installing anything.
  • To select one provider application-wide, call RustCryptoProvider::install_default() once before constructing facade contexts.
  • Bare reqsign-core users bind a provider with Context::new().with_crypto(provider), or install a global provider, before signing.
  • Hash/HMAC and Azure service SAS callers now pass the selected provider. Hash and MAC helpers return Result; service JWT formatting remains private.
  • Existing wire formats, credential-chain fallback/Ok(None) behavior, expiry/auth semantics, crate versions, and workspace isolation are preserved.
  • A generic credential chain may skip a provider error and surface credential absence; Signer::sign then reports CredentialInvalid with the request unchanged. AWS SSO-style selected identities propagate their errors. This is documented rather than changed.

#941 alignment

This PR leaves #941 and its rsa 0.10 bump untouched. RSA remains encapsulated in reqsign-crypto-rustcrypto with the existing rsa 0.9.2 requirement and MSRV. After this review, #941 can update only that provider crate; no public Reqsign API change is needed.

Validation

On the current head:

  • cargo test --workspace --all-features --no-fail-fast and doc tests pass, including Google CAB tests with their feature enabled.
  • cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo fmt, and hawkeye check pass.
  • Core integration tests cover bare missing context, early lookup, rejected second installation, concurrent installation, explicit priority over global, and independent providers on distinct contexts.
  • Facade tests cover default-crypto present and absent. With the global slot empty, default_context() binds RustCrypto, works, does not occupy OnceLock, and can still install a global provider afterward; that existing context keeps RustCrypto, while a new default_context() uses the global provider. Explicit bindings still win. Feature-off and bare missing-provider behavior are covered.
  • A default signer signs through its context provider; an explicitly selected provider is used by an existing signer.
  • RustCrypto provider tests retain hash/HMAC vectors and boundaries, both RSA PEM formats, AES-128/256-GCM with/without AAD, ECDSA verification, invalid keys, and unsupported-operation defaults.
  • BoringSSL tests retain byte-for-byte hash/HMAC/RSA/AES-GCM parity, cross-backend ECDSA verification, error kinds, and an AWS SigV4 end-to-end signing test with an explicit BoringSSL context.
  • cargo tree -p <each core/service crate> --all-features --target all --edges normal confirms zero production crypto implementation dependencies; CI enforces this per root to avoid workspace feature unification.
  • WASM checks pass for reqsign-core (all features), reqsign-crypto-rustcrypto, and the facade with default-context,default-crypto; cargo check -p reqsign --examples --all-features passes.
  • Website: pnpm install --frozen-lockfile, pnpm run validate-providers (10 providers, 7 internal crates, workspace fully claimed), pnpm build, and the third-party runtime asset check pass. reqsign-crypto-rustcrypto is classified as an internal crate; excluded Boring is not in the workspace list.
  • cargo publish -p reqsign-core --dry-run packages successfully. A full workspace publish dry-run cannot verify dependent crates against the new unpublished core API before release; release packaging remains part of the normal release process.

Base: 724d6c7; current main is 2d5daad, whose only delta is Azure CI retry scripts. The new crypto backends start on independent 1.0.0 version lines; existing core, service, and facade versions are unchanged. The PR is ready for Xuanwo and community review and is intentionally not merged by the maintenance loop.

Move all signing cryptography out of reqsign-core and the service crates
behind a process-wide CryptoProvider. Core installs one provider at most
once, never falls back to a bundled implementation, and returns
ConfigInvalid when no provider is installed. Hash, HMAC, and JWT helpers
now propagate failures; the rsa-typed JWT entry point is removed.

Migrate every signing call site, including AWS SSO/SigV4a, Azure client
certificate and SAS, Google service account and client-side CAB, Oracle,
Aliyun, Huawei, Tencent, and Volcengine. On-wire formats and existing
caller contracts are preserved.

Add reqsign-crypto-rustcrypto as a workspace member with native support
for all operations and the existing WASM subset, and add the excluded,
native-only reqsign-crypto-boring crate with a dedicated Linux CI job.
The reqsign facade re-exports RustCryptoProvider behind default-crypto
but never installs it implicitly. Document the contract, ownership and
migration in docs/crypto-provider.md.
SHA-1 cache keys now come from reqsign_core::hash, so aws-core no longer
uses the hex crate directly.
State that installation must precede credential loading that uses crypto,
and explain how generic credential chains surface Ok(None) while selected
identities such as AWS SSO propagate the underlying error. Clarify that
installation is at-most-once rather than idempotent, note Google
service-account invalid key behavior, and check every optional dependency
path per root in the production crypto graph gate.
Add explicit Context::with_crypto bindings and context fallbacks. Crypto
resolution now prefers an explicit binding, then the process-wide install,
then the fallback, and otherwise fails with ConfigInvalid at the point of
use. Contexts never install or freeze the global slot, so a provider
installed after a context was created still takes precedence over its
fallback.

The facade's default_context supplies RustCrypto as a fallback when
default-crypto is enabled, making default signers and examples work without
startup boilerplate while preserving explicit and global overrides. Bare
Context::new() still has no provider.

Thread the selected provider through signing, credential, and granting
paths and through standalone hash, JWT PEM, and Azure service SAS entry
points. Update tests to bind providers locally, add resolution-priority and
facade feature coverage, update caller documentation, and classify
reqsign-crypto-rustcrypto as an internal website crate so the provider
catalog validator accepts the new workspace member.
@Xuanwo Xuanwo changed the title feat(core)!: require an installed CryptoProvider feat(core)!: resolve CryptoProvider through Context Nov 19, 2026
Keep one explicit Context binding and resolve it before the process-wide
default. When default-crypto is enabled, default_context binds RustCrypto
only if the global slot is empty at construction; otherwise it leaves the
context unbound. This avoids a third resolution layer while keeping default
signers and examples free of install boilerplate.

Update docs, caller-facing notes, and isolated tests for install-before-
construction, OnceLock non-occupation, feature-off behavior, and explicit
provider priority.
State that a bare Context has no explicit binding, not that a global
provider is absent from the process.
Bring in the SSO AssumeRole provider chain and shared SigV4 signing
options from #954, plus the latest CI and website dependency updates.

Port the new shared signing path and role-chain tests to the two-layer
Context CryptoProvider resolution: pass the resolved provider through
sign_request_parts, generated signing keys, STS request construction, and
the role-chain fixtures. Preserve #954's profile selection, explicit
Single/Double canonicalization, S3 Express routing, and credential-chain
error behavior.
Start reqsign-crypto-rustcrypto and reqsign-crypto-boring on independent
1.0.0 lines. Update the workspace dependency, Boring's RustCrypto dev
dependency, and the versioning documentation while keeping core, service,
and facade versions unchanged.
Remove the public reqsign_core::jwt module and jwt feature, along with
core's optional serde/serde_json dependencies and the JWT-only test
support/dev dependencies.

Azure now formats its client-certificate RS256 assertion privately, and
Google shares one private crate-local JWT helper between request signing
and service-account token exchange. Both keep the existing headers,
claims, unpadded JWS encoding, PKCS#8/PKCS#1 support, and provider error
semantics. Google's base64 dependency is now always available, while the
former optional-feature wiring is removed. Port the JWT contract tests to
the service helpers and update the design/caller documentation.
Comment thread .github/workflows/ci.yml Outdated
# not unified into the roots. --all-features covers every optional
# path; --target all also covers target-specific dependencies.
for package in "${packages[@]}"; do
if cargo tree -p "$package" --all-features --target all --edges normal --prefix none \

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
if cargo tree -p "$package" --all-features --target all --edges normal --prefix none \
if cargo tree --package "$package" --all-features --target all --edges normal --prefix none \

Comment thread .github/workflows/ci.yml Outdated
Comment on lines +128 to +129
cargo check -p reqsign-core --target wasm32-unknown-unknown
cargo check -p reqsign-crypto-rustcrypto --target wasm32-unknown-unknown

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
cargo check -p reqsign-core --target wasm32-unknown-unknown
cargo check -p reqsign-crypto-rustcrypto --target wasm32-unknown-unknown
cargo check --package reqsign-core --target wasm32-unknown-unknown
cargo check --package reqsign-crypto-rustcrypto --target wasm32-unknown-unknown

Comment thread .github/workflows/ci.yml Outdated
RUST_BACKTRACE: full
- name: Facade crypto feature tests
run: |
cargo test -p reqsign --all-features --test crypto --test default_signer

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
cargo test -p reqsign --all-features --test crypto --test default_signer
cargo test --package reqsign --all-features --test crypto --test default_signer

Comment thread core/src/crypto.rs Resolved
Apply the review suggestions for the per-root dependency gate, core and
RustCrypto WASM checks, and the facade crypto feature tests.
Bring in the Context ownership and credential-cache isolation contract,
the caller-supplied Context for every facade default_signer, and the
latest service versions and documentation.

Resolve the facade README overlap by keeping the new default_signer
signature and documenting the conditional RustCrypto binding. Bind an
explicit test provider in the service-only context test and update the
default-signer integration test for the caller-context API.

Reconcile Boring's workspace path dependencies with the versions now on
the branch, and preserve the two-layer CryptoProvider design, private
service JWT helpers, backend versions, and dependency boundaries.
Document that the provider exposes the focused digest, HMAC, signature,
encryption, and random-generation operations Reqsign needs, and that one
provider serves all operations at runtime.

@erickguan erickguan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some minor comments worth ironing out.

I feel some jwt.rs can also be generic but I am not going to be in your way.

A question about design for my learning: why don't we require core instead of extracting a trait only lib when reverse dependencies? i.e. why do you allow crypto lib refer to reqsign_core?

Comment thread .github/workflows/ci.yml Outdated
- name: Facade crypto feature tests
run: |
cargo test --package reqsign --all-features --test crypto --test default_signer
cargo test -p reqsign --no-default-features --features default-context --test crypto_without_default_crypto

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
cargo test -p reqsign --no-default-features --features default-context --test crypto_without_default_crypto
cargo test --package reqsign --no-default-features --features default-context --test crypto_without_default_crypto

use support::TestProvider;

#[test]
fn concurrent_installation_elects_exactly_one_provider() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably don't need timing related test where most likely one instance works.

Comment thread crypto/rustcrypto/tests/core_hash.rs Outdated
use reqsign_crypto_rustcrypto::RustCryptoProvider;

#[test]
fn hashes_match_published_vectors_with_expected_widths() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Try no to pin hashes because we don't test its values. Length and perhaps character range checks are more than enough.

Comment thread crypto/rustcrypto/tests/provider.rs Outdated
}

#[test]
fn hashes_match_published_vectors() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same reason, not to test hash values.

Use --package in the facade crypto CI command, drop the redundant threaded install stress test, and keep deterministic install assertions. Compare hash helpers with provider raw bytes instead of pinned digests, and verify the RustCrypto adapter against direct primitives.
@Xuanwo

Xuanwo commented Nov 20, 2026

Copy link
Copy Markdown
Member Author

Thanks for the review, @erickguan. Addressed the four inline comments in 970c07a:

  • CI now uses --package for the remaining crypto_without_default_crypto command; test and feature selection are unchanged.
  • Removed the threaded global-install stress test. The deterministic early_lookup and second_install tests already cover an empty lookup not freezing the slot, the first provider being retained, and the rejected attempt being returned; I also made the latter assert the rejected provider identity directly.
  • Core hash/encoding tests no longer pin RustCrypto digest/MAC values. They compare helper output with the provider's raw bytes and independently encode those bytes; realistic distinct key/input values keep argument-order and SHA/encoding mixups detectable.
  • The RustCrypto provider tests now compare the adapter with direct sha1/sha2/hmac primitives, including block-boundary keys, rather than pinning known digests. AES, RSA, ECDSA, validation/error, Boring parity, and the independent AWS SigV4 oracle remain.

On the design question: reqsign-core owns the runtime/application contract (CryptoProvider, Context, Error/Result) and ships no implementation. A backend crate implements that contract and may depend on core without a cycle; the facade/application assembles core with the chosen backend. A trait-only crate would add another package/version boundary and require a separate shared error contract or translation layer, and no current consumer needs that split. The per-service JWT code owns claims/JWS formatting and shares RSA through CryptoProvider.

Review: #970 (review)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants