From d3a73d649e42fb7786a9735f0430859cf786a702 Mon Sep 17 00:00:00 2001 From: Tom Stejskal Date: Sun, 30 Mar 2025 21:09:51 +0200 Subject: [PATCH 1/4] Added function rustls_connection_last_error_msg --- librustls/src/connection.rs | 111 ++- librustls/src/rustls.h | 1574 ++++++++++++++++++++--------------- 2 files changed, 992 insertions(+), 693 deletions(-) diff --git a/librustls/src/connection.rs b/librustls/src/connection.rs index 55ff4f27..39d9f6d6 100644 --- a/librustls/src/connection.rs +++ b/librustls/src/connection.rs @@ -1,3 +1,4 @@ +use std::cmp::min; use std::io::{ErrorKind, Read, Write}; use std::{ffi::c_void, ptr::null}; use std::{ptr::null_mut, slice}; @@ -27,6 +28,7 @@ pub(crate) struct Connection { conn: rustls::Connection, userdata: *mut c_void, log_callback: rustls_log_callback, + last_error_msg: Option, } impl Connection { @@ -35,6 +37,7 @@ impl Connection { conn: conn.into(), userdata: null_mut(), log_callback: None, + last_error_msg: None, } } @@ -43,6 +46,7 @@ impl Connection { conn: conn.into(), userdata: null_mut(), log_callback: None, + last_error_msg: None, } } @@ -142,6 +146,7 @@ impl rustls_connection { ffi_panic_boundary! { let conn = try_mut_from_ptr!(conn); if out_n.is_null() { + conn.last_error_msg = Some("EINVAL".to_owned()); return rustls_io_result(EINVAL); } let callback = try_callback!(callback); @@ -149,7 +154,10 @@ impl rustls_connection { let mut reader = CallbackReader { callback, userdata }; let n_read = match conn.read_tls(&mut reader) { Ok(n) => n, - Err(e) => return rustls_io_result(e.raw_os_error().unwrap_or(EIO)), + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_io_result(e.raw_os_error().unwrap_or(EIO)); + } }; unsafe { *out_n = n_read; @@ -179,6 +187,7 @@ impl rustls_connection { ffi_panic_boundary! { let conn = try_mut_from_ptr!(conn); if out_n.is_null() { + conn.last_error_msg = Some("EINVAL".to_owned()); return rustls_io_result(EINVAL); } let callback = try_callback!(callback); @@ -186,7 +195,10 @@ impl rustls_connection { let mut writer = CallbackWriter { callback, userdata }; let n_written = match conn.write_tls(&mut writer) { Ok(n) => n, - Err(e) => return rustls_io_result(e.raw_os_error().unwrap_or(EIO)), + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_io_result(e.raw_os_error().unwrap_or(EIO)); + } }; unsafe { *out_n = n_written; @@ -216,6 +228,7 @@ impl rustls_connection { ffi_panic_boundary! { let conn = try_mut_from_ptr!(conn); if out_n.is_null() { + conn.last_error_msg = Some("EINVAL".to_owned()); return rustls_io_result(EINVAL); } let callback = try_callback!(callback); @@ -223,7 +236,10 @@ impl rustls_connection { let mut writer = VectoredCallbackWriter { callback, userdata }; let n_written = match conn.write_tls(&mut writer) { Ok(n) => n, - Err(e) => return rustls_io_result(e.raw_os_error().unwrap_or(EIO)), + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_io_result(e.raw_os_error().unwrap_or(EIO)); + } }; unsafe { *out_n = n_written; @@ -245,15 +261,24 @@ impl rustls_connection { let conn = try_mut_from_ptr!(conn); let guard = match userdata_push(conn.userdata, conn.log_callback) { Ok(g) => g, - Err(_) => return rustls_result::Panic, + Err(e) => { + conn.last_error_msg = Some(format!("{:?}", e)); + return rustls_result::Panic; + } }; let result = match conn.process_new_packets() { Ok(_) => rustls_result::Ok, - Err(e) => map_error(e), + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + map_error(e) + } }; match guard.try_drop() { Ok(()) => result, - Err(_) => rustls_result::Panic, + Err(e) => { + conn.last_error_msg = Some(format!("{:?}", e)); + rustls_result::Panic + } } } } @@ -337,7 +362,11 @@ impl rustls_connection { ffi_panic_boundary! { match try_mut_from_ptr!(conn).refresh_traffic_keys() { Ok(_) => rustls_result::Ok, - Err(e) => map_error(e), + Err(e) => { + let conn = try_mut_from_ptr!(conn); + conn.last_error_msg = Some(format!("{}", e)); + map_error(e) + } } } } @@ -508,11 +537,16 @@ impl rustls_connection { let conn = try_mut_from_ptr!(conn); let write_buf = try_slice!(buf, count); if out_n.is_null() { - return rustls_result::NullParameter; + let res = rustls_result::NullParameter; + conn.last_error_msg = Some(format!("{:?}", res)); + return res; } let n_written = match conn.writer().write(write_buf) { Ok(n) => n, - Err(_) => return rustls_result::Io, + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_result::Io + } }; unsafe { *out_n = n_written; @@ -543,9 +577,13 @@ impl rustls_connection { ffi_panic_boundary! { let conn = try_mut_from_ptr!(conn); if buf.is_null() { - return rustls_result::NullParameter; + let res = rustls_result::NullParameter; + conn.last_error_msg = Some(format!("{:?}", res)); + return res; } if out_n.is_null() { + let res = rustls_result::NullParameter; + conn.last_error_msg = Some(format!("{:?}", res)); return rustls_result::NullParameter; } @@ -556,12 +594,17 @@ impl rustls_connection { let n_read = match conn.reader().read(read_buf) { Ok(n) => n, Err(e) if e.kind() == ErrorKind::UnexpectedEof => { + conn.last_error_msg = Some(format!("{}", e)); return rustls_result::UnexpectedEof; } Err(e) if e.kind() == ErrorKind::WouldBlock => { + conn.last_error_msg = Some(format!("{}", e)); return rustls_result::PlaintextEmpty; } - Err(_) => return rustls_result::Io, + Err(e) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_result::Io; + } }; unsafe { *out_n = n_read; @@ -594,19 +637,26 @@ impl rustls_connection { ffi_panic_boundary! { let conn = try_mut_from_ptr!(conn); if buf.is_null() || out_n.is_null() { - return rustls_result::NullParameter; + let res = rustls_result::NullParameter; + conn.last_error_msg = Some(format!("{:?}", res)); + return res; } let mut read_buf: std::io::BorrowedBuf<'_> = try_slice_mut!(buf, count).into(); let n_read = match conn.reader().read_buf(read_buf.unfilled()) { Ok(()) => read_buf.filled().len(), Err(e) if e.kind() == ErrorKind::UnexpectedEof => { + conn.last_error_msg = Some(format!("{}", e)); return rustls_result::UnexpectedEof; } Err(e) if e.kind() == ErrorKind::WouldBlock => { + conn.last_error_msg = Some(format!("{}", e)); return rustls_result::PlaintextEmpty; } - Err(_) => return rustls_result::Io, + Err(_) => { + conn.last_error_msg = Some(format!("{}", e)); + return rustls_result::Io; + } }; unsafe { *out_n = n_read; @@ -632,6 +682,41 @@ impl rustls_connection { } } + /// Read up to `count` bytes of the last error message into `buf`. + /// If there is any error message, store the number of bytes in *out_n and + /// returns `true`. If there is no last error message, stores 0 in *out_n + /// and returns `false`. + #[no_mangle] + pub extern "C" fn rustls_connection_last_error_msg( + conn: &mut rustls_connection, + buf: *mut u8, + count: size_t, + out_n: *mut size_t, + ) -> bool { + ffi_panic_boundary! { + let conn = try_ref_from_ptr!(conn); + match &conn.last_error_msg { + Some(msg) => { + let n = min(msg.len(), count); + if n > 0 { + let buf = try_slice_mut!(buf, n); + buf.copy_from_slice(msg.as_bytes()); + } + unsafe { + *out_n = n; + } + true + } + None => { + unsafe { + *out_n = 0; + } + false + } + } + } + } + /// Free a rustls_connection. Calling with NULL is fine. /// Must not be called twice with the same value. #[no_mangle] diff --git a/librustls/src/rustls.h b/librustls/src/rustls.h index 34dd0f28..0571e9d3 100644 --- a/librustls/src/rustls.h +++ b/librustls/src/rustls.h @@ -10,7 +10,8 @@ /** * Describes which sort of handshake happened. */ -typedef enum rustls_handshake_kind { +typedef enum rustls_handshake_kind +{ /** * The type of handshake could not be determined. * @@ -21,15 +22,16 @@ typedef enum rustls_handshake_kind { * A full TLS handshake. * * This is the typical TLS connection initiation process when resumption is - * not yet unavailable, and the initial client hello was accepted by the server. + * not yet unavailable, and the initial client hello was accepted by the + * server. */ RUSTLS_HANDSHAKE_KIND_FULL = 1, /** * A full TLS handshake, with an extra round-trip for a hello retry request. * - * The server can respond with a hello retry request (HRR) if the initial client - * hello is unacceptable for several reasons, the most likely if no supported key - * shares were offered by the client. + * The server can respond with a hello retry request (HRR) if the initial + * client hello is unacceptable for several reasons, the most likely if no + * supported key shares were offered by the client. */ RUSTLS_HANDSHAKE_KIND_FULL_WITH_HELLO_RETRY_REQUEST = 2, /** @@ -45,7 +47,8 @@ typedef enum rustls_handshake_kind { /** * Numeric error codes returned from rustls-ffi API functions. */ -enum rustls_result { +enum rustls_result +{ RUSTLS_RESULT_OK = 7000, RUSTLS_RESULT_IO = 7001, RUSTLS_RESULT_NULL_PARAMETER = 7002, @@ -175,7 +178,8 @@ typedef uint32_t rustls_result; /** * Definitions of known TLS protocol versions. */ -typedef enum rustls_tls_version { +typedef enum rustls_tls_version +{ RUSTLS_TLS_VERSION_UNKNOWN = 0, RUSTLS_TLS_VERSION_SSLV2 = 512, RUSTLS_TLS_VERSION_SSLV3 = 768, @@ -210,8 +214,9 @@ typedef struct rustls_accepted_alert rustls_accepted_alert; * * In particular, if a server wants to do some potentially expensive work * to load a certificate for a given hostname, rustls_acceptor allows doing - * that asynchronously, as opposed to rustls_server_config_builder_set_hello_callback(), - * which doesn't work well for asynchronous I/O. + * that asynchronously, as opposed to + * rustls_server_config_builder_set_hello_callback(), which doesn't work well + * for asynchronous I/O. * * The general flow is: * - rustls_acceptor_new() @@ -246,8 +251,9 @@ typedef struct rustls_certificate rustls_certificate; typedef struct rustls_certified_key rustls_certified_key; /** - * A built client certificate verifier that can be provided to a `rustls_server_config_builder` - * with `rustls_server_config_builder_set_client_verifier`. + * A built client certificate verifier that can be provided to a + * `rustls_server_config_builder` with + * `rustls_server_config_builder_set_client_verifier`. */ typedef struct rustls_client_cert_verifier rustls_client_cert_verifier; @@ -262,9 +268,10 @@ typedef struct rustls_client_config rustls_client_config; /** * 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. + * 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. @@ -293,8 +300,8 @@ typedef struct rustls_crypto_provider_builder rustls_crypto_provider_builder; /** * A collection of supported Hybrid Public Key Encryption (HPKE) suites. * - * `rustls_hpke` can be provided to `rustls_client_config_builder_enable_ech` and - * `rustls_client_config_builder_enable_ech_grease()` to customize a + * `rustls_hpke` can be provided to `rustls_client_config_builder_enable_ech` + * and `rustls_client_config_builder_enable_ech_grease()` to customize a * `rustls_client_config_builder` to use Encrypted Client Hello (ECH). */ typedef struct rustls_hpke rustls_hpke; @@ -318,15 +325,16 @@ typedef struct rustls_root_cert_store rustls_root_cert_store; * A `rustls_root_cert_store` being constructed. * * A builder can be modified by adding trust anchor root certificates with - * `rustls_root_cert_store_builder_add_pem`. Once you're done adding root certificates, - * call `rustls_root_cert_store_builder_build` to turn it into a `rustls_root_cert_store`. - * This object is not safe for concurrent mutation. + * `rustls_root_cert_store_builder_add_pem`. Once you're done adding root + * certificates, call `rustls_root_cert_store_builder_build` to turn it into a + * `rustls_root_cert_store`. This object is not safe for concurrent mutation. */ typedef struct rustls_root_cert_store_builder rustls_root_cert_store_builder; /** - * A built server certificate verifier that can be provided to a `rustls_client_config_builder` - * with `rustls_client_config_builder_set_server_verifier`. + * A built server certificate verifier that can be provided to a + * `rustls_client_config_builder` with + * `rustls_client_config_builder_set_server_verifier`. */ typedef struct rustls_server_cert_verifier rustls_server_cert_verifier; @@ -405,30 +413,39 @@ typedef struct rustls_supported_ciphersuite rustls_supported_ciphersuite; /** * A client certificate verifier being constructed. * - * A builder can be modified by, e.g. `rustls_web_pki_client_cert_verifier_builder_add_crl`. + * A builder can be modified by, e.g. + * `rustls_web_pki_client_cert_verifier_builder_add_crl`. * - * Once you're done configuring settings, call `rustls_web_pki_client_cert_verifier_builder_build` - * to turn it into a `rustls_client_cert_verifier`. + * Once you're done configuring settings, call + * `rustls_web_pki_client_cert_verifier_builder_build` to turn it into a + * `rustls_client_cert_verifier`. * * This object is not safe for concurrent mutation. * - * See + * See + * * for more information. */ -typedef struct rustls_web_pki_client_cert_verifier_builder rustls_web_pki_client_cert_verifier_builder; +typedef struct rustls_web_pki_client_cert_verifier_builder + rustls_web_pki_client_cert_verifier_builder; /** * A server certificate verifier being constructed. * - * A builder can be modified by, e.g. `rustls_web_pki_server_cert_verifier_builder_add_crl`. + * A builder can be modified by, e.g. + * `rustls_web_pki_server_cert_verifier_builder_add_crl`. * - * Once you're done configuring settings, call `rustls_web_pki_server_cert_verifier_builder_build` - * to turn it into a `rustls_server_cert_verifier`. This object is not safe for concurrent mutation. + * Once you're done configuring settings, call + * `rustls_web_pki_server_cert_verifier_builder_build` to turn it into a + * `rustls_server_cert_verifier`. This object is not safe for concurrent + * mutation. * - * See + * See + * * for more information. */ -typedef struct rustls_web_pki_server_cert_verifier_builder rustls_web_pki_server_cert_verifier_builder; +typedef struct rustls_web_pki_server_cert_verifier_builder + rustls_web_pki_server_cert_verifier_builder; /** * A return value for a function that may return either success (0) or a @@ -442,29 +459,29 @@ typedef int rustls_io_result; /** * A callback for `rustls_connection_read_tls`. * - * An implementation of this callback should attempt to read up to n bytes from the - * network, storing them in `buf`. If any bytes were stored, the implementation should - * set out_n to the number of bytes stored and return 0. + * An implementation of this callback should attempt to read up to n bytes from + * the network, storing them in `buf`. If any bytes were stored, the + * implementation should set out_n to the number of bytes stored and return 0. * - * If there was an error, the implementation should return a nonzero rustls_io_result, - * which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero + * rustls_io_result, which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one read attempt to the network per call. Additional reads will - * be triggered by subsequent calls to one of the `_read_tls` methods. + * It's best to make one read attempt to the network per call. Additional reads + * will be triggered by subsequent calls to one of the `_read_tls` methods. * * `userdata` is set to the value provided to `rustls_connection_set_userdata`. - * In most cases that should be a struct that contains, at a minimum, a file descriptor. + * In most cases that should be a struct that contains, at a minimum, a file + * descriptor. * - * The buf and out_n pointers are borrowed and should not be retained across calls. + * The buf and out_n pointers are borrowed and should not be retained across + * calls. */ -typedef rustls_io_result (*rustls_read_callback)(void *userdata, - uint8_t *buf, - size_t n, - size_t *out_n); +typedef rustls_io_result (*rustls_read_callback)(void *userdata, uint8_t *buf, + size_t n, size_t *out_n); /** * A read-only view on a Rust `&str`. @@ -482,7 +499,8 @@ typedef rustls_io_result (*rustls_read_callback)(void *userdata, * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_str { +typedef struct rustls_str +{ const char *data; size_t len; } rustls_str; @@ -500,38 +518,41 @@ typedef struct rustls_str { * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_slice_bytes { +typedef struct rustls_slice_bytes +{ const uint8_t *data; size_t len; } rustls_slice_bytes; /** - * A callback for `rustls_connection_write_tls` or `rustls_accepted_alert_write_tls`. + * A callback for `rustls_connection_write_tls` or + * `rustls_accepted_alert_write_tls`. * - * An implementation of this callback should attempt to write the `n` bytes in buf - * to the network. + * An implementation of this callback should attempt to write the `n` bytes in + * buf to the network. * - * If any bytes were written, the implementation should set `out_n` to the number of - * bytes stored and return 0. + * If any bytes were written, the implementation should set `out_n` to the + * number of bytes stored and return 0. * - * If there was an error, the implementation should return a nonzero `rustls_io_result`, - * which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero + * `rustls_io_result`, which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one write attempt to the network per call. Additional writes will - * be triggered by subsequent calls to rustls_connection_write_tls. + * It's best to make one write attempt to the network per call. Additional + * writes will be triggered by subsequent calls to rustls_connection_write_tls. * - * `userdata` is set to the value provided to `rustls_connection_set_userdata`. In most - * cases that should be a struct that contains, at a minimum, a file descriptor. + * `userdata` is set to the value provided to `rustls_connection_set_userdata`. + * In most cases that should be a struct that contains, at a minimum, a file + * descriptor. * - * The buf and out_n pointers are borrowed and should not be retained across calls. + * The buf and out_n pointers are borrowed and should not be retained across + * calls. */ typedef rustls_io_result (*rustls_write_callback)(void *userdata, - const uint8_t *buf, - size_t n, + const uint8_t *buf, size_t n, size_t *out_n); /** @@ -549,7 +570,8 @@ typedef void *rustls_verify_server_cert_user_data; * server_name can contain a hostname, an IPv4 address in textual form, or an * IPv6 address in textual form. */ -typedef struct rustls_verify_server_cert_params { +typedef struct rustls_verify_server_cert_params +{ struct rustls_slice_bytes end_entity_cert_der; const struct rustls_slice_slice_bytes *intermediate_certs_der; struct rustls_str server_name; @@ -559,8 +581,9 @@ typedef struct rustls_verify_server_cert_params { /** * A callback that is invoked to verify a server certificate. */ -typedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata, - const struct rustls_verify_server_cert_params *params); +typedef uint32_t (*rustls_verify_server_cert_callback)( + rustls_verify_server_cert_user_data userdata, + const struct rustls_verify_server_cert_params *params); /** * An optional callback for logging key material. @@ -595,7 +618,8 @@ typedef size_t rustls_log_level; /** * Parameter structure passed to a `rustls_log_callback`. */ -typedef struct rustls_log_params { +typedef struct rustls_log_params +{ /** * The log level the message was logged at. */ @@ -609,7 +633,8 @@ typedef struct rustls_log_params { /** * A callback that is invoked for messages logged by rustls. */ -typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params); +typedef void (*rustls_log_callback)(void *userdata, + const struct rustls_log_params *params); /** * A callback for `rustls_connection_write_tls_vectored`. @@ -617,28 +642,29 @@ typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_para * An implementation of this callback should attempt to write the bytes in * the given `count` iovecs to the network. * - * If any bytes were written, the implementation should set out_n to the number of - * bytes written and return 0. + * If any bytes were written, the implementation should set out_n to the number + * of bytes written and return 0. * - * If there was an error, the implementation should return a nonzero rustls_io_result, - * which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero + * rustls_io_result, which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one write attempt to the network per call. Additional write will - * be triggered by subsequent calls to one of the `_write_tls` methods. + * It's best to make one write attempt to the network per call. Additional + * write will be triggered by subsequent calls to one of the `_write_tls` + * methods. * - * `userdata` is set to the value provided to `rustls_*_session_set_userdata`. In most - * cases that should be a struct that contains, at a minimum, a file descriptor. + * `userdata` is set to the value provided to `rustls_*_session_set_userdata`. + * In most cases that should be a struct that contains, at a minimum, a file + * descriptor. * - * The iov and out_n pointers are borrowed and should not be retained across calls. + * The iov and out_n pointers are borrowed and should not be retained across + * calls. */ -typedef rustls_io_result (*rustls_write_vectored_callback)(void *userdata, - const struct rustls_iovec *iov, - size_t count, - size_t *out_n); +typedef rustls_io_result (*rustls_write_vectored_callback)( + void *userdata, const struct rustls_iovec *iov, size_t count, size_t *out_n); /** * Any context information the callback will receive when invoked. @@ -658,7 +684,8 @@ typedef void *rustls_client_hello_userdata; * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_slice_u16 { +typedef struct rustls_slice_u16 +{ const uint16_t *data; size_t len; } rustls_slice_u16; @@ -671,20 +698,23 @@ typedef struct rustls_slice_u16 { * `rustls_string` will be 0. * * `signature_schemes` carries the values supplied by the client or, if the - * client did not send this TLS extension, the default schemes in the rustls library. See: + * client did not send this TLS extension, the default schemes in the rustls + * library. See: * . * * `alpn` carries the list of ALPN protocol names that the client proposed to * the server. Again, the length of this list will be 0 if none were supplied. * * All this data, when passed to a callback function, is only accessible during - * the call and may not be modified. Users of this API must copy any values that - * they want to access when the callback returned. + * the call and may not be modified. Users of this API must copy any values + * that they want to access when the callback returned. * - * 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. + * 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. */ -typedef struct rustls_client_hello { +typedef struct rustls_client_hello +{ struct rustls_str server_name; struct rustls_slice_u16 signature_schemes; const struct rustls_slice_slice_bytes *alpn; @@ -699,21 +729,24 @@ typedef struct rustls_client_hello { * * `userdata` will be set based on rustls_connection_set_userdata. * - * `hello` gives the value of the available client announcements, as interpreted - * by rustls. See the definition of `rustls_client_hello` for details. + * `hello` gives the value of the available client announcements, as + * interpreted by rustls. See the definition of `rustls_client_hello` for + * details. * * NOTE: * - the passed in `hello` and all its values are only available during the * callback invocations. - * - the passed callback function must be safe to call multiple times concurrently - * with the same userdata, unless there is only a single config and connection - * where it is installed. + * - the passed callback function must be safe to call multiple times + * concurrently with the same userdata, unless there is only a single config + * and connection where it is installed. * - * 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. + * 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. */ -typedef const struct rustls_certified_key *(*rustls_client_hello_callback)(rustls_client_hello_userdata userdata, - const struct rustls_client_hello *hello); +typedef const struct rustls_certified_key *(*rustls_client_hello_callback)( + rustls_client_hello_userdata userdata, + const struct rustls_client_hello *hello); /** * Any context information the callback will receive when invoked. @@ -727,7 +760,8 @@ typedef void *rustls_session_store_userdata; * This callback will be invoked by a TLS session when looking up the data * for a TLS session id. * - * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on + * rustls_{client,server}_session_set_userdata. * * The `buf` points to `count` consecutive bytes where the * callback is expected to copy the result to. The number of copied bytes @@ -750,12 +784,9 @@ typedef void *rustls_session_store_userdata; * NOTE: callbacks used in several sessions via a common config * must be implemented thread-safe. */ -typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userdata userdata, - const struct rustls_slice_bytes *key, - int remove_after, - uint8_t *buf, - size_t count, - size_t *out_n); +typedef uint32_t (*rustls_session_store_get_callback)( + rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, + int remove_after, uint8_t *buf, size_t count, size_t *out_n); /** * Prototype of a callback that can be installed by the application at the @@ -765,7 +796,8 @@ typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userd * been created and an id for later use is handed to the client/has * been received from the server. * - * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on + * rustls_{client,server}_session_set_userdata. * * The callback should return RUSTLS_RESULT_OK to indicate that a value was * successfully stored, or RUSTLS_RESULT_IO on failure. @@ -775,9 +807,9 @@ typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userd * NOTE: callbacks used in several sessions via a common config * must be implemented thread-safe. */ -typedef uint32_t (*rustls_session_store_put_callback)(rustls_session_store_userdata userdata, - const struct rustls_slice_bytes *key, - const struct rustls_slice_bytes *val); +typedef uint32_t (*rustls_session_store_put_callback)( + rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, + const struct rustls_slice_bytes *val); /** * Rustls' list of supported protocol versions. The length of the array is @@ -851,8 +883,7 @@ void rustls_acceptor_free(struct rustls_acceptor *acceptor); */ rustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor, rustls_read_callback callback, - void *userdata, - size_t *out_n); + void *userdata, size_t *out_n); /** * Parse all TLS bytes read so far. @@ -880,8 +911,8 @@ rustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor, * - RUSTLS_RESULT_OK: a ClientHello has successfully been parsed. * A pointer to a newly allocated rustls_accepted has been written to * *out_accepted. - * - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been read. - * Read more TLS bytes to continue. + * - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been + * read. Read more TLS bytes to continue. * - Any other rustls_result: the TLS bytes read so far cannot be parsed * as a ClientHello, and reading additional bytes won't help. * @@ -921,7 +952,8 @@ rustls_result rustls_acceptor_accept(struct rustls_acceptor *acceptor, * - The `accepted` parameter was already transformed into a connection * with rustls_accepted_into_connection. */ -struct rustls_str rustls_accepted_server_name(const struct rustls_accepted *accepted); +struct rustls_str rustls_accepted_server_name( + const struct rustls_accepted *accepted); /** * Get the i'th in the list of signature schemes offered in the ClientHello. @@ -937,15 +969,16 @@ struct rustls_str rustls_accepted_server_name(const struct rustls_accepted *acce * * Returns: * - * A TLS Signature Scheme from + * A TLS Signature Scheme from + * * * This will be 0 in these cases: * - i is greater than the number of available cipher suites. * - accepted is NULL. * - rustls_accepted_into_connection has already been called with `accepted`. */ -uint16_t rustls_accepted_signature_scheme(const struct rustls_accepted *accepted, - size_t i); +uint16_t rustls_accepted_signature_scheme( + const struct rustls_accepted *accepted, size_t i); /** * Get the i'th in the list of cipher suites offered in the ClientHello. @@ -957,7 +990,8 @@ uint16_t rustls_accepted_signature_scheme(const struct rustls_accepted *accepted * * Returns: * - * A cipher suite value from + * A cipher suite value from + * * * This will be 0 in these cases: * - i is greater than the number of available cipher suites. @@ -995,7 +1029,8 @@ uint16_t rustls_accepted_cipher_suite(const struct rustls_accepted *accepted, * If you are calling this from Rust, note that the `'static` lifetime * in the return signature is fake and must not be relied upon. */ -struct rustls_slice_bytes rustls_accepted_alpn(const struct rustls_accepted *accepted, size_t i); +struct rustls_slice_bytes rustls_accepted_alpn( + const struct rustls_accepted *accepted, size_t i); /** * Turn a rustls_accepted into a rustls_connection, given the provided @@ -1042,10 +1077,10 @@ struct rustls_slice_bytes rustls_accepted_alpn(const struct rustls_accepted *acc * rustls_connection may hold a reference to it until it is done. * See the documentation for rustls_connection for details. */ -rustls_result rustls_accepted_into_connection(struct rustls_accepted *accepted, - const struct rustls_server_config *config, - struct rustls_connection **out_conn, - struct rustls_accepted_alert **out_alert); +rustls_result rustls_accepted_into_connection( + struct rustls_accepted *accepted, const struct rustls_server_config *config, + struct rustls_connection **out_conn, + struct rustls_accepted_alert **out_alert); /** * Free a rustls_accepted. @@ -1070,14 +1105,13 @@ void rustls_accepted_free(struct rustls_accepted *accepted); * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. * - * Returns 0 for success, or an errno value on error. Passes through return values - * from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for + * Returns 0 for success, or an errno value on error. Passes through return + * values from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for * more details. */ -rustls_io_result rustls_accepted_alert_write_tls(struct rustls_accepted_alert *accepted_alert, - rustls_write_callback callback, - void *userdata, - size_t *out_n); +rustls_io_result rustls_accepted_alert_write_tls( + struct rustls_accepted_alert *accepted_alert, rustls_write_callback callback, + void *userdata, size_t *out_n); /** * Free a rustls_accepted_alert. @@ -1130,11 +1164,10 @@ rustls_result rustls_certificate_get_der(const struct rustls_certificate *cert, * `rustls_certified_key`'s memory will automatically be released when * the `rustls_server_config` is freed. */ -rustls_result rustls_certified_key_build(const uint8_t *cert_chain, - size_t cert_chain_len, - const uint8_t *private_key, - size_t private_key_len, - const struct rustls_certified_key **certified_key_out); +rustls_result rustls_certified_key_build( + const uint8_t *cert_chain, size_t cert_chain_len, const uint8_t *private_key, + size_t private_key_len, + const struct rustls_certified_key **certified_key_out); /** * Build a `rustls_certified_key` from a certificate chain and a @@ -1166,22 +1199,23 @@ rustls_result rustls_certified_key_build(const uint8_t *cert_chain, * `rustls_certified_key`'s memory will automatically be released when * the `rustls_server_config` is freed. */ -rustls_result rustls_certified_key_build_with_signing_key(const uint8_t *cert_chain, - size_t cert_chain_len, - struct rustls_signing_key *signing_key, - const struct rustls_certified_key **certified_key_out); +rustls_result rustls_certified_key_build_with_signing_key( + const uint8_t *cert_chain, size_t cert_chain_len, + struct rustls_signing_key *signing_key, + const struct rustls_certified_key **certified_key_out); /** * Return the i-th rustls_certificate in the rustls_certified_key. * - * 0 gives the end-entity certificate. 1 and higher give certificates from the chain. + * 0 gives the end-entity certificate. 1 and higher give certificates from the + * chain. * * Indexes higher than the last available certificate return NULL. * * The returned certificate is valid until the rustls_certified_key is freed. */ -const struct rustls_certificate *rustls_certified_key_get_certificate(const struct rustls_certified_key *certified_key, - size_t i); +const struct rustls_certificate *rustls_certified_key_get_certificate( + const struct rustls_certified_key *certified_key, size_t i); /** * Create a copy of the rustls_certified_key with the given OCSP response data @@ -1193,26 +1227,31 @@ const struct rustls_certificate *rustls_certified_key_get_certificate(const stru * The cloned key is independent from its original and needs to be freed * by the application. */ -rustls_result rustls_certified_key_clone_with_ocsp(const struct rustls_certified_key *certified_key, - const struct rustls_slice_bytes *ocsp_response, - const struct rustls_certified_key **cloned_key_out); +rustls_result rustls_certified_key_clone_with_ocsp( + const struct rustls_certified_key *certified_key, + const struct rustls_slice_bytes *ocsp_response, + const struct rustls_certified_key **cloned_key_out); /** - * Verify the consistency of this `rustls_certified_key`'s public and private keys. + * Verify the consistency of this `rustls_certified_key`'s public and private + * keys. * - * This is done by performing a comparison of subject public key information (SPKI) bytes - * between the certificate and private key. + * This is done by performing a comparison of subject public key information + * (SPKI) bytes between the certificate and private key. * - * If the private key matches the certificate this function returns `RUSTLS_RESULT_OK`, - * otherwise an error `rustls_result` is returned. + * If the private key matches the certificate this function returns + * `RUSTLS_RESULT_OK`, otherwise an error `rustls_result` is returned. */ -rustls_result rustls_certified_key_keys_match(const struct rustls_certified_key *key); +rustls_result rustls_certified_key_keys_match( + const struct rustls_certified_key *key); /** - * "Free" a certified_key previously returned from `rustls_certified_key_build`. + * "Free" a certified_key previously returned from + * `rustls_certified_key_build`. * * Since certified_key is actually an atomically reference-counted pointer, - * extant certified_key may still hold an internal reference to the Rust object. + * extant certified_key may still hold an internal reference to the Rust + * object. * * However, C code must consider this pointer unusable after "free"ing it. * @@ -1223,13 +1262,15 @@ void rustls_certified_key_free(const struct rustls_certified_key *key); /** * Create a `rustls_root_cert_store_builder`. * - * Caller owns the memory and may free it with `rustls_root_cert_store_free`, regardless of - * whether `rustls_root_cert_store_builder_build` was called. + * Caller owns the memory and may free it with `rustls_root_cert_store_free`, + * regardless of whether `rustls_root_cert_store_builder_build` was called. * - * If you wish to abandon the builder without calling `rustls_root_cert_store_builder_build`, - * it must be freed with `rustls_root_cert_store_builder_free`. + * If you wish to abandon the builder without calling + * `rustls_root_cert_store_builder_build`, it must be freed with + * `rustls_root_cert_store_builder_free`. */ -struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void); +struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new( + void); /** * Add one or more certificates to the root cert store builder using PEM @@ -1242,10 +1283,9 @@ struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void); * This may be useful on systems that have syntactically invalid root * certificates. */ -rustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_store_builder *builder, - const uint8_t *pem, - size_t pem_len, - bool strict); +rustls_result rustls_root_cert_store_builder_add_pem( + struct rustls_root_cert_store_builder *builder, const uint8_t *pem, + size_t pem_len, bool strict); /** * Add one or more certificates to the root cert store builder using PEM @@ -1258,21 +1298,23 @@ rustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_sto * This may be useful on systems that have syntactically invalid root * certificates. */ -rustls_result rustls_root_cert_store_builder_load_roots_from_file(struct rustls_root_cert_store_builder *builder, - const char *filename, - bool strict); +rustls_result rustls_root_cert_store_builder_load_roots_from_file( + struct rustls_root_cert_store_builder *builder, const char *filename, + bool strict); /** * Create a new `rustls_root_cert_store` from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The root cert store can be used in several `rustls_web_pki_client_cert_verifier_builder_new` - * instances and must be freed by the application when no longer needed. See the documentation of + * The root cert store can be used in several + * `rustls_web_pki_client_cert_verifier_builder_new` instances and must be + * freed by the application when no longer needed. See the documentation of * `rustls_root_cert_store_free` for details about lifetime. */ -rustls_result rustls_root_cert_store_builder_build(struct rustls_root_cert_store_builder *builder, - const struct rustls_root_cert_store **root_cert_store_out); +rustls_result rustls_root_cert_store_builder_build( + struct rustls_root_cert_store_builder *builder, + const struct rustls_root_cert_store **root_cert_store_out); /** * Free a `rustls_root_cert_store_builder` previously returned from @@ -1280,68 +1322,78 @@ rustls_result rustls_root_cert_store_builder_build(struct rustls_root_cert_store * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_root_cert_store_builder_free(struct rustls_root_cert_store_builder *builder); +void rustls_root_cert_store_builder_free( + struct rustls_root_cert_store_builder *builder); /** - * Free a rustls_root_cert_store previously returned from rustls_root_cert_store_builder_build. + * Free a rustls_root_cert_store previously returned from + * rustls_root_cert_store_builder_build. * * Calling with NULL is fine. Must not be called twice with the same value. */ void rustls_root_cert_store_free(const struct rustls_root_cert_store *store); /** - * Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from + * Return a 16-bit unsigned integer corresponding to this cipher suite's + * assignment from * . * * The bytes from the assignment are interpreted in network order. */ -uint16_t rustls_supported_ciphersuite_get_suite(const struct rustls_supported_ciphersuite *supported_ciphersuite); +uint16_t rustls_supported_ciphersuite_get_suite( + const struct rustls_supported_ciphersuite *supported_ciphersuite); /** * Returns the name of the ciphersuite as a `rustls_str`. * * If the provided ciphersuite is invalid, the `rustls_str` will contain the - * empty string. The lifetime of the `rustls_str` is the lifetime of the program, - * it does not need to be freed. + * empty string. The lifetime of the `rustls_str` is the lifetime of the + * program, it does not need to be freed. */ -struct rustls_str rustls_supported_ciphersuite_get_name(const struct rustls_supported_ciphersuite *supported_ciphersuite); +struct rustls_str rustls_supported_ciphersuite_get_name( + const struct rustls_supported_ciphersuite *supported_ciphersuite); /** * Returns the `rustls_tls_version` of the ciphersuite. * * See also `RUSTLS_ALL_VERSIONS`. */ -enum rustls_tls_version rustls_supported_ciphersuite_protocol_version(const struct rustls_supported_ciphersuite *supported_ciphersuite); +enum rustls_tls_version rustls_supported_ciphersuite_protocol_version( + const struct rustls_supported_ciphersuite *supported_ciphersuite); /** - * Create a rustls_client_config_builder using the process default crypto provider. + * 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`. + * 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 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. + * rustls_client_config_builder_load_roots_from_file or provide a custom + * verifier. */ struct rustls_client_config_builder *rustls_client_config_builder_new(void); /** * 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`. + * 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 + * `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. * @@ -1352,10 +1404,9 @@ struct rustls_client_config_builder *rustls_client_config_builder_new(void); * Ciphersuites are configured separately via the crypto provider. See * `rustls_crypto_provider_builder_set_cipher_suites` for more information. */ -rustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto_provider *provider, - const uint16_t *tls_versions, - size_t tls_versions_len, - struct rustls_client_config_builder **builder_out); +rustls_result rustls_client_config_builder_new_custom( + const struct rustls_crypto_provider *provider, const uint16_t *tls_versions, + size_t tls_versions_len, struct rustls_client_config_builder **builder_out); /** * Set a custom server certificate verifier using the builder crypto provider. @@ -1386,22 +1437,25 @@ rustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto * * */ -rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier(struct rustls_client_config_builder *config_builder, - rustls_verify_server_cert_callback callback); +rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier( + struct rustls_client_config_builder *config_builder, + rustls_verify_server_cert_callback callback); /** * Configure the server certificate verifier. * - * This increases the reference count of `verifier` and does not take ownership. + * This increases the reference count of `verifier` and does not take + * ownership. */ -void rustls_client_config_builder_set_server_verifier(struct rustls_client_config_builder *builder, - const struct rustls_server_cert_verifier *verifier); +void rustls_client_config_builder_set_server_verifier( + struct rustls_client_config_builder *builder, + const struct rustls_server_cert_verifier *verifier); /** * 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. + * `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. @@ -1414,16 +1468,16 @@ void rustls_client_config_builder_set_server_verifier(struct rustls_client_confi * * */ -rustls_result rustls_client_config_builder_set_alpn_protocols(struct rustls_client_config_builder *builder, - const struct rustls_slice_bytes *protocols, - size_t len); +rustls_result rustls_client_config_builder_set_alpn_protocols( + struct rustls_client_config_builder *builder, + const struct rustls_slice_bytes *protocols, size_t len); /** * Enable or disable SNI. * */ -void rustls_client_config_builder_set_enable_sni(struct rustls_client_config_builder *config, - bool enable); +void rustls_client_config_builder_set_enable_sni( + struct rustls_client_config_builder *config, bool enable); /** * Provide the configuration a list of certificates where the connection @@ -1441,128 +1495,142 @@ void rustls_client_config_builder_set_enable_sni(struct rustls_client_config_bui * EXPERIMENTAL: installing a client authentication callback will replace any * configured certified keys and vice versa. */ -rustls_result rustls_client_config_builder_set_certified_key(struct rustls_client_config_builder *builder, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len); +rustls_result rustls_client_config_builder_set_certified_key( + struct rustls_client_config_builder *builder, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len); /** - * Log key material to the file specified by the `SSLKEYLOGFILE` environment variable. + * Log key material to the file specified by the `SSLKEYLOGFILE` environment + * variable. * * The key material will be logged in the NSS key log format, - * and is - * compatible with tools like Wireshark. + * + * 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. + * 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`. + * For more control over which secrets are logged, or to customize the format, + * prefer `rustls_client_config_builder_set_key_log`. */ -rustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client_config_builder *builder); +rustls_result rustls_client_config_builder_set_key_log_file( + struct rustls_client_config_builder *builder); /** * 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: + * 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: * * - * 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. + * 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. + * 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. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_set_key_log(struct rustls_client_config_builder *builder, - rustls_keylog_log_callback log_cb, - rustls_keylog_will_log_callback will_log_cb); +rustls_result rustls_client_config_builder_set_key_log( + struct rustls_client_config_builder *builder, + rustls_keylog_log_callback log_cb, + rustls_keylog_will_log_callback will_log_cb); /** * 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. + * 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. + * 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`. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_enable_ech(struct rustls_client_config_builder *builder, - const uint8_t *ech_config_list_bytes, - size_t ech_config_list_bytes_size, - const struct rustls_hpke *hpke); +rustls_result rustls_client_config_builder_enable_ech( + struct rustls_client_config_builder *builder, + const uint8_t *ech_config_list_bytes, size_t ech_config_list_bytes_size, + const struct rustls_hpke *hpke); /** * 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. + * 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. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_enable_ech_grease(struct rustls_client_config_builder *builder, - const struct rustls_hpke *hpke); +rustls_result rustls_client_config_builder_enable_ech_grease( + struct rustls_client_config_builder *builder, + const struct rustls_hpke *hpke); /** - * Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config - * (read-only). + * Turn a *rustls_client_config_builder (mutable) into a const + * *rustls_client_config (read-only). */ -rustls_result rustls_client_config_builder_build(struct rustls_client_config_builder *builder, - const struct rustls_client_config **config_out); +rustls_result rustls_client_config_builder_build( + struct rustls_client_config_builder *builder, + const struct rustls_client_config **config_out); /** - * "Free" a client_config_builder without building it into a rustls_client_config. + * "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. + * 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. + * Use free only when the building of a config has to be aborted before a + * config was created. */ -void rustls_client_config_builder_free(struct rustls_client_config_builder *config); +void rustls_client_config_builder_free( + struct rustls_client_config_builder *config); /** - * Returns true if a `rustls_connection` created from the `rustls_client_config` will - * operate in FIPS mode. + * Returns true if a `rustls_connection` created from the + * `rustls_client_config` will operate in FIPS mode. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration that NIST - * recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration + * that NIST recommends, as well as ECH HPKE suites if applicable. */ bool rustls_client_config_fips(const struct rustls_client_config *config); @@ -1570,8 +1638,9 @@ bool rustls_client_config_fips(const struct rustls_client_config *config); * "Free" a `rustls_client_config` previously returned from * `rustls_client_config_builder_build`. * - * Since `rustls_client_config` is actually an atomically reference-counted pointer, - * extant client connections may still hold an internal reference to the Rust object. + * Since `rustls_client_config` is actually an atomically reference-counted + * pointer, extant client connections may still hold an internal reference to + * the Rust object. * * However, C code must consider this pointer unusable after "free"ing it. * @@ -1588,46 +1657,48 @@ void rustls_client_config_free(const struct rustls_client_config *config); * * If this returns a non-error, the memory pointed to by `conn_out` * is modified to point at a valid `rustls_connection`. The caller now owns - * the `rustls_connection` and must call `rustls_connection_free` when done with it. + * the `rustls_connection` and must call `rustls_connection_free` when done + * with it. * * The server_name parameter can contain a hostname or an IP address in * textual form (IPv4 or IPv6). This function will return an error if it * cannot be parsed as one of those types. */ -rustls_result rustls_client_connection_new(const struct rustls_client_config *config, - const char *server_name, - struct rustls_connection **conn_out); +rustls_result rustls_client_connection_new( + const struct rustls_client_config *config, const char *server_name, + struct rustls_connection **conn_out); /** - * Set the userdata pointer associated with this connection. This will be passed - * to any callbacks invoked by the connection, if you've set up callbacks in the config. - * The pointed-to data must outlive the connection. + * Set the userdata pointer associated with this connection. This will be + * passed to any callbacks invoked by the connection, if you've set up + * callbacks in the config. The pointed-to data must outlive the connection. */ -void rustls_connection_set_userdata(struct rustls_connection *conn, void *userdata); +void rustls_connection_set_userdata(struct rustls_connection *conn, + void *userdata); /** - * Set the logging callback for this connection. The log callback will be invoked - * with the userdata parameter previously set by rustls_connection_set_userdata, or - * NULL if no userdata was set. + * Set the logging callback for this connection. The log callback will be + * invoked with the userdata parameter previously set by + * rustls_connection_set_userdata, or NULL if no userdata was set. */ -void rustls_connection_set_log_callback(struct rustls_connection *conn, rustls_log_callback cb); +void rustls_connection_set_log_callback(struct rustls_connection *conn, + rustls_log_callback cb); /** - * Read some TLS bytes from the network into internal buffers. The actual network - * I/O is performed by `callback`, which you provide. Rustls will invoke your - * callback with a suitable buffer to store the read bytes into. You don't have - * to fill it up, just fill with as many bytes as you get in one syscall. - * The `userdata` parameter is passed through directly to `callback`. Note that - * this is distinct from the `userdata` parameter set with + * Read some TLS bytes from the network into internal buffers. The actual + * network I/O is performed by `callback`, which you provide. Rustls will + * invoke your callback with a suitable buffer to store the read bytes into. + * You don't have to fill it up, just fill with as many bytes as you get in one + * syscall. The `userdata` parameter is passed through directly to `callback`. + * Note that this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return values - * from callback. See rustls_read_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return + * values from callback. See rustls_read_callback for more details. * */ rustls_io_result rustls_connection_read_tls(struct rustls_connection *conn, rustls_read_callback callback, - void *userdata, - size_t *out_n); + void *userdata, size_t *out_n); /** * Write some TLS bytes to the network. The actual network I/O is performed by @@ -1637,31 +1708,29 @@ rustls_io_result rustls_connection_read_tls(struct rustls_connection *conn, * The `userdata` parameter is passed through directly to `callback`. Note that * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return values - * from callback. See rustls_write_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return + * values from callback. See rustls_write_callback for more details. * */ rustls_io_result rustls_connection_write_tls(struct rustls_connection *conn, rustls_write_callback callback, - void *userdata, - size_t *out_n); + void *userdata, size_t *out_n); /** - * Write all available TLS bytes to the network. The actual network I/O is performed by - * `callback`, which you provide. Rustls will invoke your callback with an array - * of rustls_slice_bytes, each containing a buffer with TLS bytes to send. - * You don't have to write them all, just as many as you are willing. + * Write all available TLS bytes to the network. The actual network I/O is + * performed by `callback`, which you provide. Rustls will invoke your callback + * with an array of rustls_slice_bytes, each containing a buffer with TLS bytes + * to send. You don't have to write them all, just as many as you are willing. * The `userdata` parameter is passed through directly to `callback`. Note that * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return values - * from callback. See rustls_write_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return + * values from callback. See rustls_write_callback for more details. * */ -rustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection *conn, - rustls_write_vectored_callback callback, - void *userdata, - size_t *out_n); +rustls_io_result rustls_connection_write_tls_vectored( + struct rustls_connection *conn, rustls_write_vectored_callback callback, + void *userdata, size_t *out_n); /** * Decrypt any available ciphertext from the internal buffer and put it @@ -1669,7 +1738,8 @@ rustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection * * for rustls_connection_read(). * */ -rustls_result rustls_connection_process_new_packets(struct rustls_connection *conn); +rustls_result rustls_connection_process_new_packets( + struct rustls_connection *conn); /** * @@ -1684,8 +1754,9 @@ bool rustls_connection_wants_write(const struct rustls_connection *conn); /** * Returns true if the connection is currently performing the TLS handshake. * - * Note: This may return `false` while there are still handshake packets waiting - * to be extracted and transmitted with `rustls_connection_write_tls()`. + * Note: This may return `false` while there are still handshake packets + * waiting to be extracted and transmitted with + * `rustls_connection_write_tls()`. * * See the rustls documentation for more information. * @@ -1696,7 +1767,8 @@ bool rustls_connection_is_handshaking(const struct rustls_connection *conn); /** * Returns a `rustls_handshake_kind` describing the `rustls_connection`. */ -enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_connection *conn); +enum rustls_handshake_kind rustls_connection_handshake_kind( + const struct rustls_connection *conn); /** * Sets a limit on the internal buffers used to buffer unsent plaintext (prior @@ -1705,7 +1777,8 @@ enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_ * use is higher. * */ -void rustls_connection_set_buffer_limit(struct rustls_connection *conn, size_t n); +void rustls_connection_set_buffer_limit(struct rustls_connection *conn, + size_t n); /** * Queues a close_notify fatal alert to be sent in the next write_tls call. @@ -1716,13 +1789,14 @@ void rustls_connection_send_close_notify(struct rustls_connection *conn); /** * Queues a TLS1.3 key_update message to refresh a connection’s keys. * - * Rustls internally manages key updates as required and so this function should - * seldom be used. See the Rustls documentation for important caveats and suggestions - * on occasions that merit its use. + * Rustls internally manages key updates as required and so this function + * should seldom be used. See the Rustls documentation for important caveats + * and suggestions on occasions that merit its use. * * */ -rustls_result rustls_connection_refresh_traffic_keys(struct rustls_connection *conn); +rustls_result rustls_connection_refresh_traffic_keys( + struct rustls_connection *conn); /** * Return the i-th certificate provided by the peer. @@ -1735,8 +1809,8 @@ rustls_result rustls_connection_refresh_traffic_keys(struct rustls_connection *c * `const struct rustls_connection *`). * */ -const struct rustls_certificate *rustls_connection_get_peer_certificate(const struct rustls_connection *conn, - size_t i); +const struct rustls_certificate *rustls_connection_get_peer_certificate( + const struct rustls_connection *conn, size_t i); /** * Get the ALPN protocol that was negotiated, if any. Stores a pointer to a @@ -1762,16 +1836,21 @@ void rustls_connection_get_alpn_protocol(const struct rustls_connection *conn, * * */ -uint16_t rustls_connection_get_protocol_version(const struct rustls_connection *conn); +uint16_t rustls_connection_get_protocol_version( + const struct rustls_connection *conn); /** - * Retrieves the [IANA registered cipher suite identifier][IANA] agreed with the peer. + * Retrieves the [IANA registered cipher suite identifier][IANA] agreed with + * the peer. * - * This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed. + * This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is + * agreed. * - * [IANA]: + * [IANA]: + * */ -uint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connection *conn); +uint16_t rustls_connection_get_negotiated_ciphersuite( + const struct rustls_connection *conn); /** * Retrieves the cipher suite name agreed with the peer. @@ -1783,16 +1862,20 @@ uint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connec * * */ -struct rustls_str rustls_connection_get_negotiated_ciphersuite_name(const struct rustls_connection *conn); +struct rustls_str rustls_connection_get_negotiated_ciphersuite_name( + const struct rustls_connection *conn); /** - * Retrieves the [IANA registered supported group identifier][IANA] agreed with the peer. + * Retrieves the [IANA registered supported group identifier][IANA] agreed with + * the peer. * * This returns Reserved (0x0000) until the key exchange group is agreed. * - * [IANA]: + * [IANA]: + * */ -uint16_t rustls_connection_get_negotiated_key_exchange_group(const struct rustls_connection *conn); +uint16_t rustls_connection_get_negotiated_key_exchange_group( + const struct rustls_connection *conn); /** * Retrieves the key exchange group name agreed with the peer. @@ -1802,7 +1885,8 @@ uint16_t rustls_connection_get_negotiated_key_exchange_group(const struct rustls * The lifetime of the `rustls_str` is the lifetime of the program, it does not * need to be freed. */ -struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name(const struct rustls_connection *conn); +struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name( + const struct rustls_connection *conn); /** * Write up to `count` plaintext bytes from `buf` into the `rustls_connection`. @@ -1813,8 +1897,7 @@ struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name(const * */ rustls_result rustls_connection_write(struct rustls_connection *conn, - const uint8_t *buf, - size_t count, + const uint8_t *buf, size_t count, size_t *out_n); /** @@ -1832,8 +1915,7 @@ rustls_result rustls_connection_write(struct rustls_connection *conn, * */ rustls_result rustls_connection_read(struct rustls_connection *conn, - uint8_t *buf, - size_t count, + uint8_t *buf, size_t count, size_t *out_n); #if defined(DEFINE_READ_BUF) @@ -1853,21 +1935,30 @@ rustls_result rustls_connection_read(struct rustls_connection *conn, * pointing to an uninitialized memory buffer. */ rustls_result rustls_connection_read_2(struct rustls_connection *conn, - uint8_t *buf, - size_t count, + uint8_t *buf, size_t count, size_t *out_n); #endif /** - * Returns true if the `rustls_connection` was made with a `rustls_client_config` - * or `rustls_server_config` that is FIPS compatible. + * Returns true if the `rustls_connection` was made with a + * `rustls_client_config` or `rustls_server_config` that is FIPS compatible. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration that NIST - * recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration + * that NIST recommends, as well as ECH HPKE suites if applicable. */ bool rustls_connection_fips(const struct rustls_connection *conn); +/** + * Read up to `count` bytes of the last error message into `buf`. + * If there is any error message, store the number of bytes in *out_n and + * returns `true`. If there is no last error message, stores 0 in *out_n + * and returns `false`. + */ +bool rustls_connection_last_error_msg(const struct rustls_connection *conn, + uint8_t *buf, size_t count, + size_t *out_n); + /** * Free a rustls_connection. Calling with NULL is fine. * Must not be called twice with the same value. @@ -1875,45 +1966,49 @@ bool rustls_connection_fips(const struct rustls_connection *conn); void rustls_connection_free(struct rustls_connection *conn); /** - * Constructs a new `rustls_crypto_provider_builder` using the process-wide default crypto - * provider as the base crypto provider to be customized. + * Constructs a new `rustls_crypto_provider_builder` using the process-wide + * default crypto provider as the base crypto provider to be customized. * - * When this function returns `rustls_result::Ok` a pointer to the `rustls_crypto_provider_builder` - * is written to `builder_out`. It returns `rustls_result::NoDefaultCryptoProvider` if no default - * provider has been registered. + * When this function returns `rustls_result::Ok` a pointer to the + * `rustls_crypto_provider_builder` is written to `builder_out`. It returns + * `rustls_result::NoDefaultCryptoProvider` if no default provider has been + * registered. * - * The caller owns the returned `rustls_crypto_provider_builder` and must free it using - * `rustls_crypto_provider_builder_free`. + * The caller owns the returned `rustls_crypto_provider_builder` and must free + * it using `rustls_crypto_provider_builder_free`. * - * This function is typically used for customizing the default crypto provider for specific - * connections. For example, a typical workflow might be to: + * This function is typically used for customizing the default crypto provider + * for specific connections. For example, a typical workflow might be to: * * * Either: - * * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is built with based on - * the `CRYPTO_PROVIDER` build variable. - * * Call `rustls_crypto_provider_builder_new_with_base` with the desired provider, and - * then install it as the process default with + * * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is + * built with based on the `CRYPTO_PROVIDER` build variable. + * * Call `rustls_crypto_provider_builder_new_with_base` with the desired + * provider, and then install it as the process default with * `rustls_crypto_provider_builder_build_as_default`. * * Afterward, as required for customization: - * * Use `rustls_crypto_provider_builder_new_from_default` to get a builder backed by the - * default crypto provider. - * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the supported - * ciphersuites. - * * Use `rustls_crypto_provider_builder_build` to build a customized provider. - * * Provide that customized provider to client or server configuration builders. + * * Use `rustls_crypto_provider_builder_new_from_default` to get a builder + * backed by the default crypto provider. + * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the + * supported ciphersuites. + * * Use `rustls_crypto_provider_builder_build` to build a customized + * provider. + * * Provide that customized provider to client or server configuration + * builders. */ -rustls_result rustls_crypto_provider_builder_new_from_default(struct rustls_crypto_provider_builder **builder_out); +rustls_result rustls_crypto_provider_builder_new_from_default( + struct rustls_crypto_provider_builder **builder_out); /** - * Constructs a new `rustls_crypto_provider_builder` using the given `rustls_crypto_provider` - * as the base crypto provider to be customized. + * Constructs a new `rustls_crypto_provider_builder` using the given + * `rustls_crypto_provider` as the base crypto provider to be customized. * - * The caller owns the returned `rustls_crypto_provider_builder` and must free it using - * `rustls_crypto_provider_builder_free`. + * The caller owns the returned `rustls_crypto_provider_builder` and must free + * it using `rustls_crypto_provider_builder_free`. * - * This function can be used for setting the default process wide crypto provider, - * or for constructing a custom crypto provider for a specific connection. A typical - * workflow could be to: + * This function can be used for setting the default process wide crypto + * provider, or for constructing a custom crypto provider for a specific + * connection. A typical workflow could be to: * * * Call `rustls_crypto_provider_builder_new_with_base` with a custom provider * * Install the custom provider as the process-wide default with @@ -1922,48 +2017,57 @@ rustls_result rustls_crypto_provider_builder_new_from_default(struct rustls_cryp * Or, for per-connection customization: * * * Call `rustls_crypto_provider_builder_new_with_base` with a custom provider - * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the supported - * ciphersuites. + * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the + * supported ciphersuites. * * Use `rustls_crypto_provider_builder_build` to build a customized provider. - * * Provide that customized provider to client or server configuration builders. + * * Provide that customized provider to client or server configuration + * builders. */ -struct rustls_crypto_provider_builder *rustls_crypto_provider_builder_new_with_base(const struct rustls_crypto_provider *base); +struct rustls_crypto_provider_builder * +rustls_crypto_provider_builder_new_with_base( + const struct rustls_crypto_provider *base); /** - * Customize the supported ciphersuites of the `rustls_crypto_provider_builder`. + * Customize the supported ciphersuites of the + * `rustls_crypto_provider_builder`. * - * Returns an error if the builder has already been built. Overwrites any previously - * set ciphersuites. + * Returns an error if the builder has already been built. Overwrites any + * previously set ciphersuites. */ -rustls_result rustls_crypto_provider_builder_set_cipher_suites(struct rustls_crypto_provider_builder *builder, - const struct rustls_supported_ciphersuite *const *cipher_suites, - size_t cipher_suites_len); +rustls_result rustls_crypto_provider_builder_set_cipher_suites( + struct rustls_crypto_provider_builder *builder, + const struct rustls_supported_ciphersuite *const *cipher_suites, + size_t cipher_suites_len); /** - * Builds a `rustls_crypto_provider` from the builder and returns it. Returns an error if the - * builder has already been built. + * Builds a `rustls_crypto_provider` from the builder and returns it. Returns + * an error if the builder has already been built. * - * The `rustls_crypto_provider_builder` builder is consumed and should not be used - * for further calls, except to `rustls_crypto_provider_builder_free`. The caller must - * still free the builder after a successful build. + * The `rustls_crypto_provider_builder` builder is consumed and should not be + * used for further calls, except to `rustls_crypto_provider_builder_free`. The + * caller must still free the builder after a successful build. */ -rustls_result rustls_crypto_provider_builder_build(struct rustls_crypto_provider_builder *builder, - const struct rustls_crypto_provider **provider_out); +rustls_result rustls_crypto_provider_builder_build( + struct rustls_crypto_provider_builder *builder, + const struct rustls_crypto_provider **provider_out); /** * Builds a `rustls_crypto_provider` from the builder and sets it as the * process-wide default crypto provider. * - * Afterward, the default provider can be retrieved using `rustls_crypto_provider_default`. + * Afterward, the default provider can be retrieved using + * `rustls_crypto_provider_default`. * * This can only be done once per process, and will return an error if a - * default provider has already been set, or if the builder has already been built. + * default provider has already been set, or if the builder has already been + * built. * - * The `rustls_crypto_provider_builder` builder is consumed and should not be used - * for further calls, except to `rustls_crypto_provider_builder_free`. The caller must - * still free the builder after a successful build. + * The `rustls_crypto_provider_builder` builder is consumed and should not be + * used for further calls, except to `rustls_crypto_provider_builder_free`. The + * caller must still free the builder after a successful build. */ -rustls_result rustls_crypto_provider_builder_build_as_default(struct rustls_crypto_provider_builder *builder); +rustls_result rustls_crypto_provider_builder_build_as_default( + struct rustls_crypto_provider_builder *builder); /** * Free the `rustls_crypto_provider_builder`. @@ -1971,11 +2075,13 @@ rustls_result rustls_crypto_provider_builder_build_as_default(struct rustls_cryp * Calling with `NULL` is fine. * Must not be called twice with the same value. */ -void rustls_crypto_provider_builder_free(struct rustls_crypto_provider_builder *builder); +void rustls_crypto_provider_builder_free( + struct rustls_crypto_provider_builder *builder); #if defined(DEFINE_RING) /** - * Return the `rustls_crypto_provider` backed by the `*ring*` cryptography library. + * Return the `rustls_crypto_provider` backed by the `*ring*` cryptography + * library. * * The caller owns the returned `rustls_crypto_provider` and must free it using * `rustls_crypto_provider_free`. @@ -1985,7 +2091,8 @@ const struct rustls_crypto_provider *rustls_ring_crypto_provider(void); #if defined(DEFINE_AWS_LC_RS) /** - * Return the `rustls_crypto_provider` backed by the `aws-lc-rs` cryptography library. + * Return the `rustls_crypto_provider` backed by the `aws-lc-rs` cryptography + * library. * * The caller owns the returned `rustls_crypto_provider` and must free it using * `rustls_crypto_provider_free`. @@ -1997,8 +2104,9 @@ const struct rustls_crypto_provider *rustls_aws_lc_rs_crypto_provider(void); /** * Return a `rustls_crypto_provider` that uses FIPS140-3 approved cryptography. * - * Using this function expresses in your code that you require FIPS-approved cryptography, - * and will not compile if you make a mistake with cargo features. + * Using this function expresses in your code that you require FIPS-approved + * cryptography, and will not compile if you make a mistake with cargo + * features. * * See the upstream [rustls FIPS documentation][FIPS] for more information. * @@ -2016,7 +2124,8 @@ const struct rustls_crypto_provider *rustls_default_fips_provider(void); * This may return `NULL` if no process default provider has been set using * `rustls_crypto_provider_builder_build_default`. * - * Caller owns the returned `rustls_crypto_provider` and must free it w/ `rustls_crypto_provider_free`. + * Caller owns the returned `rustls_crypto_provider` and must free it w/ + * `rustls_crypto_provider_free`. */ const struct rustls_crypto_provider *rustls_crypto_provider_default(void); @@ -2028,19 +2137,23 @@ const struct rustls_crypto_provider *rustls_crypto_provider_default(void); * * This function will return 0 if the `provider` is NULL. */ -size_t rustls_crypto_provider_ciphersuites_len(const struct rustls_crypto_provider *provider); +size_t rustls_crypto_provider_ciphersuites_len( + const struct rustls_crypto_provider *provider); /** - * Retrieve a pointer to a supported ciphersuite of the `rustls_crypto_provider`. + * Retrieve a pointer to a supported ciphersuite of the + * `rustls_crypto_provider`. * - * This function will return NULL if the `provider` is NULL, or if the index is out of bounds - * with respect to `rustls_crypto_provider_ciphersuites_len`. + * This function will return NULL if the `provider` is NULL, or if the index is + * out of bounds with respect to `rustls_crypto_provider_ciphersuites_len`. * - * The lifetime of the returned `rustls_supported_ciphersuite` is equal to the lifetime of the - * `provider` and should not be used after the `provider` is freed. + * The lifetime of the returned `rustls_supported_ciphersuite` is equal to the + * lifetime of the `provider` and should not be used after the `provider` is + * freed. */ -const struct rustls_supported_ciphersuite *rustls_crypto_provider_ciphersuites_get(const struct rustls_crypto_provider *provider, - size_t index); +const struct rustls_supported_ciphersuite * +rustls_crypto_provider_ciphersuites_get( + const struct rustls_crypto_provider *provider, size_t index); /** * Load a private key from the provided PEM content using the crypto provider. @@ -2050,26 +2163,27 @@ const struct rustls_supported_ciphersuite *rustls_crypto_provider_ciphersuites_g * the crypto provider in use. The default providers support PKCS#1, PKCS#8 or * SEC1 formats. * - * When this function returns `rustls_result::Ok` a pointer to a `rustls_signing_key` - * is written to `signing_key_out`. The caller owns the returned `rustls_signing_key` - * and must free it with `rustls_signing_key_free`. + * When this function returns `rustls_result::Ok` a pointer to a + * `rustls_signing_key` is written to `signing_key_out`. The caller owns the + * returned `rustls_signing_key` and must free it with + * `rustls_signing_key_free`. */ -rustls_result rustls_crypto_provider_load_key(const struct rustls_crypto_provider *provider, - const uint8_t *private_key, - size_t private_key_len, - struct rustls_signing_key **signing_key_out); +rustls_result rustls_crypto_provider_load_key( + const struct rustls_crypto_provider *provider, const uint8_t *private_key, + size_t private_key_len, struct rustls_signing_key **signing_key_out); /** - * Write `len` bytes of cryptographically secure random data to `buff` using the crypto provider. + * Write `len` bytes of cryptographically secure random data to `buff` using + * the crypto provider. * - * `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership - * of the buffer. + * `buff` must point to a buffer of at least `len` bytes. The caller maintains + * ownership of the buffer. * - * Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. + * Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` + * on failure. */ -rustls_result rustls_crypto_provider_random(const struct rustls_crypto_provider *provider, - uint8_t *buff, - size_t len); +rustls_result rustls_crypto_provider_random( + const struct rustls_crypto_provider *provider, uint8_t *buff, size_t len); /** * Returns true if the `rustls_crypto_provider` is operating in FIPS mode. @@ -2079,7 +2193,8 @@ rustls_result rustls_crypto_provider_random(const struct rustls_crypto_provider * `rustls_client_config_fips` or `rustls_server_config_fips` which take these * into account. */ -bool rustls_crypto_provider_fips(const struct rustls_crypto_provider *provider); +bool rustls_crypto_provider_fips( + const struct rustls_crypto_provider *provider); /** * Frees the `rustls_crypto_provider`. @@ -2087,64 +2202,71 @@ bool rustls_crypto_provider_fips(const struct rustls_crypto_provider *provider); * Calling with `NULL` is fine. * Must not be called twice with the same value. */ -void rustls_crypto_provider_free(const struct rustls_crypto_provider *provider); +void rustls_crypto_provider_free( + const struct rustls_crypto_provider *provider); /** - * Returns the number of ciphersuites the default process-wide crypto provider supports. + * Returns the number of ciphersuites the default process-wide crypto provider + * supports. * * You can use this to know the maximum allowed index for use with * `rustls_default_crypto_provider_ciphersuites_get`. * - * This function will return 0 if no process-wide default `rustls_crypto_provider` is available. + * This function will return 0 if no process-wide default + * `rustls_crypto_provider` is available. */ size_t rustls_default_crypto_provider_ciphersuites_len(void); /** - * Retrieve a pointer to a supported ciphersuite of the default process-wide crypto provider. + * Retrieve a pointer to a supported ciphersuite of the default process-wide + * crypto provider. * - * This function will return NULL if the `provider` is NULL, or if the index is out of bounds - * with respect to `rustls_default_crypto_provider_ciphersuites_len`. + * This function will return NULL if the `provider` is NULL, or if the index is + * out of bounds with respect to + * `rustls_default_crypto_provider_ciphersuites_len`. * - * The lifetime of the returned `rustls_supported_ciphersuite` is static, as the process-wide - * default provider lives for as long as the process. + * The lifetime of the returned `rustls_supported_ciphersuite` is static, as + * the process-wide default provider lives for as long as the process. */ -const struct rustls_supported_ciphersuite *rustls_default_crypto_provider_ciphersuites_get(size_t index); +const struct rustls_supported_ciphersuite * +rustls_default_crypto_provider_ciphersuites_get(size_t index); /** - * Write `len` bytes of cryptographically secure random data to `buff` using the process-wide - * default crypto provider. + * Write `len` bytes of cryptographically secure random data to `buff` using + * the process-wide default crypto provider. * - * `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership - * of the buffer. + * `buff` must point to a buffer of at least `len` bytes. The caller maintains + * ownership of the buffer. * - * Returns `RUSTLS_RESULT_OK` on success, and one of `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` - * or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. + * Returns `RUSTLS_RESULT_OK` on success, and one of + * `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` or + * `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. */ rustls_result rustls_default_crypto_provider_random(uint8_t *buff, size_t len); /** - * Frees the `rustls_signing_key`. This is safe to call with a `NULL` argument, but - * must not be called twice with the same value. + * Frees the `rustls_signing_key`. This is safe to call with a `NULL` argument, + * but must not be called twice with the same value. */ void rustls_signing_key_free(struct rustls_signing_key *signing_key); /** - * Returns a pointer to the supported `rustls_hpke` Hybrid Public Key Encryption (HPKE) - * suites, or `NULL` if HPKE is not supported. + * Returns a pointer to the supported `rustls_hpke` Hybrid Public Key + * Encryption (HPKE) suites, or `NULL` if HPKE is not supported. * * HPKE is only supported with the `aws-lc-rs` cryptography provider. * - * The returned pointer has a static lifetime equal to that of the program and does not - * need to be freed. + * The returned pointer has a static lifetime equal to that of the program and + * does not need to be freed. */ const struct rustls_hpke *rustls_supported_hpke(void); /** - * Convert a `rustls_handshake_kind` to a string with a friendly description of the kind - * of handshake. + * Convert a `rustls_handshake_kind` to a string with a friendly description of + * the kind of handshake. * - * The returned `rustls_str` has a static lifetime equal to that of the program and does - * not need to be manually freed. + * The returned `rustls_str` has a static lifetime equal to that of the program + * and does not need to be manually freed. */ struct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind); @@ -2172,7 +2294,8 @@ struct rustls_str rustls_log_level_str(rustls_log_level level); * Return the length of the outer slice. If the input pointer is NULL, * returns 0. */ -size_t rustls_slice_slice_bytes_len(const struct rustls_slice_slice_bytes *input); +size_t rustls_slice_slice_bytes_len( + const struct rustls_slice_slice_bytes *input); /** * Retrieve the nth element from the input slice of slices. @@ -2180,8 +2303,8 @@ size_t rustls_slice_slice_bytes_len(const struct rustls_slice_slice_bytes *input * If the input pointer is NULL, or n is greater than the length * of the `rustls_slice_slice_bytes`, returns rustls_slice_bytes{NULL, 0}. */ -struct rustls_slice_bytes rustls_slice_slice_bytes_get(const struct rustls_slice_slice_bytes *input, - size_t n); +struct rustls_slice_bytes rustls_slice_slice_bytes_get( + const struct rustls_slice_slice_bytes *input, size_t n); /** * Return the length of the outer slice. @@ -2196,110 +2319,124 @@ size_t rustls_slice_str_len(const struct rustls_slice_str *input); * If the input pointer is NULL, or n is greater than the length of the * rustls_slice_str, returns rustls_str{NULL, 0}. */ -struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, size_t n); +struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, + size_t n); /** - * Create a rustls_server_config_builder using the process default crypto provider. + * 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. + * 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. + * This uses the process default provider's values for the cipher suites and + * key exchange groups, as well as safe defaults for protocol versions. */ struct rustls_server_config_builder *rustls_server_config_builder_new(void); /** * 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. + * 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` 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`. + * 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. */ -rustls_result rustls_server_config_builder_new_custom(const struct rustls_crypto_provider *provider, - const uint16_t *tls_versions, - size_t tls_versions_len, - struct rustls_server_config_builder **builder_out); +rustls_result rustls_server_config_builder_new_custom( + const struct rustls_crypto_provider *provider, const uint16_t *tls_versions, + size_t tls_versions_len, struct rustls_server_config_builder **builder_out); /** - * Create a rustls_server_config_builder for TLS sessions that may verify client - * certificates. + * 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. */ -void rustls_server_config_builder_set_client_verifier(struct rustls_server_config_builder *builder, - const struct rustls_client_cert_verifier *verifier); +void rustls_server_config_builder_set_client_verifier( + struct rustls_server_config_builder *builder, + const struct rustls_client_cert_verifier *verifier); /** - * Log key material to the file specified by the `SSLKEYLOGFILE` environment variable. + * Log key material to the file specified by the `SSLKEYLOGFILE` environment + * variable. * * The key material will be logged in the NSS key log format, - * and is - * compatible with tools like Wireshark. + * + * 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. + * 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_server_config_builder_set_key_log`. + * For more control over which secrets are logged, or to customize the format, + * prefer `rustls_server_config_builder_set_key_log`. */ -rustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server_config_builder *builder); +rustls_result rustls_server_config_builder_set_key_log_file( + struct rustls_server_config_builder *builder); /** * 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: + * 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: * * - * 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. + * 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. + * 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. + * Secrets provided to the `log_cb` are **extremely sensitive** and can break + * the security of past, present and future sessions. * - * See also `rustls_server_config_builder_set_key_log_file` for a simpler way to log - * to a file specified by the `SSLKEYLOGFILE` environment variable. + * See also `rustls_server_config_builder_set_key_log_file` for a simpler way + * to log to a file specified by the `SSLKEYLOGFILE` environment variable. */ -rustls_result rustls_server_config_builder_set_key_log(struct rustls_server_config_builder *builder, - rustls_keylog_log_callback log_cb, - rustls_keylog_will_log_callback will_log_cb); +rustls_result rustls_server_config_builder_set_key_log( + struct rustls_server_config_builder *builder, + rustls_keylog_log_callback log_cb, + rustls_keylog_will_log_callback will_log_cb); /** - * "Free" a server_config_builder without building it into a rustls_server_config. + * "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. + * 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. + * Use free only when the building of a config has to be aborted before a + * config was created. */ -void rustls_server_config_builder_free(struct rustls_server_config_builder *config); +void rustls_server_config_builder_free( + struct rustls_server_config_builder *config); /** * With `ignore` != 0, the server will ignore the client ordering of cipher @@ -2307,15 +2444,15 @@ void rustls_server_config_builder_free(struct rustls_server_config_builder *conf * as configured. * */ -rustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls_server_config_builder *builder, - bool ignore); +rustls_result rustls_server_config_builder_set_ignore_client_order( + struct rustls_server_config_builder *builder, bool ignore); /** * 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 + * `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 * . * * This function makes a copy of the data in `protocols` and does not retain @@ -2323,9 +2460,9 @@ rustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls * * */ -rustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_server_config_builder *builder, - const struct rustls_slice_bytes *protocols, - size_t len); +rustls_result rustls_server_config_builder_set_alpn_protocols( + struct rustls_server_config_builder *builder, + const struct rustls_slice_bytes *protocols, size_t len); /** * Provide the configuration a list of certificates where the connection @@ -2343,29 +2480,32 @@ rustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_serv * EXPERIMENTAL: installing a client_hello callback will replace any * configured certified keys and vice versa. */ -rustls_result rustls_server_config_builder_set_certified_keys(struct rustls_server_config_builder *builder, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len); +rustls_result rustls_server_config_builder_set_certified_keys( + struct rustls_server_config_builder *builder, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len); /** - * 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`. + * 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. + * 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. */ -rustls_result rustls_server_config_builder_build(struct rustls_server_config_builder *builder, - const struct rustls_server_config **config_out); +rustls_result rustls_server_config_builder_build( + struct rustls_server_config_builder *builder, + const struct rustls_server_config **config_out); /** - * Returns true if a `rustls_connection` created from the `rustls_server_config` will - * operate in FIPS mode. + * Returns true if a `rustls_connection` created from the + * `rustls_server_config` will operate in FIPS mode. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration that NIST - * recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration + * that NIST recommends, as well as ECH HPKE suites if applicable. */ bool rustls_server_config_fips(const struct rustls_server_config *config); @@ -2382,38 +2522,43 @@ bool rustls_server_config_fips(const struct rustls_server_config *config); void rustls_server_config_free(const struct rustls_server_config *config); /** - * Create a new rustls_connection containing a server connection, and return it. + * Create a new rustls_connection containing a server connection, and return + * it. * * It is returned in the output parameter `conn_out`. * - * If this returns an error code, the memory pointed to by `conn_out` remains unchanged. + * If this returns an error code, the memory pointed to by `conn_out` remains + * unchanged. * - * If this returns a non-error, the memory pointed to by `conn_out` is modified to point - * at a valid rustls_connection + * If this returns a non-error, the memory pointed to by `conn_out` is modified + * to point at a valid rustls_connection * - * The caller now owns the rustls_connection and must call `rustls_connection_free` when - * done with it. + * The caller now owns the rustls_connection and must call + * `rustls_connection_free` when done with it. */ -rustls_result rustls_server_connection_new(const struct rustls_server_config *config, - struct rustls_connection **conn_out); +rustls_result rustls_server_connection_new( + const struct rustls_server_config *config, + struct rustls_connection **conn_out); /** - * Returns a `rustls_str` reference to the server name sent by the client in a server name - * indication (SNI) extension. + * Returns a `rustls_str` reference to the server name sent by the client in a + * server name indication (SNI) extension. * - * The returned `rustls_str` is valid until the next mutating function call affecting the - * connection. A mutating function call is one where the first argument has type - * `struct rustls_connection *` (as opposed to `const struct rustls_connection *`). The caller - * does not need to free the `rustls_str`. + * The returned `rustls_str` is valid until the next mutating function call + * affecting the connection. A mutating function call is one where the first + * argument has type `struct rustls_connection *` (as opposed to `const struct + * rustls_connection *`). The caller does not need to free the `rustls_str`. * * Returns a zero-length `rustls_str` if: * * - the connection is not a server connection. - * - the connection is a server connection but the SNI extension in the client hello has not - * been processed during the handshake yet. Check `rustls_connection_is_handshaking`. + * - the connection is a server connection but the SNI extension in the client + * hello has not been processed during the handshake yet. Check + * `rustls_connection_is_handshaking`. * - the SNI value contains null bytes. */ -struct rustls_str rustls_server_connection_get_server_name(const struct rustls_connection *conn); +struct rustls_str rustls_server_connection_get_server_name( + const struct rustls_connection *conn); /** * Register a callback to be invoked when a connection created from this config @@ -2426,13 +2571,15 @@ struct rustls_str rustls_server_connection_get_server_name(const struct rustls_c * 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. + * 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. */ -rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_server_config_builder *builder, - rustls_client_hello_callback callback); +rustls_result rustls_server_config_builder_set_hello_callback( + struct rustls_server_config_builder *builder, + rustls_client_hello_callback callback); /** * Select a `rustls_certified_key` from the list that matches the cryptographic @@ -2443,18 +2590,18 @@ rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_serv * * This is intended for servers that are configured with several keys for the * same domain name(s), for example ECDSA and RSA types. The presented keys are - * inspected in the order given and keys first in the list are given preference, - * all else being equal. However rustls is free to choose whichever it considers - * to be the best key with its knowledge about security issues and possible future - * extensions of the protocol. + * inspected in the order given and keys first in the list are given + * preference, all else being equal. However rustls is free to choose whichever + * it considers to be the best key with its knowledge about security issues and + * possible future extensions of the protocol. * * Return RUSTLS_RESULT_OK if a key was selected and RUSTLS_RESULT_NOT_FOUND * if none was suitable. */ -rustls_result rustls_client_hello_select_certified_key(const struct rustls_client_hello *hello, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len, - const struct rustls_certified_key **out_key); +rustls_result rustls_client_hello_select_certified_key( + const struct rustls_client_hello *hello, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len, const struct rustls_certified_key **out_key); /** * Register callbacks for persistence of TLS session IDs and secrets. Both @@ -2468,35 +2615,41 @@ rustls_result rustls_client_hello_select_certified_key(const struct rustls_clien * will be passed to the callbacks. Otherwise the userdata param passed to * the callbacks will be NULL. */ -void rustls_server_config_builder_set_persistence(struct rustls_server_config_builder *builder, - rustls_session_store_get_callback get_cb, - rustls_session_store_put_callback put_cb); +void rustls_server_config_builder_set_persistence( + struct rustls_server_config_builder *builder, + rustls_session_store_get_callback get_cb, + rustls_session_store_put_callback put_cb); /** * Free a `rustls_client_cert_verifier` previously returned from - * `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must not be - * called twice with the same value. + * `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must + * not be called twice with the same value. */ -void rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifier); +void rustls_client_cert_verifier_free( + struct rustls_client_cert_verifier *verifier); /** - * Create a `rustls_web_pki_client_cert_verifier_builder` using the process-wide default - * cryptography provider. + * Create a `rustls_web_pki_client_cert_verifier_builder` using the + * process-wide default cryptography provider. * - * Caller owns the memory and may eventually call `rustls_web_pki_client_cert_verifier_builder_free` - * to free it, whether or not `rustls_web_pki_client_cert_verifier_builder_build` was called. + * Caller owns the memory and may eventually call + * `rustls_web_pki_client_cert_verifier_builder_free` to free it, whether or + * not `rustls_web_pki_client_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a client certificate verifier that - * will require a client present a client certificate that chains to one of the trust anchors - * in the provided `rustls_root_cert_store`. The root cert store must not be empty. + * Without further modification the builder will produce a client certificate + * verifier that will require a client present a client certificate that chains + * to one of the trust anchors in the provided `rustls_root_cert_store`. The + * root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add certificate revocation - * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed - * for the entire certificate chain unless - * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is used. Unknown - * revocation status for certificates considered for revocation status will be treated as - * an error unless `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add + * certificate revocation lists (CRLs) to the builder. If CRLs are added, + * revocation checking will be performed for the entire certificate chain + * unless + * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is + * used. Unknown revocation status for certificates considered for revocation + * status will be treated as an error unless + * `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is * used. * * Unauthenticated clients will not be permitted unless @@ -2505,7 +2658,9 @@ void rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifi * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new(const struct rustls_root_cert_store *store); +struct rustls_web_pki_client_cert_verifier_builder * +rustls_web_pki_client_cert_verifier_builder_new( + const struct rustls_root_cert_store *store); /** * Create a `rustls_web_pki_client_cert_verifier_builder` using the specified @@ -2515,17 +2670,20 @@ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_v * `rustls_web_pki_client_cert_verifier_builder_free` to free it, whether or * not `rustls_web_pki_client_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a client certificate verifier that - * will require a client present a client certificate that chains to one of the trust anchors - * in the provided `rustls_root_cert_store`. The root cert store must not be empty. + * Without further modification the builder will produce a client certificate + * verifier that will require a client present a client certificate that chains + * to one of the trust anchors in the provided `rustls_root_cert_store`. The + * root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add certificate revocation - * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed - * for the entire certificate chain unless - * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is used. Unknown - * revocation status for certificates considered for revocation status will be treated as - * an error unless `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add + * certificate revocation lists (CRLs) to the builder. If CRLs are added, + * revocation checking will be performed for the entire certificate chain + * unless + * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is + * used. Unknown revocation status for certificates considered for revocation + * status will be treated as an error unless + * `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is * used. * * Unauthenticated clients will not be permitted unless @@ -2534,78 +2692,98 @@ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_v * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider, - const struct rustls_root_cert_store *store); +struct rustls_web_pki_client_cert_verifier_builder * +rustls_web_pki_client_cert_verifier_builder_new_with_provider( + const struct rustls_crypto_provider *provider, + const struct rustls_root_cert_store *store); /** - * Add one or more certificate revocation lists (CRLs) to the client certificate verifier - * builder by reading the CRL content from the provided buffer of PEM encoded content. + * Add one or more certificate revocation lists (CRLs) to the client + * certificate verifier builder by reading the CRL content from the provided + * buffer of PEM encoded content. * - * By default revocation checking will be performed on the entire certificate chain. To only - * check the revocation status of the end entity certificate, use - * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`. + * By default revocation checking will be performed on the entire certificate + * chain. To only check the revocation status of the end entity certificate, + * use `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`. * - * This function returns an error if the provided buffer is not valid PEM encoded content. + * This function returns an error if the provided buffer is not valid PEM + * encoded content. */ -rustls_result rustls_web_pki_client_cert_verifier_builder_add_crl(struct rustls_web_pki_client_cert_verifier_builder *builder, - const uint8_t *crl_pem, - size_t crl_pem_len); +rustls_result rustls_web_pki_client_cert_verifier_builder_add_crl( + struct rustls_web_pki_client_cert_verifier_builder *builder, + const uint8_t *crl_pem, size_t crl_pem_len); /** - * When CRLs are provided with `rustls_web_pki_client_cert_verifier_builder_add_crl`, only - * check the revocation status of end entity certificates, ignoring any intermediate certificates - * in the chain. + * When CRLs are provided with + * `rustls_web_pki_client_cert_verifier_builder_add_crl`, only check the + * revocation status of end entity certificates, ignoring any intermediate + * certificates in the chain. */ -rustls_result rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result +rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation( + struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * When CRLs are provided with `rustls_web_pki_client_cert_verifier_builder_add_crl`, and it - * isn't possible to determine the revocation status of a considered certificate, do not treat + * When CRLs are provided with + * `rustls_web_pki_client_cert_verifier_builder_add_crl`, and it isn't possible + * to determine the revocation status of a considered certificate, do not treat * it as an error condition. * - * Overrides the default behavior where unknown revocation status is considered an error. + * Overrides the default behavior where unknown revocation status is considered + * an error. */ -rustls_result rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result +rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status( + struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Allow unauthenticated anonymous clients in addition to those that present a client - * certificate that chains to one of the verifier's configured trust anchors. + * Allow unauthenticated anonymous clients in addition to those that present a + * client certificate that chains to one of the verifier's configured trust + * anchors. */ -rustls_result rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated(struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result +rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated( + struct rustls_web_pki_client_cert_verifier_builder *builder); /** * Clear the list of trust anchor hint subjects. * - * By default, the client cert verifier will use the subjects provided by the root cert - * store configured for client authentication. Calling this function will remove these - * hint subjects, indicating the client should make a free choice of which certificate - * to send. + * By default, the client cert verifier will use the subjects provided by the + * root cert store configured for client authentication. Calling this function + * will remove these hint subjects, indicating the client should make a free + * choice of which certificate to send. */ -rustls_result rustls_web_pki_client_cert_verifier_clear_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result rustls_web_pki_client_cert_verifier_clear_root_hint_subjects( + struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Add additional distinguished names to the list of trust anchor hint subjects. + * Add additional distinguished names to the list of trust anchor hint + * subjects. * - * By default, the client cert verifier will use the subjects provided by the root cert - * store configured for client authentication. Calling this function will add to these - * existing hint subjects. Calling this function with an empty `store` will have no - * effect, use `rustls_web_pki_client_cert_verifier_clear_root_hint_subjects` to clear - * the subject hints. + * By default, the client cert verifier will use the subjects provided by the + * root cert store configured for client authentication. Calling this function + * will add to these existing hint subjects. Calling this function with an + * empty `store` will have no effect, use + * `rustls_web_pki_client_cert_verifier_clear_root_hint_subjects` to clear the + * subject hints. */ -rustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder, - const struct rustls_root_cert_store *store); +rustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects( + struct rustls_web_pki_client_cert_verifier_builder *builder, + const struct rustls_root_cert_store *store); /** * Create a new client certificate verifier from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The verifier can be used in several `rustls_server_config` instances and must be - * freed by the application when no longer needed. See the documentation of - * `rustls_web_pki_client_cert_verifier_builder_free` for details about lifetime. + * The verifier can be used in several `rustls_server_config` instances and + * must be freed by the application when no longer needed. See the + * documentation of `rustls_web_pki_client_cert_verifier_builder_free` for + * details about lifetime. */ -rustls_result rustls_web_pki_client_cert_verifier_builder_build(struct rustls_web_pki_client_cert_verifier_builder *builder, - struct rustls_client_cert_verifier **verifier_out); +rustls_result rustls_web_pki_client_cert_verifier_builder_build( + struct rustls_web_pki_client_cert_verifier_builder *builder, + struct rustls_client_cert_verifier **verifier_out); /** * Free a `rustls_client_cert_verifier_builder` previously returned from @@ -2613,32 +2791,40 @@ rustls_result rustls_web_pki_client_cert_verifier_builder_build(struct rustls_we * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_web_pki_client_cert_verifier_builder_free(struct rustls_web_pki_client_cert_verifier_builder *builder); +void rustls_web_pki_client_cert_verifier_builder_free( + struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Create a `rustls_web_pki_server_cert_verifier_builder` using the process-wide default - * crypto provider. Caller owns the memory and may free it with + * Create a `rustls_web_pki_server_cert_verifier_builder` using the + * process-wide default crypto provider. Caller owns the memory and may free it + * with * - * Caller owns the memory and may free it with `rustls_web_pki_server_cert_verifier_builder_free`, - * regardless of whether `rustls_web_pki_server_cert_verifier_builder_build` was called. + * Caller owns the memory and may free it with + * `rustls_web_pki_server_cert_verifier_builder_free`, regardless of whether + * `rustls_web_pki_server_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a server certificate verifier that - * will require a server present a certificate that chains to one of the trust anchors - * in the provided `rustls_root_cert_store`. The root cert store must not be empty. + * Without further modification the builder will produce a server certificate + * verifier that will require a server present a certificate that chains to one + * of the trust anchors in the provided `rustls_root_cert_store`. The root cert + * store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add certificate revocation - * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed - * for the entire certificate chain unless - * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is used. Unknown - * revocation status for certificates considered for revocation status will be treated as - * an error unless `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add + * certificate revocation lists (CRLs) to the builder. If CRLs are added, + * revocation checking will be performed for the entire certificate chain + * unless + * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is + * used. Unknown revocation status for certificates considered for revocation + * status will be treated as an error unless + * `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is * used. * * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new(const struct rustls_root_cert_store *store); +struct rustls_web_pki_server_cert_verifier_builder * +rustls_web_pki_server_cert_verifier_builder_new( + const struct rustls_root_cert_store *store); /** * Create a `rustls_web_pki_server_cert_verifier_builder` using the specified @@ -2646,75 +2832,93 @@ struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_v * `rustls_web_pki_server_cert_verifier_builder_free`, regardless of whether * `rustls_web_pki_server_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a server certificate verifier that - * will require a server present a certificate that chains to one of the trust anchors - * in the provided `rustls_root_cert_store`. The root cert store must not be empty. + * Without further modification the builder will produce a server certificate + * verifier that will require a server present a certificate that chains to one + * of the trust anchors in the provided `rustls_root_cert_store`. The root cert + * store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add certificate revocation - * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed - * for the entire certificate chain unless - * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is used. Unknown - * revocation status for certificates considered for revocation status will be treated as - * an error unless `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add + * certificate revocation lists (CRLs) to the builder. If CRLs are added, + * revocation checking will be performed for the entire certificate chain + * unless + * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is + * used. Unknown revocation status for certificates considered for revocation + * status will be treated as an error unless + * `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is * used. Expired CRLs will not be treated as an error unless * `rustls_web_pki_server_cert_verifier_enforce_revocation_expiry` is used. * * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider, - const struct rustls_root_cert_store *store); +struct rustls_web_pki_server_cert_verifier_builder * +rustls_web_pki_server_cert_verifier_builder_new_with_provider( + const struct rustls_crypto_provider *provider, + const struct rustls_root_cert_store *store); /** - * Add one or more certificate revocation lists (CRLs) to the server certificate verifier - * builder by reading the CRL content from the provided buffer of PEM encoded content. + * Add one or more certificate revocation lists (CRLs) to the server + * certificate verifier builder by reading the CRL content from the provided + * buffer of PEM encoded content. * - * By default revocation checking will be performed on the entire certificate chain. To only - * check the revocation status of the end entity certificate, use - * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`. + * By default revocation checking will be performed on the entire certificate + * chain. To only check the revocation status of the end entity certificate, + * use `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`. * - * This function returns an error if the provided buffer is not valid PEM encoded content. + * This function returns an error if the provided buffer is not valid PEM + * encoded content. */ -rustls_result rustls_web_pki_server_cert_verifier_builder_add_crl(struct rustls_web_pki_server_cert_verifier_builder *builder, - const uint8_t *crl_pem, - size_t crl_pem_len); +rustls_result rustls_web_pki_server_cert_verifier_builder_add_crl( + struct rustls_web_pki_server_cert_verifier_builder *builder, + const uint8_t *crl_pem, size_t crl_pem_len); /** - * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, only - * check the revocation status of end entity certificates, ignoring any intermediate certificates - * in the chain. + * When CRLs are provided with + * `rustls_web_pki_server_cert_verifier_builder_add_crl`, only check the + * revocation status of end entity certificates, ignoring any intermediate + * certificates in the chain. */ -rustls_result rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result +rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation( + struct rustls_web_pki_server_cert_verifier_builder *builder); /** - * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, and it - * isn't possible to determine the revocation status of a considered certificate, do not treat + * When CRLs are provided with + * `rustls_web_pki_server_cert_verifier_builder_add_crl`, and it isn't possible + * to determine the revocation status of a considered certificate, do not treat * it as an error condition. * - * Overrides the default behavior where unknown revocation status is considered an error. + * Overrides the default behavior where unknown revocation status is considered + * an error. */ -rustls_result rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result +rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status( + struct rustls_web_pki_server_cert_verifier_builder *builder); /** - * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, and the - * CRL nextUpdate field is in the past, treat it as an error condition. + * When CRLs are provided with + * `rustls_web_pki_server_cert_verifier_builder_add_crl`, and the CRL + * nextUpdate field is in the past, treat it as an error condition. * * Overrides the default behavior where CRL expiration is ignored. */ -rustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry(struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry( + struct rustls_web_pki_server_cert_verifier_builder *builder); /** * Create a new server certificate verifier from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The verifier can be used in several `rustls_client_config` instances and must be - * freed by the application when no longer needed. See the documentation of - * `rustls_web_pki_server_cert_verifier_builder_free` for details about lifetime. + * The verifier can be used in several `rustls_client_config` instances and + * must be freed by the application when no longer needed. See the + * documentation of `rustls_web_pki_server_cert_verifier_builder_free` for + * details about lifetime. */ -rustls_result rustls_web_pki_server_cert_verifier_builder_build(struct rustls_web_pki_server_cert_verifier_builder *builder, - struct rustls_server_cert_verifier **verifier_out); +rustls_result rustls_web_pki_server_cert_verifier_builder_build( + struct rustls_web_pki_server_cert_verifier_builder *builder, + struct rustls_server_cert_verifier **verifier_out); /** * Free a `rustls_server_cert_verifier_builder` previously returned from @@ -2722,39 +2926,49 @@ rustls_result rustls_web_pki_server_cert_verifier_builder_build(struct rustls_we * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_web_pki_server_cert_verifier_builder_free(struct rustls_web_pki_server_cert_verifier_builder *builder); +void rustls_web_pki_server_cert_verifier_builder_free( + struct rustls_web_pki_server_cert_verifier_builder *builder); /** * Create a verifier that uses the default behavior for the current platform. * * This uses [`rustls-platform-verifier`][]. * - * The verifier can be used in several `rustls_client_config` instances and must be freed by - * the application using `rustls_server_cert_verifier_free` when no longer needed. + * The verifier can be used in several `rustls_client_config` instances and + * must be freed by the application using `rustls_server_cert_verifier_free` + * when no longer needed. * - * [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier + * [`rustls-platform-verifier`]: + * https://github.com/rustls/rustls-platform-verifier */ -rustls_result rustls_platform_server_cert_verifier(struct rustls_server_cert_verifier **verifier_out); +rustls_result rustls_platform_server_cert_verifier( + struct rustls_server_cert_verifier **verifier_out); /** * Create a verifier that uses the default behavior for the current platform. * * This uses [`rustls-platform-verifier`][] and the specified crypto provider. * - * The verifier can be used in several `rustls_client_config` instances and must be freed by - * the application using `rustls_server_cert_verifier_free` when no longer needed. + * The verifier can be used in several `rustls_client_config` instances and + * must be freed by the application using `rustls_server_cert_verifier_free` + * when no longer needed. * - * [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier + * [`rustls-platform-verifier`]: + * https://github.com/rustls/rustls-platform-verifier */ -struct rustls_server_cert_verifier *rustls_platform_server_cert_verifier_with_provider(const struct rustls_crypto_provider *provider); +struct rustls_server_cert_verifier * +rustls_platform_server_cert_verifier_with_provider( + const struct rustls_crypto_provider *provider); /** * Free a `rustls_server_cert_verifier` previously returned from - * `rustls_server_cert_verifier_builder_build` or `rustls_platform_server_cert_verifier`. + * `rustls_server_cert_verifier_builder_build` or + * `rustls_platform_server_cert_verifier`. * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_server_cert_verifier_free(struct rustls_server_cert_verifier *verifier); +void rustls_server_cert_verifier_free( + struct rustls_server_cert_verifier *verifier); /** * Returns a static string containing the rustls-ffi version as well as the @@ -2763,4 +2977,4 @@ void rustls_server_cert_verifier_free(struct rustls_server_cert_verifier *verifi */ struct rustls_str rustls_version(void); -#endif /* RUSTLS_H */ +#endif /* RUSTLS_H */ From 9cdf4a67b0bc8e1ce5ede9f5e41924809093f68e Mon Sep 17 00:00:00 2001 From: Tom Stejskal Date: Mon, 31 Mar 2025 11:58:03 +0200 Subject: [PATCH 2/4] Fix compilation error --- librustls/src/connection.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/librustls/src/connection.rs b/librustls/src/connection.rs index 39d9f6d6..efe55a90 100644 --- a/librustls/src/connection.rs +++ b/librustls/src/connection.rs @@ -653,7 +653,7 @@ impl rustls_connection { conn.last_error_msg = Some(format!("{}", e)); return rustls_result::PlaintextEmpty; } - Err(_) => { + Err(e) => { conn.last_error_msg = Some(format!("{}", e)); return rustls_result::Io; } From 0c2848d928776b790c819a9d92bf50d3be271b86 Mon Sep 17 00:00:00 2001 From: Tom Stejskal Date: Mon, 31 Mar 2025 14:09:36 +0200 Subject: [PATCH 3/4] revert formatting of rustls.h --- librustls/src/rustls.h | 1567 +++++++++++++++++----------------------- 1 file changed, 682 insertions(+), 885 deletions(-) diff --git a/librustls/src/rustls.h b/librustls/src/rustls.h index 0571e9d3..a1fbe85b 100644 --- a/librustls/src/rustls.h +++ b/librustls/src/rustls.h @@ -10,8 +10,7 @@ /** * Describes which sort of handshake happened. */ -typedef enum rustls_handshake_kind -{ +typedef enum rustls_handshake_kind { /** * The type of handshake could not be determined. * @@ -22,16 +21,15 @@ typedef enum rustls_handshake_kind * A full TLS handshake. * * This is the typical TLS connection initiation process when resumption is - * not yet unavailable, and the initial client hello was accepted by the - * server. + * not yet unavailable, and the initial client hello was accepted by the server. */ RUSTLS_HANDSHAKE_KIND_FULL = 1, /** * A full TLS handshake, with an extra round-trip for a hello retry request. * - * The server can respond with a hello retry request (HRR) if the initial - * client hello is unacceptable for several reasons, the most likely if no - * supported key shares were offered by the client. + * The server can respond with a hello retry request (HRR) if the initial client + * hello is unacceptable for several reasons, the most likely if no supported key + * shares were offered by the client. */ RUSTLS_HANDSHAKE_KIND_FULL_WITH_HELLO_RETRY_REQUEST = 2, /** @@ -47,8 +45,7 @@ typedef enum rustls_handshake_kind /** * Numeric error codes returned from rustls-ffi API functions. */ -enum rustls_result -{ +enum rustls_result { RUSTLS_RESULT_OK = 7000, RUSTLS_RESULT_IO = 7001, RUSTLS_RESULT_NULL_PARAMETER = 7002, @@ -178,8 +175,7 @@ typedef uint32_t rustls_result; /** * Definitions of known TLS protocol versions. */ -typedef enum rustls_tls_version -{ +typedef enum rustls_tls_version { RUSTLS_TLS_VERSION_UNKNOWN = 0, RUSTLS_TLS_VERSION_SSLV2 = 512, RUSTLS_TLS_VERSION_SSLV3 = 768, @@ -214,9 +210,8 @@ typedef struct rustls_accepted_alert rustls_accepted_alert; * * In particular, if a server wants to do some potentially expensive work * to load a certificate for a given hostname, rustls_acceptor allows doing - * that asynchronously, as opposed to - * rustls_server_config_builder_set_hello_callback(), which doesn't work well - * for asynchronous I/O. + * that asynchronously, as opposed to rustls_server_config_builder_set_hello_callback(), + * which doesn't work well for asynchronous I/O. * * The general flow is: * - rustls_acceptor_new() @@ -251,9 +246,8 @@ typedef struct rustls_certificate rustls_certificate; typedef struct rustls_certified_key rustls_certified_key; /** - * A built client certificate verifier that can be provided to a - * `rustls_server_config_builder` with - * `rustls_server_config_builder_set_client_verifier`. + * A built client certificate verifier that can be provided to a `rustls_server_config_builder` + * with `rustls_server_config_builder_set_client_verifier`. */ typedef struct rustls_client_cert_verifier rustls_client_cert_verifier; @@ -268,10 +262,9 @@ typedef struct rustls_client_config rustls_client_config; /** * 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. + * 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. @@ -300,8 +293,8 @@ typedef struct rustls_crypto_provider_builder rustls_crypto_provider_builder; /** * A collection of supported Hybrid Public Key Encryption (HPKE) suites. * - * `rustls_hpke` can be provided to `rustls_client_config_builder_enable_ech` - * and `rustls_client_config_builder_enable_ech_grease()` to customize a + * `rustls_hpke` can be provided to `rustls_client_config_builder_enable_ech` and + * `rustls_client_config_builder_enable_ech_grease()` to customize a * `rustls_client_config_builder` to use Encrypted Client Hello (ECH). */ typedef struct rustls_hpke rustls_hpke; @@ -325,16 +318,15 @@ typedef struct rustls_root_cert_store rustls_root_cert_store; * A `rustls_root_cert_store` being constructed. * * A builder can be modified by adding trust anchor root certificates with - * `rustls_root_cert_store_builder_add_pem`. Once you're done adding root - * certificates, call `rustls_root_cert_store_builder_build` to turn it into a - * `rustls_root_cert_store`. This object is not safe for concurrent mutation. + * `rustls_root_cert_store_builder_add_pem`. Once you're done adding root certificates, + * call `rustls_root_cert_store_builder_build` to turn it into a `rustls_root_cert_store`. + * This object is not safe for concurrent mutation. */ typedef struct rustls_root_cert_store_builder rustls_root_cert_store_builder; /** - * A built server certificate verifier that can be provided to a - * `rustls_client_config_builder` with - * `rustls_client_config_builder_set_server_verifier`. + * A built server certificate verifier that can be provided to a `rustls_client_config_builder` + * with `rustls_client_config_builder_set_server_verifier`. */ typedef struct rustls_server_cert_verifier rustls_server_cert_verifier; @@ -413,39 +405,30 @@ typedef struct rustls_supported_ciphersuite rustls_supported_ciphersuite; /** * A client certificate verifier being constructed. * - * A builder can be modified by, e.g. - * `rustls_web_pki_client_cert_verifier_builder_add_crl`. + * A builder can be modified by, e.g. `rustls_web_pki_client_cert_verifier_builder_add_crl`. * - * Once you're done configuring settings, call - * `rustls_web_pki_client_cert_verifier_builder_build` to turn it into a - * `rustls_client_cert_verifier`. + * Once you're done configuring settings, call `rustls_web_pki_client_cert_verifier_builder_build` + * to turn it into a `rustls_client_cert_verifier`. * * This object is not safe for concurrent mutation. * - * See - * + * See * for more information. */ -typedef struct rustls_web_pki_client_cert_verifier_builder - rustls_web_pki_client_cert_verifier_builder; +typedef struct rustls_web_pki_client_cert_verifier_builder rustls_web_pki_client_cert_verifier_builder; /** * A server certificate verifier being constructed. * - * A builder can be modified by, e.g. - * `rustls_web_pki_server_cert_verifier_builder_add_crl`. + * A builder can be modified by, e.g. `rustls_web_pki_server_cert_verifier_builder_add_crl`. * - * Once you're done configuring settings, call - * `rustls_web_pki_server_cert_verifier_builder_build` to turn it into a - * `rustls_server_cert_verifier`. This object is not safe for concurrent - * mutation. + * Once you're done configuring settings, call `rustls_web_pki_server_cert_verifier_builder_build` + * to turn it into a `rustls_server_cert_verifier`. This object is not safe for concurrent mutation. * - * See - * + * See * for more information. */ -typedef struct rustls_web_pki_server_cert_verifier_builder - rustls_web_pki_server_cert_verifier_builder; +typedef struct rustls_web_pki_server_cert_verifier_builder rustls_web_pki_server_cert_verifier_builder; /** * A return value for a function that may return either success (0) or a @@ -459,29 +442,29 @@ typedef int rustls_io_result; /** * A callback for `rustls_connection_read_tls`. * - * An implementation of this callback should attempt to read up to n bytes from - * the network, storing them in `buf`. If any bytes were stored, the - * implementation should set out_n to the number of bytes stored and return 0. + * An implementation of this callback should attempt to read up to n bytes from the + * network, storing them in `buf`. If any bytes were stored, the implementation should + * set out_n to the number of bytes stored and return 0. * - * If there was an error, the implementation should return a nonzero - * rustls_io_result, which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero rustls_io_result, + * which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one read attempt to the network per call. Additional reads - * will be triggered by subsequent calls to one of the `_read_tls` methods. + * It's best to make one read attempt to the network per call. Additional reads will + * be triggered by subsequent calls to one of the `_read_tls` methods. * * `userdata` is set to the value provided to `rustls_connection_set_userdata`. - * In most cases that should be a struct that contains, at a minimum, a file - * descriptor. + * In most cases that should be a struct that contains, at a minimum, a file descriptor. * - * The buf and out_n pointers are borrowed and should not be retained across - * calls. + * The buf and out_n pointers are borrowed and should not be retained across calls. */ -typedef rustls_io_result (*rustls_read_callback)(void *userdata, uint8_t *buf, - size_t n, size_t *out_n); +typedef rustls_io_result (*rustls_read_callback)(void *userdata, + uint8_t *buf, + size_t n, + size_t *out_n); /** * A read-only view on a Rust `&str`. @@ -499,8 +482,7 @@ typedef rustls_io_result (*rustls_read_callback)(void *userdata, uint8_t *buf, * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_str -{ +typedef struct rustls_str { const char *data; size_t len; } rustls_str; @@ -518,41 +500,38 @@ typedef struct rustls_str * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_slice_bytes -{ +typedef struct rustls_slice_bytes { const uint8_t *data; size_t len; } rustls_slice_bytes; /** - * A callback for `rustls_connection_write_tls` or - * `rustls_accepted_alert_write_tls`. + * A callback for `rustls_connection_write_tls` or `rustls_accepted_alert_write_tls`. * - * An implementation of this callback should attempt to write the `n` bytes in - * buf to the network. + * An implementation of this callback should attempt to write the `n` bytes in buf + * to the network. * - * If any bytes were written, the implementation should set `out_n` to the - * number of bytes stored and return 0. + * If any bytes were written, the implementation should set `out_n` to the number of + * bytes stored and return 0. * - * If there was an error, the implementation should return a nonzero - * `rustls_io_result`, which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero `rustls_io_result`, + * which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one write attempt to the network per call. Additional - * writes will be triggered by subsequent calls to rustls_connection_write_tls. + * It's best to make one write attempt to the network per call. Additional writes will + * be triggered by subsequent calls to rustls_connection_write_tls. * - * `userdata` is set to the value provided to `rustls_connection_set_userdata`. - * In most cases that should be a struct that contains, at a minimum, a file - * descriptor. + * `userdata` is set to the value provided to `rustls_connection_set_userdata`. In most + * cases that should be a struct that contains, at a minimum, a file descriptor. * - * The buf and out_n pointers are borrowed and should not be retained across - * calls. + * The buf and out_n pointers are borrowed and should not be retained across calls. */ typedef rustls_io_result (*rustls_write_callback)(void *userdata, - const uint8_t *buf, size_t n, + const uint8_t *buf, + size_t n, size_t *out_n); /** @@ -570,8 +549,7 @@ typedef void *rustls_verify_server_cert_user_data; * server_name can contain a hostname, an IPv4 address in textual form, or an * IPv6 address in textual form. */ -typedef struct rustls_verify_server_cert_params -{ +typedef struct rustls_verify_server_cert_params { struct rustls_slice_bytes end_entity_cert_der; const struct rustls_slice_slice_bytes *intermediate_certs_der; struct rustls_str server_name; @@ -581,9 +559,8 @@ typedef struct rustls_verify_server_cert_params /** * A callback that is invoked to verify a server certificate. */ -typedef uint32_t (*rustls_verify_server_cert_callback)( - rustls_verify_server_cert_user_data userdata, - const struct rustls_verify_server_cert_params *params); +typedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata, + const struct rustls_verify_server_cert_params *params); /** * An optional callback for logging key material. @@ -618,8 +595,7 @@ typedef size_t rustls_log_level; /** * Parameter structure passed to a `rustls_log_callback`. */ -typedef struct rustls_log_params -{ +typedef struct rustls_log_params { /** * The log level the message was logged at. */ @@ -633,8 +609,7 @@ typedef struct rustls_log_params /** * A callback that is invoked for messages logged by rustls. */ -typedef void (*rustls_log_callback)(void *userdata, - const struct rustls_log_params *params); +typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params); /** * A callback for `rustls_connection_write_tls_vectored`. @@ -642,29 +617,28 @@ typedef void (*rustls_log_callback)(void *userdata, * An implementation of this callback should attempt to write the bytes in * the given `count` iovecs to the network. * - * If any bytes were written, the implementation should set out_n to the number - * of bytes written and return 0. + * If any bytes were written, the implementation should set out_n to the number of + * bytes written and return 0. * - * If there was an error, the implementation should return a nonzero - * rustls_io_result, which will be passed through to the caller. + * If there was an error, the implementation should return a nonzero rustls_io_result, + * which will be passed through to the caller. * * On POSIX systems, returning `errno` is convenient. * * On other systems, any appropriate error code works. * - * It's best to make one write attempt to the network per call. Additional - * write will be triggered by subsequent calls to one of the `_write_tls` - * methods. + * It's best to make one write attempt to the network per call. Additional write will + * be triggered by subsequent calls to one of the `_write_tls` methods. * - * `userdata` is set to the value provided to `rustls_*_session_set_userdata`. - * In most cases that should be a struct that contains, at a minimum, a file - * descriptor. + * `userdata` is set to the value provided to `rustls_*_session_set_userdata`. In most + * cases that should be a struct that contains, at a minimum, a file descriptor. * - * The iov and out_n pointers are borrowed and should not be retained across - * calls. + * The iov and out_n pointers are borrowed and should not be retained across calls. */ -typedef rustls_io_result (*rustls_write_vectored_callback)( - void *userdata, const struct rustls_iovec *iov, size_t count, size_t *out_n); +typedef rustls_io_result (*rustls_write_vectored_callback)(void *userdata, + const struct rustls_iovec *iov, + size_t count, + size_t *out_n); /** * Any context information the callback will receive when invoked. @@ -684,8 +658,7 @@ typedef void *rustls_client_hello_userdata; * Functions that receive one of these must not dereference the data pointer * beyond the allowed lifetime. */ -typedef struct rustls_slice_u16 -{ +typedef struct rustls_slice_u16 { const uint16_t *data; size_t len; } rustls_slice_u16; @@ -698,23 +671,20 @@ typedef struct rustls_slice_u16 * `rustls_string` will be 0. * * `signature_schemes` carries the values supplied by the client or, if the - * client did not send this TLS extension, the default schemes in the rustls - * library. See: + * client did not send this TLS extension, the default schemes in the rustls library. See: * . * * `alpn` carries the list of ALPN protocol names that the client proposed to * the server. Again, the length of this list will be 0 if none were supplied. * * All this data, when passed to a callback function, is only accessible during - * the call and may not be modified. Users of this API must copy any values - * that they want to access when the callback returned. + * the call and may not be modified. Users of this API must copy any values that + * they want to access when the callback returned. * - * 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. + * 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. */ -typedef struct rustls_client_hello -{ +typedef struct rustls_client_hello { struct rustls_str server_name; struct rustls_slice_u16 signature_schemes; const struct rustls_slice_slice_bytes *alpn; @@ -729,24 +699,21 @@ typedef struct rustls_client_hello * * `userdata` will be set based on rustls_connection_set_userdata. * - * `hello` gives the value of the available client announcements, as - * interpreted by rustls. See the definition of `rustls_client_hello` for - * details. + * `hello` gives the value of the available client announcements, as interpreted + * by rustls. See the definition of `rustls_client_hello` for details. * * NOTE: * - the passed in `hello` and all its values are only available during the * callback invocations. - * - the passed callback function must be safe to call multiple times - * concurrently with the same userdata, unless there is only a single config - * and connection where it is installed. + * - the passed callback function must be safe to call multiple times concurrently + * with the same userdata, unless there is only a single config and connection + * where it is installed. * - * 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. + * 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. */ -typedef const struct rustls_certified_key *(*rustls_client_hello_callback)( - rustls_client_hello_userdata userdata, - const struct rustls_client_hello *hello); +typedef const struct rustls_certified_key *(*rustls_client_hello_callback)(rustls_client_hello_userdata userdata, + const struct rustls_client_hello *hello); /** * Any context information the callback will receive when invoked. @@ -760,8 +727,7 @@ typedef void *rustls_session_store_userdata; * This callback will be invoked by a TLS session when looking up the data * for a TLS session id. * - * `userdata` will be supplied based on - * rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. * * The `buf` points to `count` consecutive bytes where the * callback is expected to copy the result to. The number of copied bytes @@ -784,9 +750,12 @@ typedef void *rustls_session_store_userdata; * NOTE: callbacks used in several sessions via a common config * must be implemented thread-safe. */ -typedef uint32_t (*rustls_session_store_get_callback)( - rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, - int remove_after, uint8_t *buf, size_t count, size_t *out_n); +typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userdata userdata, + const struct rustls_slice_bytes *key, + int remove_after, + uint8_t *buf, + size_t count, + size_t *out_n); /** * Prototype of a callback that can be installed by the application at the @@ -796,8 +765,7 @@ typedef uint32_t (*rustls_session_store_get_callback)( * been created and an id for later use is handed to the client/has * been received from the server. * - * `userdata` will be supplied based on - * rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. * * The callback should return RUSTLS_RESULT_OK to indicate that a value was * successfully stored, or RUSTLS_RESULT_IO on failure. @@ -807,9 +775,9 @@ typedef uint32_t (*rustls_session_store_get_callback)( * NOTE: callbacks used in several sessions via a common config * must be implemented thread-safe. */ -typedef uint32_t (*rustls_session_store_put_callback)( - rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, - const struct rustls_slice_bytes *val); +typedef uint32_t (*rustls_session_store_put_callback)(rustls_session_store_userdata userdata, + const struct rustls_slice_bytes *key, + const struct rustls_slice_bytes *val); /** * Rustls' list of supported protocol versions. The length of the array is @@ -883,7 +851,8 @@ void rustls_acceptor_free(struct rustls_acceptor *acceptor); */ rustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor, rustls_read_callback callback, - void *userdata, size_t *out_n); + void *userdata, + size_t *out_n); /** * Parse all TLS bytes read so far. @@ -911,8 +880,8 @@ rustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor, * - RUSTLS_RESULT_OK: a ClientHello has successfully been parsed. * A pointer to a newly allocated rustls_accepted has been written to * *out_accepted. - * - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been - * read. Read more TLS bytes to continue. + * - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been read. + * Read more TLS bytes to continue. * - Any other rustls_result: the TLS bytes read so far cannot be parsed * as a ClientHello, and reading additional bytes won't help. * @@ -952,8 +921,7 @@ rustls_result rustls_acceptor_accept(struct rustls_acceptor *acceptor, * - The `accepted` parameter was already transformed into a connection * with rustls_accepted_into_connection. */ -struct rustls_str rustls_accepted_server_name( - const struct rustls_accepted *accepted); +struct rustls_str rustls_accepted_server_name(const struct rustls_accepted *accepted); /** * Get the i'th in the list of signature schemes offered in the ClientHello. @@ -969,16 +937,15 @@ struct rustls_str rustls_accepted_server_name( * * Returns: * - * A TLS Signature Scheme from - * + * A TLS Signature Scheme from * * This will be 0 in these cases: * - i is greater than the number of available cipher suites. * - accepted is NULL. * - rustls_accepted_into_connection has already been called with `accepted`. */ -uint16_t rustls_accepted_signature_scheme( - const struct rustls_accepted *accepted, size_t i); +uint16_t rustls_accepted_signature_scheme(const struct rustls_accepted *accepted, + size_t i); /** * Get the i'th in the list of cipher suites offered in the ClientHello. @@ -990,8 +957,7 @@ uint16_t rustls_accepted_signature_scheme( * * Returns: * - * A cipher suite value from - * + * A cipher suite value from * * This will be 0 in these cases: * - i is greater than the number of available cipher suites. @@ -1029,8 +995,7 @@ uint16_t rustls_accepted_cipher_suite(const struct rustls_accepted *accepted, * If you are calling this from Rust, note that the `'static` lifetime * in the return signature is fake and must not be relied upon. */ -struct rustls_slice_bytes rustls_accepted_alpn( - const struct rustls_accepted *accepted, size_t i); +struct rustls_slice_bytes rustls_accepted_alpn(const struct rustls_accepted *accepted, size_t i); /** * Turn a rustls_accepted into a rustls_connection, given the provided @@ -1077,10 +1042,10 @@ struct rustls_slice_bytes rustls_accepted_alpn( * rustls_connection may hold a reference to it until it is done. * See the documentation for rustls_connection for details. */ -rustls_result rustls_accepted_into_connection( - struct rustls_accepted *accepted, const struct rustls_server_config *config, - struct rustls_connection **out_conn, - struct rustls_accepted_alert **out_alert); +rustls_result rustls_accepted_into_connection(struct rustls_accepted *accepted, + const struct rustls_server_config *config, + struct rustls_connection **out_conn, + struct rustls_accepted_alert **out_alert); /** * Free a rustls_accepted. @@ -1105,13 +1070,14 @@ void rustls_accepted_free(struct rustls_accepted *accepted); * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. * - * Returns 0 for success, or an errno value on error. Passes through return - * values from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for + * Returns 0 for success, or an errno value on error. Passes through return values + * from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for * more details. */ -rustls_io_result rustls_accepted_alert_write_tls( - struct rustls_accepted_alert *accepted_alert, rustls_write_callback callback, - void *userdata, size_t *out_n); +rustls_io_result rustls_accepted_alert_write_tls(struct rustls_accepted_alert *accepted_alert, + rustls_write_callback callback, + void *userdata, + size_t *out_n); /** * Free a rustls_accepted_alert. @@ -1164,10 +1130,11 @@ rustls_result rustls_certificate_get_der(const struct rustls_certificate *cert, * `rustls_certified_key`'s memory will automatically be released when * the `rustls_server_config` is freed. */ -rustls_result rustls_certified_key_build( - const uint8_t *cert_chain, size_t cert_chain_len, const uint8_t *private_key, - size_t private_key_len, - const struct rustls_certified_key **certified_key_out); +rustls_result rustls_certified_key_build(const uint8_t *cert_chain, + size_t cert_chain_len, + const uint8_t *private_key, + size_t private_key_len, + const struct rustls_certified_key **certified_key_out); /** * Build a `rustls_certified_key` from a certificate chain and a @@ -1199,23 +1166,22 @@ rustls_result rustls_certified_key_build( * `rustls_certified_key`'s memory will automatically be released when * the `rustls_server_config` is freed. */ -rustls_result rustls_certified_key_build_with_signing_key( - const uint8_t *cert_chain, size_t cert_chain_len, - struct rustls_signing_key *signing_key, - const struct rustls_certified_key **certified_key_out); +rustls_result rustls_certified_key_build_with_signing_key(const uint8_t *cert_chain, + size_t cert_chain_len, + struct rustls_signing_key *signing_key, + const struct rustls_certified_key **certified_key_out); /** * Return the i-th rustls_certificate in the rustls_certified_key. * - * 0 gives the end-entity certificate. 1 and higher give certificates from the - * chain. + * 0 gives the end-entity certificate. 1 and higher give certificates from the chain. * * Indexes higher than the last available certificate return NULL. * * The returned certificate is valid until the rustls_certified_key is freed. */ -const struct rustls_certificate *rustls_certified_key_get_certificate( - const struct rustls_certified_key *certified_key, size_t i); +const struct rustls_certificate *rustls_certified_key_get_certificate(const struct rustls_certified_key *certified_key, + size_t i); /** * Create a copy of the rustls_certified_key with the given OCSP response data @@ -1227,31 +1193,26 @@ const struct rustls_certificate *rustls_certified_key_get_certificate( * The cloned key is independent from its original and needs to be freed * by the application. */ -rustls_result rustls_certified_key_clone_with_ocsp( - const struct rustls_certified_key *certified_key, - const struct rustls_slice_bytes *ocsp_response, - const struct rustls_certified_key **cloned_key_out); +rustls_result rustls_certified_key_clone_with_ocsp(const struct rustls_certified_key *certified_key, + const struct rustls_slice_bytes *ocsp_response, + const struct rustls_certified_key **cloned_key_out); /** - * Verify the consistency of this `rustls_certified_key`'s public and private - * keys. + * Verify the consistency of this `rustls_certified_key`'s public and private keys. * - * This is done by performing a comparison of subject public key information - * (SPKI) bytes between the certificate and private key. + * This is done by performing a comparison of subject public key information (SPKI) bytes + * between the certificate and private key. * - * If the private key matches the certificate this function returns - * `RUSTLS_RESULT_OK`, otherwise an error `rustls_result` is returned. + * If the private key matches the certificate this function returns `RUSTLS_RESULT_OK`, + * otherwise an error `rustls_result` is returned. */ -rustls_result rustls_certified_key_keys_match( - const struct rustls_certified_key *key); +rustls_result rustls_certified_key_keys_match(const struct rustls_certified_key *key); /** - * "Free" a certified_key previously returned from - * `rustls_certified_key_build`. + * "Free" a certified_key previously returned from `rustls_certified_key_build`. * * Since certified_key is actually an atomically reference-counted pointer, - * extant certified_key may still hold an internal reference to the Rust - * object. + * extant certified_key may still hold an internal reference to the Rust object. * * However, C code must consider this pointer unusable after "free"ing it. * @@ -1262,15 +1223,13 @@ void rustls_certified_key_free(const struct rustls_certified_key *key); /** * Create a `rustls_root_cert_store_builder`. * - * Caller owns the memory and may free it with `rustls_root_cert_store_free`, - * regardless of whether `rustls_root_cert_store_builder_build` was called. + * Caller owns the memory and may free it with `rustls_root_cert_store_free`, regardless of + * whether `rustls_root_cert_store_builder_build` was called. * - * If you wish to abandon the builder without calling - * `rustls_root_cert_store_builder_build`, it must be freed with - * `rustls_root_cert_store_builder_free`. + * If you wish to abandon the builder without calling `rustls_root_cert_store_builder_build`, + * it must be freed with `rustls_root_cert_store_builder_free`. */ -struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new( - void); +struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void); /** * Add one or more certificates to the root cert store builder using PEM @@ -1283,9 +1242,10 @@ struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new( * This may be useful on systems that have syntactically invalid root * certificates. */ -rustls_result rustls_root_cert_store_builder_add_pem( - struct rustls_root_cert_store_builder *builder, const uint8_t *pem, - size_t pem_len, bool strict); +rustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_store_builder *builder, + const uint8_t *pem, + size_t pem_len, + bool strict); /** * Add one or more certificates to the root cert store builder using PEM @@ -1298,23 +1258,21 @@ rustls_result rustls_root_cert_store_builder_add_pem( * This may be useful on systems that have syntactically invalid root * certificates. */ -rustls_result rustls_root_cert_store_builder_load_roots_from_file( - struct rustls_root_cert_store_builder *builder, const char *filename, - bool strict); +rustls_result rustls_root_cert_store_builder_load_roots_from_file(struct rustls_root_cert_store_builder *builder, + const char *filename, + bool strict); /** * Create a new `rustls_root_cert_store` from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The root cert store can be used in several - * `rustls_web_pki_client_cert_verifier_builder_new` instances and must be - * freed by the application when no longer needed. See the documentation of + * The root cert store can be used in several `rustls_web_pki_client_cert_verifier_builder_new` + * instances and must be freed by the application when no longer needed. See the documentation of * `rustls_root_cert_store_free` for details about lifetime. */ -rustls_result rustls_root_cert_store_builder_build( - struct rustls_root_cert_store_builder *builder, - const struct rustls_root_cert_store **root_cert_store_out); +rustls_result rustls_root_cert_store_builder_build(struct rustls_root_cert_store_builder *builder, + const struct rustls_root_cert_store **root_cert_store_out); /** * Free a `rustls_root_cert_store_builder` previously returned from @@ -1322,78 +1280,68 @@ rustls_result rustls_root_cert_store_builder_build( * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_root_cert_store_builder_free( - struct rustls_root_cert_store_builder *builder); +void rustls_root_cert_store_builder_free(struct rustls_root_cert_store_builder *builder); /** - * Free a rustls_root_cert_store previously returned from - * rustls_root_cert_store_builder_build. + * Free a rustls_root_cert_store previously returned from rustls_root_cert_store_builder_build. * * Calling with NULL is fine. Must not be called twice with the same value. */ void rustls_root_cert_store_free(const struct rustls_root_cert_store *store); /** - * Return a 16-bit unsigned integer corresponding to this cipher suite's - * assignment from + * Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from * . * * The bytes from the assignment are interpreted in network order. */ -uint16_t rustls_supported_ciphersuite_get_suite( - const struct rustls_supported_ciphersuite *supported_ciphersuite); +uint16_t rustls_supported_ciphersuite_get_suite(const struct rustls_supported_ciphersuite *supported_ciphersuite); /** * Returns the name of the ciphersuite as a `rustls_str`. * * If the provided ciphersuite is invalid, the `rustls_str` will contain the - * empty string. The lifetime of the `rustls_str` is the lifetime of the - * program, it does not need to be freed. + * empty string. The lifetime of the `rustls_str` is the lifetime of the program, + * it does not need to be freed. */ -struct rustls_str rustls_supported_ciphersuite_get_name( - const struct rustls_supported_ciphersuite *supported_ciphersuite); +struct rustls_str rustls_supported_ciphersuite_get_name(const struct rustls_supported_ciphersuite *supported_ciphersuite); /** * Returns the `rustls_tls_version` of the ciphersuite. * * See also `RUSTLS_ALL_VERSIONS`. */ -enum rustls_tls_version rustls_supported_ciphersuite_protocol_version( - const struct rustls_supported_ciphersuite *supported_ciphersuite); +enum rustls_tls_version rustls_supported_ciphersuite_protocol_version(const struct rustls_supported_ciphersuite *supported_ciphersuite); /** - * Create a rustls_client_config_builder using the process default crypto - * provider. + * 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`. + * 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 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. + * rustls_client_config_builder_load_roots_from_file or provide a custom verifier. */ struct rustls_client_config_builder *rustls_client_config_builder_new(void); /** * 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`. + * 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 + * `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. * @@ -1404,9 +1352,10 @@ struct rustls_client_config_builder *rustls_client_config_builder_new(void); * Ciphersuites are configured separately via the crypto provider. See * `rustls_crypto_provider_builder_set_cipher_suites` for more information. */ -rustls_result rustls_client_config_builder_new_custom( - const struct rustls_crypto_provider *provider, const uint16_t *tls_versions, - size_t tls_versions_len, struct rustls_client_config_builder **builder_out); +rustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto_provider *provider, + const uint16_t *tls_versions, + size_t tls_versions_len, + struct rustls_client_config_builder **builder_out); /** * Set a custom server certificate verifier using the builder crypto provider. @@ -1437,25 +1386,22 @@ rustls_result rustls_client_config_builder_new_custom( * * */ -rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier( - struct rustls_client_config_builder *config_builder, - rustls_verify_server_cert_callback callback); +rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier(struct rustls_client_config_builder *config_builder, + rustls_verify_server_cert_callback callback); /** * Configure the server certificate verifier. * - * This increases the reference count of `verifier` and does not take - * ownership. + * This increases the reference count of `verifier` and does not take ownership. */ -void rustls_client_config_builder_set_server_verifier( - struct rustls_client_config_builder *builder, - const struct rustls_server_cert_verifier *verifier); +void rustls_client_config_builder_set_server_verifier(struct rustls_client_config_builder *builder, + const struct rustls_server_cert_verifier *verifier); /** * 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. + * `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. @@ -1468,16 +1414,16 @@ void rustls_client_config_builder_set_server_verifier( * * */ -rustls_result rustls_client_config_builder_set_alpn_protocols( - struct rustls_client_config_builder *builder, - const struct rustls_slice_bytes *protocols, size_t len); +rustls_result rustls_client_config_builder_set_alpn_protocols(struct rustls_client_config_builder *builder, + const struct rustls_slice_bytes *protocols, + size_t len); /** * Enable or disable SNI. * */ -void rustls_client_config_builder_set_enable_sni( - struct rustls_client_config_builder *config, bool enable); +void rustls_client_config_builder_set_enable_sni(struct rustls_client_config_builder *config, + bool enable); /** * Provide the configuration a list of certificates where the connection @@ -1495,142 +1441,128 @@ void rustls_client_config_builder_set_enable_sni( * EXPERIMENTAL: installing a client authentication callback will replace any * configured certified keys and vice versa. */ -rustls_result rustls_client_config_builder_set_certified_key( - struct rustls_client_config_builder *builder, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len); +rustls_result rustls_client_config_builder_set_certified_key(struct rustls_client_config_builder *builder, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len); /** - * Log key material to the file specified by the `SSLKEYLOGFILE` environment - * variable. + * Log key material to the file specified by the `SSLKEYLOGFILE` environment variable. * * The key material will be logged in the NSS key log format, - * - * and is compatible with tools like Wireshark. + * 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. + * 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`. + * For more control over which secrets are logged, or to customize the format, prefer + * `rustls_client_config_builder_set_key_log`. */ -rustls_result rustls_client_config_builder_set_key_log_file( - struct rustls_client_config_builder *builder); +rustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client_config_builder *builder); /** * 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: + * 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: * * - * 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. + * 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. + * 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. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_set_key_log( - struct rustls_client_config_builder *builder, - rustls_keylog_log_callback log_cb, - rustls_keylog_will_log_callback will_log_cb); +rustls_result rustls_client_config_builder_set_key_log(struct rustls_client_config_builder *builder, + rustls_keylog_log_callback log_cb, + rustls_keylog_will_log_callback will_log_cb); /** * 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. + * 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. + * 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`. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_enable_ech( - struct rustls_client_config_builder *builder, - const uint8_t *ech_config_list_bytes, size_t ech_config_list_bytes_size, - const struct rustls_hpke *hpke); +rustls_result rustls_client_config_builder_enable_ech(struct rustls_client_config_builder *builder, + const uint8_t *ech_config_list_bytes, + size_t ech_config_list_bytes_size, + const struct rustls_hpke *hpke); /** * 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. + * 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. + * 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. + * 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. */ -rustls_result rustls_client_config_builder_enable_ech_grease( - struct rustls_client_config_builder *builder, - const struct rustls_hpke *hpke); +rustls_result rustls_client_config_builder_enable_ech_grease(struct rustls_client_config_builder *builder, + const struct rustls_hpke *hpke); /** - * Turn a *rustls_client_config_builder (mutable) into a const - * *rustls_client_config (read-only). + * Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config + * (read-only). */ -rustls_result rustls_client_config_builder_build( - struct rustls_client_config_builder *builder, - const struct rustls_client_config **config_out); +rustls_result rustls_client_config_builder_build(struct rustls_client_config_builder *builder, + const struct rustls_client_config **config_out); /** - * "Free" a client_config_builder without building it into a - * rustls_client_config. + * "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. + * 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. + * Use free only when the building of a config has to be aborted before a config + * was created. */ -void rustls_client_config_builder_free( - struct rustls_client_config_builder *config); +void rustls_client_config_builder_free(struct rustls_client_config_builder *config); /** - * Returns true if a `rustls_connection` created from the - * `rustls_client_config` will operate in FIPS mode. + * Returns true if a `rustls_connection` created from the `rustls_client_config` will + * operate in FIPS mode. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration - * that NIST recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration that NIST + * recommends, as well as ECH HPKE suites if applicable. */ bool rustls_client_config_fips(const struct rustls_client_config *config); @@ -1638,9 +1570,8 @@ bool rustls_client_config_fips(const struct rustls_client_config *config); * "Free" a `rustls_client_config` previously returned from * `rustls_client_config_builder_build`. * - * Since `rustls_client_config` is actually an atomically reference-counted - * pointer, extant client connections may still hold an internal reference to - * the Rust object. + * Since `rustls_client_config` is actually an atomically reference-counted pointer, + * extant client connections may still hold an internal reference to the Rust object. * * However, C code must consider this pointer unusable after "free"ing it. * @@ -1657,48 +1588,46 @@ void rustls_client_config_free(const struct rustls_client_config *config); * * If this returns a non-error, the memory pointed to by `conn_out` * is modified to point at a valid `rustls_connection`. The caller now owns - * the `rustls_connection` and must call `rustls_connection_free` when done - * with it. + * the `rustls_connection` and must call `rustls_connection_free` when done with it. * * The server_name parameter can contain a hostname or an IP address in * textual form (IPv4 or IPv6). This function will return an error if it * cannot be parsed as one of those types. */ -rustls_result rustls_client_connection_new( - const struct rustls_client_config *config, const char *server_name, - struct rustls_connection **conn_out); +rustls_result rustls_client_connection_new(const struct rustls_client_config *config, + const char *server_name, + struct rustls_connection **conn_out); /** - * Set the userdata pointer associated with this connection. This will be - * passed to any callbacks invoked by the connection, if you've set up - * callbacks in the config. The pointed-to data must outlive the connection. + * Set the userdata pointer associated with this connection. This will be passed + * to any callbacks invoked by the connection, if you've set up callbacks in the config. + * The pointed-to data must outlive the connection. */ -void rustls_connection_set_userdata(struct rustls_connection *conn, - void *userdata); +void rustls_connection_set_userdata(struct rustls_connection *conn, void *userdata); /** - * Set the logging callback for this connection. The log callback will be - * invoked with the userdata parameter previously set by - * rustls_connection_set_userdata, or NULL if no userdata was set. + * Set the logging callback for this connection. The log callback will be invoked + * with the userdata parameter previously set by rustls_connection_set_userdata, or + * NULL if no userdata was set. */ -void rustls_connection_set_log_callback(struct rustls_connection *conn, - rustls_log_callback cb); +void rustls_connection_set_log_callback(struct rustls_connection *conn, rustls_log_callback cb); /** - * Read some TLS bytes from the network into internal buffers. The actual - * network I/O is performed by `callback`, which you provide. Rustls will - * invoke your callback with a suitable buffer to store the read bytes into. - * You don't have to fill it up, just fill with as many bytes as you get in one - * syscall. The `userdata` parameter is passed through directly to `callback`. - * Note that this is distinct from the `userdata` parameter set with + * Read some TLS bytes from the network into internal buffers. The actual network + * I/O is performed by `callback`, which you provide. Rustls will invoke your + * callback with a suitable buffer to store the read bytes into. You don't have + * to fill it up, just fill with as many bytes as you get in one syscall. + * The `userdata` parameter is passed through directly to `callback`. Note that + * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return - * values from callback. See rustls_read_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return values + * from callback. See rustls_read_callback for more details. * */ rustls_io_result rustls_connection_read_tls(struct rustls_connection *conn, rustls_read_callback callback, - void *userdata, size_t *out_n); + void *userdata, + size_t *out_n); /** * Write some TLS bytes to the network. The actual network I/O is performed by @@ -1708,29 +1637,31 @@ rustls_io_result rustls_connection_read_tls(struct rustls_connection *conn, * The `userdata` parameter is passed through directly to `callback`. Note that * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return - * values from callback. See rustls_write_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return values + * from callback. See rustls_write_callback for more details. * */ rustls_io_result rustls_connection_write_tls(struct rustls_connection *conn, rustls_write_callback callback, - void *userdata, size_t *out_n); + void *userdata, + size_t *out_n); /** - * Write all available TLS bytes to the network. The actual network I/O is - * performed by `callback`, which you provide. Rustls will invoke your callback - * with an array of rustls_slice_bytes, each containing a buffer with TLS bytes - * to send. You don't have to write them all, just as many as you are willing. + * Write all available TLS bytes to the network. The actual network I/O is performed by + * `callback`, which you provide. Rustls will invoke your callback with an array + * of rustls_slice_bytes, each containing a buffer with TLS bytes to send. + * You don't have to write them all, just as many as you are willing. * The `userdata` parameter is passed through directly to `callback`. Note that * this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * Returns 0 for success, or an errno value on error. Passes through return - * values from callback. See rustls_write_callback for more details. + * Returns 0 for success, or an errno value on error. Passes through return values + * from callback. See rustls_write_callback for more details. * */ -rustls_io_result rustls_connection_write_tls_vectored( - struct rustls_connection *conn, rustls_write_vectored_callback callback, - void *userdata, size_t *out_n); +rustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection *conn, + rustls_write_vectored_callback callback, + void *userdata, + size_t *out_n); /** * Decrypt any available ciphertext from the internal buffer and put it @@ -1738,8 +1669,7 @@ rustls_io_result rustls_connection_write_tls_vectored( * for rustls_connection_read(). * */ -rustls_result rustls_connection_process_new_packets( - struct rustls_connection *conn); +rustls_result rustls_connection_process_new_packets(struct rustls_connection *conn); /** * @@ -1754,9 +1684,8 @@ bool rustls_connection_wants_write(const struct rustls_connection *conn); /** * Returns true if the connection is currently performing the TLS handshake. * - * Note: This may return `false` while there are still handshake packets - * waiting to be extracted and transmitted with - * `rustls_connection_write_tls()`. + * Note: This may return `false` while there are still handshake packets waiting + * to be extracted and transmitted with `rustls_connection_write_tls()`. * * See the rustls documentation for more information. * @@ -1767,8 +1696,7 @@ bool rustls_connection_is_handshaking(const struct rustls_connection *conn); /** * Returns a `rustls_handshake_kind` describing the `rustls_connection`. */ -enum rustls_handshake_kind rustls_connection_handshake_kind( - const struct rustls_connection *conn); +enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_connection *conn); /** * Sets a limit on the internal buffers used to buffer unsent plaintext (prior @@ -1777,8 +1705,7 @@ enum rustls_handshake_kind rustls_connection_handshake_kind( * use is higher. * */ -void rustls_connection_set_buffer_limit(struct rustls_connection *conn, - size_t n); +void rustls_connection_set_buffer_limit(struct rustls_connection *conn, size_t n); /** * Queues a close_notify fatal alert to be sent in the next write_tls call. @@ -1789,14 +1716,13 @@ void rustls_connection_send_close_notify(struct rustls_connection *conn); /** * Queues a TLS1.3 key_update message to refresh a connection’s keys. * - * Rustls internally manages key updates as required and so this function - * should seldom be used. See the Rustls documentation for important caveats - * and suggestions on occasions that merit its use. + * Rustls internally manages key updates as required and so this function should + * seldom be used. See the Rustls documentation for important caveats and suggestions + * on occasions that merit its use. * * */ -rustls_result rustls_connection_refresh_traffic_keys( - struct rustls_connection *conn); +rustls_result rustls_connection_refresh_traffic_keys(struct rustls_connection *conn); /** * Return the i-th certificate provided by the peer. @@ -1809,8 +1735,8 @@ rustls_result rustls_connection_refresh_traffic_keys( * `const struct rustls_connection *`). * */ -const struct rustls_certificate *rustls_connection_get_peer_certificate( - const struct rustls_connection *conn, size_t i); +const struct rustls_certificate *rustls_connection_get_peer_certificate(const struct rustls_connection *conn, + size_t i); /** * Get the ALPN protocol that was negotiated, if any. Stores a pointer to a @@ -1836,21 +1762,16 @@ void rustls_connection_get_alpn_protocol(const struct rustls_connection *conn, * * */ -uint16_t rustls_connection_get_protocol_version( - const struct rustls_connection *conn); +uint16_t rustls_connection_get_protocol_version(const struct rustls_connection *conn); /** - * Retrieves the [IANA registered cipher suite identifier][IANA] agreed with - * the peer. + * Retrieves the [IANA registered cipher suite identifier][IANA] agreed with the peer. * - * This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is - * agreed. + * This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed. * - * [IANA]: - * + * [IANA]: */ -uint16_t rustls_connection_get_negotiated_ciphersuite( - const struct rustls_connection *conn); +uint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connection *conn); /** * Retrieves the cipher suite name agreed with the peer. @@ -1862,20 +1783,16 @@ uint16_t rustls_connection_get_negotiated_ciphersuite( * * */ -struct rustls_str rustls_connection_get_negotiated_ciphersuite_name( - const struct rustls_connection *conn); +struct rustls_str rustls_connection_get_negotiated_ciphersuite_name(const struct rustls_connection *conn); /** - * Retrieves the [IANA registered supported group identifier][IANA] agreed with - * the peer. + * Retrieves the [IANA registered supported group identifier][IANA] agreed with the peer. * * This returns Reserved (0x0000) until the key exchange group is agreed. * - * [IANA]: - * + * [IANA]: */ -uint16_t rustls_connection_get_negotiated_key_exchange_group( - const struct rustls_connection *conn); +uint16_t rustls_connection_get_negotiated_key_exchange_group(const struct rustls_connection *conn); /** * Retrieves the key exchange group name agreed with the peer. @@ -1885,8 +1802,7 @@ uint16_t rustls_connection_get_negotiated_key_exchange_group( * The lifetime of the `rustls_str` is the lifetime of the program, it does not * need to be freed. */ -struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name( - const struct rustls_connection *conn); +struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name(const struct rustls_connection *conn); /** * Write up to `count` plaintext bytes from `buf` into the `rustls_connection`. @@ -1897,7 +1813,8 @@ struct rustls_str rustls_connection_get_negotiated_key_exchange_group_name( * */ rustls_result rustls_connection_write(struct rustls_connection *conn, - const uint8_t *buf, size_t count, + const uint8_t *buf, + size_t count, size_t *out_n); /** @@ -1915,7 +1832,8 @@ rustls_result rustls_connection_write(struct rustls_connection *conn, * */ rustls_result rustls_connection_read(struct rustls_connection *conn, - uint8_t *buf, size_t count, + uint8_t *buf, + size_t count, size_t *out_n); #if defined(DEFINE_READ_BUF) @@ -1935,17 +1853,18 @@ rustls_result rustls_connection_read(struct rustls_connection *conn, * pointing to an uninitialized memory buffer. */ rustls_result rustls_connection_read_2(struct rustls_connection *conn, - uint8_t *buf, size_t count, + uint8_t *buf, + size_t count, size_t *out_n); #endif /** - * Returns true if the `rustls_connection` was made with a - * `rustls_client_config` or `rustls_server_config` that is FIPS compatible. + * Returns true if the `rustls_connection` was made with a `rustls_client_config` + * or `rustls_server_config` that is FIPS compatible. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration - * that NIST recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration that NIST + * recommends, as well as ECH HPKE suites if applicable. */ bool rustls_connection_fips(const struct rustls_connection *conn); @@ -1956,7 +1875,8 @@ bool rustls_connection_fips(const struct rustls_connection *conn); * and returns `false`. */ bool rustls_connection_last_error_msg(const struct rustls_connection *conn, - uint8_t *buf, size_t count, + uint8_t *buf, + size_t count, size_t *out_n); /** @@ -1966,49 +1886,45 @@ bool rustls_connection_last_error_msg(const struct rustls_connection *conn, void rustls_connection_free(struct rustls_connection *conn); /** - * Constructs a new `rustls_crypto_provider_builder` using the process-wide - * default crypto provider as the base crypto provider to be customized. + * Constructs a new `rustls_crypto_provider_builder` using the process-wide default crypto + * provider as the base crypto provider to be customized. * - * When this function returns `rustls_result::Ok` a pointer to the - * `rustls_crypto_provider_builder` is written to `builder_out`. It returns - * `rustls_result::NoDefaultCryptoProvider` if no default provider has been - * registered. + * When this function returns `rustls_result::Ok` a pointer to the `rustls_crypto_provider_builder` + * is written to `builder_out`. It returns `rustls_result::NoDefaultCryptoProvider` if no default + * provider has been registered. * - * The caller owns the returned `rustls_crypto_provider_builder` and must free - * it using `rustls_crypto_provider_builder_free`. + * The caller owns the returned `rustls_crypto_provider_builder` and must free it using + * `rustls_crypto_provider_builder_free`. * - * This function is typically used for customizing the default crypto provider - * for specific connections. For example, a typical workflow might be to: + * This function is typically used for customizing the default crypto provider for specific + * connections. For example, a typical workflow might be to: * * * Either: - * * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is - * built with based on the `CRYPTO_PROVIDER` build variable. - * * Call `rustls_crypto_provider_builder_new_with_base` with the desired - * provider, and then install it as the process default with + * * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is built with based on + * the `CRYPTO_PROVIDER` build variable. + * * Call `rustls_crypto_provider_builder_new_with_base` with the desired provider, and + * then install it as the process default with * `rustls_crypto_provider_builder_build_as_default`. * * Afterward, as required for customization: - * * Use `rustls_crypto_provider_builder_new_from_default` to get a builder - * backed by the default crypto provider. - * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the - * supported ciphersuites. - * * Use `rustls_crypto_provider_builder_build` to build a customized - * provider. - * * Provide that customized provider to client or server configuration - * builders. + * * Use `rustls_crypto_provider_builder_new_from_default` to get a builder backed by the + * default crypto provider. + * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the supported + * ciphersuites. + * * Use `rustls_crypto_provider_builder_build` to build a customized provider. + * * Provide that customized provider to client or server configuration builders. */ -rustls_result rustls_crypto_provider_builder_new_from_default( - struct rustls_crypto_provider_builder **builder_out); +rustls_result rustls_crypto_provider_builder_new_from_default(struct rustls_crypto_provider_builder **builder_out); /** - * Constructs a new `rustls_crypto_provider_builder` using the given - * `rustls_crypto_provider` as the base crypto provider to be customized. + * Constructs a new `rustls_crypto_provider_builder` using the given `rustls_crypto_provider` + * as the base crypto provider to be customized. * - * The caller owns the returned `rustls_crypto_provider_builder` and must free - * it using `rustls_crypto_provider_builder_free`. + * The caller owns the returned `rustls_crypto_provider_builder` and must free it using + * `rustls_crypto_provider_builder_free`. * - * This function can be used for setting the default process wide crypto - * provider, or for constructing a custom crypto provider for a specific - * connection. A typical workflow could be to: + * This function can be used for setting the default process wide crypto provider, + * or for constructing a custom crypto provider for a specific connection. A typical + * workflow could be to: * * * Call `rustls_crypto_provider_builder_new_with_base` with a custom provider * * Install the custom provider as the process-wide default with @@ -2017,57 +1933,48 @@ rustls_result rustls_crypto_provider_builder_new_from_default( * Or, for per-connection customization: * * * Call `rustls_crypto_provider_builder_new_with_base` with a custom provider - * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the - * supported ciphersuites. + * * Use `rustls_crypto_provider_builder_set_cipher_suites` to customize the supported + * ciphersuites. * * Use `rustls_crypto_provider_builder_build` to build a customized provider. - * * Provide that customized provider to client or server configuration - * builders. + * * Provide that customized provider to client or server configuration builders. */ -struct rustls_crypto_provider_builder * -rustls_crypto_provider_builder_new_with_base( - const struct rustls_crypto_provider *base); +struct rustls_crypto_provider_builder *rustls_crypto_provider_builder_new_with_base(const struct rustls_crypto_provider *base); /** - * Customize the supported ciphersuites of the - * `rustls_crypto_provider_builder`. + * Customize the supported ciphersuites of the `rustls_crypto_provider_builder`. * - * Returns an error if the builder has already been built. Overwrites any - * previously set ciphersuites. + * Returns an error if the builder has already been built. Overwrites any previously + * set ciphersuites. */ -rustls_result rustls_crypto_provider_builder_set_cipher_suites( - struct rustls_crypto_provider_builder *builder, - const struct rustls_supported_ciphersuite *const *cipher_suites, - size_t cipher_suites_len); +rustls_result rustls_crypto_provider_builder_set_cipher_suites(struct rustls_crypto_provider_builder *builder, + const struct rustls_supported_ciphersuite *const *cipher_suites, + size_t cipher_suites_len); /** - * Builds a `rustls_crypto_provider` from the builder and returns it. Returns - * an error if the builder has already been built. + * Builds a `rustls_crypto_provider` from the builder and returns it. Returns an error if the + * builder has already been built. * - * The `rustls_crypto_provider_builder` builder is consumed and should not be - * used for further calls, except to `rustls_crypto_provider_builder_free`. The - * caller must still free the builder after a successful build. + * The `rustls_crypto_provider_builder` builder is consumed and should not be used + * for further calls, except to `rustls_crypto_provider_builder_free`. The caller must + * still free the builder after a successful build. */ -rustls_result rustls_crypto_provider_builder_build( - struct rustls_crypto_provider_builder *builder, - const struct rustls_crypto_provider **provider_out); +rustls_result rustls_crypto_provider_builder_build(struct rustls_crypto_provider_builder *builder, + const struct rustls_crypto_provider **provider_out); /** * Builds a `rustls_crypto_provider` from the builder and sets it as the * process-wide default crypto provider. * - * Afterward, the default provider can be retrieved using - * `rustls_crypto_provider_default`. + * Afterward, the default provider can be retrieved using `rustls_crypto_provider_default`. * * This can only be done once per process, and will return an error if a - * default provider has already been set, or if the builder has already been - * built. + * default provider has already been set, or if the builder has already been built. * - * The `rustls_crypto_provider_builder` builder is consumed and should not be - * used for further calls, except to `rustls_crypto_provider_builder_free`. The - * caller must still free the builder after a successful build. + * The `rustls_crypto_provider_builder` builder is consumed and should not be used + * for further calls, except to `rustls_crypto_provider_builder_free`. The caller must + * still free the builder after a successful build. */ -rustls_result rustls_crypto_provider_builder_build_as_default( - struct rustls_crypto_provider_builder *builder); +rustls_result rustls_crypto_provider_builder_build_as_default(struct rustls_crypto_provider_builder *builder); /** * Free the `rustls_crypto_provider_builder`. @@ -2075,13 +1982,11 @@ rustls_result rustls_crypto_provider_builder_build_as_default( * Calling with `NULL` is fine. * Must not be called twice with the same value. */ -void rustls_crypto_provider_builder_free( - struct rustls_crypto_provider_builder *builder); +void rustls_crypto_provider_builder_free(struct rustls_crypto_provider_builder *builder); #if defined(DEFINE_RING) /** - * Return the `rustls_crypto_provider` backed by the `*ring*` cryptography - * library. + * Return the `rustls_crypto_provider` backed by the `*ring*` cryptography library. * * The caller owns the returned `rustls_crypto_provider` and must free it using * `rustls_crypto_provider_free`. @@ -2091,8 +1996,7 @@ const struct rustls_crypto_provider *rustls_ring_crypto_provider(void); #if defined(DEFINE_AWS_LC_RS) /** - * Return the `rustls_crypto_provider` backed by the `aws-lc-rs` cryptography - * library. + * Return the `rustls_crypto_provider` backed by the `aws-lc-rs` cryptography library. * * The caller owns the returned `rustls_crypto_provider` and must free it using * `rustls_crypto_provider_free`. @@ -2104,9 +2008,8 @@ const struct rustls_crypto_provider *rustls_aws_lc_rs_crypto_provider(void); /** * Return a `rustls_crypto_provider` that uses FIPS140-3 approved cryptography. * - * Using this function expresses in your code that you require FIPS-approved - * cryptography, and will not compile if you make a mistake with cargo - * features. + * Using this function expresses in your code that you require FIPS-approved cryptography, + * and will not compile if you make a mistake with cargo features. * * See the upstream [rustls FIPS documentation][FIPS] for more information. * @@ -2124,8 +2027,7 @@ const struct rustls_crypto_provider *rustls_default_fips_provider(void); * This may return `NULL` if no process default provider has been set using * `rustls_crypto_provider_builder_build_default`. * - * Caller owns the returned `rustls_crypto_provider` and must free it w/ - * `rustls_crypto_provider_free`. + * Caller owns the returned `rustls_crypto_provider` and must free it w/ `rustls_crypto_provider_free`. */ const struct rustls_crypto_provider *rustls_crypto_provider_default(void); @@ -2137,23 +2039,19 @@ const struct rustls_crypto_provider *rustls_crypto_provider_default(void); * * This function will return 0 if the `provider` is NULL. */ -size_t rustls_crypto_provider_ciphersuites_len( - const struct rustls_crypto_provider *provider); +size_t rustls_crypto_provider_ciphersuites_len(const struct rustls_crypto_provider *provider); /** - * Retrieve a pointer to a supported ciphersuite of the - * `rustls_crypto_provider`. + * Retrieve a pointer to a supported ciphersuite of the `rustls_crypto_provider`. * - * This function will return NULL if the `provider` is NULL, or if the index is - * out of bounds with respect to `rustls_crypto_provider_ciphersuites_len`. + * This function will return NULL if the `provider` is NULL, or if the index is out of bounds + * with respect to `rustls_crypto_provider_ciphersuites_len`. * - * The lifetime of the returned `rustls_supported_ciphersuite` is equal to the - * lifetime of the `provider` and should not be used after the `provider` is - * freed. + * The lifetime of the returned `rustls_supported_ciphersuite` is equal to the lifetime of the + * `provider` and should not be used after the `provider` is freed. */ -const struct rustls_supported_ciphersuite * -rustls_crypto_provider_ciphersuites_get( - const struct rustls_crypto_provider *provider, size_t index); +const struct rustls_supported_ciphersuite *rustls_crypto_provider_ciphersuites_get(const struct rustls_crypto_provider *provider, + size_t index); /** * Load a private key from the provided PEM content using the crypto provider. @@ -2163,27 +2061,26 @@ rustls_crypto_provider_ciphersuites_get( * the crypto provider in use. The default providers support PKCS#1, PKCS#8 or * SEC1 formats. * - * When this function returns `rustls_result::Ok` a pointer to a - * `rustls_signing_key` is written to `signing_key_out`. The caller owns the - * returned `rustls_signing_key` and must free it with - * `rustls_signing_key_free`. + * When this function returns `rustls_result::Ok` a pointer to a `rustls_signing_key` + * is written to `signing_key_out`. The caller owns the returned `rustls_signing_key` + * and must free it with `rustls_signing_key_free`. */ -rustls_result rustls_crypto_provider_load_key( - const struct rustls_crypto_provider *provider, const uint8_t *private_key, - size_t private_key_len, struct rustls_signing_key **signing_key_out); +rustls_result rustls_crypto_provider_load_key(const struct rustls_crypto_provider *provider, + const uint8_t *private_key, + size_t private_key_len, + struct rustls_signing_key **signing_key_out); /** - * Write `len` bytes of cryptographically secure random data to `buff` using - * the crypto provider. + * Write `len` bytes of cryptographically secure random data to `buff` using the crypto provider. * - * `buff` must point to a buffer of at least `len` bytes. The caller maintains - * ownership of the buffer. + * `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership + * of the buffer. * - * Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` - * on failure. + * Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. */ -rustls_result rustls_crypto_provider_random( - const struct rustls_crypto_provider *provider, uint8_t *buff, size_t len); +rustls_result rustls_crypto_provider_random(const struct rustls_crypto_provider *provider, + uint8_t *buff, + size_t len); /** * Returns true if the `rustls_crypto_provider` is operating in FIPS mode. @@ -2193,8 +2090,7 @@ rustls_result rustls_crypto_provider_random( * `rustls_client_config_fips` or `rustls_server_config_fips` which take these * into account. */ -bool rustls_crypto_provider_fips( - const struct rustls_crypto_provider *provider); +bool rustls_crypto_provider_fips(const struct rustls_crypto_provider *provider); /** * Frees the `rustls_crypto_provider`. @@ -2202,71 +2098,64 @@ bool rustls_crypto_provider_fips( * Calling with `NULL` is fine. * Must not be called twice with the same value. */ -void rustls_crypto_provider_free( - const struct rustls_crypto_provider *provider); +void rustls_crypto_provider_free(const struct rustls_crypto_provider *provider); /** - * Returns the number of ciphersuites the default process-wide crypto provider - * supports. + * Returns the number of ciphersuites the default process-wide crypto provider supports. * * You can use this to know the maximum allowed index for use with * `rustls_default_crypto_provider_ciphersuites_get`. * - * This function will return 0 if no process-wide default - * `rustls_crypto_provider` is available. + * This function will return 0 if no process-wide default `rustls_crypto_provider` is available. */ size_t rustls_default_crypto_provider_ciphersuites_len(void); /** - * Retrieve a pointer to a supported ciphersuite of the default process-wide - * crypto provider. + * Retrieve a pointer to a supported ciphersuite of the default process-wide crypto provider. * - * This function will return NULL if the `provider` is NULL, or if the index is - * out of bounds with respect to - * `rustls_default_crypto_provider_ciphersuites_len`. + * This function will return NULL if the `provider` is NULL, or if the index is out of bounds + * with respect to `rustls_default_crypto_provider_ciphersuites_len`. * - * The lifetime of the returned `rustls_supported_ciphersuite` is static, as - * the process-wide default provider lives for as long as the process. + * The lifetime of the returned `rustls_supported_ciphersuite` is static, as the process-wide + * default provider lives for as long as the process. */ -const struct rustls_supported_ciphersuite * -rustls_default_crypto_provider_ciphersuites_get(size_t index); +const struct rustls_supported_ciphersuite *rustls_default_crypto_provider_ciphersuites_get(size_t index); /** - * Write `len` bytes of cryptographically secure random data to `buff` using - * the process-wide default crypto provider. + * Write `len` bytes of cryptographically secure random data to `buff` using the process-wide + * default crypto provider. * - * `buff` must point to a buffer of at least `len` bytes. The caller maintains - * ownership of the buffer. + * `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership + * of the buffer. * - * Returns `RUSTLS_RESULT_OK` on success, and one of - * `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` or - * `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. + * Returns `RUSTLS_RESULT_OK` on success, and one of `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` + * or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure. */ rustls_result rustls_default_crypto_provider_random(uint8_t *buff, size_t len); /** - * Frees the `rustls_signing_key`. This is safe to call with a `NULL` argument, - * but must not be called twice with the same value. + * Frees the `rustls_signing_key`. This is safe to call with a `NULL` argument, but + * must not be called twice with the same value. */ void rustls_signing_key_free(struct rustls_signing_key *signing_key); /** - * Returns a pointer to the supported `rustls_hpke` Hybrid Public Key - * Encryption (HPKE) suites, or `NULL` if HPKE is not supported. + * Returns a pointer to the supported `rustls_hpke` Hybrid Public Key Encryption (HPKE) + * suites, or `NULL` if HPKE is not supported. * * HPKE is only supported with the `aws-lc-rs` cryptography provider. * - * The returned pointer has a static lifetime equal to that of the program and - * does not need to be freed. + * The returned pointer has a static lifetime equal to that of the program and does not + * need to be freed. */ const struct rustls_hpke *rustls_supported_hpke(void); /** - * Convert a `rustls_handshake_kind` to a string with a friendly description of - * the kind of handshake. + * Convert a `rustls_handshake_kind` to a string with a friendly description of the kind + * of handshake. * - * The returned `rustls_str` has a static lifetime equal to that of the program - * and does not need to be manually freed. + * The returned `rustls_str` has a static lifetime equal to that of the program and does + * not need to be manually freed. */ struct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind); @@ -2294,8 +2183,7 @@ struct rustls_str rustls_log_level_str(rustls_log_level level); * Return the length of the outer slice. If the input pointer is NULL, * returns 0. */ -size_t rustls_slice_slice_bytes_len( - const struct rustls_slice_slice_bytes *input); +size_t rustls_slice_slice_bytes_len(const struct rustls_slice_slice_bytes *input); /** * Retrieve the nth element from the input slice of slices. @@ -2303,8 +2191,8 @@ size_t rustls_slice_slice_bytes_len( * If the input pointer is NULL, or n is greater than the length * of the `rustls_slice_slice_bytes`, returns rustls_slice_bytes{NULL, 0}. */ -struct rustls_slice_bytes rustls_slice_slice_bytes_get( - const struct rustls_slice_slice_bytes *input, size_t n); +struct rustls_slice_bytes rustls_slice_slice_bytes_get(const struct rustls_slice_slice_bytes *input, + size_t n); /** * Return the length of the outer slice. @@ -2319,124 +2207,110 @@ size_t rustls_slice_str_len(const struct rustls_slice_str *input); * If the input pointer is NULL, or n is greater than the length of the * rustls_slice_str, returns rustls_str{NULL, 0}. */ -struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, - size_t n); +struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, size_t n); /** - * Create a rustls_server_config_builder using the process default crypto - * provider. + * 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. + * 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. + * This uses the process default provider's values for the cipher suites and key exchange + * groups, as well as safe defaults for protocol versions. */ struct rustls_server_config_builder *rustls_server_config_builder_new(void); /** * 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. + * 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` 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`. + * 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. */ -rustls_result rustls_server_config_builder_new_custom( - const struct rustls_crypto_provider *provider, const uint16_t *tls_versions, - size_t tls_versions_len, struct rustls_server_config_builder **builder_out); +rustls_result rustls_server_config_builder_new_custom(const struct rustls_crypto_provider *provider, + const uint16_t *tls_versions, + size_t tls_versions_len, + struct rustls_server_config_builder **builder_out); /** - * Create a rustls_server_config_builder for TLS sessions that may verify - * client certificates. + * 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. */ -void rustls_server_config_builder_set_client_verifier( - struct rustls_server_config_builder *builder, - const struct rustls_client_cert_verifier *verifier); +void rustls_server_config_builder_set_client_verifier(struct rustls_server_config_builder *builder, + const struct rustls_client_cert_verifier *verifier); /** - * Log key material to the file specified by the `SSLKEYLOGFILE` environment - * variable. + * Log key material to the file specified by the `SSLKEYLOGFILE` environment variable. * * The key material will be logged in the NSS key log format, - * - * and is compatible with tools like Wireshark. + * 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. + * 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_server_config_builder_set_key_log`. + * For more control over which secrets are logged, or to customize the format, prefer + * `rustls_server_config_builder_set_key_log`. */ -rustls_result rustls_server_config_builder_set_key_log_file( - struct rustls_server_config_builder *builder); +rustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server_config_builder *builder); /** * 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: + * 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: * * - * 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. + * 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. + * 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. + * Secrets provided to the `log_cb` are **extremely sensitive** and can break the security + * of past, present and future sessions. * - * See also `rustls_server_config_builder_set_key_log_file` for a simpler way - * to log to a file specified by the `SSLKEYLOGFILE` environment variable. + * See also `rustls_server_config_builder_set_key_log_file` for a simpler way to log + * to a file specified by the `SSLKEYLOGFILE` environment variable. */ -rustls_result rustls_server_config_builder_set_key_log( - struct rustls_server_config_builder *builder, - rustls_keylog_log_callback log_cb, - rustls_keylog_will_log_callback will_log_cb); +rustls_result rustls_server_config_builder_set_key_log(struct rustls_server_config_builder *builder, + rustls_keylog_log_callback log_cb, + rustls_keylog_will_log_callback will_log_cb); /** - * "Free" a server_config_builder without building it into a - * rustls_server_config. + * "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. + * 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. + * Use free only when the building of a config has to be aborted before a config + * was created. */ -void rustls_server_config_builder_free( - struct rustls_server_config_builder *config); +void rustls_server_config_builder_free(struct rustls_server_config_builder *config); /** * With `ignore` != 0, the server will ignore the client ordering of cipher @@ -2444,15 +2318,15 @@ void rustls_server_config_builder_free( * as configured. * */ -rustls_result rustls_server_config_builder_set_ignore_client_order( - struct rustls_server_config_builder *builder, bool ignore); +rustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls_server_config_builder *builder, + bool ignore); /** * 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 + * `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 * . * * This function makes a copy of the data in `protocols` and does not retain @@ -2460,9 +2334,9 @@ rustls_result rustls_server_config_builder_set_ignore_client_order( * * */ -rustls_result rustls_server_config_builder_set_alpn_protocols( - struct rustls_server_config_builder *builder, - const struct rustls_slice_bytes *protocols, size_t len); +rustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_server_config_builder *builder, + const struct rustls_slice_bytes *protocols, + size_t len); /** * Provide the configuration a list of certificates where the connection @@ -2480,32 +2354,29 @@ rustls_result rustls_server_config_builder_set_alpn_protocols( * EXPERIMENTAL: installing a client_hello callback will replace any * configured certified keys and vice versa. */ -rustls_result rustls_server_config_builder_set_certified_keys( - struct rustls_server_config_builder *builder, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len); +rustls_result rustls_server_config_builder_set_certified_keys(struct rustls_server_config_builder *builder, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len); /** - * 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`. + * 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. + * 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. */ -rustls_result rustls_server_config_builder_build( - struct rustls_server_config_builder *builder, - const struct rustls_server_config **config_out); +rustls_result rustls_server_config_builder_build(struct rustls_server_config_builder *builder, + const struct rustls_server_config **config_out); /** - * Returns true if a `rustls_connection` created from the - * `rustls_server_config` will operate in FIPS mode. + * Returns true if a `rustls_connection` created from the `rustls_server_config` will + * operate in FIPS mode. * * This is different from `rustls_crypto_provider_fips` which is concerned - * only with cryptography, whereas this also covers TLS-level configuration - * that NIST recommends, as well as ECH HPKE suites if applicable. + * only with cryptography, whereas this also covers TLS-level configuration that NIST + * recommends, as well as ECH HPKE suites if applicable. */ bool rustls_server_config_fips(const struct rustls_server_config *config); @@ -2522,43 +2393,38 @@ bool rustls_server_config_fips(const struct rustls_server_config *config); void rustls_server_config_free(const struct rustls_server_config *config); /** - * Create a new rustls_connection containing a server connection, and return - * it. + * Create a new rustls_connection containing a server connection, and return it. * * It is returned in the output parameter `conn_out`. * - * If this returns an error code, the memory pointed to by `conn_out` remains - * unchanged. + * If this returns an error code, the memory pointed to by `conn_out` remains unchanged. * - * If this returns a non-error, the memory pointed to by `conn_out` is modified - * to point at a valid rustls_connection + * If this returns a non-error, the memory pointed to by `conn_out` is modified to point + * at a valid rustls_connection * - * The caller now owns the rustls_connection and must call - * `rustls_connection_free` when done with it. + * The caller now owns the rustls_connection and must call `rustls_connection_free` when + * done with it. */ -rustls_result rustls_server_connection_new( - const struct rustls_server_config *config, - struct rustls_connection **conn_out); +rustls_result rustls_server_connection_new(const struct rustls_server_config *config, + struct rustls_connection **conn_out); /** - * Returns a `rustls_str` reference to the server name sent by the client in a - * server name indication (SNI) extension. + * Returns a `rustls_str` reference to the server name sent by the client in a server name + * indication (SNI) extension. * - * The returned `rustls_str` is valid until the next mutating function call - * affecting the connection. A mutating function call is one where the first - * argument has type `struct rustls_connection *` (as opposed to `const struct - * rustls_connection *`). The caller does not need to free the `rustls_str`. + * The returned `rustls_str` is valid until the next mutating function call affecting the + * connection. A mutating function call is one where the first argument has type + * `struct rustls_connection *` (as opposed to `const struct rustls_connection *`). The caller + * does not need to free the `rustls_str`. * * Returns a zero-length `rustls_str` if: * * - the connection is not a server connection. - * - the connection is a server connection but the SNI extension in the client - * hello has not been processed during the handshake yet. Check - * `rustls_connection_is_handshaking`. + * - the connection is a server connection but the SNI extension in the client hello has not + * been processed during the handshake yet. Check `rustls_connection_is_handshaking`. * - the SNI value contains null bytes. */ -struct rustls_str rustls_server_connection_get_server_name( - const struct rustls_connection *conn); +struct rustls_str rustls_server_connection_get_server_name(const struct rustls_connection *conn); /** * Register a callback to be invoked when a connection created from this config @@ -2571,15 +2437,13 @@ struct rustls_str rustls_server_connection_get_server_name( * 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. + * 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. */ -rustls_result rustls_server_config_builder_set_hello_callback( - struct rustls_server_config_builder *builder, - rustls_client_hello_callback callback); +rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_server_config_builder *builder, + rustls_client_hello_callback callback); /** * Select a `rustls_certified_key` from the list that matches the cryptographic @@ -2590,18 +2454,18 @@ rustls_result rustls_server_config_builder_set_hello_callback( * * This is intended for servers that are configured with several keys for the * same domain name(s), for example ECDSA and RSA types. The presented keys are - * inspected in the order given and keys first in the list are given - * preference, all else being equal. However rustls is free to choose whichever - * it considers to be the best key with its knowledge about security issues and - * possible future extensions of the protocol. + * inspected in the order given and keys first in the list are given preference, + * all else being equal. However rustls is free to choose whichever it considers + * to be the best key with its knowledge about security issues and possible future + * extensions of the protocol. * * Return RUSTLS_RESULT_OK if a key was selected and RUSTLS_RESULT_NOT_FOUND * if none was suitable. */ -rustls_result rustls_client_hello_select_certified_key( - const struct rustls_client_hello *hello, - const struct rustls_certified_key *const *certified_keys, - size_t certified_keys_len, const struct rustls_certified_key **out_key); +rustls_result rustls_client_hello_select_certified_key(const struct rustls_client_hello *hello, + const struct rustls_certified_key *const *certified_keys, + size_t certified_keys_len, + const struct rustls_certified_key **out_key); /** * Register callbacks for persistence of TLS session IDs and secrets. Both @@ -2615,41 +2479,35 @@ rustls_result rustls_client_hello_select_certified_key( * will be passed to the callbacks. Otherwise the userdata param passed to * the callbacks will be NULL. */ -void rustls_server_config_builder_set_persistence( - struct rustls_server_config_builder *builder, - rustls_session_store_get_callback get_cb, - rustls_session_store_put_callback put_cb); +void rustls_server_config_builder_set_persistence(struct rustls_server_config_builder *builder, + rustls_session_store_get_callback get_cb, + rustls_session_store_put_callback put_cb); /** * Free a `rustls_client_cert_verifier` previously returned from - * `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must - * not be called twice with the same value. + * `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must not be + * called twice with the same value. */ -void rustls_client_cert_verifier_free( - struct rustls_client_cert_verifier *verifier); +void rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifier); /** - * Create a `rustls_web_pki_client_cert_verifier_builder` using the - * process-wide default cryptography provider. + * Create a `rustls_web_pki_client_cert_verifier_builder` using the process-wide default + * cryptography provider. * - * Caller owns the memory and may eventually call - * `rustls_web_pki_client_cert_verifier_builder_free` to free it, whether or - * not `rustls_web_pki_client_cert_verifier_builder_build` was called. + * Caller owns the memory and may eventually call `rustls_web_pki_client_cert_verifier_builder_free` + * to free it, whether or not `rustls_web_pki_client_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a client certificate - * verifier that will require a client present a client certificate that chains - * to one of the trust anchors in the provided `rustls_root_cert_store`. The - * root cert store must not be empty. + * Without further modification the builder will produce a client certificate verifier that + * will require a client present a client certificate that chains to one of the trust anchors + * in the provided `rustls_root_cert_store`. The root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add - * certificate revocation lists (CRLs) to the builder. If CRLs are added, - * revocation checking will be performed for the entire certificate chain - * unless - * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is - * used. Unknown revocation status for certificates considered for revocation - * status will be treated as an error unless - * `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add certificate revocation + * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed + * for the entire certificate chain unless + * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is used. Unknown + * revocation status for certificates considered for revocation status will be treated as + * an error unless `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is * used. * * Unauthenticated clients will not be permitted unless @@ -2658,9 +2516,7 @@ void rustls_client_cert_verifier_free( * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_client_cert_verifier_builder * -rustls_web_pki_client_cert_verifier_builder_new( - const struct rustls_root_cert_store *store); +struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new(const struct rustls_root_cert_store *store); /** * Create a `rustls_web_pki_client_cert_verifier_builder` using the specified @@ -2670,20 +2526,17 @@ rustls_web_pki_client_cert_verifier_builder_new( * `rustls_web_pki_client_cert_verifier_builder_free` to free it, whether or * not `rustls_web_pki_client_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a client certificate - * verifier that will require a client present a client certificate that chains - * to one of the trust anchors in the provided `rustls_root_cert_store`. The - * root cert store must not be empty. + * Without further modification the builder will produce a client certificate verifier that + * will require a client present a client certificate that chains to one of the trust anchors + * in the provided `rustls_root_cert_store`. The root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add - * certificate revocation lists (CRLs) to the builder. If CRLs are added, - * revocation checking will be performed for the entire certificate chain - * unless - * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is - * used. Unknown revocation status for certificates considered for revocation - * status will be treated as an error unless - * `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_client_cert_verifier_builder_add_crl` is used to add certificate revocation + * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed + * for the entire certificate chain unless + * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation` is used. Unknown + * revocation status for certificates considered for revocation status will be treated as + * an error unless `rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status` is * used. * * Unauthenticated clients will not be permitted unless @@ -2692,98 +2545,78 @@ rustls_web_pki_client_cert_verifier_builder_new( * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_client_cert_verifier_builder * -rustls_web_pki_client_cert_verifier_builder_new_with_provider( - const struct rustls_crypto_provider *provider, - const struct rustls_root_cert_store *store); +struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider, + const struct rustls_root_cert_store *store); /** - * Add one or more certificate revocation lists (CRLs) to the client - * certificate verifier builder by reading the CRL content from the provided - * buffer of PEM encoded content. + * Add one or more certificate revocation lists (CRLs) to the client certificate verifier + * builder by reading the CRL content from the provided buffer of PEM encoded content. * - * By default revocation checking will be performed on the entire certificate - * chain. To only check the revocation status of the end entity certificate, - * use `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`. + * By default revocation checking will be performed on the entire certificate chain. To only + * check the revocation status of the end entity certificate, use + * `rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`. * - * This function returns an error if the provided buffer is not valid PEM - * encoded content. + * This function returns an error if the provided buffer is not valid PEM encoded content. */ -rustls_result rustls_web_pki_client_cert_verifier_builder_add_crl( - struct rustls_web_pki_client_cert_verifier_builder *builder, - const uint8_t *crl_pem, size_t crl_pem_len); +rustls_result rustls_web_pki_client_cert_verifier_builder_add_crl(struct rustls_web_pki_client_cert_verifier_builder *builder, + const uint8_t *crl_pem, + size_t crl_pem_len); /** - * When CRLs are provided with - * `rustls_web_pki_client_cert_verifier_builder_add_crl`, only check the - * revocation status of end entity certificates, ignoring any intermediate - * certificates in the chain. + * When CRLs are provided with `rustls_web_pki_client_cert_verifier_builder_add_crl`, only + * check the revocation status of end entity certificates, ignoring any intermediate certificates + * in the chain. */ -rustls_result -rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation( - struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * When CRLs are provided with - * `rustls_web_pki_client_cert_verifier_builder_add_crl`, and it isn't possible - * to determine the revocation status of a considered certificate, do not treat + * When CRLs are provided with `rustls_web_pki_client_cert_verifier_builder_add_crl`, and it + * isn't possible to determine the revocation status of a considered certificate, do not treat * it as an error condition. * - * Overrides the default behavior where unknown revocation status is considered - * an error. + * Overrides the default behavior where unknown revocation status is considered an error. */ -rustls_result -rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status( - struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Allow unauthenticated anonymous clients in addition to those that present a - * client certificate that chains to one of the verifier's configured trust - * anchors. + * Allow unauthenticated anonymous clients in addition to those that present a client + * certificate that chains to one of the verifier's configured trust anchors. */ -rustls_result -rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated( - struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated(struct rustls_web_pki_client_cert_verifier_builder *builder); /** * Clear the list of trust anchor hint subjects. * - * By default, the client cert verifier will use the subjects provided by the - * root cert store configured for client authentication. Calling this function - * will remove these hint subjects, indicating the client should make a free - * choice of which certificate to send. + * By default, the client cert verifier will use the subjects provided by the root cert + * store configured for client authentication. Calling this function will remove these + * hint subjects, indicating the client should make a free choice of which certificate + * to send. */ -rustls_result rustls_web_pki_client_cert_verifier_clear_root_hint_subjects( - struct rustls_web_pki_client_cert_verifier_builder *builder); +rustls_result rustls_web_pki_client_cert_verifier_clear_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Add additional distinguished names to the list of trust anchor hint - * subjects. + * Add additional distinguished names to the list of trust anchor hint subjects. * - * By default, the client cert verifier will use the subjects provided by the - * root cert store configured for client authentication. Calling this function - * will add to these existing hint subjects. Calling this function with an - * empty `store` will have no effect, use - * `rustls_web_pki_client_cert_verifier_clear_root_hint_subjects` to clear the - * subject hints. + * By default, the client cert verifier will use the subjects provided by the root cert + * store configured for client authentication. Calling this function will add to these + * existing hint subjects. Calling this function with an empty `store` will have no + * effect, use `rustls_web_pki_client_cert_verifier_clear_root_hint_subjects` to clear + * the subject hints. */ -rustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects( - struct rustls_web_pki_client_cert_verifier_builder *builder, - const struct rustls_root_cert_store *store); +rustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder, + const struct rustls_root_cert_store *store); /** * Create a new client certificate verifier from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The verifier can be used in several `rustls_server_config` instances and - * must be freed by the application when no longer needed. See the - * documentation of `rustls_web_pki_client_cert_verifier_builder_free` for - * details about lifetime. + * The verifier can be used in several `rustls_server_config` instances and must be + * freed by the application when no longer needed. See the documentation of + * `rustls_web_pki_client_cert_verifier_builder_free` for details about lifetime. */ -rustls_result rustls_web_pki_client_cert_verifier_builder_build( - struct rustls_web_pki_client_cert_verifier_builder *builder, - struct rustls_client_cert_verifier **verifier_out); +rustls_result rustls_web_pki_client_cert_verifier_builder_build(struct rustls_web_pki_client_cert_verifier_builder *builder, + struct rustls_client_cert_verifier **verifier_out); /** * Free a `rustls_client_cert_verifier_builder` previously returned from @@ -2791,40 +2624,32 @@ rustls_result rustls_web_pki_client_cert_verifier_builder_build( * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_web_pki_client_cert_verifier_builder_free( - struct rustls_web_pki_client_cert_verifier_builder *builder); +void rustls_web_pki_client_cert_verifier_builder_free(struct rustls_web_pki_client_cert_verifier_builder *builder); /** - * Create a `rustls_web_pki_server_cert_verifier_builder` using the - * process-wide default crypto provider. Caller owns the memory and may free it - * with + * Create a `rustls_web_pki_server_cert_verifier_builder` using the process-wide default + * crypto provider. Caller owns the memory and may free it with * - * Caller owns the memory and may free it with - * `rustls_web_pki_server_cert_verifier_builder_free`, regardless of whether - * `rustls_web_pki_server_cert_verifier_builder_build` was called. + * Caller owns the memory and may free it with `rustls_web_pki_server_cert_verifier_builder_free`, + * regardless of whether `rustls_web_pki_server_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a server certificate - * verifier that will require a server present a certificate that chains to one - * of the trust anchors in the provided `rustls_root_cert_store`. The root cert - * store must not be empty. + * Without further modification the builder will produce a server certificate verifier that + * will require a server present a certificate that chains to one of the trust anchors + * in the provided `rustls_root_cert_store`. The root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add - * certificate revocation lists (CRLs) to the builder. If CRLs are added, - * revocation checking will be performed for the entire certificate chain - * unless - * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is - * used. Unknown revocation status for certificates considered for revocation - * status will be treated as an error unless - * `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add certificate revocation + * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed + * for the entire certificate chain unless + * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is used. Unknown + * revocation status for certificates considered for revocation status will be treated as + * an error unless `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is * used. * * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_server_cert_verifier_builder * -rustls_web_pki_server_cert_verifier_builder_new( - const struct rustls_root_cert_store *store); +struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new(const struct rustls_root_cert_store *store); /** * Create a `rustls_web_pki_server_cert_verifier_builder` using the specified @@ -2832,93 +2657,75 @@ rustls_web_pki_server_cert_verifier_builder_new( * `rustls_web_pki_server_cert_verifier_builder_free`, regardless of whether * `rustls_web_pki_server_cert_verifier_builder_build` was called. * - * Without further modification the builder will produce a server certificate - * verifier that will require a server present a certificate that chains to one - * of the trust anchors in the provided `rustls_root_cert_store`. The root cert - * store must not be empty. + * Without further modification the builder will produce a server certificate verifier that + * will require a server present a certificate that chains to one of the trust anchors + * in the provided `rustls_root_cert_store`. The root cert store must not be empty. * * Revocation checking will not be performed unless - * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add - * certificate revocation lists (CRLs) to the builder. If CRLs are added, - * revocation checking will be performed for the entire certificate chain - * unless - * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is - * used. Unknown revocation status for certificates considered for revocation - * status will be treated as an error unless - * `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is + * `rustls_web_pki_server_cert_verifier_builder_add_crl` is used to add certificate revocation + * lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed + * for the entire certificate chain unless + * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation` is used. Unknown + * revocation status for certificates considered for revocation status will be treated as + * an error unless `rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status` is * used. Expired CRLs will not be treated as an error unless * `rustls_web_pki_server_cert_verifier_enforce_revocation_expiry` is used. * * This copies the contents of the `rustls_root_cert_store`. It does not take * ownership of the pointed-to data. */ -struct rustls_web_pki_server_cert_verifier_builder * -rustls_web_pki_server_cert_verifier_builder_new_with_provider( - const struct rustls_crypto_provider *provider, - const struct rustls_root_cert_store *store); +struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider, + const struct rustls_root_cert_store *store); /** - * Add one or more certificate revocation lists (CRLs) to the server - * certificate verifier builder by reading the CRL content from the provided - * buffer of PEM encoded content. + * Add one or more certificate revocation lists (CRLs) to the server certificate verifier + * builder by reading the CRL content from the provided buffer of PEM encoded content. * - * By default revocation checking will be performed on the entire certificate - * chain. To only check the revocation status of the end entity certificate, - * use `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`. + * By default revocation checking will be performed on the entire certificate chain. To only + * check the revocation status of the end entity certificate, use + * `rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`. * - * This function returns an error if the provided buffer is not valid PEM - * encoded content. + * This function returns an error if the provided buffer is not valid PEM encoded content. */ -rustls_result rustls_web_pki_server_cert_verifier_builder_add_crl( - struct rustls_web_pki_server_cert_verifier_builder *builder, - const uint8_t *crl_pem, size_t crl_pem_len); +rustls_result rustls_web_pki_server_cert_verifier_builder_add_crl(struct rustls_web_pki_server_cert_verifier_builder *builder, + const uint8_t *crl_pem, + size_t crl_pem_len); /** - * When CRLs are provided with - * `rustls_web_pki_server_cert_verifier_builder_add_crl`, only check the - * revocation status of end entity certificates, ignoring any intermediate - * certificates in the chain. + * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, only + * check the revocation status of end entity certificates, ignoring any intermediate certificates + * in the chain. */ -rustls_result -rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation( - struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_server_cert_verifier_builder *builder); /** - * When CRLs are provided with - * `rustls_web_pki_server_cert_verifier_builder_add_crl`, and it isn't possible - * to determine the revocation status of a considered certificate, do not treat + * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, and it + * isn't possible to determine the revocation status of a considered certificate, do not treat * it as an error condition. * - * Overrides the default behavior where unknown revocation status is considered - * an error. + * Overrides the default behavior where unknown revocation status is considered an error. */ -rustls_result -rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status( - struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_server_cert_verifier_builder *builder); /** - * When CRLs are provided with - * `rustls_web_pki_server_cert_verifier_builder_add_crl`, and the CRL - * nextUpdate field is in the past, treat it as an error condition. + * When CRLs are provided with `rustls_web_pki_server_cert_verifier_builder_add_crl`, and the + * CRL nextUpdate field is in the past, treat it as an error condition. * * Overrides the default behavior where CRL expiration is ignored. */ -rustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry( - struct rustls_web_pki_server_cert_verifier_builder *builder); +rustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry(struct rustls_web_pki_server_cert_verifier_builder *builder); /** * Create a new server certificate verifier from the builder. * * The builder is consumed and cannot be used again, but must still be freed. * - * The verifier can be used in several `rustls_client_config` instances and - * must be freed by the application when no longer needed. See the - * documentation of `rustls_web_pki_server_cert_verifier_builder_free` for - * details about lifetime. + * The verifier can be used in several `rustls_client_config` instances and must be + * freed by the application when no longer needed. See the documentation of + * `rustls_web_pki_server_cert_verifier_builder_free` for details about lifetime. */ -rustls_result rustls_web_pki_server_cert_verifier_builder_build( - struct rustls_web_pki_server_cert_verifier_builder *builder, - struct rustls_server_cert_verifier **verifier_out); +rustls_result rustls_web_pki_server_cert_verifier_builder_build(struct rustls_web_pki_server_cert_verifier_builder *builder, + struct rustls_server_cert_verifier **verifier_out); /** * Free a `rustls_server_cert_verifier_builder` previously returned from @@ -2926,49 +2733,39 @@ rustls_result rustls_web_pki_server_cert_verifier_builder_build( * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_web_pki_server_cert_verifier_builder_free( - struct rustls_web_pki_server_cert_verifier_builder *builder); +void rustls_web_pki_server_cert_verifier_builder_free(struct rustls_web_pki_server_cert_verifier_builder *builder); /** * Create a verifier that uses the default behavior for the current platform. * * This uses [`rustls-platform-verifier`][]. * - * The verifier can be used in several `rustls_client_config` instances and - * must be freed by the application using `rustls_server_cert_verifier_free` - * when no longer needed. + * The verifier can be used in several `rustls_client_config` instances and must be freed by + * the application using `rustls_server_cert_verifier_free` when no longer needed. * - * [`rustls-platform-verifier`]: - * https://github.com/rustls/rustls-platform-verifier + * [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier */ -rustls_result rustls_platform_server_cert_verifier( - struct rustls_server_cert_verifier **verifier_out); +rustls_result rustls_platform_server_cert_verifier(struct rustls_server_cert_verifier **verifier_out); /** * Create a verifier that uses the default behavior for the current platform. * * This uses [`rustls-platform-verifier`][] and the specified crypto provider. * - * The verifier can be used in several `rustls_client_config` instances and - * must be freed by the application using `rustls_server_cert_verifier_free` - * when no longer needed. + * The verifier can be used in several `rustls_client_config` instances and must be freed by + * the application using `rustls_server_cert_verifier_free` when no longer needed. * - * [`rustls-platform-verifier`]: - * https://github.com/rustls/rustls-platform-verifier + * [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier */ -struct rustls_server_cert_verifier * -rustls_platform_server_cert_verifier_with_provider( - const struct rustls_crypto_provider *provider); +struct rustls_server_cert_verifier *rustls_platform_server_cert_verifier_with_provider(const struct rustls_crypto_provider *provider); /** * Free a `rustls_server_cert_verifier` previously returned from - * `rustls_server_cert_verifier_builder_build` or - * `rustls_platform_server_cert_verifier`. + * `rustls_server_cert_verifier_builder_build` or `rustls_platform_server_cert_verifier`. * * Calling with NULL is fine. Must not be called twice with the same value. */ -void rustls_server_cert_verifier_free( - struct rustls_server_cert_verifier *verifier); +void rustls_server_cert_verifier_free(struct rustls_server_cert_verifier *verifier); /** * Returns a static string containing the rustls-ffi version as well as the @@ -2977,4 +2774,4 @@ void rustls_server_cert_verifier_free( */ struct rustls_str rustls_version(void); -#endif /* RUSTLS_H */ +#endif /* RUSTLS_H */ From a2e7587df01e3995e8e1232245db975f6a74e146 Mon Sep 17 00:00:00 2001 From: Tom Stejskal Date: Mon, 31 Mar 2025 18:14:38 +0200 Subject: [PATCH 4/4] fix pull request issued - update rustls.h using cbindgen - fix formatting issue --- librustls/src/connection.rs | 2 +- librustls/src/rustls.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/librustls/src/connection.rs b/librustls/src/connection.rs index efe55a90..acdf91d3 100644 --- a/librustls/src/connection.rs +++ b/librustls/src/connection.rs @@ -545,7 +545,7 @@ impl rustls_connection { Ok(n) => n, Err(e) => { conn.last_error_msg = Some(format!("{}", e)); - return rustls_result::Io + return rustls_result::Io; } }; unsafe { diff --git a/librustls/src/rustls.h b/librustls/src/rustls.h index a1fbe85b..0dbc3c27 100644 --- a/librustls/src/rustls.h +++ b/librustls/src/rustls.h @@ -1874,7 +1874,7 @@ bool rustls_connection_fips(const struct rustls_connection *conn); * returns `true`. If there is no last error message, stores 0 in *out_n * and returns `false`. */ -bool rustls_connection_last_error_msg(const struct rustls_connection *conn, +bool rustls_connection_last_error_msg(struct rustls_connection *conn, uint8_t *buf, size_t count, size_t *out_n);