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. 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. Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config. This uses rustls safe default values for the cipher suites, key exchange groups and 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( cipher_suites: *const *const rustls_supported_ciphersuite, cipher_suites_len: size_t, 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. Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config. Specify cipher suites in preference order; the cipher_suites parameter must point to an array containing len pointers to rustls_supported_ciphersuite previously obtained from rustls_all_ciphersuites_get_entry(), or to a provided array, RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES. Set 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.

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

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.

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_use_roots( config_builder: *mut rustls_client_config_builder, roots: *const rustls_root_cert_store ) -> rustls_result

Use the trusted root certificates from the provided store.

This replaces any trusted roots already configured with copies from roots. This adds 1 to the refcount for roots. When you call rustls_client_config_free or rustls_client_config_builder_free, those will subtract 1 from the refcount for roots.

#[no_mangle]

pub extern "C" fn rustls_client_config_builder_load_roots_from_file( config_builder: *mut rustls_client_config_builder, filename: *const c_char ) -> rustls_result

Add trusted root certificates from the named file, which should contain PEM-formatted certificates.

#[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 ) -> *const rustls_client_config

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.