rustls-letsencrypt 0.1.4

Automatic Let's Encrypt, ACME, and local-CA certificate management for rustls listeners
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
# rustls-letsencrypt

Automatic TLS certificate issuance, selection, storage, and renewal for Rust servers.

`rustls-letsencrypt` puts certificate management directly in front of your TLS connections. It reads the ClientHello, selects the best certificate for its SNI hostname, obtains a certificate when one is missing, answers ACME `tls-alpn-01` challenges on port 443, and hands the completed TLS stream back to your application.

The manager is process-scoped. Register the port-443 ALPN handler once, then add managed TLS handlers on any other port without repeating configuration.

## How it works

The listener on port 443 serves two kinds of TLS connection through the same
socket:

1. For ordinary clients, it reads SNI from ClientHello, selects the valid ACME
   certificate or local fallback, completes TLS, and returns the encrypted
   stream to the application.
2. For an ACME validation connection offering only `acme-tls/1`, it verifies
   that this process initiated the matching order, serves the temporary RFC 8737
   challenge certificate, completes validation internally, and does not expose
   that connection to the application.
3. When an allowed hostname has no certificate, the manager starts ACME
   issuance and, when enabled, local fallback issuance. The resulting records
   are stored separately and published to the in-memory certificate cache.
4. Other managed listeners—such as Kafka on 9092—share that cache. They can
   trigger issuance, while the CA's separate validation connection arrives at
   the already-running port-443 listener.

```text
ordinary client ─┐
                 ├─ TCP 443 ─ ClientHello/SNI/ALPN ─┬─ acme-tls/1 → challenge
ACME validator ──┘                                  └─ normal TLS → application

Kafka client ───── TCP 9092 ─ shared manager/cache ── normal TLS → Kafka
                                      │
                                      └─ missing cert starts issuance
```

### Why TLS-ALPN-01 on port 443 instead of HTTP-01 on port 80?

- A TLS-only service does not need to open or maintain a plaintext HTTP
  listener on port 80.
- Networks that intentionally expose only HTTPS can keep that policy.
- Validation follows the same TCP ingress and SNI routing path as production
  TLS traffic.
- The temporary challenge certificate is scoped to the requested hostname and
  `acme-tls/1`; it is never used for application traffic.
- Non-HTTP services such as Kafka can obtain certificates without pretending to
  be an HTTP server.

TLS-ALPN-01 is not universally better. The CA must reach this manager on TCP
443, and any load balancer or reverse proxy in front must pass the challenge
ClientHello through rather than terminating it with an unrelated certificate.
When an existing HTTP proxy owns validation routing, HTTP-01 may be simpler.

The interception is transparent to the application protocol. The manager
special-cases only a matching, locally initiated `acme-tls/1` validation
connection. Ordinary HTTPS continues through the normal TLS handshake and the
accepted stream contains the original HTTP bytes unchanged. The same is true
for Kafka or any other protocol carried over TLS: after certificate selection,
the crate does not parse, proxy, rewrite, or otherwise participate in the
application protocol. Configure `application_alpn_protocols` when the
application needs protocols such as `h2` or `http/1.1` advertised by the TLS
server.

```text
                              ┌────────────────────────────┐
                              │ process certificate manager│
                              │ ACME + Local + renewal     │
                              └─────────────┬──────────────┘
                                            │
                   ┌────────────────────────┼───────────────────────┐
                   │                        │                       │
             port 443 handler        port 9092 handler       port 8443 handler
             TLS + acme-tls/1         normal TLS              normal TLS
```

## Features

- Automatic ACME issuance through the TLS-ALPN-01 challenge.
- Let's Encrypt production and staging profiles.
- Managed local Pebble support for development without public DNS or Internet ingress.
- Custom RFC 8555-compatible ACME directory support.
- A process-wide certificate cache shared by TLS listeners on every port.
- Exact hostname and label-glob allowlists (`*` never crosses a dot).
- Optional DNS-to-public-IP ownership checks before public ACME issuance.
- A persisted local CA named `AcmeLocalCA` for immediate fallback certificates.
- Concurrent local and ACME issuance for a previously unseen hostname.
- Deterministic certificate preference: valid ACME, then valid local certificate.
- Lock-free certificate resolution through per-domain ArcSwap snapshots.
- JSON folder storage with separate `ACME/` and `Local/` namespaces.
- Automatic renewal before expiry with bounded retries.
- A configurable absolute deadline for every issuance and renewal attempt, defaulting to 60 seconds.
- Structured lifecycle events, subscriptions, callbacks, and built-in stderr/stdout output.
- Native Tokio API and an optional blocking adapter.
- Certificate retrieval for application integrations such as Kafka.

## How it behaves

For every ordinary TLS ClientHello with SNI, the acceptor uses this resolution order:

```text
1. Valid certificate from the configured ACME provider
2. Valid certificate issued by AcmeLocalCA
3. Start or join both issuance tasks and wait for an in-flight result
```

ACME and local certificates coexist. A local certificate never overwrites an ACME certificate. If local issuance finishes first, the current connection can use it immediately. When ACME issuance succeeds, the next connection automatically uses the ACME certificate.

Existing connections keep the certificate snapshot selected for their handshake. Certificate replacement does not interrupt established connections.

> A certificate issued by `AcmeLocalCA` is trusted only by clients that have installed that CA. It is not a replacement for a publicly trusted certificate.

## Installation

```toml
[dependencies]
rustls-letsencrypt = "0.1"
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
```

Enable the blocking facade or managed Pebble support when needed:

```toml
[dependencies]
rustls-letsencrypt = { version = "0.1", features = ["blocking", "managed-pebble"] }
```

## Quick start

The port-443 handler must be registered first. It initializes the process manager and makes ACME TLS-ALPN validation available.

## Ready-to-run examples

The repository includes practical configurations in `examples/`, all using
`./certs` for JSON certificate storage:

```console
# Public production (edit the literal host/IP in the example first)
cargo run --example letsencrypt_prod

# Public staging with application-subscribed events (edit the literal host/IP first)
cargo run --example letsencrypt_staging

# Local Pebble, no public DNS/IP verification, unprivileged port 8443
cargo run --features managed-pebble --example pebble_local

# QUIC using the certificate already stored for api.example.com
cargo run --features quic-example --example quic
```

The production and staging examples use explicit public DNS resolvers, verify
that the hostname resolves to the configured public IP, and keep local fallback
enabled. Production logs to stderr; staging subscribes to structured events.
The Pebble example uses stderr logging, private loopback binding, and disables
the public DNS ownership gate.

The QUIC example demonstrates the non-TLS-listener use case: call
`get_certificate("api.example.com")`, convert the returned PEM material into
your QUIC library's server configuration, and run QUIC on another port (4433
in the example). It expects that the 443 ALPN listener has already obtained the
certificate in the same process.

```rust,no_run
use rustls_letsencrypt::{
    register_alpn_handler,
    AcmeEndpoint,
    AlpnHandlerConfig,
    EventOutput,
    HostPattern,
    LetsEncryptAcmeProfile,
};
use std::{net::IpAddr, path::PathBuf};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("0.0.0.0:443").await?;

    let config = AlpnHandlerConfig {
        allowed_hosts: vec![
            HostPattern::exact("broker.example.com")?,
            HostPattern::single_label_wildcard("*.services.example.com")?,
        ],
        verify_dns_before_issuance: true,
        dns_servers: None, // Use the system resolver.
        public_ip_addresses: vec!["203.0.113.10".parse::<IpAddr>()?],
        cert_store_directory: PathBuf::from("./certificates"),
        acme_endpoint: AcmeEndpoint::LetsEncrypt(
            LetsEncryptAcmeProfile::Production,
        ),
        events: EventOutput::Stderr,
        ..AlpnHandlerConfig::default()
    };

    let mut incoming = register_alpn_handler(listener, Some(config)).await?;

    while let Some(connection) = incoming.accept().await? {
        tokio::spawn(async move {
            let tls_stream = connection.into_stream();
            // Read and write your application protocol through tls_stream.
            drop(tls_stream);
        });
    }

    Ok(())
}
```

The returned handler accepts ordinary application TLS on port 443 and internally consumes matching `acme-tls/1` validation connections. ACME validation streams are never handed to application code.

Passing `None` uses defaults, but issuance remains disabled until at least one allowed host is configured or valid certificates are already present in the store.

## TLS on another port

After the port-443 handler is ready, register ordinary handlers without any additional configuration:

```rust,no_run
use rustls_letsencrypt::register_handler;
use tokio::net::TcpListener;

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let kafka_listener = TcpListener::bind("0.0.0.0:9092").await?;
let mut kafka_tls = register_handler(kafka_listener).await?;

while let Some(connection) = kafka_tls.accept().await? {
    let server_name = connection.server_name();
    let negotiated_alpn = connection.negotiated_alpn();
    let stream = connection.into_stream();

    println!("accepted TLS for {server_name:?} using {negotiated_alpn:?}");
    drop(stream);
}
# Ok(())
# }
```

Calling `register_handler` before `register_alpn_handler` returns `AlpnHandlerNotRegistered`. Calling it while port-443 initialization is incomplete returns `AlpnHandlerNotReady`.

All handlers share:

- allowed-host policy;
- certificate cache;
- ACME account and challenge registry;
- local CA;
- issuance single-flights;
- folder store;
- renewal scheduler;
- event bus.

If a connection on port 9092 requests an allowed hostname with no certificate, it can trigger issuance. The CA's separate validation connection is answered on port 443. If the original client disconnects, issuance continues and the result is stored for its next attempt.

## Deployment recipes

These configurations are intended as practical starting points. Pass the chosen
configuration to `register_alpn_handler` on the listener that receives ACME
TLS-ALPN validation traffic.

### Local development with managed Pebble

Enable the `managed-pebble` feature and ensure `pebble` is in `PATH`:

```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput,
    HostPattern, ManagedPebbleConfig};

# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
    allowed_hosts: vec![HostPattern::exact("api.test")?],
    acme_endpoint: AcmeEndpoint::Pebble(ManagedPebbleConfig {
        pebble_bind: "127.0.0.1:14000".parse()?,
        pebble_executable: None,
        working_directory: None,
        state_directory: Some("./dev-certs/pebble-state".into()),
    }),
    cert_store_directory: "./dev-certs".into(),
    verify_dns_before_issuance: false,
    local_fallback_enabled: true,
    issuance_attempt_timeout_secs: 30,
    events: EventOutput::Stderr,
    // Set this only when deliberately testing on an unprivileged port.
    allow_non_443_listener: false,
    ..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```

Pebble certificates are test certificates. Clients must trust Pebble's generated
test CA; never add that CA to a production or system-wide trust store.

### Let's Encrypt staging

Use staging while validating public DNS, firewall rules, port 443 routing, and
renewal behavior:

```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput,
    HostPattern, LetsEncryptAcmeProfile};

# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
    allowed_hosts: vec![HostPattern::exact("api.example.com")?],
    acme_endpoint: AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Staging),
    acme_contacts: vec!["mailto:ops@example.com".into()],
    public_ip_addresses: vec!["203.0.113.10".parse()?],
    verify_dns_before_issuance: true,
    cert_store_directory: "/var/lib/my-service/certificates".into(),
    local_fallback_enabled: true,
    issuance_attempt_timeout_secs: 60,
    events: EventOutput::Stderr,
    ..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```

Staging certificates are not publicly trusted. A local fallback is useful only
for clients that already trust `Local/CA.pem`.

### Let's Encrypt production

Move to production only after the staging journey succeeds:

```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, DnsServer,
    EventOutput, HostPattern, LetsEncryptAcmeProfile};

# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
    allowed_hosts: vec![
        HostPattern::exact("api.example.com")?,
        HostPattern::exact("broker.example.com")?,
    ],
    acme_endpoint: AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Production),
    acme_contacts: vec!["mailto:ops@example.com".into()],
    public_ip_addresses: vec!["203.0.113.10".parse()?],
    dns_servers: Some(vec!["1.1.1.1:53".parse::<DnsServer>()?]),
    verify_dns_before_issuance: true,
    cert_store_directory: "/var/lib/my-service/certificates".into(),
    renew_days_before_expiry: 15,
    renew_check_interval_secs: 3_600,
    renew_check_max_interval_secs: 43_200,
    issuance_attempt_timeout_secs: 60,
    local_fallback_enabled: true,
    events: EventOutput::Stderr,
    ..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```

The service must be reachable by the CA on TCP port 443 and the configured DNS
names must resolve to one of `public_ip_addresses`.

### Private services using only AcmeLocalCA

For an internal service that must never contact an ACME server:

```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, AlpnHandlerConfig, EventOutput, HostPattern};

# fn configuration() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
    allowed_hosts: vec![HostPattern::single_label_wildcard("*.internal.example")?],
    acme_endpoint: AcmeEndpoint::LocalOnly,
    verify_dns_before_issuance: false,
    local_fallback_enabled: true,
    local_leaf_validity_days: 30,
    cert_store_directory: "/var/lib/my-service/private-certs".into(),
    events: EventOutput::Stderr,
    ..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```

Install `Local/CA.pem` only in the intended private clients. Protect
`Local/CA.key` as a CA signing key. `LocalOnly` never initializes an ACME order.

## Configuration

Use `AlpnHandlerConfig` only with `register_alpn_handler`. Other handlers intentionally accept no certificate-manager configuration.

```rust,no_run
use rustls_letsencrypt::{
    AcmeEndpoint,
    AlpnHandlerConfig,
    DnsServer,
    EventOutput,
    HostPattern,
    LetsEncryptAcmeProfile,
};
use std::{net::IpAddr, path::PathBuf};

# fn config() -> Result<AlpnHandlerConfig, Box<dyn std::error::Error>> {
let config = AlpnHandlerConfig {
    allowed_hosts: vec![HostPattern::exact("api.example.com")?],
    verify_dns_before_issuance: true,
    dns_servers: Some(vec![DnsServer::udp_then_tcp("1.1.1.1:53".parse()?)]),
    public_ip_addresses: vec!["203.0.113.10".parse::<IpAddr>()?],
    cert_store_directory: PathBuf::from("./certificates"),
    acme_endpoint: AcmeEndpoint::LetsEncrypt(
        LetsEncryptAcmeProfile::Production,
    ),
    renew_days_before_expiry: 15,
    renew_check_interval_secs: 3_600,
    renew_check_max_interval_secs: 43_200,
    client_hello_timeout_secs: 5,
    issuance_attempt_timeout_secs: 60,
    initial_connection_wait_timeout_secs: 60,
    dns_lookup_timeout_secs: 5,
    pebble_startup_timeout_secs: 30,
    local_fallback_enabled: true,
    events: EventOutput::Stderr,
    ..AlpnHandlerConfig::default()
};
# Ok(config)
# }
```

### Defaults

| Setting | Default | Meaning |
|---|---:|---|
| `renew_days_before_expiry` | 15 days | A certificate becomes due for renewal |
| `renew_check_interval_secs` | 3,600 | Scheduled scan and first retry interval |
| `renew_check_max_interval_secs` | 43,200 | Maximum per-domain/issuer retry backoff |
| `client_hello_timeout_secs` | 5 | Absolute seconds allowed to receive ClientHello |
| `issuance_attempt_timeout_secs` | 60 | Absolute seconds allowed for each issuance or renewal attempt |
| `initial_connection_wait_timeout_secs` | 60 | Seconds a triggering handshake waits |
| `dns_lookup_timeout_secs` | 5 | Absolute seconds allowed for one DNS ownership lookup |
| `pebble_startup_timeout_secs` | 30 | Seconds allowed for managed Pebble readiness |
| `local_fallback_enabled` | enabled | Issue an immediate locally trusted fallback |
| `verify_dns_before_issuance` | `true` | Verify public DNS before ACME issuance/renewal |
| `dns_servers` | `None` | Use the operating system's configured resolver |
| `events` | `Stderr` | Built-in event presentation |

Timeout values are interpreted as seconds and converted to internal `Duration` values after configuration validation. `issuance_attempt_timeout_secs` is not capped at 60; the configured value is honored. The default is 60 seconds.

### Allowed hosts

Only configured hostnames may trigger issuance or receive a managed certificate.

```rust,no_run
# use rustls_letsencrypt::HostPattern;
# fn hosts() -> Result<(), Box<dyn std::error::Error>> {
let exact = HostPattern::exact("api.example.com")?;
let pattern = HostPattern::single_label_wildcard("*.services.example.com")?;
# Ok(())
# }
```

The wildcard is an allowlist pattern, not a wildcard certificate request. The
convenience `AlpnHandlerConfig::for_host` and `for_hosts` helpers detect these
patterns automatically:

- `*.services.example.com` matches `one.services.example.com`.
- It does not match `services.example.com`.
- It does not match `one.two.services.example.com`.
- `*help.wushilin.net` matches `myhelp.wushilin.net`.
- `*.*.*` matches any hostname with exactly three labels.
- `*` matches any one-label hostname, but is usually too broad for a public service.
- `*` matches only characters within one label; it never matches a dot.
- Every ACME order uses the concrete SNI hostname.

TLS-ALPN-01 cannot issue wildcard certificates.

Hostnames are normalized to lowercase ASCII form before policy, cache, storage, and ACME lookup. SNI is required for on-demand issuance.

### Public IP ownership gate

`verify_dns_before_issuance` explicitly controls this additional pre-issuance safety gate and defaults to `true`.

When enabled, before public ACME issuance or renewal the manager:

1. verifies the concrete SNI hostname against `allowed_hosts`;
2. resolves its A and AAAA records;
3. requires at least one result to match `public_ip_addresses`;
4. starts or joins the ACME order only after those checks pass.

This check happens during issuance and ACME renewal, not on every TLS handshake. A mismatch produces `DnsOwnershipMismatch` and an event without contacting the ACME server.

Multiple IPv4 and IPv6 addresses are supported for dual-stack and migration scenarios.

By default, lookup uses the operating system's resolver configuration. Supply one or more DNS servers when the application needs deterministic or independent resolution:

```rust,no_run
# use rustls_letsencrypt::{AlpnHandlerConfig, DnsServer};
let config = AlpnHandlerConfig {
    verify_dns_before_issuance: true,
    dns_servers: Some(vec![
        "udp://1.1.1.1:53".parse::<DnsServer>()?,
        "tcp://8.8.8.8:1053".parse::<DnsServer>()?,
        "udp://[2001:4860:4860::8888]:53".parse::<DnsServer>()?,
    ]),
    public_ip_addresses: vec!["203.0.113.10".parse()?],
    ..AlpnHandlerConfig::default()
};
# Ok::<(), Box<dyn std::error::Error>>(())
```

Use `udp://` for UDP-only resolution and `tcp://` for TCP-only resolution. A bare address such as `1.1.1.1:53` means UDP with TCP retry/failover, which is the normal choice when truncated UDP responses must be retried. Brackets are required around IPv6 literals. DNS servers are tried according to the resolver's failover policy under one bounded lookup deadline. An empty `Some(vec![])` is rejected; use `None` for the system resolver. Unsupported schemes fail configuration parsing explicitly; DNS-over-TLS and DNS-over-HTTPS are not currently enabled by these values.

To rely only on `allowed_hosts`, disable DNS verification explicitly:

```rust,no_run
# use rustls_letsencrypt::AlpnHandlerConfig;
let config = AlpnHandlerConfig {
    verify_dns_before_issuance: false,
    public_ip_addresses: vec![],
    ..AlpnHandlerConfig::default()
};
```

When verification is disabled, `public_ip_addresses` and `dns_servers` are not used for issuance policy. The manager emits a startup warning event so this weaker policy is visible. The hostname allowlist remains mandatory and ACME still performs its own external domain validation.

Managed Pebble does not use public DNS verification. Its validation environment uses the scoped local hostname mapping described below.

## ACME providers

### Let's Encrypt

```rust,no_run
# use rustls_letsencrypt::{AcmeEndpoint, LetsEncryptAcmeProfile};
let staging = AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Staging);
let production = AcmeEndpoint::LetsEncrypt(LetsEncryptAcmeProfile::Production);
```

Use staging until DNS, firewall, challenge routing, and renewal behavior are verified. Staging certificates are not publicly trusted.

### Managed Pebble

Managed Pebble provides a complete local ACME journey when public DNS or inbound Internet access is unavailable.

To build Pebble with Go and install the executable where the managed integration
test finds it:

```console
go install github.com/letsencrypt/pebble/v2/cmd/pebble@latest
sudo install -m 0755 "$(go env GOPATH)/bin/pebble" /usr/local/bin/pebble
pebble -version
```

Alternatively, place a trusted Pebble release binary at
`/usr/local/bin/pebble`. `ManagedPebbleConfig::pebble_executable` can select a
different absolute path. The crate never downloads or installs Pebble itself.

```rust,no_run
use rustls_letsencrypt::{AcmeEndpoint, ManagedPebbleConfig};

let endpoint = AcmeEndpoint::Pebble(ManagedPebbleConfig {
    pebble_bind: "127.0.0.1:1232".parse()?,
    pebble_executable: None, // Resolve `pebble` from PATH.
    working_directory: Some("./pebble-runtime".into()),
    state_directory: Some("./certificates/pebble-state".into()),
    ..ManagedPebbleConfig::default()
});
# Ok::<(), Box<dyn std::error::Error>>(())
```

When Pebble is selected, `pebble_bind` is required and must be loopback. `working_directory` is optional and sets only the spawned Pebble process's current directory; registration fails if it is not an existing directory. Generated configuration, keys, and certificates use resolved paths and remain independent of that working directory.

At registration, the manager:

1. resolves `pebble` from `PATH`, or uses `pebble_executable`;
2. generates the required local configuration and trust material;
3. starts Pebble and the scoped local validation adapter;
4. waits for readiness;
5. starts the normal ACME client against it;
6. supervises and stops its child processes on shutdown.

If the executable is unavailable, registration returns `PebbleExecutableNotFound`. The crate never downloads Pebble, installs packages, or silently starts Docker.

Managed validation maps concrete allowed hostnames only inside the Pebble test environment. It does not modify `/etc/hosts`, system DNS, or the public-IP policy used by Let's Encrypt.

Run the real managed-Pebble integration test with:

```console
cargo test --all-features managed_pebble_issues_and_serves_acme_certificate -- --ignored --nocapture
```

The test requires the `pebble` executable in `PATH`. It starts an isolated
Pebble process and DNS server, completes a real TLS-ALPN-01 order, verifies the
certificate was persisted in the ACME namespace, and uses it for an application
TLS handshake. All listeners use ephemeral loopback ports, so root privileges
and public DNS are unnecessary.

The automated lifecycle suite also covers local fallback when ACME is
unreachable, ACME-before-local selection, expired-certificate removal from both
memory and storage, aggressive renewal thresholds, forced local renewal,
per-domain/per-issuer exponential retry with a configured cap, failed-renewal
events, event replay, callback delivery and panic isolation, CA/key validation,
namespace coexistence, ClientHello TLS handling, and DNS transport parsing.
Renewal tests call the scheduler logic directly, so they verify hour-scale
policies deterministically without making the test suite sleep for hours.

Optional live DNS compatibility tests verify explicit resolvers over both
transports:

```console
cargo test --all-features explicit_cloudflare_udp_dns_resolves -- --ignored
cargo test --all-features explicit_google_tcp_dns_resolves -- --ignored
```

With `dns_servers: None`, ownership checks use the operating system resolver.

Pebble-issued certificates are stored under `ACME/` and selected before `AcmeLocalCA` certificates. Clients must trust Pebble's test root. Pebble certificates are test certificates and are never treated as Let's Encrypt production certificates.

To connect to a Pebble instance managed outside this process, configure it as a custom ACME endpoint with its directory URL, stable issuer ID, and TLS trust root.

### Custom ACME server

```rust,no_run
# use rustls_letsencrypt::AcmeEndpoint;
let endpoint = AcmeEndpoint::Custom {
    directory_url: "https://ca.internal.example/acme/directory".parse()?,
    issuer_id: "internal-ca".into(),
    tls_trust_roots: vec![],
};
```

Accounts and certificates are scoped to the resolved directory and issuer ID. Changing endpoints does not reuse credentials from another ACME server.

## Local fallback certificates

When local fallback is enabled, the store contains one persisted local CA named `AcmeLocalCA`:

```text
certificates/Local/CA.pem
certificates/Local/CA.key
```

If both files are absent, the manager generates them. If both exist, they are loaded as the local issuer, allowing an application or operator to supply its own local CA. If only one exists, or the pair is invalid, initialization fails rather than silently generating or replacing key material.

The manager validates that:

- `CA.pem` contains exactly one supported CA certificate;
- `CA.key` is a supported private key matching the certificate's public key;
- the certificate has `CA:TRUE` basic constraints;
- key usage permits certificate signing;
- the CA is currently within its validity period;
- its algorithm and key size satisfy configured policy.

The manager can issue a short-lived leaf locally while the configured ACME order is still running.

For a new hostname, local and ACME issuance run concurrently:

```text
first ClientHello
      │
      ├── LocalCaIssuer ── usually completes first ── handshake may continue
      │
      └── ACME issuer ─── completes later ─────────── preferred thereafter
```

The first connection subscribes to the shared issuance results before either task starts, so it cannot miss a fast local completion. Other simultaneous connections join the same per-domain/issuer task instead of creating duplicate certificates or ACME orders.

Install the `AcmeLocalCA` certificate in the trust store of clients that are allowed to accept local fallback. A client without this trust anchor will correctly reject the local certificate.

### Replacing the local CA

Local certificate records include the SHA-256 fingerprint of the CA that issued them. At startup, every record under `Local/` is cryptographically validated against the current `CA.pem`, including signature, issuer relationship, SAN, key match, validity, and recorded CA fingerprint.

When `CA.pem` and `CA.key` are replaced with a new valid matching pair:

1. the manager validates the complete candidate pair;
2. it atomically installs a new in-memory `LocalCaState`;
3. it clears local ArcSwap slots for leaves not issued by the new CA;
4. it removes those records from the active `Local/` store and moves them to a non-loadable quarantine/audit location;
5. subsequent handshakes issue or select leaves from the new CA;
6. ACME certificates under `ACME/` are unaffected.

Existing TLS connections keep their already selected certificate snapshot. New connections never receive a leaf known to belong to the previous local CA after the replacement is committed.

Use the transactional API when replacing the CA from inside the application:

```rust,no_run
# async fn replace() -> Result<(), Box<dyn std::error::Error>> {
rustls_letsencrypt::install_local_ca(
    std::fs::read("new-ca.pem")?,
    std::fs::read("new-ca.key")?,
).await?;
# Ok(())
# }
```

This validates first, writes temporary files with restrictive permissions, commits the pair, and invalidates old local leaves as one manager operation.

Direct filesystem replacement is also detected by a watched/reconciled local-CA generation check. Because two separate files cannot be replaced atomically as a pair, the watcher debounces changes and adopts a replacement only after `CA.pem` and `CA.key` form a valid matching pair. A partial or invalid replacement emits `LocalCaReloadFailed` and leaves the last valid in-memory CA and its certificates active; it does not erase working certificates. `reload_local_ca()` is available when deterministic reload timing is required.

TLS handshakes do not parse CA files. They read the current in-memory CA generation and local certificate slots. This keeps the hot path lock-free while ensuring that a committed mid-process CA replacement invalidates stale leaves before subsequent selection.

All local-CA actions are observable through both the configured console output and `subscribe_events()`:

```text
INFO  local CA loaded: fingerprint sha256:...
INFO  local CA replacement detected
INFO  local CA replaced: sha256:old... -> sha256:new...
WARN  local certificate quarantined: api.example.com was issued by sha256:old...
ERROR local CA reload failed: CA.key does not match CA.pem; retaining current CA
```

Corresponding structured events include `LocalCaGenerated`, `LocalCaLoaded`, `LocalCaReloadStarted`, `LocalCaReplaced`, `LocalCaReloadFailed`, and `LocalCertificateQuarantined`. They carry redacted fingerprints and safe validation details, never CA or leaf private-key bytes.

Disable fallback when every client requires a publicly trusted certificate:

```rust,no_run
# use rustls_letsencrypt::AlpnHandlerConfig;
let config = AlpnHandlerConfig {
    local_fallback_enabled: false,
    ..AlpnHandlerConfig::default()
};
```

## Renewal

Every stored ACME and local certificate is renewed through its own issuer.

- A certificate becomes due 15 days before expiry by default.
- The scheduler checks every hour by default.
- Missing or expired certificates trigger issuance immediately; they do not wait for the next scan.
- Due variants are submitted concurrently across domains and issuers.
- Each attempt has an independent absolute deadline from `issuance_attempt_timeout_secs`, defaulting to 60 seconds.
- Failed attempts back off per domain and issuer: 1h, 2h, 4h, 8h, 12h, then 12h.
- A successful issuer attempt resets only that issuer's backoff.
- A still-valid old certificate remains available during a failed renewal.
- An expired certificate is removed and is never served.
- Local issuance may restore service while ACME retries continue.

The `ACME/` and `Local/` variants renew independently and continue to coexist.

Retry suppression and counters are process-local in this release. The store
traits reserve issuer-specific retry metadata for a durable scheduler, but the
manager does not yet restore backoff counters after process restart; certificate
expiry timestamps remain authoritative and the first post-restart scan may retry
a due certificate immediately.

## Events and logging

Certificate management should not be a black box. Every material lifecycle transition is emitted as a structured `Event`.

```rust,no_run
use rustls_letsencrypt::subscribe_events;

# async fn observe() -> Result<(), Box<dyn std::error::Error>> {
let mut events = subscribe_events()?;

while let Some(event) = events.recv().await? {
    println!("{} {:?}", event.sequence, event.kind);
}
# Ok(())
# }
```

Subscriptions work in every output mode:

```rust
pub enum EventOutput {
    Subscribe, // No built-in console output.
    Stderr,    // Default.
    Stdout,
}
```

| Mode | Built-in output | Subscription API |
|---|---|---|
| `Subscribe` | none | available |
| `Stderr` | stderr | available |
| `Stdout` | stdout | available |

Example output:

```text
2026-07-25T10:00:00Z INFO renewal scan started: 6 certificate variants
2026-07-25T10:00:00Z INFO checked asd.com [lets-encrypt-production]: 152 days remaining (expires 2028-12-01)
2026-07-25T10:00:00Z INFO renewal due for pppp.com [lets-encrypt-production]: 14 days remaining
2026-07-25T10:00:00Z INFO renewing pppp.com [lets-encrypt-production], attempt 1
2026-07-25T10:00:08Z INFO renewal succeeded for pppp.com; new expiry 2028-12-01; elapsed 8.2s
```

An optional callback can observe startup events that occur before a subscriber is created:

```rust,no_run
# use rustls_letsencrypt::{AlpnHandlerConfig, Event};
# use std::sync::Arc;
let config = AlpnHandlerConfig::builder()
    .event_handler(Arc::new(|event: &Event| {
        // Forward quickly to your own logger, metrics system, or queue.
        eprintln!("{:?}", event.kind);
    }))
    .build()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```

The event bus is bounded and producers never wait on consumers. Slow subscribers receive a lag indication and can reconcile through `list_certificates()` or the manager status snapshot. Callback and console presentation run outside handshake, issuer, scheduler, and store-lock paths.

The bus is created before store and local-CA initialization and keeps a bounded startup history. A subscriber opened immediately after `register_alpn_handler` receives retained initialization events before live events, including local CA generation/load validation and stale-leaf quarantine. Each event's sequence number preserves the boundary between replayed and live delivery.

Events never contain private keys, account keys, challenge tokens, JWS bodies, or unrestricted ACME responses.

The optional `tracing` integration emits structured fields without installing a tracing subscriber or selecting a formatter.

## Reading certificates

Applications may retrieve certificate material through the process-scoped API:

```rust,no_run
# async fn read_cert() -> Result<(), Box<dyn std::error::Error>> {
let certificate = rustls_letsencrypt::get_certificate("broker.example.com").await?;

println!("issuer: {}", certificate.issuer_id());
println!("expires: {}", certificate.not_after());

let leaf_pem = certificate.leaf_pem();
let chain_pem = certificate.chain_pem();
let private_key = certificate.private_key_pem();
# Ok(())
# }
```

`get_certificate` follows the same valid-ACME-then-valid-local selection order as TLS. Issuer-specific retrieval is also available when an integration needs both variants.

Prefer the parsed rustls certified-key API when the consumer is in process; it avoids exposing private-key text. Private-key wrapper types do not implement `Debug` and are zeroized where possible.

The static API is process-local. Another process can open a compatible store read-only or consume an explicitly configured authenticated management service. This crate does not force Kafka or another external service to reload its TLS configuration.

## Kafka-style deployment

A Kafka integration can keep Kafka on 9092 while the certificate manager owns port 443:

```text
Internet/CA ── port 443 ── rustls-letsencrypt challenge handler

Kafka clients ── port 9092 ── managed TLS handler ── Kafka protocol
```

Alternatively, Kafka may read the atomically stored certificate files and use its own reload mechanism. The manager cannot share one TCP address with a separate process unless a fronting TCP router directs SNI and `acme-tls/1` traffic correctly.

## Certificate stores

Certificate management is independent of the storage backend. The process manager accepts an `Arc<dyn CertStore>`:

```rust,no_run
# use std::sync::Arc;
# use rustls_letsencrypt::{AlpnHandlerConfig, FolderCertStore};
let store = Arc::new(FolderCertStore::open("./certificates").await?);

let config = AlpnHandlerConfig::builder()
    .cert_store(store)
    .build()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```

`CertStore` covers:

- issuer-scoped certificate variants;
- ACME accounts;
- the local CA certificate and private key;
- renewal/backoff metadata;
- atomic certificate commits;
- compare-and-swap local CA replacement;
- removal and quarantine;
- optional change notifications and revision tracking.

Every store exposes two typed namespaces:

```rust,no_run
# use rustls_letsencrypt::CertStore;
# fn inspect(store: &dyn CertStore) {
let acme = store.acme();
let local = store.local();
# }
```

- `AcmeStoreNamespace` contains ACME accounts, ACME-issued certificate variants, issuer-specific retry state, and ACME quarantine records.
- `LocalStoreNamespace` contains `AcmeLocalCA`, locally issued leaves, local retry state, and local quarantine records.

This split is enforced by the API rather than inferred from filenames. ACME account operations do not exist on the local namespace, and local CA replacement does not exist on the ACME namespace. The ACME namespace may still contain several issuer IDs—for example Let's Encrypt production, staging, Pebble, or a custom CA—without mixing them with local certificates.

The manager never depends on JSON paths or filesystem behavior. This allows later backends such as:

- `SqliteCertStore`, using transactions and explicit ACME/Local tables;
- `RocksDbCertStore`, using atomic write batches and explicit ACME/Local column families or key prefixes;
- a remote or application-owned store;
- an in-memory test store.

All backends must provide atomic visibility: readers see either the previous complete record or the new complete record, never a partial certificate or CA. The ACME and Local namespaces remain separate regardless of physical representation.

Certificate records are loaded from the backend at manager startup. Local CA changes can be applied explicitly through `reload_local_ca`; arbitrary out-of-process certificate edits are not periodically imported in this release. Store reads do not occur on every TLS handshake; validated values are loaded into the same ArcSwap cache.

### Folder store

`FolderCertStore` is the default backend. The `cert_store_directory` convenience setting constructs it automatically:

```text
certificates/
├── accounts/
│   └── <directory-hash>.json
├── ACME/
│   └── <stable-domain-key>.json
├── Local/
│   ├── CA.pem
│   ├── CA.key
│   └── <stable-domain-key>.json
└── metadata.json
```

Each certificate record contains:

- schema version;
- normalized hostname and SANs;
- private key PEM;
- leaf certificate PEM;
- ordered intermediate/CA chain;
- `not_before` and `not_after`;
- issuer, endpoint, and provenance metadata;
- storage timestamp and SHA-256 fingerprint.

Writes use a same-directory temporary file, restrictive permissions, flush, and atomic rename. ACME and local variants never overwrite one another.

In-process mutation uses per-domain/issuer async guards and a short-lived folder writer mutex. TLS resolution never takes the storage mutex. The store mutex is not held during ACME requests or certificate generation.

One process owns the writable store. Read-only cross-process access is safe through atomic replacement; multiple independent writer processes are not supported unless cross-process locking is explicitly enabled.

The store contains private keys, including the powerful `Local/CA.key`. Protect and back it up accordingly. Newly created secret files use mode `0600` on Unix. Operators should also enforce restrictive parent-directory permissions and verify permissions on externally supplied CA files.

## ClientHello handling

The acceptor reads ClientHello under one absolute timeout using rustls's lazy acceptor. Rustls retains and replays the consumed ClientHello bytes into the eventual handshake and applies its parser limits.

Connections are rejected when ClientHello is malformed, incomplete, oversized, or too slow. SNI and the complete offered ALPN list are inspected before choosing the TLS configuration.

For a matching active ACME validation request, the server advertises only `acme-tls/1` and uses the temporary RFC 8737 challenge certificate. Unsolicited challenge connections are rejected and never create orders.

## Blocking API

Enable the `blocking` feature for synchronous applications:

```rust,no_run
use rustls_letsencrypt::blocking;
use rustls_letsencrypt::{AlpnHandlerConfig, EventOutput};
use std::net::TcpListener;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener_443 = TcpListener::bind("0.0.0.0:443")?;
    let config = AlpnHandlerConfig {
        events: EventOutput::Stderr,
        // allowed hosts, public IPs, store, and ACME endpoint...
        ..AlpnHandlerConfig::default()
    };

    let mut tls_443 = blocking::register_alpn_handler(listener_443, Some(config))?;

    let listener_9092 = TcpListener::bind("0.0.0.0:9092")?;
    let mut tls_9092 = blocking::register_handler(listener_9092)?;

    while let Some(connection) = tls_9092.accept()? {
        std::thread::spawn(move || {
            let mut stream = connection;
            // Use std::io::Read and std::io::Write on stream.
            let _ = &mut stream;
        });
    }

    drop(tls_443);
    Ok(())
}
```

The blocking facade uses one long-lived private Tokio runtime. It does not create a runtime per connection. Calling a blocking adapter from inside an async runtime returns `InvalidConfig` with a blocking-inside-async-runtime explanation.

The blocking end-to-end test uses the process-global manager and therefore runs
as an isolated ignored test:

```console
cargo test --all-features blocking_acceptor_completes_tls_and_supports_read_write -- --ignored --nocapture
```

Blocking event subscriptions provide `recv` and `try_recv`.

## Failure behavior

- Unknown hosts never trigger issuance.
- Missing SNI never triggers issuance.
- A DNS ownership mismatch never contacts the public ACME server.
- `register_handler` fails until the port-443 handler is ready.
- Issuance fails fast when no challenge handler is available.
- Disconnecting a waiting client does not cancel issuance.
- Concurrent requests join one task per domain and issuer.
- Failed renewal keeps the previous certificate until it expires.
- Expired certificates are removed and never served.
- Local fallback does not reset ACME retry state.
- Slow event consumers never delay certificate management.
- A failed managed Pebble startup leaves no partial global manager or child process.

## Security notes

- Use Let's Encrypt staging before production.
- Restrict `allowed_hosts`; never treat it as untrusted free-form regex.
- Keep `cert_store_directory` private. Files contain certificate and CA private keys.
- Install `AcmeLocalCA` only in clients intended to trust local fallback.
- Never install Pebble's test roots in a production or general-purpose trust store.
- Do not expose managed Pebble on a non-loopback address.
- Do not log certificate records, account keys, challenge tokens, or private keys.
- Public DNS must resolve to a configured public IP, and the CA must be able to reach public port 443.
- A reverse proxy or NAT may map to another local port, but the public ACME validation endpoint remains port 443.

## Feature flags

| Feature | Default | Purpose |
|---|---:|---|
| `tokio-runtime` | yes | Async listener and stream integration |
| `folder-store` | yes | JSON folder-backed storage |
| `tracing` | optional | Structured tracing adapter |
| `blocking` | no | Synchronous facade |
| `pebble` | no | Pebble client/test configuration |
| `managed-pebble` | no | Supervise a system Pebble executable |

## License

Licensed under either Apache-2.0 or MIT, at your option.