Struct rustls_ffi::server::rustls_server_config_builder

pub struct rustls_server_config_builder { /* private fields */ }

A server config being constructed.

A builder can be modified by, e.g. rustls_server_config_builder_load_native_roots. Once you’re done configuring settings, call rustls_server_config_builder_build to turn it into a *const rustls_server_config.

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

This object is not safe for concurrent mutation. https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html

Implementations

impl rustls_server_config_builder

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_new() -> *mut rustls_server_config_builder

Create a rustls_server_config_builder using the process default crypto provider.

Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config.

Alternatively, if an error occurs or, you don’t wish to build a config, call rustls_server_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.

#[no_mangle]

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

Create a rustls_server_config_builder using the specified crypto provider.

Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config.

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

tls_versions set the TLS protocol versions to use when negotiating a TLS session.

tls_versions 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.

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_server_config_builder_set_client_verifier( builder: *mut rustls_server_config_builder, verifier: *const rustls_client_cert_verifier, )

Create a rustls_server_config_builder for TLS sessions that may verify client certificates.

This increases the refcount of verifier and doesn’t take ownership.

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_free( config: *mut rustls_server_config_builder, )

“Free” a server_config_builder without building it into a rustls_server_config.

Normally builders are built into rustls_server_configs via rustls_server_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.

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_ignore_client_order( builder: *mut rustls_server_config_builder, ignore: bool, ) -> rustls_result

With ignore != 0, the server will ignore the client ordering of cipher suites, aka preference, during handshake and respect its own ordering as configured. https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html#structfield.ignore_client_order

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_alpn_protocols( builder: *mut rustls_server_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 point to a slice of bytes that contains a single ALPN protocol from 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/server/struct.ServerConfig.html#structfield.alpn_protocols

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_certified_keys( builder: *mut rustls_server_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 client’s signature verification capabilities.

Servers 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_hello callback will replace any configured certified keys and vice versa.

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_build( builder: *mut rustls_server_config_builder, config_out: *mut *const rustls_server_config, ) -> rustls_result

Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config (read-only). The constructed rustls_server_config will be written to the config_out pointer when this function returns rustls_result::Ok.

This function may return an error if no process default crypto provider has been set and the builder was constructed using rustls_server_config_builder_new, or if no certificate resolver was set.

impl rustls_server_config_builder

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_hello_callback( builder: *mut rustls_server_config_builder, callback: rustls_client_hello_callback, ) -> rustls_result

Register a callback to be invoked when a connection created from this config sees a TLS ClientHello message. 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.

Any existing ResolvesServerCert implementation currently installed in the rustls_server_config will be replaced. This also means registering twice will overwrite the first registration. It is not permitted to pass a NULL value for callback.

EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as the rustls library is re-evaluating their current approach to client hello handling. Installing a client_hello callback will replace any configured certified keys and vice versa. Same holds true for the set_certified_keys variant.

impl rustls_server_config_builder

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_persistence( builder: *mut rustls_server_config_builder, get_cb: rustls_session_store_get_callback, put_cb: rustls_session_store_put_callback, ) -> rustls_result

Register callbacks for persistence of TLS session IDs and secrets. Both keys and values are highly sensitive data, containing enough information to break the security of the connections involved.

If userdata has been set with rustls_connection_set_userdata, it will be passed to the callbacks. Otherwise the userdata param passed to the callbacks will be NULL.