Struct rustls_client_config_builder

pub struct rustls_client_config_builder { /* private fields */ }

A client config being constructed.

A builder can be modified by, e.g. rustls_client_config_builder_load_roots_from_file. Once you’re done configuring settings, call rustls_client_config_builder_build to turn it into a *rustls_client_config.

Alternatively, if an error occurs or, you don’t wish to build a config, call rustls_client_config_builder_free to free the builder directly.

This object is not safe for concurrent mutation. Under the hood, it corresponds to a Box<ClientConfig>. https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html

Implementations

impl rustls_client_config_builder

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_new() -> *mut rustls_client_config_builder

Create a rustls_client_config_builder using the process default crypto provider.

Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config.

Alternatively, if an error occurs or, you don’t wish to build a config, call rustls_client_config_builder_free to free the builder directly.

This uses the process default provider’s values for the cipher suites and key exchange groups, as well as safe defaults for protocol versions.

This starts out with no trusted roots. Caller must add roots with rustls_client_config_builder_load_roots_from_file or provide a custom verifier.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_new_custom( provider: *const rustls_crypto_provider, tls_versions: *const u16, tls_versions_len: size_t, builder_out: *mut *mut rustls_client_config_builder, ) -> rustls_result

Create a rustls_client_config_builder using the specified crypto provider.

Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config.

Alternatively, if an error occurs or, you don’t wish to build a config, call rustls_client_config_builder_free to free the builder directly.

tls_version sets the TLS protocol versions to use when negotiating a TLS session. tls_version is the version of the protocol, as defined in rfc8446, ch. 4.2.1 and end of ch. 5.1. Some values are defined in rustls_tls_version for convenience, and the arrays RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly.

tls_versions will only be used during the call and the application retains ownership. tls_versions_len is the number of consecutive uint16_t pointed to by tls_versions.

Ciphersuites are configured separately via the crypto provider. See rustls_crypto_provider_builder_set_cipher_suites for more information.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_dangerous_set_certificate_verifier( config_builder: *mut rustls_client_config_builder, callback: rustls_verify_server_cert_callback, ) -> rustls_result

Set a custom server certificate verifier using the builder crypto provider. Returns rustls_result::NoDefaultCryptoProvider if no process default crypto provider has been set, and the builder was not constructed with an explicit provider choice.

The callback must not capture any of the pointers in its rustls_verify_server_cert_params. If userdata has been set with rustls_connection_set_userdata, it will be passed to the callback. Otherwise the userdata param passed to the callback will be NULL.

The callback must be safe to call on any thread at any time, including multiple concurrent calls. So, for instance, if the callback mutates userdata (or other shared state), it must use synchronization primitives to make such mutation safe.

The callback receives certificate chain information as raw bytes. Currently this library offers no functions to parse the certificates, so you’ll need to bring your own certificate parsing library if you need to parse them.

If the custom verifier accepts the certificate, it should return RUSTLS_RESULT_OK. Otherwise, it may return any other rustls_result error. Feel free to use an appropriate error from the RUSTLS_RESULT_CERT_* section.

https://docs.rs/rustls/latest/rustls/client/struct.DangerousClientConfig.html#method.set_certificate_verifier

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_server_verifier( builder: *mut rustls_client_config_builder, verifier: *const rustls_server_cert_verifier, )

Configure the server certificate verifier.

This increases the reference count of verifier and does not take ownership.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_alpn_protocols( builder: *mut rustls_client_config_builder, protocols: *const rustls_slice_bytes<'_>, len: size_t, ) -> rustls_result

Set the ALPN protocol list to the given protocols.

protocols must point to a buffer of rustls_slice_bytes (built by the caller) with len elements.

Each element of the buffer must be a rustls_slice_bytes whose data field points to a single ALPN protocol ID.

Standard ALPN protocol IDs are defined at https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids.

This function makes a copy of the data in protocols and does not retain any pointers, so the caller can free the pointed-to memory after calling.

https://docs.rs/rustls/latest/rustls/client/struct.ClientConfig.html#structfield.alpn_protocols

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_enable_sni( config: *mut rustls_client_config_builder, enable: bool, )

Enable or disable SNI. https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.enable_sni

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_certified_key( builder: *mut rustls_client_config_builder, certified_keys: *const *const rustls_certified_key, certified_keys_len: size_t, ) -> rustls_result

Provide the configuration a list of certificates where the connection will select the first one that is compatible with the server’s signature verification capabilities.

Clients that want to support both ECDSA and RSA certificates will want the ECSDA to go first in the list.

The built configuration will keep a reference to all certified keys provided. The client may rustls_certified_key_free() afterwards without the configuration losing them. The same certified key may also be used in multiple configs.

EXPERIMENTAL: installing a client authentication callback will replace any configured certified keys and vice versa.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_key_log_file( builder: *mut rustls_client_config_builder, ) -> rustls_result

Log key material to the file specified by the SSLKEYLOGFILE environment variable.

The key material will be logged in the NSS key log format, https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format and is compatible with tools like Wireshark.

Secrets logged in this manner are extremely sensitive and can break the security of past, present and future sessions.

For more control over which secrets are logged, or to customize the format, prefer rustls_client_config_builder_set_key_log.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_set_key_log( builder: *mut rustls_client_config_builder, log_cb: rustls_keylog_log_callback, will_log_cb: rustls_keylog_will_log_callback, ) -> rustls_result

Provide callbacks to manage logging key material.

The log_cb argument is mandatory and must not be NULL or a NullParameter error is returned. The log_cb will be invoked with a client_random to identify the relevant session, a label to identify the purpose of the secret, and the secret itself. See the Rustls documentation of the KeyLog trait for more information on possible labels: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log

The will_log_cb may be NULL, in which case all key material will be provided to the log_cb. By providing a custom will_log_cb you may return 0 for labels you don’t wish to log, and non-zero for labels you do wish to log as a performance optimization.

Both callbacks must be thread-safe. Arguments provided to the callback live only for as long as the callback is executing and are not valid after the callback returns. The callbacks must not retain references to the provided data.

Secrets provided to the log_cb are extremely sensitive and can break the security of past, present and future sessions.

See also rustls_client_config_builder_set_key_log_file for a simpler way to log to a file specified by the SSLKEYLOGFILE environment variable.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_enable_ech( builder: *mut rustls_client_config_builder, ech_config_list_bytes: *const u8, ech_config_list_bytes_size: size_t, hpke: *const rustls_hpke, ) -> rustls_result

Configure the client for Encrypted Client Hello (ECH).

This requires providing a TLS encoded list of ECH configurations that should have been retrieved from the DNS HTTPS record for the domain you intend to connect to. This should be done using DNS-over-HTTPS to avoid leaking the domain name you are connecting to ahead of the TLS handshake.

At least one of the ECH configurations must be compatible with the provided rustls_hpke instance. See rustls_supported_hpke() for more information.

Calling this function will replace any existing ECH configuration set by previous calls to rustls_client_config_builder_enable_ech() or rustls_client_config_builder_enable_ech_grease().

The provided ech_config_list_bytes and rustls_hpke must not be NULL or an error will be returned. The caller maintains ownership of the ECH config list TLS bytes and rustls_hpke instance. This function does not retain any reference to ech_config_list_bytes.

A RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS error is returned if the builder’s TLS versions have been customized via rustls_client_config_builder_new_custom() and the customization isn’t “only TLS 1.3”. ECH may only be used with TLS 1.3.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_enable_ech_grease( builder: *mut rustls_client_config_builder, hpke: *const rustls_hpke, ) -> rustls_result

Configure the client for GREASE Encrypted Client Hello (ECH).

This is a feature to prevent ossification of the TLS handshake by acting as though ECH were configured for an imaginary ECH config generated with one of the rustls_hpke supported suites, chosen at random.

The provided rustls_client_config_builder and rustls_hpke must not be NULL or an error will be returned. The caller maintains ownership of both the rustls_client_config_builder and the rustls_hpke instance.

Calling this function will replace any existing ECH configuration set by previous calls to rustls_client_config_builder_enable_ech() or rustls_client_config_builder_enable_ech_grease().

A RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS error is returned if the builder’s TLS versions have been customized via rustls_client_config_builder_new_custom() and the customization isn’t “only TLS 1.3”. ECH may only be used with TLS 1.3.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_build( builder: *mut rustls_client_config_builder, config_out: *mut *const rustls_client_config, ) -> rustls_result

Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config (read-only).

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_free( config: *mut rustls_client_config_builder, )

“Free” a client_config_builder without building it into a rustls_client_config.

Normally builders are built into rustls_client_config via rustls_client_config_builder_build and may not be free’d or otherwise used afterwards.

Use free only when the building of a config has to be aborted before a config was created.