Struct rustls_ffi::server::rustls_server_config_builder

pub struct rustls_server_config_builder { /* fields omitted */ }

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. This object is not safe for concurrent mutation. https://docs.rs/rustls/0.20.0/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. Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config. This uses rustls safe default values for the cipher suites, key exchange groups and protocol versions.

#[no_mangle]

pub extern "C" fn rustls_server_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_server_config_builder
) -> rustls_result

Create a rustls_server_config_builder. Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_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(). 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.

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.

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_client_verifier(
    config_builder: *mut rustls_server_config_builder,
    verifier: *const rustls_client_cert_verifier
)

Create a rustls_server_config_builder for TLS sessions that require valid client certificates. The passed rustls_client_cert_verifier may be used in several builders. If input is NULL, this will return NULL. For memory lifetime, see rustls_server_config_builder_new.

#[no_mangle]

pub extern "C" fn rustls_server_config_builder_set_client_verifier_optional(
    config_builder: *mut rustls_server_config_builder,
    verifier: *const rustls_client_cert_verifier_optional
)

Create a rustls_server_config_builder for TLS sessions that accept valid client certificates, but do not require them. The passed rustls_client_cert_verifier_optional may be used in several builders. If input is NULL, this will return NULL. For memory lifetime, see rustls_server_config_builder_new.

#[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/0.20.0/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/0.20.0/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 session 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
) -> *const rustls_server_config

Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config (read-only).

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 session created from this config is seeing 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 crustls 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 sessions 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.