alktls 0.1.0

Shared TLS setup types: server and client rustls configs, cert resolvers, verifiers, and ACME state-machine wiring, transport-agnostic and shareable across transports.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# alktls

Shared TLS setup types for `rustls`: server and client config
construction, cert resolvers, verifiers, and ACME state-machine wiring —
transport-agnostic and shareable across transports.

The crate owns **config construction**: given an identity and an ALPN
list, produce a `rustls::ServerConfig` or `rustls::ClientConfig` and
hand it to whichever transport the deployment runs (QUIC, TCP+TLS, or
your own wrapper). It does not dial, accept, dispatch, or resolve peer
identities — those stay in the transport and auth layers.

Not tied to any particular stack: compose it with any transport that
consumes a `rustls` config.

## Quick start

### Server — one identity, N transports

```rust
use std::sync::Arc;
use alktls::{TlsServerConfig, TlsIdentity};

// Any of: X509 { cert, key }, RawKey(Ed25519SecretKey),
// SelfSigned, or Acme { .. } (behind the `acme` feature).
let identity = TlsIdentity::RawKey(Ed25519SecretKey::generate());
let alpn = vec![b"my/protocol".to_vec()];

let tls = Arc::new(TlsServerConfig::new(&identity, &alpn).await?);
// The same config feeds every transport — share it via Arc, never
// re-build per transport (and never spawn a second ACME machine):
let _rustls = tls.rustls_config();          // any custom wrapper
#[cfg(feature = "tcp")]
let _acceptor = tls.for_tcp_tls();          // tokio-rustls TlsAcceptor
#[cfg(feature = "noq")]
let _quic = tls.for_noq()?;                 // noq (QUIC) ServerConfig
```

On the ACME path the config spawns a background renewal task and
appends `acme-tls/1` to the ALPN list for you (idempotently); the
handle lives in the config, which is why `TlsServerConfig` is not
`Clone` — share via `Arc`.

### Client — pin, CA, or fail closed

```rust
use alktls::{ConnectionCredentials, RemoteIdentity, TlsClientConfig};

// Known peer: pin its fingerprint (the fingerprint IS the trust
// anchor). Pins are format-exact: `ed25519:<hex>` for raw-key
// remotes, `SHA256:<hex>` for X.509 remotes.
let creds = ConnectionCredentials::new()
    .with_remote_identity(RemoteIdentity {
        fingerprint: "ed25519:64-digit-lowercase-hex".into(),
    });
let config = TlsClientConfig::new(&creds, b"my/protocol")?;
let _rustls = config.into_rustls_config();  // for a TCP+TLS dial

// Unknown X.509 endpoint: `remote_identity: None` → CA verification
// against the platform root store (falls back to webpki-roots when
// the platform bundle is missing, e.g. containers).
let public = ConnectionCredentials::new();
let _config = TlsClientConfig::new(&public, b"my/protocol")?;
```

Verifier selection follows the identity: known peer + fingerprint →
pin; unknown + X.509 → CA; unknown + raw key → **fail closed** at the
handshake. Unknown raw-key remotes are never downgraded to CA
verification — a raw-key remote has no CA, so it is always a known
peer.

### Identity model

[`TlsIdentity`](https://docs.rs/alktls/latest/alktls/enum.TlsIdentity.html)
is the one identity type on both paths:

| Identity | Server presents | Client auth presents |
|----------|-----------------|----------------------|
| `X509 { cert, key }` | cert chain from PEM files | cert chain from PEM files |
| `RawKey(Ed25519SecretKey)` | RFC 7250 raw public key (SPKI) | RFC 7250 raw public key |
| `SelfSigned` | generated in-memory dev cert (no SANs, never expires; pair with fingerprint pinning) | nothing (`NoClientCertResolver`) |
| `Acme { .. }` (`acme` feature) | ACME-managed cert, auto-renewed | config error — server-only |

Client-auth presentation follows the local identity: raw key and X.509
present their cert, `SelfSigned`/`None` present nothing.

### Behavior-preservation invariants

Some settings look optional but are load-bearing — the crate sets them
on every path so callers cannot forget them:

- **`max_early_data_size = u32::MAX`** on server configs (0-RTT works
  out of the box), `enable_early_data = true` on the client.
- **`aws-lc-rs`** as the crypto provider everywhere.
- **`acme-tls/1` ALPN append** for the ACME path only, done by the
  crate.
- **Non-empty root store** — the client CA path merges `webpki-roots`
  when the platform store is empty.
- **Fail closed** — verifier selection never silently downgrades; a
  wrong pin fails the handshake, not the verification posture.
- **Proof-of-possession by default** — the default server verifier
  verifies the client's CertificateVerify signature against the
  presented cert (raw-key and X.509 paths), so a copied cert is not
  usable by a party that lacks the matching private key. The
  no-possession escape hatch ([`AcceptAnyCertVerifier`](https://docs.rs/alktls/latest/alktls/struct.AcceptAnyCertVerifier.html))
  exists but is never the default.

## Features

| Feature | Contents |
|---------|----------|
| *(default)* | config construction, identity/credential/fingerprint types, PEM loading, verifiers, resolvers |
| `tcp` | [`for_tcp_tls()`](https://docs.rs/alktls/latest/alktls/struct.TlsServerConfig.html#method.for_tcp_tls) — the `tokio-rustls` acceptor wrapper |
| `noq` | [`for_noq()`](https://docs.rs/alktls/latest/alktls/struct.TlsServerConfig.html#method.for_noq) — QUIC config wrapping via `noq` |
| `acme` | the ACME path — `rustls-acme` state machine, background renewal, `acme-tls/1` |

The default crate is deliberately lean (rustls + cert material + tokio
spawn); the transport-specific dependencies are opt-in.

## Scope boundary

This crate is the **cert/config provider, not the accept loop**. It
does not bind sockets, dial, or dispatch — accept loops and dial seams
live in the consumers. Handshake-time outcomes (a rejected cert, a
mismatched pin) surface through the transport's connector, not through
[`TlsError`](https://docs.rs/alktls/latest/alktls/enum.TlsError.html),
which covers config construction only. ACME state-machine runtime
events are logged in the spawned renewal task.

## Documentation

- [Architecture docs](docs/architecture/README.md) — the authoritative
  spec: overview, the server and client API surfaces, and ADRs 001–008
  (extraction baseline, `TlsError` shape, `noq`, accessors, config-type
  ownership, module layout, RFC 7250 negotiation, possession
  verification).
- [API docs](https://docs.rs/alktls) — full crate documentation on
  docs.rs.

## Verification

```bash
cargo test                  # default crate
cargo test --all-features   # + tcp, noq, acme suites
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```

## License

MIT OR Apache-2.0