bookclerk_tls

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

The one TLS backend for the Bookclerk hosts.

Every first-party TLS client and server in the hosts uses rustls with the aws-lc-rs crypto provider, which also brings the hybrid post-quantum key exchange (X25519MLKEM768) rustls prefers. This crate is the single place that names the provider, so no crate falls back to another one (ring or OpenSSL) and the build compiles one crypto library.

  • crypto_provider hands the provider to code that builds a rustls ClientConfig or ServerConfig itself (the node API listener and client).
  • ureq is the ureq crate as host crates use it: use bookclerk_tls::ureq; and then ureq::get(url) as usual. Its request functions send through http_agent instead of ureq's own default agent, which has no provider (the workspace builds ureq with rustls-no-provider) and would panic on its first HTTPS request. Host crates depend on this crate rather than on ureq directly, so that agent is out of reach.
  • http_agent is the shared blocking HTTP client behind those functions.
  • ureq_tls_config is the same TLS setting for crates that build a custom ureq agent.

See docs/internals/tls.md.

Item Kind Summary
crypto_provider function The rustls crypto provider every host TLS connection uses: aws-lc-rs with its default cipher suites and key exchange groups.
ureq_tls_config function ureq TLS settings that use crypto_provider and Mozilla's root certificates (webpki-roots), as ureq's default agent does.
http_agent function The shared blocking HTTP client for the hosts.

Modules

  • ureq: The ureq crate with the hosts' TLS: everything ureq exports, except that the request functions (get, post, …), run and agent use http_agent.

Functions

crypto_provider

pub fn crypto_provider() -> Arc<CryptoProvider>

The rustls crypto provider every host TLS connection uses: aws-lc-rs with its default cipher suites and key exchange groups.

Returns

A shared handle to the provider. Every call returns the same instance, so rustls and ureq can pool configurations built from it.

ureq_tls_config

pub fn ureq_tls_config() -> TlsConfig

ureq TLS settings that use crypto_provider and Mozilla's root certificates (webpki-roots), as ureq's default agent does.

Returns

A TLS configuration to pass to ureq::config::ConfigBuilder::tls_config.

http_agent

pub fn http_agent() -> Agent

The shared blocking HTTP client for the hosts.

It has ureq's default settings apart from TLS, which uses ureq_tls_config. Callers that need other settings (timeouts, status handling) set them per request, or build their own agent with ureq_tls_config.

Returns

A clone of one process-wide agent; clones share its connection pool.

Generated from crates/bookclerk-tls at main · View as Markdown