tls.rs

Overview

This file provides functionality to create and configure a TLS-enabled client configuration for network transport. It primarily exposes a single function that builds a wtransport::ClientConfig instance using TLS settings derived from client credentials and optional ALPN (Application-Layer Protocol Negotiation) preferences. The TLS configuration is assembled by delegating to an internal helper function, allowing flexible setup for both debug and production environments.

The main responsibility of this file is to abstract the process of configuring a secure client transport layer, integrating TLS parameters seamlessly with the underlying transport client configuration.

Functions

create_client_config

pub fn create_client_config(
    is_debug: bool,
    credential: &NetCredential,
    alpn_preferred: &[&str],
) -> Result<wtransport::ClientConfig, anyhow::Error>

Description

Constructs a client configuration for secure network transport using TLS. It incorporates TLS settings based on provided credentials and ALPN protocol preferences. The function supports a debug mode toggle which may influence TLS parameters (e.g., certificate verification looseness).

It internally calls client_tls_config to generate the TLS configuration, then uses that to build a wtransport::ClientConfig with default binding and custom TLS applied.

Parameters

• is_debug (bool): A flag indicating whether the client is running in debug mode. This may affect TLS validation behavior.

• credential (&NetCredential): A reference to a network credential object that contains necessary certificates or keys for TLS setup.

• alpn_preferred (&[&str]): A slice of string references specifying preferred ALPN protocols for the TLS handshake.

Returns

• Result<wtransport::ClientConfig, anyhow::Error>: On success, returns a configured wtransport::ClientConfig instance ready for use in client connections. On failure, returns an error wrapped in the anyhow::Error type.

Usage Example

let credential = NetCredential::load_from_file("client_cert.pem")?;
let alpn_protocols = vec!["h2", "http/1.1"];
let client_config = create_client_config(false, &credential, &alpn_protocols)?;

Implementation Details

• Delegates the creation of the TLS configuration to client_tls_config, passing along debug flags, credentials, and ALPN preferences.

• Constructs a wtransport::ClientConfig using a builder pattern:

  • Calls with_bind_default() to set default binding options.

  • Applies the custom TLS configuration via with_custom_tls(tls_config).

  • Finalizes the build with build().

• Uses Rust's Result type for error propagation, leveraging the anyhow crate for error handling.

Interactions with Other System Components

• client_tls_config function (in crate::tls): This function is responsible for producing the underlying TLS configuration. It is a critical collaborator and encapsulates the TLS setup logic, including certificate validation and protocol negotiation.

• NetCredential struct: Represents client credentials such as certificates or private keys needed for TLS. This file relies on this struct to obtain authentication material.

• wtransport::ClientConfig struct: Represents the client-side transport configuration that supports custom TLS settings. This file builds and returns instances of this struct configured for secure communication.

The file acts as a bridge between raw TLS configuration and the client transport layer setup, abstracting complexity and providing a simplified API for client configuration.

Diagram: Function Workflow

flowchart TD
A[create_client_config] --> B[client_tls_config]
B -->|Returns TLS config| C[wtransport::ClientConfig Builder]
C --> D["with_bind_default()"]
D --> E["with_custom_tls(tls_config)"]
E --> F["build()"]
F --> G[Result<ClientConfig, Error>]

This diagram illustrates the flow within the create_client_config function, showing how it calls client_tls_config, then uses the returned TLS config to build and return a client configuration object.