Struct rustls_ffi::client::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.

impl rustls_client_config_builder

#[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.

impl rustls_client_config_builder

#[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.