# TLS Provider Tasks

Internal working plan for making `rscrypto` usable under `rustls` without
turning `rscrypto` into a TLS stack.

## Goal

Build a separate provider crate:

```text
application -> rustls -> rscrypto-rustls -> rscrypto
```

`rustls` owns the protocol. `rscrypto` owns primitive implementations. The
provider crate owns glue.

## Non-Goals

- Do not reimplement TLS in `rscrypto`.
- Do not add `rustls` as a dependency of the core crate.
- Do not delegate cryptography back to AWS-LC, OpenSSL, or `ring` and call it a pure provider.
- Do not claim public-web TLS coverage until certificate verification covers the real algorithm set.

## Current Primitive Reality

Available in core:

- `Aes128Gcm`
- `Aes256Gcm`
- `ChaCha20Poly1305`
- `HkdfSha256`
- `HkdfSha384`
- SHA-256 and SHA-384 transcript hashes
- `X25519`
- `Ed25519`

Missing for broad public-web TLS:

- RSA-PSS verification.
- RSA-PKCS1v1.5 verification for legacy certificate chains.
- ECDSA P-256 verification.
- ECDSA P-384 verification.
- P-256 and P-384 ECDH groups.
- Provider crate wiring and interop tests.
- A production random provider policy.

## Crate Shape

Add `rscrypto-rustls` only when the workspace is ready for integration crates.

Expected boundaries:

- depends on `rscrypto`
- depends on `rustls`
- uses `rustls-pki-types` or WebPKI types only where the provider surface requires them
- keeps all TLS glue outside `rscrypto`
- advertises only implemented cipher suites, signature algorithms, and key exchange groups

## Build Order

### 1. Provider Skeleton

- [ ] Create `rscrypto-rustls`.
- [ ] Wire the current `rustls` provider surface.
- [ ] Keep feature flags explicit.
- [ ] Add a smoke-test client/server example.

Verify:

- [ ] `rscrypto` core has no dependency on `rustls`.
- [ ] Provider advertises no algorithms it cannot execute.
- [ ] Unsupported algorithms fail closed.

### 2. TLS 1.3 Symmetric Suites

- [ ] `TLS13_CHACHA20_POLY1305_SHA256`.
- [ ] `TLS13_AES_128_GCM_SHA256`.
- [ ] `TLS13_AES_256_GCM_SHA384`.
- [ ] HKDF-SHA256 and HKDF-SHA384 expansion.
- [ ] SHA-256 and SHA-384 transcript hash wiring.
- [ ] secure random provider backed by `getrandom` or a future FIPS DRBG.

Verify:

- [ ] rustls client/server interop passes.
- [ ] Bad AEAD tags fail.
- [ ] Bad transcript hashes fail.
- [ ] Suite selection exposes only implemented suites.

### 3. Key Exchange Groups

- [ ] X25519.
- [ ] P-256 ECDH after P-256 exists.
- [ ] P-384 ECDH after P-384 exists.
- [ ] Hybrid ML-KEM groups only after ML-KEM is production-quality.

Verify:

- [ ] Shared secret matches compatible vectors.
- [ ] Malformed public keys fail closed.
- [ ] Secret scalar and shared-secret material zeroize.
- [ ] Runtime provider advertises only implemented groups.

### 4. Certificate Signature Verification

Private deployments can start with Ed25519. Public-web TLS needs RSA and ECDSA.

- [ ] Ed25519 verification.
- [ ] RSA-PSS verification.
- [ ] RSA-PKCS1v1.5 verification.
- [ ] ECDSA P-256 verification.
- [ ] ECDSA P-384 verification.
- [ ] explicit legacy policy for SHA-1 certificate signatures, default reject.

Verify:

- [ ] WebPKI algorithm list matches provider advertising.
- [ ] Wycheproof and malformed-signature vectors are included.
- [ ] Invalid signatures return opaque verification failures.
- [ ] Unsupported certificate algorithms fail clearly.

### 5. Server Signing Keys

Do this after verification works.

- [ ] Ed25519 signing key support.
- [ ] RSA-PSS signing key support only after blinding strategy is done.
- [ ] ECDSA P-256 signing key support.
- [ ] ECDSA P-384 signing key support.
- [ ] DER key loading rejects malformed input without panics.

Verify:

- [ ] TLS 1.3 server handshakes complete.
- [ ] Private key material never appears in `Debug`.
- [ ] Signing errors do not expose key internals.

### 6. TLS 1.2

TLS 1.2 is not first-wave work.

- [ ] AES-GCM TLS 1.2 suites.
- [ ] ChaCha20-Poly1305 TLS 1.2 suites.
- [ ] RSA/ECDSA signature algorithms required by rustls.
- [ ] reject CBC suites.
- [ ] reject static RSA key exchange.

## FIPS Interaction

A rustls provider and a FIPS boundary are related, but not the same thing.

- A normal provider can ship first.
- A future FIPS provider must expose only algorithms inside the documented or validated boundary.
- A FIPS provider must not report FIPS status without matching module boundary, self-tests, DRBG, operational environment, and release evidence.

See [`fips.md`](fips.md).
