Struct SslCtxBuilder 

pub struct SslCtxBuilder<R: Role> { /* private fields */ }

Fluent typestate builder for SslCtx.

Use SslCtxBuilder::<Server>::new() or SslCtxBuilder::<Client>::new() to start the builder chain, configure via consuming methods, then call build() to obtain a fully-configured SslCtx.

Role separation

The type parameter R (either Server or Client) ensures that role-specific methods — e.g. certificate for servers, verify_peer for clients — are only available on the appropriate builder type.

Example — server

let ctx = SslCtxBuilder::<Server>::new()?
    .certificate(&cert)?
    .private_key(&key)?
    .check_private_key()?
    .build()?;

Example — client

let ctx = SslCtxBuilder::<Client>::new()?
    .default_ca_paths()?
    .verify_peer()
    .verify_hostname("example.com")?
    .alpn_protos_list(&["h2", "http/1.1"])?
    .build()?;

Implementations

impl SslCtxBuilder<Server>

pub fn new() -> Result<Self, ErrorStack>

Create a new server TLS context builder using TLS_server_method().

Errors

Returns Err if SSL_CTX_new fails (e.g. OOM).

impl SslCtxBuilder<Client>

pub fn new() -> Result<Self, ErrorStack>

Create a new client TLS context builder using TLS_client_method().

Errors

Returns Err if SSL_CTX_new fails (e.g. OOM).

impl<R: Role> SslCtxBuilder<R>

pub fn min_proto_version(self, ver: TlsVersion) -> Result<Self, ErrorStack>

Set the minimum acceptable TLS protocol version.

Uses SSL_CTX_ctrl with SSL_CTRL_SET_MIN_PROTO_VERSION (123).

Errors

pub fn max_proto_version(self, ver: TlsVersion) -> Result<Self, ErrorStack>

Set the maximum acceptable TLS protocol version.

Uses SSL_CTX_ctrl with SSL_CTRL_SET_MAX_PROTO_VERSION (124).

Errors

pub fn cipher_list(self, list: &CStr) -> Result<Self, ErrorStack>

Set the allowed cipher list for TLS 1.2 and below.

list uses OpenSSL cipher string syntax (e.g. c"HIGH:!aNULL:!MD5").

Errors

pub fn ciphersuites(self, list: &CStr) -> Result<Self, ErrorStack>

Set the allowed TLS 1.3 ciphersuites.

list uses OpenSSL ciphersuite syntax (e.g. c"TLS_AES_256_GCM_SHA384").

Errors

pub fn session_cache_mode(self, mode: i64) -> Self

Configure the session cache mode.

Pass 0 (SSL_SESS_CACHE_OFF) to disable caching.

pub fn alpn_protocols(self, protocols: &[u8]) -> Result<Self, ErrorStack>

Set the ALPN protocol list in OpenSSL wire format (length-prefixed bytes).

Example: b"\x02h2\x08http/1.1" advertises H2 then HTTP/1.1.

For a string-slice convenience, use alpn_protos_list.

Errors

Returns Err on failure.

Note

SSL_CTX_set_alpn_protos uses an inverted return convention: 0 means success, non-zero means failure (opposite to most OpenSSL functions).

pub fn alpn_protos_list(self, protos: &[&str]) -> Result<Self, ErrorStack>

Set the ALPN protocol list from a slice of protocol name strings.

Encodes protos into the wire-format length-prefixed byte string and calls SSL_CTX_set_alpn_protos. Protocols longer than 255 bytes are rejected with Err.

Errors

Returns Err if any protocol name exceeds 255 bytes or if the underlying OpenSSL call fails.

pub fn build(self) -> Result<SslCtx, ErrorStack>

Consume the builder and return a configured SslCtx.

Errors

Currently infallible, but returns Result for API consistency with potential future validation steps.

impl SslCtxBuilder<Server>

pub fn certificate(self, cert: &X509) -> Result<Self, ErrorStack>

Load a certificate that will be presented to clients during the handshake.

Wraps SSL_CTX_use_certificate.

Errors

pub fn add_chain_cert(self, cert: &X509) -> Result<Self, ErrorStack>

Append an intermediate CA certificate to the certificate chain.

Uses SSL_CTX_ctrl with SSL_CTRL_EXTRA_CHAIN_CERT (14). OpenSSL takes ownership of the X509*, so this method calls X509_up_ref first to keep cert alive after the call.

Errors

pub fn private_key(self, key: &Pkey<Private>) -> Result<Self, ErrorStack>

Load the private key corresponding to the certificate.

Wraps SSL_CTX_use_PrivateKey.

Errors

pub fn check_private_key(self) -> Result<Self, ErrorStack>

Verify that the loaded certificate and private key are consistent.

Errors

Returns Err if the key/certificate pair is invalid or not yet loaded.

pub fn verify_client(self, require: bool) -> Self

Request (or require) a client certificate during the TLS handshake.

When require is true, combines SSL_VERIFY_PEER with SSL_VERIFY_FAIL_IF_NO_PEER_CERT — the handshake fails if the client does not present a certificate. When false, only SSL_VERIFY_PEER is set — the client certificate is requested but not mandatory.

impl SslCtxBuilder<Client>

pub fn default_ca_paths(self) -> Result<Self, ErrorStack>

Load the system default CA certificate bundle for peer verification.

Wraps SSL_CTX_set_default_verify_paths.

Errors

pub fn ca_bundle_file(self, path: &Path) -> Result<Self, ErrorStack>

Load CA certificates from a PEM file at path.

Only the CA certificate file is loaded (not a directory).

Errors

Returns Err if the path contains non-UTF-8 bytes, contains a NUL byte, or if SSL_CTX_load_verify_locations fails.

pub fn ca_cert(self, cert: &X509) -> Result<Self, ErrorStack>

Add a single CA certificate to the context’s trust store.

Calls SSL_CTX_get_cert_store then X509_STORE_add_cert. Does not transfer ownership — cert remains valid after this call.

Errors

pub fn verify_peer(self) -> Self

Enable verification of the server’s certificate.

Sets SSL_VERIFY_PEER. Call after loading CA certificates so that OpenSSL has a trust anchor.

pub fn verify_hostname(self, hostname: &str) -> Result<Self, ErrorStack>

Set the expected server hostname for automatic certificate hostname verification on all connections derived from this context.

Uses SSL_CTX_get0_param to get the context-level X509_VERIFY_PARAM and then X509_VERIFY_PARAM_set1_host to set the hostname. All Ssl connections created from this SslCtx inherit the hostname check.

For per-connection overrides (e.g. one SslCtx shared across connections to different servers), use Ssl::set_verify_hostname instead.

Errors

Returns Err if hostname contains a NUL byte or if X509_VERIFY_PARAM_set1_host fails.

pub fn verify_hostname_flags( self, flags: HostnameFlags, ) -> Result<Self, ErrorStack>

Set hostname verification flags on this context.

Applied to every connection derived from this context. Typically called after verify_hostname to refine how wildcard certificates are matched.

Uses SSL_CTX_get0_param to obtain the context-level X509_VERIFY_PARAM, then calls X509_VERIFY_PARAM_set_hostflags.

Errors

Returns Err if SSL_CTX_get0_param returns a null pointer (should not happen for a freshly created context).

Trait Implementations

impl<R: Role> Drop for SslCtxBuilder<R>

fn drop(&mut self)

Executes the destructor for this type.

impl<R: Role> Send for SslCtxBuilder<R>