diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index a73f32cd..04b1bbe7 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -28,7 +28,7 @@ jobs: - name: Install zola uses: taiki-e/install-action@v2.87.31 with: - tool: zola@0.19.1 # Matched to rustls repo + tool: zola@0.23.6 - name: Verify API docs JSON data run: | diff --git a/librustls/src/acceptor.rs b/librustls/src/acceptor.rs index 72b159e8..b7df6fe0 100644 --- a/librustls/src/acceptor.rs +++ b/librustls/src/acceptor.rs @@ -16,30 +16,31 @@ use crate::server::rustls_server_config; /// A buffer and parser for ClientHello bytes. /// -/// This allows reading ClientHello before choosing a rustls_server_config. +/// This allows reading ClientHello before choosing a `rustls_server_config`. /// /// It's useful when the server config will be based on parameters in the /// ClientHello: server name indication (SNI), ALPN protocols, signature /// schemes, and cipher suites. /// /// 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(), +/// 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. /// /// The general flow is: -/// - rustls_acceptor_new() -/// - Loop: -/// - Read bytes from the network it with rustls_acceptor_read_tls(). -/// - If successful, parse those bytes with rustls_acceptor_accept(). -/// - If that returns RUSTLS_RESULT_ACCEPTOR_NOT_READY, continue. -/// - Otherwise, break. -/// - If rustls_acceptor_accept() returned RUSTLS_RESULT_OK: -/// - Examine the resulting rustls_accepted. -/// - Create or select a rustls_server_config. -/// - Call rustls_accepted_into_connection(). -/// - Otherwise, there was a problem with the ClientHello data and the -/// connection should be rejected. +/// +/// - `rustls_acceptor_new()` +/// - Loop: +/// - Read bytes from the network with `rustls_acceptor_read_tls()`. +/// - If successful, parse those bytes with `rustls_acceptor_accept()`. +/// - If that returns `RUSTLS_RESULT_ACCEPTOR_NOT_READY`, continue. +/// - Otherwise, break. +/// - If `rustls_acceptor_accept()` returned `RUSTLS_RESULT_OK`: +/// - Examine the resulting `rustls_accepted`. +/// - Create or select a `rustls_server_config`. +/// - Call `rustls_accepted_into_connection()`. +/// - Otherwise, there was a problem with the ClientHello data and the +/// connection should be rejected. pub struct rustls_acceptor { _private: [u8; 0], } @@ -49,7 +50,7 @@ impl Castable for rustls_acceptor { type RustType = Acceptor; } -/// A parsed ClientHello produced by a rustls_acceptor. +/// A parsed ClientHello produced by a `rustls_acceptor`. /// /// It is used to check server name indication (SNI), ALPN protocols, /// signature schemes, and cipher suites. It can be combined with a @@ -64,7 +65,7 @@ impl Castable for rustls_accepted { } impl rustls_acceptor { - /// Create and return a new rustls_acceptor. + /// Create and return a new `rustls_acceptor`. /// /// Caller owns the pointed-to memory and must eventually free it with /// `rustls_acceptor_free()`. @@ -75,11 +76,11 @@ impl rustls_acceptor { } } - /// Free a rustls_acceptor. + /// Free a `rustls_acceptor`. /// - /// Parameters: + /// **Parameters:** /// - /// acceptor: The rustls_acceptor to free. + /// - `acceptor`: The `rustls_acceptor` to free. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -96,19 +97,19 @@ impl rustls_acceptor { /// read bytes into. You don't have to fill it up, just fill with as many /// bytes as you get in one syscall. /// - /// Parameters: + /// **Parameters:** /// - /// acceptor: The rustls_acceptor to read bytes into. - /// callback: A function that will perform the actual network I/O. - /// Must be valid to call with the given userdata parameter until + /// - `acceptor`: The `rustls_acceptor` to read bytes into. + /// - `callback`: A function that will perform the actual network I/O. + /// It must be valid to call with the given `userdata` parameter until /// this function call returns. - /// userdata: An opaque parameter to be passed directly to `callback`. + /// - `userdata`: An opaque parameter to be passed directly to `callback`. /// Note: this is distinct from the `userdata` parameter set with /// `rustls_connection_set_userdata`. - /// out_n: An output parameter. This will be passed through to `callback`, - /// which should use it to store the number of bytes written. + /// - `out_n`: An output parameter that receives the number of bytes read when + /// this function returns 0. It is unchanged on error. /// - /// Returns: + /// **Returns:** /// /// - 0: Success. You should call `rustls_acceptor_accept()` next. /// - Any non-zero value: error. @@ -146,37 +147,39 @@ impl rustls_acceptor { /// Parse all TLS bytes read so far. /// - /// If those bytes make up a ClientHello, create a rustls_accepted from them. + /// If those bytes make up a ClientHello, create a `rustls_accepted` from them. /// - /// Parameters: + /// **Parameters:** /// - /// acceptor: The rustls_acceptor to access. - /// out_accepted: An output parameter. The pointed-to pointer will be set - /// to a new rustls_accepted only when the function returns - /// RUSTLS_RESULT_OK. The memory is owned by the caller and must eventually - /// be freed - /// out_alert: An output parameter. The pointed-to pointer will be set - /// to a new rustls_accepted_alert only when the function returns - /// a non-OK result. The memory is owned by the caller and must eventually - /// be freed with rustls_accepted_alert_free. The caller should call - /// rustls_accepted_alert_write_tls to write the alert bytes to the TLS - /// connection before freeing the rustls_accepted_alert. + /// - `acceptor`: The `rustls_acceptor` to access. + /// - `out_accepted`: An output parameter. The pointed-to pointer will be set + /// to a new `rustls_accepted` only when the function returns + /// `RUSTLS_RESULT_OK`. The memory is owned by the caller and must eventually + /// be freed with `rustls_accepted_free`. + /// - `out_alert`: An output parameter. The pointed-to pointer will be set + /// to a new `rustls_accepted_alert` only when a complete ClientHello is rejected. + /// `RUSTLS_RESULT_ACCEPTOR_NOT_READY` and earlier errors such as a NULL parameter do not + /// write it. The memory is owned by the caller and must eventually + /// be freed with `rustls_accepted_alert_free`. The caller should call + /// `rustls_accepted_alert_write_tls` to write the alert bytes to the TLS + /// connection before freeing the `rustls_accepted_alert`. /// - /// At most one of out_accepted or out_alert will be set. + /// The function does not initialize either output pointer. It writes at most one of + /// `out_accepted` and `out_alert`. The other retains its original value. /// - /// Returns: + /// **Returns:** /// - /// - 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. + /// - `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. - /// - Any other rustls_result: the TLS bytes read so far cannot be parsed + /// - Any other `rustls_result`: the TLS bytes read so far cannot be parsed /// as a ClientHello, and reading additional bytes won't help. /// - /// Memory and lifetimes: + /// **Memory and lifetimes:** /// - /// After this method returns RUSTLS_RESULT_OK, `acceptor` is + /// After this method returns `RUSTLS_RESULT_OK`, `acceptor` is /// still allocated and valid. It needs to be freed regardless of success /// or failure of this function. /// @@ -211,24 +214,25 @@ impl rustls_acceptor { impl rustls_accepted { /// Get the server name indication (SNI) from the ClientHello. /// - /// Parameters: + /// **Parameters:** /// - /// accepted: The rustls_accepted to access. + /// - `accepted`: The `rustls_accepted` to access. /// - /// Returns: + /// **Returns:** /// - /// A rustls_str containing the SNI field. + /// A `rustls_str` containing the SNI field. /// - /// The returned value is valid until rustls_accepted_into_connection or - /// rustls_accepted_free is called on the same `accepted`. It is not owned + /// The returned value is valid until `rustls_accepted_into_connection` or + /// `rustls_accepted_free` is called on the same `accepted`. It is not owned /// by the caller and does not need to be freed. /// - /// This will be a zero-length rustls_str in these error cases: + /// This will be a zero-length `rustls_str` in these error cases: /// - /// - The SNI contains a NUL byte. - /// - The `accepted` parameter was NULL. - /// - The `accepted` parameter was already transformed into a connection - /// with rustls_accepted_into_connection. + /// - The ClientHello did not contain an SNI extension. + /// - The SNI contains a NUL byte. + /// - The `accepted` parameter was NULL. + /// - The `accepted` parameter was already transformed into a connection + /// with `rustls_accepted_into_connection`. #[no_mangle] pub extern "C" fn rustls_accepted_server_name( accepted: *const rustls_accepted, @@ -251,25 +255,28 @@ impl rustls_accepted { } } - /// Get the i'th in the list of signature schemes offered in the ClientHello. + /// Get the i-th entry in the list of signature schemes offered in the ClientHello. /// /// This is useful in selecting a server certificate when there are multiple /// available for the same server name, for instance when selecting /// between an RSA and an ECDSA certificate. /// - /// Parameters: + /// **Parameters:** /// - /// accepted: The rustls_accepted to access. - /// i: Fetch the signature scheme at this offset. + /// - `accepted`: The `rustls_accepted` to access. + /// - `i`: Fetch the signature scheme at this offset. /// - /// Returns: + /// **Returns:** /// - /// A TLS Signature Scheme from + /// A TLS Signature Scheme from the [IANA TLS SignatureScheme registry]. /// /// 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`. + /// + /// - `i` is greater than or equal to the number of offered signature schemes. + /// - `accepted` is NULL. + /// - `rustls_accepted_into_connection` has already been called with `accepted`. + /// + /// [IANA TLS SignatureScheme registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme #[no_mangle] pub extern "C" fn rustls_accepted_signature_scheme( accepted: *const rustls_accepted, @@ -290,24 +297,27 @@ impl rustls_accepted { } } - /// Get the i'th in the list of cipher suites offered in the ClientHello. + /// Get the i-th entry in the list of cipher suites offered in the ClientHello. /// - /// Parameters: + /// **Parameters:** /// - /// accepted: The rustls_accepted to access. - /// i: Fetch the cipher suite at this offset. + /// - `accepted`: The `rustls_accepted` to access. + /// - `i`: Fetch the cipher suite at this offset. /// - /// Returns: + /// **Returns:** /// - /// A cipher suite value from + /// A cipher suite value from the [IANA TLS Cipher Suites registry]. /// /// 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`. + /// + /// - `i` is greater than or equal to the number of offered cipher suites. + /// - `accepted` is NULL. + /// - `rustls_accepted_into_connection` has already been called with `accepted`. /// /// Note that 0 is technically a valid cipher suite "TLS_NULL_WITH_NULL_NULL", /// but this library will never support null ciphers. + /// + /// [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 #[no_mangle] pub extern "C" fn rustls_accepted_cipher_suite( accepted: *const rustls_accepted, @@ -328,25 +338,28 @@ impl rustls_accepted { } } - /// Get the i'th in the list of ALPN protocols requested in the ClientHello. + /// Get the i-th entry in the list of ALPN protocols requested in the ClientHello. /// - /// accepted: The rustls_accepted to access. - /// i: Fetch the ALPN value at this offset. + /// **Parameters:** /// - /// Returns: + /// - `accepted`: The `rustls_accepted` to access. + /// - `i`: Fetch the ALPN value at this offset. /// - /// A rustls_slice_bytes containing the i'th ALPN protocol. This may + /// **Returns:** + /// + /// A `rustls_slice_bytes` containing the i-th ALPN protocol. This may /// contain internal NUL bytes and is not guaranteed to contain valid /// UTF-8. /// - /// This will be a zero-length rustls_slice bytes in these cases: - /// - i is greater than the number of offered ALPN protocols. - /// - The client did not offer the ALPN extension. - /// - The `accepted` parameter was already transformed into a connection - /// with rustls_accepted_into_connection. + /// This will be a zero-length `rustls_slice_bytes` in these cases: + /// + /// - `i` is greater than or equal to the number of offered ALPN protocols. + /// - The client did not offer the ALPN extension. + /// - The `accepted` parameter was already transformed into a connection + /// with `rustls_accepted_into_connection`. /// - /// The returned value is valid until rustls_accepted_into_connection or - /// rustls_accepted_free is called on the same `accepted`. It is not owned + /// The returned value is valid until `rustls_accepted_into_connection` or + /// `rustls_accepted_free` is called on the same `accepted`. It is not owned /// by the caller and does not need to be freed. /// /// If you are calling this from Rust, note that the `'static` lifetime @@ -373,49 +386,51 @@ impl rustls_accepted { } } - /// Turn a rustls_accepted into a rustls_connection, given the provided - /// rustls_server_config. + /// Turn a `rustls_accepted` into a `rustls_connection`, given the provided + /// `rustls_server_config`. /// - /// Parameters: + /// **Parameters:** /// - /// accepted: The rustls_accepted to transform. - /// config: The configuration with which to create this connection. - /// out_conn: An output parameter. The pointed-to pointer will be set - /// to a new rustls_connection only when the function returns - /// RUSTLS_RESULT_OK. - /// out_alert: An output parameter. The pointed-to pointer will be set - /// to a new rustls_accepted_alert when, and only when, the function returns - /// a non-OK result. The memory is owned by the caller and must eventually - /// be freed with rustls_accepted_alert_free. The caller should call - /// rustls_accepted_alert_write_tls to write the alert bytes to - /// the TLS connection before freeing the rustls_accepted_alert. + /// - `accepted`: The `rustls_accepted` to transform. + /// - `config`: The configuration with which to create this connection. + /// - `out_conn`: An output parameter. The pointed-to pointer will be set + /// to a new `rustls_connection` only when the function returns + /// `RUSTLS_RESULT_OK`. The caller owns the connection and must eventually + /// free it with `rustls_connection_free`. + /// - `out_alert`: An output parameter. The pointed-to pointer will be set + /// to a new `rustls_accepted_alert` when constructing the connection fails + /// with a TLS error. Earlier errors, such as a NULL parameter, do not write it. + /// The memory is owned by the caller and must eventually + /// be freed with `rustls_accepted_alert_free`. The caller should call + /// `rustls_accepted_alert_write_tls` to write the alert bytes to + /// the TLS connection before freeing the `rustls_accepted_alert`. /// - /// At most one of out_conn or out_alert will be set. + /// The function does not initialize either output pointer. It writes at most one of + /// `out_conn` and `out_alert`. The other retains its original value. /// - /// Returns: + /// **Returns:** /// - /// - RUSTLS_RESULT_OK: The `accepted` parameter was successfully - /// transformed into a rustls_connection, and *out_conn was written to. - /// - RUSTLS_RESULT_ALREADY_USED: This function was called twice on the - /// same rustls_connection. - /// - RUSTLS_RESULT_NULL_PARAMETER: One of the input parameters was NULL. + /// - `RUSTLS_RESULT_OK`: The `accepted` parameter was successfully + /// transformed into a `rustls_connection`, and `*out_conn` was written to. + /// - `RUSTLS_RESULT_ALREADY_USED`: This function was called twice on the + /// same `rustls_accepted`. + /// - `RUSTLS_RESULT_NULL_PARAMETER`: One of the input parameters was NULL. + /// - Any other `rustls_result`: constructing the connection failed and an alert was written + /// to `out_alert`. /// - /// Memory and lifetimes: + /// **Memory and lifetimes:** /// /// In both success and failure cases, this consumes the contents of /// `accepted` but does not free its allocated memory. In either case, - /// call rustls_accepted_free to avoid a memory leak. + /// call `rustls_accepted_free` to avoid a memory leak. /// /// Calling accessor methods on an `accepted` after consuming it will /// return zero or default values. /// - /// The rustls_connection emitted by this function in the success case - /// is owned by the caller and must eventually be freed. - /// /// This function does not take ownership of `config`. It does increment /// `config`'s internal reference count, indicating that the - /// rustls_connection may hold a reference to it until it is done. - /// See the documentation for rustls_connection for details. + /// `rustls_connection` may hold a reference to it until it is done. + /// See the documentation for `rustls_connection` for details. #[no_mangle] pub extern "C" fn rustls_accepted_into_connection( accepted: *mut rustls_accepted, @@ -443,11 +458,11 @@ impl rustls_accepted { } } - /// Free a rustls_accepted. + /// Free a `rustls_accepted`. /// - /// Parameters: + /// **Parameters:** /// - /// accepted: The rustls_accepted to free. + /// - `accepted`: The `rustls_accepted` to free. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -480,9 +495,12 @@ impl rustls_accepted_alert { /// 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 - /// more details. + /// On success, returns 0 and writes the number of bytes written to `out_n`. + /// On error, returns an errno value passed through from `callback` and leaves + /// `out_n` unchanged. See `rustls_write_callback` or rustls's [`AcceptedAlert`] + /// for more details. + /// + /// [`AcceptedAlert`]: https://docs.rs/rustls/latest/rustls/server/struct.AcceptedAlert.html #[no_mangle] pub extern "C" fn rustls_accepted_alert_write_tls( accepted_alert: *mut rustls_accepted_alert, @@ -510,11 +528,11 @@ impl rustls_accepted_alert { } } - /// Free a rustls_accepted_alert. + /// Free a `rustls_accepted_alert`. /// - /// Parameters: + /// **Parameters:** /// - /// accepted_alert: The rustls_accepted_alert to free. + /// - `accepted_alert`: The `rustls_accepted_alert` to free. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] diff --git a/librustls/src/certificate.rs b/librustls/src/certificate.rs index 696f21c6..8c42a7e7 100644 --- a/librustls/src/certificate.rs +++ b/librustls/src/certificate.rs @@ -19,7 +19,10 @@ use crate::rslice::rustls_slice_bytes; /// An X.509 certificate, as used in rustls. /// Corresponds to `CertificateDer` in the Rust pki-types API. -/// +/// +/// See also the rustls-pki-types documentation for [`CertificateDer`]. +/// +/// [`CertificateDer`]: https://docs.rs/rustls-pki-types/latest/rustls_pki_types/struct.CertificateDer.html pub struct rustls_certificate<'a> { _private: [u8; 0], _marker: PhantomData<&'a ()>, @@ -30,8 +33,13 @@ impl<'a> Castable for rustls_certificate<'a> { type RustType = CertificateDer<'a>; } -/// Get the DER data of the certificate itself. -/// The data is owned by the certificate and has the same lifetime. +/// Get the certificate's DER data. +/// +/// On success, `out_der_data` receives a borrowed pointer and `out_der_len` receives its length. +/// The data remains owned by `cert` and is valid only as long as `cert`. The caller must not +/// modify or free it. +/// +/// On error, the output parameters are unchanged. #[no_mangle] pub extern "C" fn rustls_certificate_get_der( cert: *const rustls_certificate, @@ -58,7 +66,10 @@ pub extern "C" fn rustls_certificate_get_der( /// plus a private key that matches the end-entity (leaf) certificate. /// /// Corresponds to `CertifiedKey` in the Rust API. -/// +/// +/// See also the rustls documentation for [`CertifiedKey`]. +/// +/// [`CertifiedKey`]: https://docs.rs/rustls/latest/rustls/sign/struct.CertifiedKey.html pub struct rustls_certified_key { _private: [u8; 0], } @@ -77,7 +88,7 @@ impl rustls_certified_key { /// certificate first. /// /// `private_key` must point to a buffer of `private_key_len` bytes, containing - /// a PEM-encoded private key in either PKCS#1, PKCS#8 or SEC#1 format when + /// a PEM-encoded private key in either PKCS#1, PKCS#8, or SEC1 format when /// using `aws-lc-rs` as the crypto provider. Supported formats may vary by /// provider. /// @@ -91,7 +102,9 @@ impl rustls_certified_key { /// /// This function does not take ownership of any of its input pointers. It /// parses the pointed-to data and makes a copy of the result. You may - /// free the cert_chain and private_key pointers after calling it. + /// free the `cert_chain` and `private_key` buffers after calling it. + /// + /// `certified_key_out` is unchanged if the function returns an error. /// /// Typically, you will build a `rustls_certified_key`, use it to create a /// `rustls_server_config` (which increments the reference count), and then @@ -155,9 +168,14 @@ impl rustls_certified_key { /// may retain a pointer to the object. The memory will be freed when all /// references are gone. /// - /// This function does not take ownership of any of its input pointers. It - /// parses the pointed-to data and makes a copy of the result. You may - /// free the cert_chain and private_key pointers after calling it. + /// This function copies the `cert_chain` data and does not take ownership of + /// that buffer. Once the `cert_chain` pointer has been validated, the function + /// takes ownership of `signing_key`, including when a later operation returns + /// an error. The caller must not use or free the signing key afterward. If + /// `cert_chain` is NULL, the function returns `RUSTLS_RESULT_NULL_PARAMETER` + /// without consuming `signing_key`. + /// + /// `certified_key_out` is unchanged if the function returns an error. /// /// Typically, you will build a `rustls_certified_key`, use it to create a /// `rustls_server_config` (which increments the reference count), and then @@ -191,13 +209,13 @@ impl rustls_certified_key { } } - /// Return the i-th rustls_certificate in the rustls_certified_key. + /// 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. /// /// Indexes higher than the last available certificate return NULL. /// - /// The returned certificate is valid until the rustls_certified_key is freed. + /// The returned certificate is valid until the `rustls_certified_key` is freed. #[no_mangle] pub extern "C" fn rustls_certified_key_get_certificate<'a>( certified_key: *const rustls_certified_key, @@ -212,14 +230,15 @@ impl rustls_certified_key { } } - /// Create a copy of the rustls_certified_key with the given OCSP response data + /// Create a copy of the `rustls_certified_key` with the given OCSP response data /// as DER encoded bytes. /// /// The OCSP response may be given as NULL to clear any possibly present OCSP /// data from the cloned key. /// - /// The cloned key is independent from its original and needs to be freed - /// by the application. + /// The function copies `ocsp_response` and does not take ownership of either input. + /// On success, `cloned_key_out` receives an independently owned key that the caller must + /// free with `rustls_certified_key_free`. On error, `cloned_key_out` is unchanged. #[no_mangle] pub extern "C" fn rustls_certified_key_clone_with_ocsp( certified_key: *const rustls_certified_key, @@ -258,12 +277,11 @@ impl rustls_certified_key { } } - /// "Free" a certified_key previously returned from `rustls_certified_key_build`. + /// Release the caller's reference to a `rustls_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. - /// - /// However, C code must consider this pointer unusable after "free"ing it. + /// Other objects may still hold internal references to the atomically reference-counted + /// Rust object. Regardless, the caller must not use `key` after this function returns. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -296,11 +314,9 @@ pub(crate) struct RootCertStoreBuilder { impl rustls_root_cert_store_builder { /// 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. - /// - /// 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`. + /// The caller owns the returned builder and must eventually free it with + /// `rustls_root_cert_store_builder_free`, whether or not + /// `rustls_root_cert_store_builder_build` is called. #[no_mangle] pub extern "C" fn rustls_root_cert_store_builder_new() -> *mut rustls_root_cert_store_builder { ffi_panic_boundary! { @@ -318,6 +334,8 @@ impl rustls_root_cert_store_builder { /// When `strict` is false, unparseable root certificates will be ignored. /// This may be useful on systems that have syntactically invalid root /// certificates. + /// + /// This function copies the parsed certificates and does not retain `pem`. #[no_mangle] pub extern "C" fn rustls_root_cert_store_builder_add_pem( builder: *mut rustls_root_cert_store_builder, @@ -363,6 +381,9 @@ impl rustls_root_cert_store_builder { /// When `strict` is false, unparseable root certificates will be ignored. /// This may be useful on systems that have syntactically invalid root /// certificates. + /// + /// `filename` must be a NUL-terminated UTF-8 string. It is borrowed for the + /// duration of the call and is not retained. #[no_mangle] pub extern "C" fn rustls_root_cert_store_builder_load_roots_from_file( builder: *mut rustls_root_cert_store_builder, @@ -411,9 +432,9 @@ impl rustls_root_cert_store_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 - /// `rustls_root_cert_store_free` for details about lifetime. + /// On success, `root_cert_store_out` receives a new root certificate store. The caller owns + /// it and must free it with `rustls_root_cert_store_free` when no longer needed. The store can + /// be used in multiple verifier builders. #[no_mangle] pub extern "C" fn rustls_root_cert_store_builder_build( builder: *mut rustls_root_cert_store_builder, @@ -444,7 +465,10 @@ impl rustls_root_cert_store_builder { } /// A root certificate store. -/// +/// +/// See also the rustls documentation for [`RootCertStore`]. +/// +/// [`RootCertStore`]: https://docs.rs/rustls/latest/rustls/struct.RootCertStore.html pub struct rustls_root_cert_store { _private: [u8; 0], } @@ -455,7 +479,8 @@ impl Castable for rustls_root_cert_store { } impl rustls_root_cert_store { - /// 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. #[no_mangle] diff --git a/librustls/src/cipher.rs b/librustls/src/cipher.rs index 66526731..ef01998c 100644 --- a/librustls/src/cipher.rs +++ b/librustls/src/cipher.rs @@ -16,10 +16,12 @@ impl Castable for rustls_supported_ciphersuite { } impl rustls_supported_ciphersuite { - /// 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 + /// in the [IANA TLS Cipher Suites registry]. /// /// The bytes from the assignment are interpreted in network order. + /// + /// [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 #[no_mangle] pub extern "C" fn rustls_supported_ciphersuite_get_suite( supported_ciphersuite: *const rustls_supported_ciphersuite, diff --git a/librustls/src/client.rs b/librustls/src/client.rs index bb559f8a..afd801e5 100644 --- a/librustls/src/client.rs +++ b/librustls/src/client.rs @@ -29,16 +29,19 @@ use crate::verifier::rustls_server_cert_verifier; /// A client config being constructed. /// -/// A builder can be modified by, e.g. `rustls_client_config_builder_load_roots_from_file`. +/// A builder can be modified by, e.g. `rustls_client_config_builder_set_server_verifier`. /// Once you're done configuring settings, call `rustls_client_config_builder_build` -/// to turn it into a *rustls_client_config. +/// to turn it into a `rustls_client_config`. /// /// Alternatively, if an error occurs or, you don't wish to build a config, /// call `rustls_client_config_builder_free` to free the builder directly. /// /// This object is not safe for concurrent mutation. Under the hood, /// it corresponds to a `Box`. -/// +/// +/// See also the rustls documentation for [`ConfigBuilder`]. +/// +/// [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html pub struct rustls_client_config_builder { _private: [u8; 0], } @@ -86,7 +89,10 @@ impl Default for ClientConfigBuilder { /// A client config that is done being constructed and is now read-only. /// /// Under the hood, this object corresponds to an `Arc`. -/// +/// +/// See also the rustls documentation for [`ClientConfig`]. +/// +/// [`ClientConfig`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html pub struct rustls_client_config { _private: [u8; 0], } @@ -97,7 +103,7 @@ impl Castable for rustls_client_config { } impl rustls_client_config_builder { - /// 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`. @@ -108,8 +114,9 @@ impl rustls_client_config_builder { /// 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. + /// This starts out with no trusted roots. The caller must provide a verifier with + /// `rustls_client_config_builder_set_server_verifier` or + /// `rustls_client_config_builder_dangerous_set_certificate_verifier`. #[no_mangle] pub extern "C" fn rustls_client_config_builder_new() -> *mut rustls_client_config_builder { ffi_panic_boundary! { @@ -121,7 +128,7 @@ impl rustls_client_config_builder { } } - /// Create a rustls_client_config_builder using the specified crypto provider. + /// 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`. @@ -129,16 +136,23 @@ impl rustls_client_config_builder { /// Alternatively, if an error occurs or, you don't wish to build a config, /// call `rustls_client_config_builder_free` to free the builder directly. /// - /// `tls_version` sets the TLS protocol versions to use when negotiating a TLS session. - /// `tls_version` is the version of the protocol, as defined in rfc8446, - /// ch. 4.2.1 and end of ch. 5.1. Some values are defined in - /// `rustls_tls_version` for convenience, and the arrays - /// RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly. + /// `tls_versions` sets the TLS protocol versions to use when negotiating a + /// TLS session. Each value is a protocol version as defined in RFC 8446, + /// sections 4.2.1 and 5.1. Some values are defined in `rustls_tls_version` + /// for convenience, and the arrays + /// `RUSTLS_DEFAULT_VERSIONS` or `RUSTLS_ALL_VERSIONS` can be used directly. /// /// `tls_versions` will only be used during the call and the application retains /// ownership. `tls_versions_len` is the number of consecutive `uint16_t` /// pointed to by `tls_versions`. /// + /// On `RUSTLS_RESULT_OK`, `builder_out` receives a builder owned by the caller. + /// It must eventually be passed to `rustls_client_config_builder_build` or freed with + /// `rustls_client_config_builder_free`. On error, `builder_out` is unchanged. + /// + /// The function borrows `provider` for the duration of the call and retains its own + /// reference afterward. + /// /// Ciphersuites are configured separately via the crypto provider. See /// `rustls_crypto_provider_builder_set_cipher_suites` for more information. #[no_mangle] @@ -174,13 +188,13 @@ impl rustls_client_config_builder { } /// Set a custom server certificate verifier using the builder crypto provider. - /// Returns rustls_result::NoDefaultCryptoProvider if no process default crypto + /// Returns `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` if no process default crypto /// provider has been set, and the builder was not constructed with an explicit /// provider choice. /// /// The callback must not capture any of the pointers in its - /// rustls_verify_server_cert_params. - /// If `userdata` has been set with rustls_connection_set_userdata, it + /// `rustls_verify_server_cert_params`. + /// If `userdata` has been set with `rustls_connection_set_userdata`, it /// will be passed to the callback. Otherwise the userdata param passed to /// the callback will be NULL. /// @@ -195,11 +209,13 @@ impl rustls_client_config_builder { /// if you need to parse them. /// /// If the custom verifier accepts the certificate, it should return - /// RUSTLS_RESULT_OK. Otherwise, it may return any other rustls_result error. - /// Feel free to use an appropriate error from the RUSTLS_RESULT_CERT_* - /// section. + /// `RUSTLS_RESULT_OK`. Otherwise, it may return any other `rustls_result` error, + /// including one of the certificate-related errors. /// - /// + /// See also the rustls documentation for + /// [`DangerousClientConfig::set_certificate_verifier`]. + /// + /// [`DangerousClientConfig::set_certificate_verifier`]: https://docs.rs/rustls/latest/rustls/client/struct.DangerousClientConfig.html#method.set_certificate_verifier #[no_mangle] pub extern "C" fn rustls_client_config_builder_dangerous_set_certificate_verifier( config_builder: *mut rustls_client_config_builder, @@ -224,7 +240,25 @@ impl rustls_client_config_builder { /// Configure the server certificate verifier. /// - /// This increases the reference count of `verifier` and does not take ownership. + /// For the usual case of verifying servers against a custom set of root + /// certificates: + /// + /// 1. Create a `rustls_root_cert_store_builder` with + /// `rustls_root_cert_store_builder_new`. + /// 2. Add roots with `rustls_root_cert_store_builder_add_pem` or + /// `rustls_root_cert_store_builder_load_roots_from_file`, then call + /// `rustls_root_cert_store_builder_build`. + /// 3. Pass the resulting store to + /// `rustls_web_pki_server_cert_verifier_builder_new`, then call + /// `rustls_web_pki_server_cert_verifier_builder_build`. + /// 4. Pass the resulting verifier to this function. + /// + /// Alternatively, `rustls_platform_server_cert_verifier` creates a verifier + /// using the platform's certificate facilities and trust store. + /// + /// This function increases the reference count of `verifier` and does not + /// take ownership. The caller must still free its verifier pointer with + /// `rustls_server_cert_verifier_free` when it is no longer needed. #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_server_verifier( builder: *mut rustls_client_config_builder, @@ -241,16 +275,18 @@ impl rustls_client_config_builder { /// `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 + /// Each element of the buffer must be a `rustls_slice_bytes` whose /// data field points to a single ALPN protocol ID. /// - /// Standard ALPN protocol IDs are defined at - /// . + /// Standard ALPN protocol IDs are defined in the [IANA registry]. /// /// This function makes a copy of the data in `protocols` and does not retain /// any pointers, so the caller can free the pointed-to memory after calling. /// - /// + /// See also the rustls documentation for [`ClientConfig::alpn_protocols`]. + /// + /// [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids + /// [`ClientConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/client/struct.ClientConfig.html#structfield.alpn_protocols #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_alpn_protocols( builder: *mut rustls_client_config_builder, @@ -275,7 +311,9 @@ impl rustls_client_config_builder { /// /// The default is `true`. /// - /// + /// See also the rustls documentation for [`ClientConfig::check_selected_alpn`]. + /// + /// [`ClientConfig::check_selected_alpn`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.check_selected_alpn #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_check_selected_alpn( config: *mut rustls_client_config_builder, @@ -298,7 +336,9 @@ impl rustls_client_config_builder { /// By default the extension is not sent. Note that servers are free to /// ignore the request, it is only a hint. /// - /// + /// See also the rustls documentation for [`ClientConfig::send_ticket_request`]. + /// + /// [`ClientConfig::send_ticket_request`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.send_ticket_request #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_send_ticket_request( builder: *mut rustls_client_config_builder, @@ -316,7 +356,10 @@ impl rustls_client_config_builder { } /// Enable or disable SNI. - /// + /// + /// See also the rustls documentation for [`ClientConfig::enable_sni`]. + /// + /// [`ClientConfig::enable_sni`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.enable_sni #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_enable_sni( config: *mut rustls_client_config_builder, @@ -363,15 +406,16 @@ impl rustls_client_config_builder { /// 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. + /// The key material will be logged in the [NSS key log format] 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. /// /// For more control over which secrets are logged, or to customize the format, prefer /// `rustls_client_config_builder_set_key_log`. + /// + /// [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_key_log_file( builder: *mut rustls_client_config_builder, @@ -388,8 +432,7 @@ impl rustls_client_config_builder { /// 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: - /// + /// rustls documentation for [`KeyLog::log`] 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 @@ -404,6 +447,8 @@ impl rustls_client_config_builder { /// /// 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. + /// + /// [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log #[no_mangle] pub extern "C" fn rustls_client_config_builder_set_key_log( builder: *mut rustls_client_config_builder, @@ -530,8 +575,14 @@ impl rustls_client_config_builder { } } - /// Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config + /// Turn a mutable `rustls_client_config_builder` into a const `rustls_client_config` /// (read-only). + /// + /// This function takes ownership of `builder`. The caller must not use or free the builder + /// after calling this function, regardless of the result. + /// + /// On `RUSTLS_RESULT_OK`, `config_out` receives a config owned by the caller, which must + /// eventually be freed with `rustls_client_config_free`. On error, `config_out` is unchanged. #[no_mangle] pub extern "C" fn rustls_client_config_builder_build( builder: *mut rustls_client_config_builder, @@ -597,13 +648,11 @@ impl rustls_client_config_builder { } } - /// "Free" a client_config_builder without building it into a rustls_client_config. - /// - /// Normally builders are built into rustls_client_config via `rustls_client_config_builder_build` - /// and may not be free'd or otherwise used afterwards. + /// Free a `rustls_client_config_builder` without building it into a + /// `rustls_client_config`. /// - /// Use free only when the building of a config has to be aborted before a config - /// was created. + /// Do not call this after `rustls_client_config_builder_build`, which consumes and frees the + /// builder. Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] pub extern "C" fn rustls_client_config_builder_free(config: *mut rustls_client_config_builder) { ffi_panic_boundary! { @@ -633,6 +682,12 @@ pub struct rustls_verify_server_cert_params<'a> { pub type rustls_verify_server_cert_user_data = *mut libc::c_void; /// A callback that is invoked to verify a server certificate. +/// +/// `userdata` is the value set with `rustls_connection_set_userdata`. `params` and all data +/// referenced by its fields are borrowed and valid only for the duration of the callback. +/// +/// See `rustls_client_config_builder_dangerous_set_certificate_verifier` for return values and +/// thread-safety requirements. // According to the nomicon https://doc.rust-lang.org/nomicon/ffi.html#the-nullable-pointer-optimization): // > Option c_int> is a correct way to represent a // > nullable function pointer using the C ABI (corresponding to the C type int (*)(int)). @@ -664,7 +719,7 @@ unsafe impl Send for Verifier {} /// Safety: Verifier is Sync if the C code that passes us a callback that /// obeys the concurrency safety requirements documented in -/// rustls_client_config_builder_dangerous_set_certificate_verifier. +/// `rustls_client_config_builder_dangerous_set_certificate_verifier`. unsafe impl Sync for Verifier {} impl ServerCertVerifier for Verifier { @@ -784,13 +839,12 @@ impl rustls_client_config { } } - /// "Free" a `rustls_client_config` previously returned from + /// Release the caller's reference to 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. - /// - /// However, C code must consider this pointer unusable after "free"ing it. + /// Existing client connections may still hold internal references to the atomically + /// reference-counted Rust object. Regardless, the caller must not use `config` after this + /// function returns. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -808,6 +862,9 @@ impl rustls_client_config { /// /// This function copies the contents of `server_name`. /// + /// The connection retains an internal reference to `config`. This function + /// does not take ownership of the caller's config pointer. + /// /// Uses the `rustls_client_config` to determine ALPN protocol support. Prefer /// `rustls_client_connection_new_alpn` to customize this per-connection. /// @@ -816,7 +873,7 @@ impl rustls_client_config { /// /// 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. + /// cannot be parsed as one of those types. It must be NUL-terminated. #[no_mangle] pub extern "C" fn rustls_client_connection_new( config: *const rustls_client_config, @@ -837,7 +894,7 @@ impl rustls_client_config { /// /// Operates the same as `rustls_client_connection_new`, but allows specifying /// custom per-connection ALPN protocols instead of inheriting ALPN protocols - /// from the `rustls_clinet_config`. + /// from the `rustls_client_config`. /// /// If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to /// point at a valid `rustls_connection`. The caller now owns the `rustls_connection` @@ -845,12 +902,15 @@ impl rustls_client_config { /// /// This function copies the contents of `server_name`. /// + /// The connection retains an internal reference to `config`. This function + /// does not take ownership of the caller's config pointer. + /// /// If this returns an error code, the memory pointed to by `conn_out` remains /// unchanged. /// /// 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. + /// cannot be parsed as one of those types. It must be NUL-terminated. /// /// `alpn_protocols` must point to a buffer of `rustls_slice_bytes` (built by the caller) /// with `alpn_protocols_len` elements. Each element of the buffer must be a `rustls_slice_bytes` @@ -858,8 +918,9 @@ impl rustls_client_config { /// data in `alpn_protocols` and does not retain any pointers, so the caller can free the /// pointed-to memory after calling. /// - /// Standard ALPN protocol IDs are defined at - /// . + /// Standard ALPN protocol IDs are defined in the [IANA registry]. + /// + /// [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids #[no_mangle] pub extern "C" fn rustls_client_connection_new_alpn( config: *const rustls_client_config, diff --git a/librustls/src/connection.rs b/librustls/src/connection.rs index c9d34dff..77690a26 100644 --- a/librustls/src/connection.rs +++ b/librustls/src/connection.rs @@ -104,7 +104,9 @@ impl Castable for rustls_connection { impl rustls_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. + /// + /// The pointed-to data must remain valid until the userdata is replaced or the connection + /// is freed. Rustls does not take ownership of the data and will not free it. #[no_mangle] pub extern "C" fn rustls_connection_set_userdata( conn: *mut rustls_connection, @@ -114,7 +116,7 @@ impl rustls_connection { } /// 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 + /// with the userdata parameter previously set by `rustls_connection_set_userdata`, or /// NULL if no userdata was set. #[no_mangle] pub extern "C" fn rustls_connection_set_log_callback( @@ -133,9 +135,14 @@ impl rustls_connection { /// 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. - /// + /// + /// On success, returns 0 and writes the number of bytes read to `out_n`. On error, returns + /// an errno value passed through from `callback` and leaves `out_n` unchanged. See + /// `rustls_read_callback` for more details. + /// + /// See also the rustls documentation for [`Connection::read_tls`]. + /// + /// [`Connection::read_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.read_tls #[no_mangle] pub extern "C" fn rustls_connection_read_tls( conn: *mut rustls_connection, @@ -170,9 +177,14 @@ impl rustls_connection { /// 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. - /// + /// + /// On success, returns 0 and writes the number of bytes written to `out_n`. On error, + /// returns an errno value passed through from `callback` and leaves `out_n` unchanged. + /// See `rustls_write_callback` for more details. + /// + /// See also the rustls documentation for [`Connection::write_tls`]. + /// + /// [`Connection::write_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.write_tls #[no_mangle] pub extern "C" fn rustls_connection_write_tls( conn: *mut rustls_connection, @@ -202,14 +214,19 @@ impl rustls_connection { /// 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. + /// 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. - /// + /// + /// On success, returns 0 and writes the number of bytes written to `out_n`. On error, + /// returns an errno value passed through from `callback` and leaves `out_n` unchanged. + /// See `rustls_write_vectored_callback` for more details. + /// + /// See also the rustls documentation for [`Writer::write_vectored`]. + /// + /// [`Writer::write_vectored`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write_vectored #[no_mangle] pub extern "C" fn rustls_connection_write_tls_vectored( conn: *mut rustls_connection, @@ -239,8 +256,11 @@ impl rustls_connection { /// Decrypt any available ciphertext from the internal buffer and put it /// into the internal plaintext buffer, potentially making bytes available - /// for rustls_connection_read(). - /// + /// for `rustls_connection_read()`. + /// + /// See also the rustls documentation for [`Connection::process_new_packets`]. + /// + /// [`Connection::process_new_packets`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.process_new_packets #[no_mangle] pub extern "C" fn rustls_connection_process_new_packets( conn: *mut rustls_connection, @@ -262,7 +282,9 @@ impl rustls_connection { } } - /// + /// See also the rustls documentation for [`CommonState::wants_read`]. + /// + /// [`CommonState::wants_read`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_read #[no_mangle] pub extern "C" fn rustls_connection_wants_read(conn: *const rustls_connection) -> bool { ffi_panic_boundary! { @@ -270,7 +292,9 @@ impl rustls_connection { } } - /// + /// See also the rustls documentation for [`CommonState::wants_write`]. + /// + /// [`CommonState::wants_write`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_write #[no_mangle] pub extern "C" fn rustls_connection_wants_write(conn: *const rustls_connection) -> bool { ffi_panic_boundary! { @@ -283,9 +307,9 @@ impl rustls_connection { /// 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. + /// See also the rustls documentation for [`CommonState::is_handshaking`]. /// - /// + /// [`CommonState::is_handshaking`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.is_handshaking #[no_mangle] pub extern "C" fn rustls_connection_is_handshaking(conn: *const rustls_connection) -> bool { ffi_panic_boundary! { @@ -310,7 +334,10 @@ impl rustls_connection { /// to completing the TLS handshake) and unsent TLS records. By default, there /// is no limit. The limit can be set at any time, even if the current buffer /// use is higher. - /// + /// + /// See also the rustls documentation for [`Connection::set_buffer_limit`]. + /// + /// [`Connection::set_buffer_limit`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.set_buffer_limit #[no_mangle] pub extern "C" fn rustls_connection_set_buffer_limit(conn: *mut rustls_connection, n: usize) { ffi_panic_boundary! { @@ -318,8 +345,12 @@ impl rustls_connection { } } - /// Queues a close_notify fatal alert to be sent in the next write_tls call. - /// + /// Queues a close_notify alert to be sent by the next call to + /// `rustls_connection_write_tls()`. + /// + /// See also the rustls documentation for [`Connection::send_close_notify`]. + /// + /// [`Connection::send_close_notify`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.send_close_notify #[no_mangle] pub extern "C" fn rustls_connection_send_close_notify(conn: *mut rustls_connection) { ffi_panic_boundary! { @@ -330,10 +361,11 @@ impl rustls_connection { /// 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 + /// seldom be used. See the rustls documentation for + /// [`ConnectionCommon::refresh_traffic_keys`] for important caveats and suggestions /// on occasions that merit its use. /// - /// + /// [`ConnectionCommon::refresh_traffic_keys`]: https://docs.rs/rustls/latest/rustls/struct.ConnectionCommon.html#method.refresh_traffic_keys #[no_mangle] pub extern "C" fn rustls_connection_refresh_traffic_keys( conn: *mut rustls_connection, @@ -348,13 +380,16 @@ impl rustls_connection { /// Return the i-th certificate provided by the peer. /// Index 0 is the end entity certificate. Higher indexes are certificates - /// in the chain. Requesting an index higher than what is available returns - /// NULL. + /// in the chain. Requesting an out-of-range index returns NULL. + /// /// The returned pointer 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 *`). - /// + /// affecting the connection. A mutating function call is one where the first + /// argument is a mutable pointer to `rustls_connection` (as opposed to a const + /// pointer). + /// + /// See also the rustls documentation for [`Connection::peer_certificates`]. + /// + /// [`Connection::peer_certificates`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.peer_certificates #[no_mangle] pub extern "C" fn rustls_connection_get_peer_certificate<'a>( conn: *const rustls_connection, @@ -372,16 +407,22 @@ impl rustls_connection { } /// Get the ALPN protocol that was negotiated, if any. Stores a pointer to a - /// borrowed buffer of bytes, and that buffer's len, in the output parameters. - /// The borrow lives as long as the connection. + /// borrowed buffer of bytes, and that buffer's length, in the output parameters. /// If the connection is still handshaking, or no ALPN protocol was negotiated, /// stores NULL and 0 in the output parameters. - /// The provided pointer 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 borrowed buffer is owned by the connection and is valid until the next + /// mutating function call affecting the connection. A mutating function call + /// is one where the first argument is a mutable pointer to + /// `rustls_connection` (as opposed to a const pointer). + /// The caller must not modify or free the borrowed buffer. + /// + /// If `conn` or either output parameter is NULL, both output values are unchanged. + /// Protocol identifiers are listed in the [IANA TLS Parameters registry]. See + /// also the rustls documentation for [`Connection::alpn_protocol`]. + /// + /// [IANA TLS Parameters registry]: https://www.iana.org/assignments/tls-parameters/ + /// [`Connection::alpn_protocol`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.alpn_protocol #[no_mangle] pub extern "C" fn rustls_connection_get_alpn_protocol( conn: *const rustls_connection, @@ -411,8 +452,12 @@ impl rustls_connection { /// Return the TLS protocol version that has been negotiated. Before this /// has been decided during the handshake, this will return 0. Otherwise, /// the u16 version number as defined in the relevant RFC is returned. - /// - /// + /// + /// See also the rustls documentation for [`Connection::protocol_version`] and + /// [`ProtocolVersion`]. + /// + /// [`Connection::protocol_version`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.protocol_version + /// [`ProtocolVersion`]: https://docs.rs/rustls/latest/rustls/internal/msgs/enums/enum.ProtocolVersion.html #[no_mangle] pub extern "C" fn rustls_connection_get_protocol_version( conn: *const rustls_connection, @@ -425,11 +470,11 @@ impl rustls_connection { } } - /// Retrieves the [IANA registered cipher suite identifier][IANA] agreed with the peer. + /// Retrieves the [IANA registered cipher suite identifier] agreed with the peer. /// /// This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed. /// - /// [IANA]: + /// [IANA registered cipher suite identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 #[no_mangle] pub extern "C" fn rustls_connection_get_negotiated_ciphersuite( conn: *const rustls_connection, @@ -449,7 +494,9 @@ impl rustls_connection { /// The lifetime of the `rustls_str` is the lifetime of the program, it does not /// need to be freed. /// - /// + /// See also the rustls documentation for [`Connection::negotiated_cipher_suite`]. + /// + /// [`Connection::negotiated_cipher_suite`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.negotiated_cipher_suite #[no_mangle] pub extern "C" fn rustls_connection_get_negotiated_ciphersuite_name( conn: *const rustls_connection, @@ -462,11 +509,11 @@ impl rustls_connection { } } - /// Retrieves the [IANA registered supported group identifier][IANA] agreed with the peer. + /// Retrieves the [IANA registered supported group identifier] agreed with the peer. /// /// This returns Reserved (0x0000) until the key exchange group is agreed. /// - /// [IANA]: + /// [IANA registered supported group identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 #[no_mangle] pub extern "C" fn rustls_connection_get_negotiated_key_exchange_group( conn: *const rustls_connection, @@ -515,9 +562,15 @@ impl rustls_connection { /// Write up to `count` plaintext bytes from `buf` into the `rustls_connection`. /// This will increase the number of output bytes available to /// `rustls_connection_write_tls`. - /// On success, store the number of bytes actually written in *out_n + /// On success, store the number of bytes actually written in `*out_n` /// (this may be less than `count`). - /// + /// + /// This function borrows `buf` for the duration of the call and does not retain it. + /// On error, `out_n` is unchanged. + /// + /// See also the rustls documentation for [`Writer::write`]. + /// + /// [`Writer::write`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write #[no_mangle] pub extern "C" fn rustls_connection_write( conn: *mut rustls_connection, @@ -543,17 +596,22 @@ impl rustls_connection { } /// Read up to `count` plaintext bytes from the `rustls_connection` into `buf`. - /// On success, store the number of bytes read in *out_n (this may be less - /// than `count`). A success with *out_n set to 0 means "all bytes currently + /// On success, store the number of bytes read in `*out_n` (this may be less + /// than `count`). A success with `*out_n` set to 0 means "all bytes currently /// available have been read, but more bytes may become available after - /// subsequent calls to rustls_connection_read_tls and - /// rustls_connection_process_new_packets." + /// subsequent calls to `rustls_connection_read_tls` and + /// `rustls_connection_process_new_packets`. /// /// Subtle note: Even though this function only writes to `buf` and does not /// read from it, the memory in `buf` must be initialized before the call (for /// Rust-internal reasons). Initializing a buffer once and then using it /// multiple times without zeroizing before each call is fine. - /// + /// + /// The function does not retain `buf`. On error, `out_n` is unchanged. + /// + /// See also the rustls documentation for [`Reader::read`]. + /// + /// [`Reader::read`]: https://docs.rs/rustls/latest/rustls/struct.Reader.html#method.read #[no_mangle] pub extern "C" fn rustls_connection_read( conn: *mut rustls_connection, @@ -589,11 +647,11 @@ impl rustls_connection { } /// Read up to `count` plaintext bytes from the `rustls_connection` into `buf`. - /// On success, store the number of bytes read in *out_n (this may be less - /// than `count`). A success with *out_n set to 0 means "all bytes currently + /// On success, store the number of bytes read in `*out_n` (this may be less + /// than `count`). A success with `*out_n` set to 0 means "all bytes currently /// available have been read, but more bytes may become available after - /// subsequent calls to rustls_connection_read_tls and - /// rustls_connection_process_new_packets." + /// subsequent calls to `rustls_connection_read_tls` and + /// `rustls_connection_process_new_packets`. /// /// This experimental API is only available when using a nightly Rust compiler /// and enabling the `read_buf` Cargo feature. It will be deprecated and later @@ -601,6 +659,8 @@ impl rustls_connection { /// /// Unlike with `rustls_connection_read`, this function may be called with `buf` /// pointing to an uninitialized memory buffer. + /// + /// The function does not retain `buf`. On error, `out_n` is unchanged. #[cfg(feature = "read_buf")] #[no_mangle] pub extern "C" fn rustls_connection_read_2( @@ -650,7 +710,7 @@ impl rustls_connection { } } - /// Free a rustls_connection. Calling with NULL is fine. + /// Free a `rustls_connection`. Calling with NULL is fine. /// Must not be called twice with the same value. #[no_mangle] pub extern "C" fn rustls_connection_free(conn: *mut rustls_connection) { diff --git a/librustls/src/crypto_provider.rs b/librustls/src/crypto_provider.rs index 48f5e500..03e7aa1c 100644 --- a/librustls/src/crypto_provider.rs +++ b/librustls/src/crypto_provider.rs @@ -62,13 +62,15 @@ impl CryptoProviderBuilder { /// 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_NO_DEFAULT_CRYPTO_PROVIDER` 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`. /// +/// On error, `builder_out` is unchanged. +/// /// This function is typically used for customizing the default crypto provider for specific /// connections. For example, a typical workflow might be to: /// @@ -115,6 +117,9 @@ pub extern "C" fn rustls_crypto_provider_builder_new_from_default( /// The caller owns the returned `rustls_crypto_provider_builder` and must free it using /// `rustls_crypto_provider_builder_free`. /// +/// This function does not take ownership of `base`. The builder retains its own +/// reference. +/// /// 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: @@ -178,6 +183,9 @@ pub extern "C" fn rustls_crypto_provider_builder_set_cipher_suites( /// 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. +/// +/// On `RUSTLS_RESULT_OK`, `provider_out` receives a provider owned by the caller, which must +/// eventually be freed with `rustls_crypto_provider_free`. On error, `provider_out` is unchanged. #[no_mangle] pub extern "C" fn rustls_crypto_provider_builder_build( builder: *mut rustls_crypto_provider_builder, @@ -275,9 +283,10 @@ pub extern "C" fn rustls_default_fips_provider() -> *const rustls_crypto_provide /// Retrieve a pointer to the process default `rustls_crypto_provider`. /// /// This may return `NULL` if no process default provider has been set using -/// `rustls_crypto_provider_builder_build_default`. +/// `rustls_crypto_provider_builder_build_as_default`. /// -/// Caller owns the returned `rustls_crypto_provider` and must free it w/ `rustls_crypto_provider_free`. +/// The caller owns the returned `rustls_crypto_provider` and must free it with +/// `rustls_crypto_provider_free`. #[no_mangle] pub extern "C" fn rustls_crypto_provider_default() -> *const rustls_crypto_provider { ffi_panic_boundary! { @@ -288,7 +297,8 @@ pub extern "C" fn rustls_crypto_provider_default() -> *const rustls_crypto_provi } } -/// A C representation of a Rustls [`CryptoProvider`]. +/// A C representation of a Rustls +/// [`CryptoProvider`](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html). pub struct rustls_crypto_provider { _private: [u8; 0], } @@ -298,10 +308,10 @@ impl Castable for rustls_crypto_provider { type RustType = CryptoProvider; } -/// Returns the number of ciphersuites the `rustls_crypto_provider` supports. +/// Returns the number of cipher suites the `rustls_crypto_provider` supports. /// -/// You can use this to know the maximum allowed index for use with -/// `rustls_crypto_provider_ciphersuites_get`. +/// Valid indices for `rustls_crypto_provider_ciphersuites_get` range from 0 (inclusive) to the +/// returned length (exclusive). /// /// This function will return 0 if the `provider` is NULL. #[no_mangle] @@ -313,13 +323,14 @@ pub extern "C" fn rustls_crypto_provider_ciphersuites_len( } } -/// Retrieve a pointer to a supported ciphersuite of the `rustls_crypto_provider`. +/// Retrieve a pointer to a supported cipher suite 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`. /// /// 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. +/// `provider` and should not be used after the `provider` is freed. The returned pointer is +/// borrowed and must not be freed. #[no_mangle] pub extern "C" fn rustls_crypto_provider_ciphersuites_get( provider: *const rustls_crypto_provider, @@ -340,9 +351,12 @@ pub extern "C" fn 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` +/// 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`. +/// +/// The function copies the private key data and does not retain `private_key`. On error, +/// `signing_key_out` is unchanged. #[no_mangle] pub extern "C" fn rustls_crypto_provider_load_key( provider: *const rustls_crypto_provider, @@ -417,10 +431,10 @@ pub extern "C" fn rustls_crypto_provider_free(provider: *const rustls_crypto_pro } } -/// Returns the number of ciphersuites the default process-wide crypto provider supports. +/// Returns the number of cipher suites 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`. +/// Valid indices for `rustls_default_crypto_provider_ciphersuites_get` range from 0 (inclusive) +/// to the returned length (exclusive). /// /// This function will return 0 if no process-wide default `rustls_crypto_provider` is available. #[no_mangle] @@ -433,13 +447,14 @@ pub extern "C" fn rustls_default_crypto_provider_ciphersuites_len() -> usize { } } -/// Retrieve a pointer to a supported ciphersuite of the default process-wide crypto provider. +/// Retrieve a pointer to a supported cipher suite 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 returns NULL if no process-wide default provider is available or if `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. +/// default provider lives for as long as the process. The returned pointer is borrowed and must +/// not be freed. #[no_mangle] pub extern "C" fn rustls_default_crypto_provider_ciphersuites_get( index: usize, diff --git a/librustls/src/enums.rs b/librustls/src/enums.rs index 262945e2..f442ffb3 100644 --- a/librustls/src/enums.rs +++ b/librustls/src/enums.rs @@ -68,14 +68,14 @@ pub 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. + /// unavailable and the initial ClientHello is accepted by the server. Full = 0x1, /// 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 ClientHello + /// is unacceptable for several reasons, the most likely being that the client offered + /// no supported key shares. FullWithHelloRetryRequest = 0x2, /// A resumed TLS handshake. diff --git a/librustls/src/error.rs b/librustls/src/error.rs index 22a43ab6..90ce55d2 100644 --- a/librustls/src/error.rs +++ b/librustls/src/error.rs @@ -210,12 +210,15 @@ pub enum rustls_result { } impl rustls_result { - /// After a rustls function returns an error, you may call - /// this to get a pointer to a buffer containing a detailed error - /// message. + /// After a rustls function returns an error, you may call this to write a detailed error + /// message into the caller-provided `buf`. /// - /// The contents of the error buffer will be out_n bytes long, - /// UTF-8 encoded, and not NUL-terminated. + /// This writes at most `len` bytes and stores the number written in `out_n`. If the full + /// message is longer than `len`, it is truncated. The output is UTF-8 encoded and is not + /// NUL-terminated. + /// + /// If `buf` or `out_n` is NULL, this function does nothing. The caller retains ownership of + /// `buf`, and the function does not retain it. #[no_mangle] pub extern "C" fn rustls_error( result: c_uint, @@ -240,7 +243,7 @@ impl rustls_result { } } - /// Returns true if the `result` is a certificate related error. + /// Returns true if the `result` is a certificate-related error. #[no_mangle] pub extern "C" fn rustls_result_is_cert_error(result: c_uint) -> bool { use rustls_result::*; diff --git a/librustls/src/io.rs b/librustls/src/io.rs index 1dd86321..9073c851 100644 --- a/librustls/src/io.rs +++ b/librustls/src/io.rs @@ -6,11 +6,11 @@ use crate::error::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 +/// 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. +/// 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, +/// 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. @@ -20,10 +20,10 @@ use crate::error::rustls_io_result; /// 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. +/// `userdata` is the value passed to the function invoking this callback. In most cases that +/// should point to a struct containing, 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. pub type rustls_read_callback = Option< unsafe extern "C" fn( userdata: *mut c_void, @@ -59,11 +59,11 @@ impl Read for CallbackReader { /// 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 +/// 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. +/// 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. @@ -73,12 +73,12 @@ impl Read for CallbackReader { /// 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. +/// 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 the value passed to the function invoking this callback. In most cases that +/// should point to a struct containing, 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. pub type rustls_write_callback = Option< unsafe extern "C" fn( userdata: *mut c_void, @@ -118,9 +118,14 @@ impl Write for CallbackWriter { /// An alias for `struct iovec` from uio.h (on Unix) or `WSABUF` on Windows. /// -/// You should cast `const struct rustls_iovec *` to `const struct iovec *` on -/// Unix, or `const *LPWSABUF` on Windows. See [`std::io::IoSlice`] for details -/// on interoperability with platform specific vectored IO. +/// On Unix, cast `const rustls_iovec *` to `const struct iovec *`. On Windows, +/// cast it to `const WSABUF *`; `LPWSABUF` is an alias for the non-const pointer +/// `WSABUF *`. +/// +/// See [`std::io::IoSlice`] for details on interoperability with platform-specific +/// vectored IO. +/// +/// [`std::io::IoSlice`]: https://doc.rust-lang.org/std/io/struct.IoSlice.html pub struct rustls_iovec { _private: [u8; 0], } @@ -130,23 +135,23 @@ pub struct rustls_iovec { /// 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 +/// 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, +/// 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 +/// It's best to make one write attempt to the network per call. Additional writes 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 the value passed to the function invoking this callback. In most cases that +/// should point to a struct containing, 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. pub type rustls_write_vectored_callback = Option< unsafe extern "C" fn( userdata: *mut c_void, diff --git a/librustls/src/log.rs b/librustls/src/log.rs index 67b7e53e..638ac938 100644 --- a/librustls/src/log.rs +++ b/librustls/src/log.rs @@ -48,7 +48,9 @@ pub(crate) fn ensure_log_registered() { /// Use with `rustls_log_level_str` to convert to a string label. pub type rustls_log_level = usize; -/// Return a rustls_str containing the stringified version of a log level. +/// Return a `rustls_str` containing the stringified version of a log level. +/// +/// The returned string has static lifetime and does not need to be freed. #[no_mangle] pub extern "C" fn rustls_log_level_str(level: rustls_log_level) -> rustls_str<'static> { let s = match level { @@ -72,6 +74,9 @@ pub struct rustls_log_params<'a> { } /// A callback that is invoked for messages logged by rustls. +/// +/// `params` and the message it references are borrowed and valid only for the duration of the +/// callback. `userdata` is the value set with `rustls_connection_set_userdata`. #[expect(non_camel_case_types)] pub type rustls_log_callback = Option; diff --git a/librustls/src/rslice.rs b/librustls/src/rslice.rs index 1154e6e6..6054a2e1 100644 --- a/librustls/src/rslice.rs +++ b/librustls/src/rslice.rs @@ -8,7 +8,7 @@ use libc::{c_char, size_t}; /// /// This is used to pass data from rustls-ffi to callback functions provided /// by the user of the API. -/// `len` indicates the number of bytes than can be safely read. +/// `len` indicates the number of bytes that can be safely read. /// /// The memory exposed is available as specified by the function /// using this in its signature. For instance, when this is a parameter to a @@ -89,8 +89,12 @@ pub extern "C" fn rustls_slice_slice_bytes_len(input: *const rustls_slice_slice_ /// Retrieve the nth element from the input slice of slices. /// -/// 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}. +/// If the input pointer is NULL, or `n` is greater than or equal to the length +/// of the `rustls_slice_slice_bytes`, returns a `rustls_slice_bytes` with a NULL data pointer +/// and a length of 0. +/// +/// Otherwise, the returned byte slice borrows its data from `input`. It remains valid for the +/// same lifetime as `input` and must not be freed. #[no_mangle] pub extern "C" fn rustls_slice_slice_bytes_get( input: *const rustls_slice_slice_bytes, @@ -145,9 +149,10 @@ fn test_rustls_slice_slice_bytes() { /// The contents are guaranteed to be valid UTF-8. /// /// As an additional guarantee on top of Rust's normal UTF-8 guarantee, -/// a `rustls_str` is guaranteed not to contain internal NUL bytes, so it is -/// safe to interpolate into a C string or compare using strncmp. Keep in mind -/// that it is not NUL-terminated. +/// a `rustls_str` is guaranteed not to contain internal NUL bytes. Its `data` +/// and `len` fields can be passed to APIs that accept an explicit byte length. +/// The `data` field is not NUL-terminated and must not be passed to functions +/// that expect a C string. /// /// The memory exposed is available as specified by the function /// using this in its signature. For instance, when this is a parameter to a @@ -187,10 +192,10 @@ impl Default for rustls_str<'_> { } } -/// rustls_str represents a string that can be passed to C code. +/// `rustls_str` represents a string that can be passed to C code. /// /// The string should not have any internal NUL bytes and is not NUL terminated. -/// C code should not create rustls_str objects, they should only be created in Rust +/// C code should not create `rustls_str` objects, they should only be created in Rust /// code. impl rustls_str<'_> { pub fn from_str_unchecked(s: &'static str) -> rustls_str<'static> { @@ -201,16 +206,16 @@ impl rustls_str<'_> { } } - /// Change a rustls_str's lifetime to 'static. + /// Change a `rustls_str`'s lifetime to 'static. /// /// This doesn't actually change how long the pointed-to data lives, but - /// is necessary when returning a rustls_str (as opposed to passing it + /// is necessary when returning a `rustls_str` (as opposed to passing it /// into a callback), because Rust can't figure out the "real" lifetime. /// /// # Safety /// /// The caller is responsible for requiring (usually via - /// documentation) that nothing uses the resulting rustls_str past its + /// documentation) that nothing uses the resulting `rustls_str` past its /// actual validity period. The validity period is somewhat ill-defined /// at present, but the Stacked Borrows experiment provides one definition, /// by which a shared reference is valid until a mutable reference (to @@ -219,11 +224,11 @@ impl rustls_str<'_> { std::mem::transmute(self) } - /// Change a rustls_str back to a &str. + /// Change a `rustls_str` back to a &str. /// /// # Safety /// - /// The caller must ensure the rustls_str data is valid utf8 + /// The caller must ensure the `rustls_str` data is valid utf8 pub unsafe fn to_str(&self) -> &str { str::from_utf8_unchecked(slice::from_raw_parts(self.data as *const u8, self.len)) } @@ -321,8 +326,11 @@ pub extern "C" fn rustls_slice_str_len(input: *const rustls_slice_str) -> size_t /// Retrieve the nth element from the input slice of `&str`s. /// -/// If the input pointer is NULL, or n is greater than the length of the -/// rustls_slice_str, returns rustls_str{NULL, 0}. +/// If the input pointer is NULL, or `n` is greater than or equal to the length of the +/// `rustls_slice_str`, returns a `rustls_str` with a NULL data pointer and a length of 0. +/// +/// Otherwise, the returned string borrows its data from `input`. It remains valid for the same +/// lifetime as `input` and must not be freed. #[no_mangle] pub extern "C" fn rustls_slice_str_get(input: *const rustls_slice_str, n: size_t) -> rustls_str { let input: &rustls_slice_str = unsafe { @@ -376,7 +384,7 @@ fn test_rustls_slice_str() { /// /// This is used to pass data from rustls-ffi to callback functions provided /// by the user of the API. -/// `len` indicates the number of bytes than can be safely read. +/// `len` indicates the number of 16-bit integers that can be safely read. /// /// The memory exposed is available as specified by the function /// using this in its signature. For instance, when this is a parameter to a diff --git a/librustls/src/rustls.h b/librustls/src/rustls.h index 61625c49..9715376a 100644 --- a/librustls/src/rustls.h +++ b/librustls/src/rustls.h @@ -195,15 +195,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. + * unavailable and the initial ClientHello is 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 ClientHello + * is unacceptable for several reasons, the most likely being that the client offered + * no supported key shares. */ RUSTLS_HANDSHAKE_KIND_FULL_WITH_HELLO_RETRY_REQUEST = 2, /** @@ -217,7 +217,7 @@ typedef enum rustls_handshake_kind { } rustls_handshake_kind; /** - * A parsed ClientHello produced by a rustls_acceptor. + * A parsed ClientHello produced by a `rustls_acceptor`. * * It is used to check server name indication (SNI), ALPN protocols, * signature schemes, and cipher suites. It can be combined with a @@ -233,37 +233,41 @@ typedef struct rustls_accepted_alert rustls_accepted_alert; /** * A buffer and parser for ClientHello bytes. * - * This allows reading ClientHello before choosing a rustls_server_config. + * This allows reading ClientHello before choosing a `rustls_server_config`. * * It's useful when the server config will be based on parameters in the * ClientHello: server name indication (SNI), ALPN protocols, signature * schemes, and cipher suites. * * 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(), + * 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. * * The general flow is: - * - rustls_acceptor_new() - * - Loop: - * - Read bytes from the network it with rustls_acceptor_read_tls(). - * - If successful, parse those bytes with rustls_acceptor_accept(). - * - If that returns RUSTLS_RESULT_ACCEPTOR_NOT_READY, continue. - * - Otherwise, break. - * - If rustls_acceptor_accept() returned RUSTLS_RESULT_OK: - * - Examine the resulting rustls_accepted. - * - Create or select a rustls_server_config. - * - Call rustls_accepted_into_connection(). - * - Otherwise, there was a problem with the ClientHello data and the - * connection should be rejected. + * + * - `rustls_acceptor_new()` + * - Loop: + * - Read bytes from the network with `rustls_acceptor_read_tls()`. + * - If successful, parse those bytes with `rustls_acceptor_accept()`. + * - If that returns `RUSTLS_RESULT_ACCEPTOR_NOT_READY`, continue. + * - Otherwise, break. + * - If `rustls_acceptor_accept()` returned `RUSTLS_RESULT_OK`: + * - Examine the resulting `rustls_accepted`. + * - Create or select a `rustls_server_config`. + * - Call `rustls_accepted_into_connection()`. + * - Otherwise, there was a problem with the ClientHello data and the + * connection should be rejected. */ typedef struct rustls_acceptor rustls_acceptor; /** * An X.509 certificate, as used in rustls. * Corresponds to `CertificateDer` in the Rust pki-types API. - * + * + * See also the rustls-pki-types documentation for [`CertificateDer`]. + * + * [`CertificateDer`]: https://docs.rs/rustls-pki-types/latest/rustls_pki_types/struct.CertificateDer.html */ typedef struct rustls_certificate rustls_certificate; @@ -272,7 +276,10 @@ typedef struct rustls_certificate rustls_certificate; * plus a private key that matches the end-entity (leaf) certificate. * * Corresponds to `CertifiedKey` in the Rust API. - * + * + * See also the rustls documentation for [`CertifiedKey`]. + * + * [`CertifiedKey`]: https://docs.rs/rustls/latest/rustls/sign/struct.CertifiedKey.html */ typedef struct rustls_certified_key rustls_certified_key; @@ -286,23 +293,29 @@ typedef struct rustls_client_cert_verifier rustls_client_cert_verifier; * A client config that is done being constructed and is now read-only. * * Under the hood, this object corresponds to an `Arc`. - * + * + * See also the rustls documentation for [`ClientConfig`]. + * + * [`ClientConfig`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html */ 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`. + * A builder can be modified by, e.g. `rustls_client_config_builder_set_server_verifier`. * Once you're done configuring settings, call `rustls_client_config_builder_build` - * to turn it into a *rustls_client_config. + * to turn it into a `rustls_client_config`. * * Alternatively, if an error occurs or, you don't wish to build a config, * call `rustls_client_config_builder_free` to free the builder directly. * * This object is not safe for concurrent mutation. Under the hood, * it corresponds to a `Box`. - * + * + * See also the rustls documentation for [`ConfigBuilder`]. + * + * [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html */ typedef struct rustls_client_config_builder rustls_client_config_builder; @@ -312,7 +325,8 @@ typedef struct rustls_client_config_builder rustls_client_config_builder; typedef struct rustls_connection rustls_connection; /** - * A C representation of a Rustls [`CryptoProvider`]. + * A C representation of a Rustls + * [`CryptoProvider`](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html). */ typedef struct rustls_crypto_provider rustls_crypto_provider; @@ -333,15 +347,23 @@ typedef struct rustls_hpke rustls_hpke; /** * An alias for `struct iovec` from uio.h (on Unix) or `WSABUF` on Windows. * - * You should cast `const struct rustls_iovec *` to `const struct iovec *` on - * Unix, or `const *LPWSABUF` on Windows. See [`std::io::IoSlice`] for details - * on interoperability with platform specific vectored IO. + * On Unix, cast `const rustls_iovec *` to `const struct iovec *`. On Windows, + * cast it to `const WSABUF *`; `LPWSABUF` is an alias for the non-const pointer + * `WSABUF *`. + * + * See [`std::io::IoSlice`] for details on interoperability with platform-specific + * vectored IO. + * + * [`std::io::IoSlice`]: https://doc.rust-lang.org/std/io/struct.IoSlice.html */ typedef struct rustls_iovec rustls_iovec; /** * A root certificate store. - * + * + * See also the rustls documentation for [`RootCertStore`]. + * + * [`RootCertStore`]: https://docs.rs/rustls/latest/rustls/struct.RootCertStore.html */ typedef struct rustls_root_cert_store rustls_root_cert_store; @@ -365,23 +387,28 @@ typedef struct rustls_server_cert_verifier rustls_server_cert_verifier; * A server config that is done being constructed and is now read-only. * * Under the hood, this object corresponds to an `Arc`. - * + * + * See also the rustls documentation for [`ServerConfig`]. + * + * [`ServerConfig`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html */ typedef struct rustls_server_config rustls_server_config; /** * A server config being constructed. * - * A builder can be modified by, - * e.g. rustls_server_config_builder_load_native_roots. Once you're - * done configuring settings, call rustls_server_config_builder_build - * to turn it into a *const rustls_server_config. + * A builder can be modified by, e.g. `rustls_server_config_builder_set_certified_keys`. + * Once you're done configuring settings, call `rustls_server_config_builder_build` + * to turn it into a `rustls_server_config`. * * Alternatively, if an error occurs or, you don't wish to build a config, * call `rustls_server_config_builder_free` to free the builder directly. * * This object is not safe for concurrent mutation. - * + * + * See also the rustls documentation for [`ConfigBuilder`]. + * + * [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html */ typedef struct rustls_server_config_builder rustls_server_config_builder; @@ -443,8 +470,9 @@ typedef struct rustls_supported_ciphersuite rustls_supported_ciphersuite; * * This object is not safe for concurrent mutation. * - * See - * for more information. + * See also the rustls documentation for [`ClientCertVerifierBuilder`]. + * + * [`ClientCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/server/struct.ClientCertVerifierBuilder.html */ typedef struct rustls_web_pki_client_cert_verifier_builder rustls_web_pki_client_cert_verifier_builder; @@ -456,8 +484,9 @@ typedef struct rustls_web_pki_client_cert_verifier_builder rustls_web_pki_client * 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 - * for more information. + * See also the rustls documentation for [`ServerCertVerifierBuilder`]. + * + * [`ServerCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/client/struct.ServerCertVerifierBuilder.html */ typedef struct rustls_web_pki_server_cert_verifier_builder rustls_web_pki_server_cert_verifier_builder; @@ -473,11 +502,11 @@ 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 + * 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. + * 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, + * 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. @@ -487,10 +516,10 @@ typedef int rustls_io_result; * 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. + * `userdata` is the value passed to the function invoking this callback. In most cases that + * should point to a struct containing, 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, @@ -503,9 +532,10 @@ typedef rustls_io_result (*rustls_read_callback)(void *userdata, * The contents are guaranteed to be valid UTF-8. * * As an additional guarantee on top of Rust's normal UTF-8 guarantee, - * a `rustls_str` is guaranteed not to contain internal NUL bytes, so it is - * safe to interpolate into a C string or compare using strncmp. Keep in mind - * that it is not NUL-terminated. + * a `rustls_str` is guaranteed not to contain internal NUL bytes. Its `data` + * and `len` fields can be passed to APIs that accept an explicit byte length. + * The `data` field is not NUL-terminated and must not be passed to functions + * that expect a C string. * * The memory exposed is available as specified by the function * using this in its signature. For instance, when this is a parameter to a @@ -523,7 +553,7 @@ typedef struct rustls_str { * * This is used to pass data from rustls-ffi to callback functions provided * by the user of the API. - * `len` indicates the number of bytes than can be safely read. + * `len` indicates the number of bytes that can be safely read. * * The memory exposed is available as specified by the function * using this in its signature. For instance, when this is a parameter to a @@ -539,11 +569,11 @@ typedef struct rustls_slice_bytes { /** * 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 + * 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. + * 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. @@ -553,12 +583,12 @@ typedef struct rustls_slice_bytes { * 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. + * 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 the value passed to the function invoking this callback. In most cases that + * should point to a struct containing, 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, @@ -589,6 +619,12 @@ typedef struct rustls_verify_server_cert_params { /** * A callback that is invoked to verify a server certificate. + * + * `userdata` is the value set with `rustls_connection_set_userdata`. `params` and all data + * referenced by its fields are borrowed and valid only for the duration of the callback. + * + * See `rustls_client_config_builder_dangerous_set_certificate_verifier` for return values and + * thread-safety requirements. */ typedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata, const struct rustls_verify_server_cert_params *params); @@ -639,6 +675,9 @@ typedef struct rustls_log_params { /** * A callback that is invoked for messages logged by rustls. + * + * `params` and the message it references are borrowed and valid only for the duration of the + * callback. `userdata` is the value set with `rustls_connection_set_userdata`. */ typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params); @@ -648,23 +687,23 @@ 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 + * 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, + * 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 + * It's best to make one write attempt to the network per call. Additional writes 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 the value passed to the function invoking this callback. In most cases that + * should point to a struct containing, 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, @@ -681,7 +720,7 @@ typedef void *rustls_client_hello_userdata; * * This is used to pass data from rustls-ffi to callback functions provided * by the user of the API. - * `len` indicates the number of bytes than can be safely read. + * `len` indicates the number of 16-bit integers that can be safely read. * * The memory exposed is available as specified by the function * using this in its signature. For instance, when this is a parameter to a @@ -695,31 +734,34 @@ typedef struct rustls_slice_u16 { } rustls_slice_u16; /** - * The TLS Client Hello information provided to a ClientHelloCallback function. + * The TLS ClientHello information provided to a `rustls_client_hello_callback`. * - * `server_name` is the value of the ServerNameIndication extension provided + * `server_name` is the value of the server name indication (SNI) extension provided * by the client. If the client did not send an SNI, the length of this - * `rustls_string` will be 0. + * `rustls_str` 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 the rustls documentation for [`SignatureScheme`] for more information. * * `named_groups` carries the values of the `named_groups` extension sent by the * client. If the client did not send a `named_groups` extension, the length of - * this `rustls_slice_u16` will be 0. The meaning of this extension differ - * based on TLS version. See the Rustls documentation for more information: - * + * this `rustls_slice_u16` will be 0. The meaning of this extension differs + * based on TLS version. See the rustls documentation for + * [`ClientHello::named_groups`] for more information. * * `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. + * they want to access after the callback returns. * * 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. + * the rustls library is re-evaluating its current approach to ClientHello handling. + * + * [`SignatureScheme`]: https://docs.rs/rustls/latest/rustls/enum.SignatureScheme.html + * [`ClientHello::named_groups`]: https://rustls.dev/docs/server/struct.ClientHello.html#method.named_groups */ typedef struct rustls_client_hello { struct rustls_str server_name; @@ -732,23 +774,23 @@ typedef struct rustls_client_hello { * Prototype of a callback that can be installed by the application at the * `rustls_server_config`. * - * This callback will be invoked by a `rustls_connection` once the TLS client - * hello message has been received. + * This callback will be invoked by a `rustls_connection` once the TLS ClientHello + * message has been received. * - * `userdata` will be set based on rustls_connection_set_userdata. + * `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` contains the client parameters parsed 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 + * **Note:** + * + * - The passed-in `hello` and all its values are only valid during the callback invocation. + * - The callback 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. + * the rustls library is re-evaluating its current approach to ClientHello handling. */ typedef const struct rustls_certified_key *(*rustls_client_hello_callback)(rustls_client_hello_userdata userdata, const struct rustls_client_hello *hello); @@ -763,9 +805,9 @@ typedef void *rustls_session_store_userdata; * `rustls_server_config` or `rustls_client_config`. * * This callback will be invoked by a TLS session when looking up the data - * for a TLS session id. + * for a TLS session ID. * - * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on `rustls_connection_set_userdata`. * * The `buf` points to `count` consecutive bytes where the * callback is expected to copy the result to. The number of copied bytes @@ -776,17 +818,17 @@ typedef void *rustls_session_store_userdata; * do a partial copy but instead remove the value from its store and * act as if it was never found. * - * The callback should return RUSTLS_RESULT_OK to indicate that a value was - * retrieved and written in its entirety into `buf`, or RUSTLS_RESULT_NOT_FOUND + * The callback should return `RUSTLS_RESULT_OK` to indicate that a value was + * retrieved and written in its entirety into `buf`, or `RUSTLS_RESULT_NOT_FOUND` * if no session was retrieved. * - * When `remove_after` is != 0, the returned data needs to be removed + * When `remove_after` is nonzero, the returned data needs to be removed * from the store. * - * NOTE: the passed in `key` and `buf` are only available during the - * callback invocation. - * NOTE: callbacks used in several sessions via a common config - * must be implemented thread-safe. + * **Notes:** + * + * - The passed-in `key` and `buf` are only valid during the callback invocation. + * - Callbacks shared by several sessions through a common config must be thread-safe. */ typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, @@ -799,19 +841,18 @@ typedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userd * Prototype of a callback that can be installed by the application at the * `rustls_server_config` or `rustls_client_config`. * - * This callback will be invoked by a TLS session when a TLS session - * been created and an id for later use is handed to the client/has - * been received from the server. + * This callback will be invoked when a resumable TLS session has been created and a session ID + * has either been sent to the client or received from the server. * - * `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. + * `userdata` will be supplied based on `rustls_connection_set_userdata`. * - * The callback should return RUSTLS_RESULT_OK to indicate that a value was - * successfully stored, or RUSTLS_RESULT_IO on failure. + * The callback should return `RUSTLS_RESULT_OK` to indicate that a value was + * successfully stored, or `RUSTLS_RESULT_IO` on failure. * - * NOTE: the passed in `key` and `val` are only available during the - * callback invocation. - * NOTE: callbacks used in several sessions via a common config - * must be implemented thread-safe. + * **Notes:** + * + * - The passed-in `key` and `val` are only valid during the callback invocation. + * - Callbacks shared by several sessions through a common config must be thread-safe. */ typedef uint32_t (*rustls_session_store_put_callback)(rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, @@ -840,7 +881,7 @@ extern const uint16_t RUSTLS_DEFAULT_VERSIONS[2]; extern const size_t RUSTLS_DEFAULT_VERSIONS_LEN; /** - * Create and return a new rustls_acceptor. + * Create and return a new `rustls_acceptor`. * * Caller owns the pointed-to memory and must eventually free it with * `rustls_acceptor_free()`. @@ -848,11 +889,11 @@ extern const size_t RUSTLS_DEFAULT_VERSIONS_LEN; struct rustls_acceptor *rustls_acceptor_new(void); /** - * Free a rustls_acceptor. + * Free a `rustls_acceptor`. * - * Parameters: + * **Parameters:** * - * acceptor: The rustls_acceptor to free. + * - `acceptor`: The `rustls_acceptor` to free. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -866,19 +907,19 @@ void rustls_acceptor_free(struct rustls_acceptor *acceptor); * read bytes into. You don't have to fill it up, just fill with as many * bytes as you get in one syscall. * - * Parameters: + * **Parameters:** * - * acceptor: The rustls_acceptor to read bytes into. - * callback: A function that will perform the actual network I/O. - * Must be valid to call with the given userdata parameter until + * - `acceptor`: The `rustls_acceptor` to read bytes into. + * - `callback`: A function that will perform the actual network I/O. + * It must be valid to call with the given `userdata` parameter until * this function call returns. - * userdata: An opaque parameter to be passed directly to `callback`. + * - `userdata`: An opaque parameter to be passed directly to `callback`. * Note: this is distinct from the `userdata` parameter set with * `rustls_connection_set_userdata`. - * out_n: An output parameter. This will be passed through to `callback`, - * which should use it to store the number of bytes written. + * - `out_n`: An output parameter that receives the number of bytes read when + * this function returns 0. It is unchanged on error. * - * Returns: + * **Returns:** * * - 0: Success. You should call `rustls_acceptor_accept()` next. * - Any non-zero value: error. @@ -895,37 +936,39 @@ rustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor, /** * Parse all TLS bytes read so far. * - * If those bytes make up a ClientHello, create a rustls_accepted from them. + * If those bytes make up a ClientHello, create a `rustls_accepted` from them. * - * Parameters: + * **Parameters:** * - * acceptor: The rustls_acceptor to access. - * out_accepted: An output parameter. The pointed-to pointer will be set - * to a new rustls_accepted only when the function returns - * RUSTLS_RESULT_OK. The memory is owned by the caller and must eventually - * be freed - * out_alert: An output parameter. The pointed-to pointer will be set - * to a new rustls_accepted_alert only when the function returns - * a non-OK result. The memory is owned by the caller and must eventually - * be freed with rustls_accepted_alert_free. The caller should call - * rustls_accepted_alert_write_tls to write the alert bytes to the TLS - * connection before freeing the rustls_accepted_alert. + * - `acceptor`: The `rustls_acceptor` to access. + * - `out_accepted`: An output parameter. The pointed-to pointer will be set + * to a new `rustls_accepted` only when the function returns + * `RUSTLS_RESULT_OK`. The memory is owned by the caller and must eventually + * be freed with `rustls_accepted_free`. + * - `out_alert`: An output parameter. The pointed-to pointer will be set + * to a new `rustls_accepted_alert` only when a complete ClientHello is rejected. + * `RUSTLS_RESULT_ACCEPTOR_NOT_READY` and earlier errors such as a NULL parameter do not + * write it. The memory is owned by the caller and must eventually + * be freed with `rustls_accepted_alert_free`. The caller should call + * `rustls_accepted_alert_write_tls` to write the alert bytes to the TLS + * connection before freeing the `rustls_accepted_alert`. * - * At most one of out_accepted or out_alert will be set. + * The function does not initialize either output pointer. It writes at most one of + * `out_accepted` and `out_alert`. The other retains its original value. * - * Returns: + * **Returns:** * - * - 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. + * - `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. - * - Any other rustls_result: the TLS bytes read so far cannot be parsed + * - Any other `rustls_result`: the TLS bytes read so far cannot be parsed * as a ClientHello, and reading additional bytes won't help. * - * Memory and lifetimes: + * **Memory and lifetimes:** * - * After this method returns RUSTLS_RESULT_OK, `acceptor` is + * After this method returns `RUSTLS_RESULT_OK`, `acceptor` is * still allocated and valid. It needs to be freed regardless of success * or failure of this function. * @@ -940,94 +983,104 @@ rustls_result rustls_acceptor_accept(struct rustls_acceptor *acceptor, /** * Get the server name indication (SNI) from the ClientHello. * - * Parameters: + * **Parameters:** * - * accepted: The rustls_accepted to access. + * - `accepted`: The `rustls_accepted` to access. * - * Returns: + * **Returns:** * - * A rustls_str containing the SNI field. + * A `rustls_str` containing the SNI field. * - * The returned value is valid until rustls_accepted_into_connection or - * rustls_accepted_free is called on the same `accepted`. It is not owned + * The returned value is valid until `rustls_accepted_into_connection` or + * `rustls_accepted_free` is called on the same `accepted`. It is not owned * by the caller and does not need to be freed. * - * This will be a zero-length rustls_str in these error cases: + * This will be a zero-length `rustls_str` in these error cases: * - * - The SNI contains a NUL byte. - * - The `accepted` parameter was NULL. - * - The `accepted` parameter was already transformed into a connection - * with rustls_accepted_into_connection. + * - The ClientHello did not contain an SNI extension. + * - The SNI contains a NUL byte. + * - The `accepted` parameter was NULL. + * - 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); /** - * Get the i'th in the list of signature schemes offered in the ClientHello. + * Get the i-th entry in the list of signature schemes offered in the ClientHello. * * This is useful in selecting a server certificate when there are multiple * available for the same server name, for instance when selecting * between an RSA and an ECDSA certificate. * - * Parameters: + * **Parameters:** * - * accepted: The rustls_accepted to access. - * i: Fetch the signature scheme at this offset. + * - `accepted`: The `rustls_accepted` to access. + * - `i`: Fetch the signature scheme at this offset. * - * Returns: + * **Returns:** * - * A TLS Signature Scheme from + * A TLS Signature Scheme from the [IANA TLS SignatureScheme registry]. * * 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`. + * + * - `i` is greater than or equal to the number of offered signature schemes. + * - `accepted` is NULL. + * - `rustls_accepted_into_connection` has already been called with `accepted`. + * + * [IANA TLS SignatureScheme registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme */ 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. + * Get the i-th entry in the list of cipher suites offered in the ClientHello. * - * Parameters: + * **Parameters:** * - * accepted: The rustls_accepted to access. - * i: Fetch the cipher suite at this offset. + * - `accepted`: The `rustls_accepted` to access. + * - `i`: Fetch the cipher suite at this offset. * - * Returns: + * **Returns:** * - * A cipher suite value from + * A cipher suite value from the [IANA TLS Cipher Suites registry]. * * 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`. + * + * - `i` is greater than or equal to the number of offered cipher suites. + * - `accepted` is NULL. + * - `rustls_accepted_into_connection` has already been called with `accepted`. * * Note that 0 is technically a valid cipher suite "TLS_NULL_WITH_NULL_NULL", * but this library will never support null ciphers. + * + * [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 */ uint16_t rustls_accepted_cipher_suite(const struct rustls_accepted *accepted, size_t i); /** - * Get the i'th in the list of ALPN protocols requested in the ClientHello. + * Get the i-th entry in the list of ALPN protocols requested in the ClientHello. * - * accepted: The rustls_accepted to access. - * i: Fetch the ALPN value at this offset. + * **Parameters:** * - * Returns: + * - `accepted`: The `rustls_accepted` to access. + * - `i`: Fetch the ALPN value at this offset. * - * A rustls_slice_bytes containing the i'th ALPN protocol. This may + * **Returns:** + * + * A `rustls_slice_bytes` containing the i-th ALPN protocol. This may * contain internal NUL bytes and is not guaranteed to contain valid * UTF-8. * - * This will be a zero-length rustls_slice bytes in these cases: - * - i is greater than the number of offered ALPN protocols. - * - The client did not offer the ALPN extension. - * - The `accepted` parameter was already transformed into a connection - * with rustls_accepted_into_connection. + * This will be a zero-length `rustls_slice_bytes` in these cases: + * + * - `i` is greater than or equal to the number of offered ALPN protocols. + * - The client did not offer the ALPN extension. + * - The `accepted` parameter was already transformed into a connection + * with `rustls_accepted_into_connection`. * - * The returned value is valid until rustls_accepted_into_connection or - * rustls_accepted_free is called on the same `accepted`. It is not owned + * The returned value is valid until `rustls_accepted_into_connection` or + * `rustls_accepted_free` is called on the same `accepted`. It is not owned * by the caller and does not need to be freed. * * If you are calling this from Rust, note that the `'static` lifetime @@ -1036,49 +1089,51 @@ uint16_t rustls_accepted_cipher_suite(const struct rustls_accepted *accepted, 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 - * rustls_server_config. - * - * Parameters: - * - * accepted: The rustls_accepted to transform. - * config: The configuration with which to create this connection. - * out_conn: An output parameter. The pointed-to pointer will be set - * to a new rustls_connection only when the function returns - * RUSTLS_RESULT_OK. - * out_alert: An output parameter. The pointed-to pointer will be set - * to a new rustls_accepted_alert when, and only when, the function returns - * a non-OK result. The memory is owned by the caller and must eventually - * be freed with rustls_accepted_alert_free. The caller should call - * rustls_accepted_alert_write_tls to write the alert bytes to - * the TLS connection before freeing the rustls_accepted_alert. - * - * At most one of out_conn or out_alert will be set. - * - * Returns: - * - * - RUSTLS_RESULT_OK: The `accepted` parameter was successfully - * transformed into a rustls_connection, and *out_conn was written to. - * - RUSTLS_RESULT_ALREADY_USED: This function was called twice on the - * same rustls_connection. - * - RUSTLS_RESULT_NULL_PARAMETER: One of the input parameters was NULL. + * Turn a `rustls_accepted` into a `rustls_connection`, given the provided + * `rustls_server_config`. * - * Memory and lifetimes: + * **Parameters:** + * + * - `accepted`: The `rustls_accepted` to transform. + * - `config`: The configuration with which to create this connection. + * - `out_conn`: An output parameter. The pointed-to pointer will be set + * to a new `rustls_connection` only when the function returns + * `RUSTLS_RESULT_OK`. The caller owns the connection and must eventually + * free it with `rustls_connection_free`. + * - `out_alert`: An output parameter. The pointed-to pointer will be set + * to a new `rustls_accepted_alert` when constructing the connection fails + * with a TLS error. Earlier errors, such as a NULL parameter, do not write it. + * The memory is owned by the caller and must eventually + * be freed with `rustls_accepted_alert_free`. The caller should call + * `rustls_accepted_alert_write_tls` to write the alert bytes to + * the TLS connection before freeing the `rustls_accepted_alert`. + * + * The function does not initialize either output pointer. It writes at most one of + * `out_conn` and `out_alert`. The other retains its original value. + * + * **Returns:** + * + * - `RUSTLS_RESULT_OK`: The `accepted` parameter was successfully + * transformed into a `rustls_connection`, and `*out_conn` was written to. + * - `RUSTLS_RESULT_ALREADY_USED`: This function was called twice on the + * same `rustls_accepted`. + * - `RUSTLS_RESULT_NULL_PARAMETER`: One of the input parameters was NULL. + * - Any other `rustls_result`: constructing the connection failed and an alert was written + * to `out_alert`. + * + * **Memory and lifetimes:** * * In both success and failure cases, this consumes the contents of * `accepted` but does not free its allocated memory. In either case, - * call rustls_accepted_free to avoid a memory leak. + * call `rustls_accepted_free` to avoid a memory leak. * * Calling accessor methods on an `accepted` after consuming it will * return zero or default values. * - * The rustls_connection emitted by this function in the success case - * is owned by the caller and must eventually be freed. - * * This function does not take ownership of `config`. It does increment * `config`'s internal reference count, indicating that the - * rustls_connection may hold a reference to it until it is done. - * See the documentation for rustls_connection for details. + * `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, @@ -1086,11 +1141,11 @@ rustls_result rustls_accepted_into_connection(struct rustls_accepted *accepted, struct rustls_accepted_alert **out_alert); /** - * Free a rustls_accepted. + * Free a `rustls_accepted`. * - * Parameters: + * **Parameters:** * - * accepted: The rustls_accepted to free. + * - `accepted`: The `rustls_accepted` to free. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -1108,9 +1163,12 @@ 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 - * more details. + * On success, returns 0 and writes the number of bytes written to `out_n`. + * On error, returns an errno value passed through from `callback` and leaves + * `out_n` unchanged. See `rustls_write_callback` or rustls's [`AcceptedAlert`] + * for more details. + * + * [`AcceptedAlert`]: https://docs.rs/rustls/latest/rustls/server/struct.AcceptedAlert.html */ rustls_io_result rustls_accepted_alert_write_tls(struct rustls_accepted_alert *accepted_alert, rustls_write_callback callback, @@ -1118,19 +1176,24 @@ rustls_io_result rustls_accepted_alert_write_tls(struct rustls_accepted_alert *a size_t *out_n); /** - * Free a rustls_accepted_alert. + * Free a `rustls_accepted_alert`. * - * Parameters: + * **Parameters:** * - * accepted_alert: The rustls_accepted_alert to free. + * - `accepted_alert`: The `rustls_accepted_alert` to free. * * Calling with NULL is fine. Must not be called twice with the same value. */ void rustls_accepted_alert_free(struct rustls_accepted_alert *accepted_alert); /** - * Get the DER data of the certificate itself. - * The data is owned by the certificate and has the same lifetime. + * Get the certificate's DER data. + * + * On success, `out_der_data` receives a borrowed pointer and `out_der_len` receives its length. + * The data remains owned by `cert` and is valid only as long as `cert`. The caller must not + * modify or free it. + * + * On error, the output parameters are unchanged. */ rustls_result rustls_certificate_get_der(const struct rustls_certificate *cert, const uint8_t **out_der_data, @@ -1145,7 +1208,7 @@ rustls_result rustls_certificate_get_der(const struct rustls_certificate *cert, * certificate first. * * `private_key` must point to a buffer of `private_key_len` bytes, containing - * a PEM-encoded private key in either PKCS#1, PKCS#8 or SEC#1 format when + * a PEM-encoded private key in either PKCS#1, PKCS#8, or SEC1 format when * using `aws-lc-rs` as the crypto provider. Supported formats may vary by * provider. * @@ -1159,7 +1222,9 @@ rustls_result rustls_certificate_get_der(const struct rustls_certificate *cert, * * This function does not take ownership of any of its input pointers. It * parses the pointed-to data and makes a copy of the result. You may - * free the cert_chain and private_key pointers after calling it. + * free the `cert_chain` and `private_key` buffers after calling it. + * + * `certified_key_out` is unchanged if the function returns an error. * * Typically, you will build a `rustls_certified_key`, use it to create a * `rustls_server_config` (which increments the reference count), and then @@ -1193,9 +1258,14 @@ rustls_result rustls_certified_key_build(const uint8_t *cert_chain, * may retain a pointer to the object. The memory will be freed when all * references are gone. * - * This function does not take ownership of any of its input pointers. It - * parses the pointed-to data and makes a copy of the result. You may - * free the cert_chain and private_key pointers after calling it. + * This function copies the `cert_chain` data and does not take ownership of + * that buffer. Once the `cert_chain` pointer has been validated, the function + * takes ownership of `signing_key`, including when a later operation returns + * an error. The caller must not use or free the signing key afterward. If + * `cert_chain` is NULL, the function returns `RUSTLS_RESULT_NULL_PARAMETER` + * without consuming `signing_key`. + * + * `certified_key_out` is unchanged if the function returns an error. * * Typically, you will build a `rustls_certified_key`, use it to create a * `rustls_server_config` (which increments the reference count), and then @@ -1210,26 +1280,27 @@ rustls_result rustls_certified_key_build_with_signing_key(const uint8_t *cert_ch const struct rustls_certified_key **certified_key_out); /** - * Return the i-th rustls_certificate in the rustls_certified_key. + * 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. * * Indexes higher than the last available certificate return NULL. * - * The returned certificate is valid until the rustls_certified_key is freed. + * 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); /** - * Create a copy of the rustls_certified_key with the given OCSP response data + * Create a copy of the `rustls_certified_key` with the given OCSP response data * as DER encoded bytes. * * The OCSP response may be given as NULL to clear any possibly present OCSP * data from the cloned key. * - * The cloned key is independent from its original and needs to be freed - * by the application. + * The function copies `ocsp_response` and does not take ownership of either input. + * On success, `cloned_key_out` receives an independently owned key that the caller must + * free with `rustls_certified_key_free`. On error, `cloned_key_out` is unchanged. */ rustls_result rustls_certified_key_clone_with_ocsp(const struct rustls_certified_key *certified_key, const struct rustls_slice_bytes *ocsp_response, @@ -1247,12 +1318,11 @@ rustls_result rustls_certified_key_clone_with_ocsp(const struct rustls_certified rustls_result rustls_certified_key_keys_match(const struct rustls_certified_key *key); /** - * "Free" a certified_key previously returned from `rustls_certified_key_build`. + * Release the caller's reference to a `rustls_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. - * - * However, C code must consider this pointer unusable after "free"ing it. + * Other objects may still hold internal references to the atomically reference-counted + * Rust object. Regardless, the caller must not use `key` after this function returns. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -1261,11 +1331,9 @@ 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. - * - * 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`. + * The caller owns the returned builder and must eventually free it with + * `rustls_root_cert_store_builder_free`, whether or not + * `rustls_root_cert_store_builder_build` is called. */ struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void); @@ -1279,6 +1347,8 @@ struct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void); * When `strict` is false, unparseable root certificates will be ignored. * This may be useful on systems that have syntactically invalid root * certificates. + * + * This function copies the parsed certificates and does not retain `pem`. */ rustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_store_builder *builder, const uint8_t *pem, @@ -1295,6 +1365,9 @@ rustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_sto * When `strict` is false, unparseable root certificates will be ignored. * This may be useful on systems that have syntactically invalid root * certificates. + * + * `filename` must be a NUL-terminated UTF-8 string. It is borrowed for the + * duration of the call and is not retained. */ rustls_result rustls_root_cert_store_builder_load_roots_from_file(struct rustls_root_cert_store_builder *builder, const char *filename, @@ -1305,9 +1378,9 @@ rustls_result rustls_root_cert_store_builder_load_roots_from_file(struct rustls_ * * 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 - * `rustls_root_cert_store_free` for details about lifetime. + * On success, `root_cert_store_out` receives a new root certificate store. The caller owns + * it and must free it with `rustls_root_cert_store_free` when no longer needed. The store can + * be used in multiple verifier builders. */ 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); @@ -1321,17 +1394,20 @@ rustls_result rustls_root_cert_store_builder_build(struct rustls_root_cert_store 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 + * in the [IANA TLS Cipher Suites registry]. * * The bytes from the assignment are interpreted in network order. + * + * [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 */ uint16_t rustls_supported_ciphersuite_get_suite(const struct rustls_supported_ciphersuite *supported_ciphersuite); @@ -1352,7 +1428,7 @@ struct rustls_str rustls_supported_ciphersuite_get_name(const struct rustls_supp 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`. @@ -1363,13 +1439,14 @@ enum rustls_tls_version rustls_supported_ciphersuite_protocol_version(const stru * 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. + * This starts out with no trusted roots. The caller must provide a verifier with + * `rustls_client_config_builder_set_server_verifier` or + * `rustls_client_config_builder_dangerous_set_certificate_verifier`. */ struct rustls_client_config_builder *rustls_client_config_builder_new(void); /** - * Create a rustls_client_config_builder using the specified crypto provider. + * 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`. @@ -1377,16 +1454,23 @@ struct rustls_client_config_builder *rustls_client_config_builder_new(void); * Alternatively, if an error occurs or, you don't wish to build a config, * call `rustls_client_config_builder_free` to free the builder directly. * - * `tls_version` sets the TLS protocol versions to use when negotiating a TLS session. - * `tls_version` is the version of the protocol, as defined in rfc8446, - * ch. 4.2.1 and end of ch. 5.1. Some values are defined in - * `rustls_tls_version` for convenience, and the arrays - * RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly. + * `tls_versions` sets the TLS protocol versions to use when negotiating a + * TLS session. Each value is a protocol version as defined in RFC 8446, + * sections 4.2.1 and 5.1. Some values are defined in `rustls_tls_version` + * for convenience, and the arrays + * `RUSTLS_DEFAULT_VERSIONS` or `RUSTLS_ALL_VERSIONS` can be used directly. * * `tls_versions` will only be used during the call and the application retains * ownership. `tls_versions_len` is the number of consecutive `uint16_t` * pointed to by `tls_versions`. * + * On `RUSTLS_RESULT_OK`, `builder_out` receives a builder owned by the caller. + * It must eventually be passed to `rustls_client_config_builder_build` or freed with + * `rustls_client_config_builder_free`. On error, `builder_out` is unchanged. + * + * The function borrows `provider` for the duration of the call and retains its own + * reference afterward. + * * Ciphersuites are configured separately via the crypto provider. See * `rustls_crypto_provider_builder_set_cipher_suites` for more information. */ @@ -1397,13 +1481,13 @@ rustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto /** * Set a custom server certificate verifier using the builder crypto provider. - * Returns rustls_result::NoDefaultCryptoProvider if no process default crypto + * Returns `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER` if no process default crypto * provider has been set, and the builder was not constructed with an explicit * provider choice. * * The callback must not capture any of the pointers in its - * rustls_verify_server_cert_params. - * If `userdata` has been set with rustls_connection_set_userdata, it + * `rustls_verify_server_cert_params`. + * If `userdata` has been set with `rustls_connection_set_userdata`, it * will be passed to the callback. Otherwise the userdata param passed to * the callback will be NULL. * @@ -1418,11 +1502,13 @@ rustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto * if you need to parse them. * * If the custom verifier accepts the certificate, it should return - * RUSTLS_RESULT_OK. Otherwise, it may return any other rustls_result error. - * Feel free to use an appropriate error from the RUSTLS_RESULT_CERT_* - * section. + * `RUSTLS_RESULT_OK`. Otherwise, it may return any other `rustls_result` error, + * including one of the certificate-related errors. + * + * See also the rustls documentation for + * [`DangerousClientConfig::set_certificate_verifier`]. * - * + * [`DangerousClientConfig::set_certificate_verifier`]: https://docs.rs/rustls/latest/rustls/client/struct.DangerousClientConfig.html#method.set_certificate_verifier */ rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier(struct rustls_client_config_builder *config_builder, rustls_verify_server_cert_callback callback); @@ -1430,7 +1516,25 @@ rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier(st /** * Configure the server certificate verifier. * - * This increases the reference count of `verifier` and does not take ownership. + * For the usual case of verifying servers against a custom set of root + * certificates: + * + * 1. Create a `rustls_root_cert_store_builder` with + * `rustls_root_cert_store_builder_new`. + * 2. Add roots with `rustls_root_cert_store_builder_add_pem` or + * `rustls_root_cert_store_builder_load_roots_from_file`, then call + * `rustls_root_cert_store_builder_build`. + * 3. Pass the resulting store to + * `rustls_web_pki_server_cert_verifier_builder_new`, then call + * `rustls_web_pki_server_cert_verifier_builder_build`. + * 4. Pass the resulting verifier to this function. + * + * Alternatively, `rustls_platform_server_cert_verifier` creates a verifier + * using the platform's certificate facilities and trust store. + * + * This function increases the reference count of `verifier` and does not + * take ownership. The caller must still free its verifier pointer with + * `rustls_server_cert_verifier_free` when it is no longer needed. */ void rustls_client_config_builder_set_server_verifier(struct rustls_client_config_builder *builder, const struct rustls_server_cert_verifier *verifier); @@ -1441,16 +1545,18 @@ void rustls_client_config_builder_set_server_verifier(struct rustls_client_confi * `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 + * Each element of the buffer must be a `rustls_slice_bytes` whose * data field points to a single ALPN protocol ID. * - * Standard ALPN protocol IDs are defined at - * . + * Standard ALPN protocol IDs are defined in the [IANA registry]. * * This function makes a copy of the data in `protocols` and does not retain * any pointers, so the caller can free the pointed-to memory after calling. * - * + * See also the rustls documentation for [`ClientConfig::alpn_protocols`]. + * + * [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids + * [`ClientConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/client/struct.ClientConfig.html#structfield.alpn_protocols */ rustls_result rustls_client_config_builder_set_alpn_protocols(struct rustls_client_config_builder *builder, const struct rustls_slice_bytes *protocols, @@ -1461,7 +1567,9 @@ rustls_result rustls_client_config_builder_set_alpn_protocols(struct rustls_clie * * The default is `true`. * - * + * See also the rustls documentation for [`ClientConfig::check_selected_alpn`]. + * + * [`ClientConfig::check_selected_alpn`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.check_selected_alpn */ void rustls_client_config_builder_set_check_selected_alpn(struct rustls_client_config_builder *config, bool enable); @@ -1478,7 +1586,9 @@ void rustls_client_config_builder_set_check_selected_alpn(struct rustls_client_c * By default the extension is not sent. Note that servers are free to * ignore the request, it is only a hint. * - * + * See also the rustls documentation for [`ClientConfig::send_ticket_request`]. + * + * [`ClientConfig::send_ticket_request`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.send_ticket_request */ rustls_result rustls_client_config_builder_set_send_ticket_request(struct rustls_client_config_builder *builder, uint8_t new_session_count, @@ -1486,7 +1596,10 @@ rustls_result rustls_client_config_builder_set_send_ticket_request(struct rustls /** * Enable or disable SNI. - * + * + * See also the rustls documentation for [`ClientConfig::enable_sni`]. + * + * [`ClientConfig::enable_sni`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.enable_sni */ void rustls_client_config_builder_set_enable_sni(struct rustls_client_config_builder *config, bool enable); @@ -1514,15 +1627,16 @@ rustls_result rustls_client_config_builder_set_certified_key(struct rustls_clien /** * 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. + * The key material will be logged in the [NSS key log format] 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. * * For more control over which secrets are logged, or to customize the format, prefer * `rustls_client_config_builder_set_key_log`. + * + * [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format */ rustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client_config_builder *builder); @@ -1532,8 +1646,7 @@ rustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client * 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: - * + * rustls documentation for [`KeyLog::log`] 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 @@ -1548,6 +1661,8 @@ rustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client * * 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. + * + * [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log */ rustls_result rustls_client_config_builder_set_key_log(struct rustls_client_config_builder *builder, rustls_keylog_log_callback log_cb, @@ -1605,20 +1720,24 @@ rustls_result rustls_client_config_builder_enable_ech_grease(struct rustls_clien const struct rustls_hpke *hpke); /** - * Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config + * Turn a mutable `rustls_client_config_builder` into a const `rustls_client_config` * (read-only). + * + * This function takes ownership of `builder`. The caller must not use or free the builder + * after calling this function, regardless of the result. + * + * On `RUSTLS_RESULT_OK`, `config_out` receives a config owned by the caller, which must + * eventually be freed with `rustls_client_config_free`. On error, `config_out` is unchanged. */ 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. - * - * Normally builders are built into rustls_client_config via `rustls_client_config_builder_build` - * and may not be free'd or otherwise used afterwards. + * Free a `rustls_client_config_builder` without building it into a + * `rustls_client_config`. * - * Use free only when the building of a config has to be aborted before a config - * was created. + * Do not call this after `rustls_client_config_builder_build`, which consumes and frees the + * builder. Calling with NULL is fine. Must not be called twice with the same value. */ void rustls_client_config_builder_free(struct rustls_client_config_builder *config); @@ -1633,13 +1752,12 @@ void rustls_client_config_builder_free(struct rustls_client_config_builder *conf bool rustls_client_config_fips(const struct rustls_client_config *config); /** - * "Free" a `rustls_client_config` previously returned from + * Release the caller's reference to 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. - * - * However, C code must consider this pointer unusable after "free"ing it. + * Existing client connections may still hold internal references to the atomically + * reference-counted Rust object. Regardless, the caller must not use `config` after this + * function returns. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -1654,6 +1772,9 @@ void rustls_client_config_free(const struct rustls_client_config *config); * * This function copies the contents of `server_name`. * + * The connection retains an internal reference to `config`. This function + * does not take ownership of the caller's config pointer. + * * Uses the `rustls_client_config` to determine ALPN protocol support. Prefer * `rustls_client_connection_new_alpn` to customize this per-connection. * @@ -1662,7 +1783,7 @@ void rustls_client_config_free(const struct rustls_client_config *config); * * 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. + * cannot be parsed as one of those types. It must be NUL-terminated. */ rustls_result rustls_client_connection_new(const struct rustls_client_config *config, const char *server_name, @@ -1673,7 +1794,7 @@ rustls_result rustls_client_connection_new(const struct rustls_client_config *co * * Operates the same as `rustls_client_connection_new`, but allows specifying * custom per-connection ALPN protocols instead of inheriting ALPN protocols - * from the `rustls_clinet_config`. + * from the `rustls_client_config`. * * If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to * point at a valid `rustls_connection`. The caller now owns the `rustls_connection` @@ -1681,12 +1802,15 @@ rustls_result rustls_client_connection_new(const struct rustls_client_config *co * * This function copies the contents of `server_name`. * + * The connection retains an internal reference to `config`. This function + * does not take ownership of the caller's config pointer. + * * If this returns an error code, the memory pointed to by `conn_out` remains * unchanged. * * 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. + * cannot be parsed as one of those types. It must be NUL-terminated. * * `alpn_protocols` must point to a buffer of `rustls_slice_bytes` (built by the caller) * with `alpn_protocols_len` elements. Each element of the buffer must be a `rustls_slice_bytes` @@ -1694,8 +1818,9 @@ rustls_result rustls_client_connection_new(const struct rustls_client_config *co * data in `alpn_protocols` and does not retain any pointers, so the caller can free the * pointed-to memory after calling. * - * Standard ALPN protocol IDs are defined at - * . + * Standard ALPN protocol IDs are defined in the [IANA registry]. + * + * [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids */ rustls_result rustls_client_connection_new_alpn(const struct rustls_client_config *config, const char *server_name, @@ -1706,13 +1831,15 @@ rustls_result rustls_client_connection_new_alpn(const struct rustls_client_confi /** * 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. + * + * The pointed-to data must remain valid until the userdata is replaced or the connection + * is freed. Rustls does not take ownership of the data and will not free it. */ 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 + * 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); @@ -1725,9 +1852,14 @@ void rustls_connection_set_log_callback(struct rustls_connection *conn, rustls_l * 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. - * + * + * On success, returns 0 and writes the number of bytes read to `out_n`. On error, returns + * an errno value passed through from `callback` and leaves `out_n` unchanged. See + * `rustls_read_callback` for more details. + * + * See also the rustls documentation for [`Connection::read_tls`]. + * + * [`Connection::read_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.read_tls */ rustls_io_result rustls_connection_read_tls(struct rustls_connection *conn, rustls_read_callback callback, @@ -1742,9 +1874,14 @@ 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. - * + * + * On success, returns 0 and writes the number of bytes written to `out_n`. On error, + * returns an errno value passed through from `callback` and leaves `out_n` unchanged. + * See `rustls_write_callback` for more details. + * + * See also the rustls documentation for [`Connection::write_tls`]. + * + * [`Connection::write_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.write_tls */ rustls_io_result rustls_connection_write_tls(struct rustls_connection *conn, rustls_write_callback callback, @@ -1754,14 +1891,19 @@ rustls_io_result rustls_connection_write_tls(struct rustls_connection *conn, /** * 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. + * 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. - * + * + * On success, returns 0 and writes the number of bytes written to `out_n`. On error, + * returns an errno value passed through from `callback` and leaves `out_n` unchanged. + * See `rustls_write_vectored_callback` for more details. + * + * See also the rustls documentation for [`Writer::write_vectored`]. + * + * [`Writer::write_vectored`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write_vectored */ rustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection *conn, rustls_write_vectored_callback callback, @@ -1771,18 +1913,25 @@ rustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection * /** * Decrypt any available ciphertext from the internal buffer and put it * into the internal plaintext buffer, potentially making bytes available - * for rustls_connection_read(). - * + * for `rustls_connection_read()`. + * + * See also the rustls documentation for [`Connection::process_new_packets`]. + * + * [`Connection::process_new_packets`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.process_new_packets */ rustls_result rustls_connection_process_new_packets(struct rustls_connection *conn); /** - * + * See also the rustls documentation for [`CommonState::wants_read`]. + * + * [`CommonState::wants_read`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_read */ bool rustls_connection_wants_read(const struct rustls_connection *conn); /** - * + * See also the rustls documentation for [`CommonState::wants_write`]. + * + * [`CommonState::wants_write`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_write */ bool rustls_connection_wants_write(const struct rustls_connection *conn); @@ -1792,9 +1941,9 @@ bool rustls_connection_wants_write(const struct rustls_connection *conn); * 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. + * See also the rustls documentation for [`CommonState::is_handshaking`]. * - * + * [`CommonState::is_handshaking`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.is_handshaking */ bool rustls_connection_is_handshaking(const struct rustls_connection *conn); @@ -1808,13 +1957,21 @@ enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_ * to completing the TLS handshake) and unsent TLS records. By default, there * is no limit. The limit can be set at any time, even if the current buffer * use is higher. - * + * + * See also the rustls documentation for [`Connection::set_buffer_limit`]. + * + * [`Connection::set_buffer_limit`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.set_buffer_limit */ -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. - * + * Queues a close_notify alert to be sent by the next call to + * `rustls_connection_write_tls()`. + * + * See also the rustls documentation for [`Connection::send_close_notify`]. + * + * [`Connection::send_close_notify`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.send_close_notify */ void rustls_connection_send_close_notify(struct rustls_connection *conn); @@ -1822,39 +1979,49 @@ 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 + * seldom be used. See the rustls documentation for + * [`ConnectionCommon::refresh_traffic_keys`] for important caveats and suggestions * on occasions that merit its use. * - * + * [`ConnectionCommon::refresh_traffic_keys`]: https://docs.rs/rustls/latest/rustls/struct.ConnectionCommon.html#method.refresh_traffic_keys */ rustls_result rustls_connection_refresh_traffic_keys(struct rustls_connection *conn); /** * Return the i-th certificate provided by the peer. * Index 0 is the end entity certificate. Higher indexes are certificates - * in the chain. Requesting an index higher than what is available returns - * NULL. + * in the chain. Requesting an out-of-range index returns NULL. + * * The returned pointer 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 *`). - * + * affecting the connection. A mutating function call is one where the first + * argument is a mutable pointer to `rustls_connection` (as opposed to a const + * pointer). + * + * See also the rustls documentation for [`Connection::peer_certificates`]. + * + * [`Connection::peer_certificates`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.peer_certificates */ 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 - * borrowed buffer of bytes, and that buffer's len, in the output parameters. - * The borrow lives as long as the connection. + * borrowed buffer of bytes, and that buffer's length, in the output parameters. * If the connection is still handshaking, or no ALPN protocol was negotiated, * stores NULL and 0 in the output parameters. - * The provided pointer 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 borrowed buffer is owned by the connection and is valid until the next + * mutating function call affecting the connection. A mutating function call + * is one where the first argument is a mutable pointer to + * `rustls_connection` (as opposed to a const pointer). + * The caller must not modify or free the borrowed buffer. + * + * If `conn` or either output parameter is NULL, both output values are unchanged. + * Protocol identifiers are listed in the [IANA TLS Parameters registry]. See + * also the rustls documentation for [`Connection::alpn_protocol`]. + * + * [IANA TLS Parameters registry]: https://www.iana.org/assignments/tls-parameters/ + * [`Connection::alpn_protocol`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.alpn_protocol */ void rustls_connection_get_alpn_protocol(const struct rustls_connection *conn, const uint8_t **protocol_out, @@ -1864,17 +2031,21 @@ void rustls_connection_get_alpn_protocol(const struct rustls_connection *conn, * Return the TLS protocol version that has been negotiated. Before this * has been decided during the handshake, this will return 0. Otherwise, * the u16 version number as defined in the relevant RFC is returned. - * - * + * + * See also the rustls documentation for [`Connection::protocol_version`] and + * [`ProtocolVersion`]. + * + * [`Connection::protocol_version`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.protocol_version + * [`ProtocolVersion`]: https://docs.rs/rustls/latest/rustls/internal/msgs/enums/enum.ProtocolVersion.html */ 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] agreed with the peer. * * This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed. * - * [IANA]: + * [IANA registered cipher suite identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 */ uint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connection *conn); @@ -1886,16 +2057,18 @@ uint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connec * The lifetime of the `rustls_str` is the lifetime of the program, it does not * need to be freed. * - * + * See also the rustls documentation for [`Connection::negotiated_cipher_suite`]. + * + * [`Connection::negotiated_cipher_suite`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.negotiated_cipher_suite */ 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] agreed with the peer. * * This returns Reserved (0x0000) until the key exchange group is agreed. * - * [IANA]: + * [IANA registered supported group identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 */ uint16_t rustls_connection_get_negotiated_key_exchange_group(const struct rustls_connection *conn); @@ -1920,9 +2093,15 @@ uint32_t rustls_connection_get_tls13_tickets_received(const struct rustls_connec * Write up to `count` plaintext bytes from `buf` into the `rustls_connection`. * This will increase the number of output bytes available to * `rustls_connection_write_tls`. - * On success, store the number of bytes actually written in *out_n + * On success, store the number of bytes actually written in `*out_n` * (this may be less than `count`). - * + * + * This function borrows `buf` for the duration of the call and does not retain it. + * On error, `out_n` is unchanged. + * + * See also the rustls documentation for [`Writer::write`]. + * + * [`Writer::write`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write */ rustls_result rustls_connection_write(struct rustls_connection *conn, const uint8_t *buf, @@ -1931,17 +2110,22 @@ rustls_result rustls_connection_write(struct rustls_connection *conn, /** * Read up to `count` plaintext bytes from the `rustls_connection` into `buf`. - * On success, store the number of bytes read in *out_n (this may be less - * than `count`). A success with *out_n set to 0 means "all bytes currently + * On success, store the number of bytes read in `*out_n` (this may be less + * than `count`). A success with `*out_n` set to 0 means "all bytes currently * available have been read, but more bytes may become available after - * subsequent calls to rustls_connection_read_tls and - * rustls_connection_process_new_packets." + * subsequent calls to `rustls_connection_read_tls` and + * `rustls_connection_process_new_packets`. * * Subtle note: Even though this function only writes to `buf` and does not * read from it, the memory in `buf` must be initialized before the call (for * Rust-internal reasons). Initializing a buffer once and then using it * multiple times without zeroizing before each call is fine. - * + * + * The function does not retain `buf`. On error, `out_n` is unchanged. + * + * See also the rustls documentation for [`Reader::read`]. + * + * [`Reader::read`]: https://docs.rs/rustls/latest/rustls/struct.Reader.html#method.read */ rustls_result rustls_connection_read(struct rustls_connection *conn, uint8_t *buf, @@ -1951,11 +2135,11 @@ rustls_result rustls_connection_read(struct rustls_connection *conn, #if defined(DEFINE_READ_BUF) /** * Read up to `count` plaintext bytes from the `rustls_connection` into `buf`. - * On success, store the number of bytes read in *out_n (this may be less - * than `count`). A success with *out_n set to 0 means "all bytes currently + * On success, store the number of bytes read in `*out_n` (this may be less + * than `count`). A success with `*out_n` set to 0 means "all bytes currently * available have been read, but more bytes may become available after - * subsequent calls to rustls_connection_read_tls and - * rustls_connection_process_new_packets." + * subsequent calls to `rustls_connection_read_tls` and + * `rustls_connection_process_new_packets`. * * This experimental API is only available when using a nightly Rust compiler * and enabling the `read_buf` Cargo feature. It will be deprecated and later @@ -1963,6 +2147,8 @@ rustls_result rustls_connection_read(struct rustls_connection *conn, * * Unlike with `rustls_connection_read`, this function may be called with `buf` * pointing to an uninitialized memory buffer. + * + * The function does not retain `buf`. On error, `out_n` is unchanged. */ rustls_result rustls_connection_read_2(struct rustls_connection *conn, uint8_t *buf, @@ -1981,7 +2167,7 @@ rustls_result rustls_connection_read_2(struct rustls_connection *conn, bool rustls_connection_fips(const struct rustls_connection *conn); /** - * Free a rustls_connection. Calling with NULL is fine. + * Free a `rustls_connection`. Calling with NULL is fine. * Must not be called twice with the same value. */ void rustls_connection_free(struct rustls_connection *conn); @@ -1990,13 +2176,15 @@ 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. * - * 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_NO_DEFAULT_CRYPTO_PROVIDER` 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`. * + * On error, `builder_out` is unchanged. + * * This function is typically used for customizing the default crypto provider for specific * connections. For example, a typical workflow might be to: * @@ -2023,6 +2211,9 @@ rustls_result rustls_crypto_provider_builder_new_from_default(struct rustls_cryp * The caller owns the returned `rustls_crypto_provider_builder` and must free it using * `rustls_crypto_provider_builder_free`. * + * This function does not take ownership of `base`. The builder retains its own + * reference. + * * 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: @@ -2058,6 +2249,9 @@ rustls_result rustls_crypto_provider_builder_set_cipher_suites(struct rustls_cry * 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. + * + * On `RUSTLS_RESULT_OK`, `provider_out` receives a provider owned by the caller, which must + * eventually be freed with `rustls_crypto_provider_free`. On error, `provider_out` is unchanged. */ rustls_result rustls_crypto_provider_builder_build(struct rustls_crypto_provider_builder *builder, const struct rustls_crypto_provider **provider_out); @@ -2126,30 +2320,32 @@ const struct rustls_crypto_provider *rustls_default_fips_provider(void); * Retrieve a pointer to the process default `rustls_crypto_provider`. * * This may return `NULL` if no process default provider has been set using - * `rustls_crypto_provider_builder_build_default`. + * `rustls_crypto_provider_builder_build_as_default`. * - * Caller owns the returned `rustls_crypto_provider` and must free it w/ `rustls_crypto_provider_free`. + * The caller owns the returned `rustls_crypto_provider` and must free it with + * `rustls_crypto_provider_free`. */ const struct rustls_crypto_provider *rustls_crypto_provider_default(void); /** - * Returns the number of ciphersuites the `rustls_crypto_provider` supports. + * Returns the number of cipher suites the `rustls_crypto_provider` supports. * - * You can use this to know the maximum allowed index for use with - * `rustls_crypto_provider_ciphersuites_get`. + * Valid indices for `rustls_crypto_provider_ciphersuites_get` range from 0 (inclusive) to the + * returned length (exclusive). * * This function will return 0 if the `provider` is NULL. */ 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 cipher suite 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`. * * 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. + * `provider` and should not be used after the `provider` is freed. The returned pointer is + * borrowed and must not be freed. */ const struct rustls_supported_ciphersuite *rustls_crypto_provider_ciphersuites_get(const struct rustls_crypto_provider *provider, size_t index); @@ -2162,9 +2358,12 @@ 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` + * 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`. + * + * The function copies the private key data and does not retain `private_key`. On error, + * `signing_key_out` is unchanged. */ rustls_result rustls_crypto_provider_load_key(const struct rustls_crypto_provider *provider, const uint8_t *private_key, @@ -2202,23 +2401,24 @@ bool rustls_crypto_provider_fips(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 cipher suites 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`. + * Valid indices for `rustls_default_crypto_provider_ciphersuites_get` range from 0 (inclusive) + * to the returned length (exclusive). * * 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 cipher suite 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 returns NULL if no process-wide default provider is available or if `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. + * default provider lives for as long as the process. The returned pointer is borrowed and must + * not be freed. */ const struct rustls_supported_ciphersuite *rustls_default_crypto_provider_ciphersuites_get(size_t index); @@ -2261,22 +2461,27 @@ const struct rustls_hpke *rustls_supported_hpke(void); struct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind); /** - * After a rustls function returns an error, you may call - * this to get a pointer to a buffer containing a detailed error - * message. + * After a rustls function returns an error, you may call this to write a detailed error + * message into the caller-provided `buf`. + * + * This writes at most `len` bytes and stores the number written in `out_n`. If the full + * message is longer than `len`, it is truncated. The output is UTF-8 encoded and is not + * NUL-terminated. * - * The contents of the error buffer will be out_n bytes long, - * UTF-8 encoded, and not NUL-terminated. + * If `buf` or `out_n` is NULL, this function does nothing. The caller retains ownership of + * `buf`, and the function does not retain it. */ void rustls_error(unsigned int result, char *buf, size_t len, size_t *out_n); /** - * Returns true if the `result` is a certificate related error. + * Returns true if the `result` is a certificate-related error. */ bool rustls_result_is_cert_error(unsigned int result); /** - * Return a rustls_str containing the stringified version of a log level. + * Return a `rustls_str` containing the stringified version of a log level. + * + * The returned string has static lifetime and does not need to be freed. */ struct rustls_str rustls_log_level_str(rustls_log_level level); @@ -2289,8 +2494,12 @@ size_t rustls_slice_slice_bytes_len(const struct rustls_slice_slice_bytes *input /** * Retrieve the nth element from the input slice of slices. * - * 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}. + * If the input pointer is NULL, or `n` is greater than or equal to the length + * of the `rustls_slice_slice_bytes`, returns a `rustls_slice_bytes` with a NULL data pointer + * and a length of 0. + * + * Otherwise, the returned byte slice borrows its data from `input`. It remains valid for the + * same lifetime as `input` and must not be freed. */ struct rustls_slice_bytes rustls_slice_slice_bytes_get(const struct rustls_slice_slice_bytes *input, size_t n); @@ -2305,16 +2514,19 @@ size_t rustls_slice_str_len(const struct rustls_slice_str *input); /** * Retrieve the nth element from the input slice of `&str`s. * - * If the input pointer is NULL, or n is greater than the length of the - * rustls_slice_str, returns rustls_str{NULL, 0}. + * If the input pointer is NULL, or `n` is greater than or equal to the length of the + * `rustls_slice_str`, returns a `rustls_str` with a NULL data pointer and a length of 0. + * + * Otherwise, the returned string borrows its data from `input`. It remains valid for the same + * lifetime as `input` and must not be freed. */ 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. @@ -2325,24 +2537,30 @@ struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, siz struct rustls_server_config_builder *rustls_server_config_builder_new(void); /** - * Create a rustls_server_config_builder using the specified crypto provider. + * 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` 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_versions` sets the TLS protocol versions to use when negotiating a TLS session. + * Each value is a protocol version as defined in RFC 8446, sections 4.2.1 and 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`. * + * On `RUSTLS_RESULT_OK`, `builder_out` receives a builder owned by the caller. + * It must eventually be passed to `rustls_server_config_builder_build` or freed with + * `rustls_server_config_builder_free`. On error, `builder_out` is unchanged. + * + * The function borrows `provider` for the duration of the call and retains its own + * reference afterward. + * * Ciphersuites are configured separately via the crypto provider. See * `rustls_crypto_provider_builder_set_cipher_suites` for more information. */ @@ -2352,10 +2570,24 @@ rustls_result rustls_server_config_builder_new_custom(const struct rustls_crypto struct rustls_server_config_builder **builder_out); /** - * Create a rustls_server_config_builder for TLS sessions that may verify client - * certificates. + * Configure a `rustls_server_config_builder` to verify client certificates. + * Client authentication is disabled unless this function is called. * - * This increases the refcount of `verifier` and doesn't take ownership. + * To require client certificates that chain to a custom set of roots: + * + * 1. Create a `rustls_root_cert_store_builder` with + * `rustls_root_cert_store_builder_new`. + * 2. Add roots with `rustls_root_cert_store_builder_add_pem` or + * `rustls_root_cert_store_builder_load_roots_from_file`, then call + * `rustls_root_cert_store_builder_build`. + * 3. Pass the resulting store to + * `rustls_web_pki_client_cert_verifier_builder_new`, then call + * `rustls_web_pki_client_cert_verifier_builder_build`. + * 4. Pass the resulting verifier to this function. + * + * This function increases the reference count of `verifier` and does not + * take ownership. The caller must still free its verifier pointer with + * `rustls_client_cert_verifier_free` when it is no longer needed. */ void rustls_server_config_builder_set_client_verifier(struct rustls_server_config_builder *builder, const struct rustls_client_cert_verifier *verifier); @@ -2363,15 +2595,16 @@ void rustls_server_config_builder_set_client_verifier(struct rustls_server_confi /** * 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. + * The key material will be logged in the [NSS key log format] 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. * * For more control over which secrets are logged, or to customize the format, prefer * `rustls_server_config_builder_set_key_log`. + * + * [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format */ rustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server_config_builder *builder); @@ -2381,8 +2614,7 @@ rustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server * 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: - * + * rustls documentation for [`KeyLog::log`] 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 @@ -2397,19 +2629,19 @@ rustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server * * 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. + * + * [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log */ 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. - * - * Normally builders are built into rustls_server_configs via `rustls_server_config_builder_build` - * and may not be free'd or otherwise used afterwards. + * Free a `rustls_server_config_builder` without building it into a + * `rustls_server_config`. * - * Use free only when the building of a config has to be aborted before a config - * was created. + * Do not call this after `rustls_server_config_builder_build`, which consumes and frees the + * builder. Calling with NULL is fine. Must not be called twice with the same value. */ void rustls_server_config_builder_free(struct rustls_server_config_builder *config); @@ -2417,7 +2649,10 @@ void rustls_server_config_builder_free(struct rustls_server_config_builder *conf * With `ignore` != 0, the server will ignore the client ordering of cipher * suites, aka preference, during handshake and respect its own ordering * as configured. - * + * + * See also the rustls documentation for [`ServerConfig::ignore_client_order`]. + * + * [`ServerConfig::ignore_client_order`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html#structfield.ignore_client_order */ rustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls_server_config_builder *builder, bool ignore); @@ -2426,7 +2661,10 @@ rustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls * Set the number of TLS 1.3 NewSessionTickets sent after a full handshake. * * Setting this to 0 disables session ticket issuance entirely. - * + * + * See also the rustls documentation for [`ServerConfig::send_tls13_tickets`]. + * + * [`ServerConfig::send_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.send_tls13_tickets */ rustls_result rustls_server_config_builder_set_send_tls13_tickets(struct rustls_server_config_builder *builder, size_t n); @@ -2440,7 +2678,9 @@ rustls_result rustls_server_config_builder_set_send_tls13_tickets(struct rustls_ * 0 (the default) ignores client requests entirely, clients get the configured * `send_tls13_tickets` count regardless. * - * + * See also the rustls documentation for [`ServerConfig::max_tls13_tickets`]. + * + * [`ServerConfig::max_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.max_tls13_tickets */ rustls_result rustls_server_config_builder_set_max_tls13_tickets(struct rustls_server_config_builder *builder, size_t max); @@ -2450,13 +2690,15 @@ rustls_result rustls_server_config_builder_set_max_tls13_tickets(struct rustls_s * * `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 - * . + * contains a single ALPN protocol from the [IANA registry]. * * This function makes a copy of the data in `protocols` and does not retain * any pointers, so the caller can free the pointed-to memory after calling. * - * + * See also the rustls documentation for [`ServerConfig::alpn_protocols`]. + * + * [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids + * [`ServerConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.alpn_protocols */ rustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_server_config_builder *builder, const struct rustls_slice_bytes *protocols, @@ -2468,12 +2710,14 @@ rustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_serv * verification capabilities. * * Servers that want to support both ECDSA and RSA certificates will want - * the ECSDA to go first in the list. + * the ECDSA certificate to go first in the list. * - * The built configuration will keep a reference to all certified keys - * provided. The client may `rustls_certified_key_free()` afterwards - * without the configuration losing them. The same certified key may also - * be used in multiple configs. + * In the usual case, first call `rustls_certified_key_build` with the PEM + * certificate chain and private key, then pass the resulting + * `rustls_certified_key` pointer to this function. The builder and built + * configuration keep a reference to each certified key, so the caller may + * call `rustls_certified_key_free()` after this function returns. The same + * certified key may also be used in multiple configs. * * EXPERIMENTAL: installing a client_hello callback will replace any * configured certified keys and vice versa. @@ -2483,9 +2727,15 @@ rustls_result rustls_server_config_builder_set_certified_keys(struct rustls_serv size_t certified_keys_len); /** - * Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config + * Turn a mutable `rustls_server_config_builder` 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`. + * pointer when this function returns `RUSTLS_RESULT_OK`. + * + * This function takes ownership of `builder`. The caller must not use or free the builder + * after calling this function, regardless of the result. + * + * On `RUSTLS_RESULT_OK`, `config_out` receives a config owned by the caller, which must + * eventually be freed with `rustls_server_config_free`. On error, `config_out` is unchanged. * * 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 @@ -2505,29 +2755,32 @@ rustls_result rustls_server_config_builder_build(struct rustls_server_config_bui bool rustls_server_config_fips(const struct rustls_server_config *config); /** - * "Free" a rustls_server_config previously returned from - * rustls_server_config_builder_build. + * Release the caller's reference to a `rustls_server_config` previously returned from + * `rustls_server_config_builder_build`. + * + * Existing server connections may still hold internal references to the atomically + * reference-counted Rust object. Regardless, the caller must not use `config` after this + * function returns. * - * Since rustls_server_config is actually an - * atomically reference-counted pointer, extant server connections may still - * hold an internal reference to the Rust object. However, C code must - * consider this pointer unusable after "free"ing it. * Calling with NULL is fine. Must not be called twice with the same value. */ 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 a non-error, the memory pointed to by `conn_out` is modified to point - * at a valid rustls_connection + * at a valid `rustls_connection` * - * The caller now owns the rustls_connection and must call `rustls_connection_free` when + * The caller now owns the `rustls_connection` and must call `rustls_connection_free` when * done with it. + * + * The connection retains an internal reference to `config`. This function + * does not take ownership of the caller's config pointer. */ rustls_result rustls_server_connection_new(const struct rustls_server_config *config, struct rustls_connection **conn_out); @@ -2537,14 +2790,14 @@ rustls_result rustls_server_connection_new(const struct rustls_server_config *co * 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`. + * connection. A mutating function call is one where the first argument is a mutable pointer to + * `rustls_connection` (as opposed to a const pointer). 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 + * - the connection is a server connection but the SNI extension in the ClientHello has not * been processed during the handshake yet. Check `rustls_connection_is_handshaking`. * - the SNI value contains null bytes. */ @@ -2553,7 +2806,7 @@ struct rustls_str rustls_server_connection_get_server_name(const struct rustls_c /** * Register a callback to be invoked when a connection created from this config * sees a TLS ClientHello message. If `userdata` has been set with - * rustls_connection_set_userdata, it will be passed to the callback. + * `rustls_connection_set_userdata`, it will be passed to the callback. * Otherwise the userdata param passed to the callback will be NULL. * * Any existing `ResolvesServerCert` implementation currently installed in the @@ -2562,7 +2815,7 @@ struct rustls_str rustls_server_connection_get_server_name(const struct rustls_c * 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. + * the rustls library is re-evaluating its current approach to ClientHello handling. * Installing a client_hello callback will replace any configured certified keys * and vice versa. Same holds true for the set_certified_keys variant. */ @@ -2571,10 +2824,10 @@ rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_serv /** * Select a `rustls_certified_key` from the list that matches the cryptographic - * parameters of a TLS client hello. + * parameters of a TLS ClientHello. * * Note that this does not do any SNI matching. The input certificates should - * already have been filtered to ones matching the SNI from the client hello. + * already have been filtered to ones matching the SNI from the ClientHello. * * 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 @@ -2583,8 +2836,14 @@ rustls_result rustls_server_config_builder_set_hello_callback(struct rustls_serv * 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 + * Return `RUSTLS_RESULT_OK` if a key was selected and `RUSTLS_RESULT_NOT_FOUND` * if none was suitable. + * + * On success, `out_key` is set to one of the pointers from `certified_keys`. The function does + * not take ownership or increment the reference count. The returned pointer remains valid only + * while the caller keeps the corresponding input key alive and must not be freed separately. + * + * On error, `out_key` is unchanged. */ rustls_result rustls_client_hello_select_certified_key(const struct rustls_client_hello *hello, const struct rustls_certified_key *const *certified_keys, @@ -2599,7 +2858,7 @@ rustls_result rustls_client_hello_select_certified_key(const struct rustls_clien * If `builder`, `get_cb`, or `put_cb` are NULL, this function will return * immediately without doing anything. * - * If `userdata` has been set with rustls_connection_set_userdata, it + * If `userdata` has been set with `rustls_connection_set_userdata`, it * will be passed to the callbacks. Otherwise the userdata param passed to * the callbacks will be NULL. */ @@ -2609,8 +2868,8 @@ void rustls_server_config_builder_set_persistence(struct rustls_server_config_bu /** * 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_web_pki_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); @@ -2622,7 +2881,7 @@ void rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifi * 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 + * will require a client to 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 @@ -2637,8 +2896,9 @@ void rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifi * Unauthenticated clients will not be permitted unless * `rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated` is used. * - * This copies the contents of the `rustls_root_cert_store`. It does not take - * ownership of the pointed-to data. + * This does not take ownership of `store`. The builder retains its own + * reference, so the caller may free its root certificate store pointer after + * this function returns. */ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new(const struct rustls_root_cert_store *store); @@ -2651,7 +2911,7 @@ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_v * 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 + * will require a client to 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 @@ -2666,8 +2926,9 @@ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_v * Unauthenticated clients will not be permitted unless * `rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated` is used. * - * This copies the contents of the `rustls_root_cert_store`. It does not take - * ownership of the pointed-to data. + * This does not take ownership of `provider` or `store`. The builder retains + * its own references, so the caller may free both input pointers after this + * function returns. */ 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); @@ -2681,6 +2942,8 @@ struct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_v * `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. + * + * It copies the parsed CRLs and does not retain `crl_pem`. */ 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, @@ -2735,16 +2998,17 @@ rustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects(struct * * 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. + * On `RUSTLS_RESULT_OK`, `verifier_out` receives a verifier owned by the caller. It can be + * used in several `rustls_server_config` instances and must be freed with + * `rustls_client_cert_verifier_free` when no longer needed. On error, `verifier_out` is + * unchanged. */ 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 - * `rustls_client_cert_verifier_builder_new`. + * Free a `rustls_web_pki_client_cert_verifier_builder` previously returned from + * `rustls_web_pki_client_cert_verifier_builder_new`. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -2758,7 +3022,7 @@ void rustls_web_pki_client_cert_verifier_builder_free(struct rustls_web_pki_clie * 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 + * will require a server to 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 @@ -2770,8 +3034,9 @@ void rustls_web_pki_client_cert_verifier_builder_free(struct rustls_web_pki_clie * 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. + * This does not take ownership of `store`. The builder retains its own + * reference, so the caller may free its root certificate store pointer after + * this function returns. */ struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new(const struct rustls_root_cert_store *store); @@ -2782,7 +3047,7 @@ struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_v * `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 + * will require a server to 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 @@ -2795,8 +3060,9 @@ struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_v * 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. + * This does not take ownership of `provider` or `store`. The builder retains + * its own references, so the caller may free both input pointers after this + * function returns. */ 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); @@ -2810,6 +3076,8 @@ struct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_v * `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. + * + * It copies the parsed CRLs and does not retain `crl_pem`. */ 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, @@ -2844,16 +3112,17 @@ rustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry(stru * * 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. + * On `RUSTLS_RESULT_OK`, `verifier_out` receives a verifier owned by the caller. It can be + * used in several `rustls_client_config` instances and must be freed with + * `rustls_server_cert_verifier_free` when no longer needed. On error, `verifier_out` is + * unchanged. */ 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 - * `rustls_server_cert_verifier_builder_new`. + * Free a `rustls_web_pki_server_cert_verifier_builder` previously returned from + * `rustls_web_pki_server_cert_verifier_builder_new`. * * Calling with NULL is fine. Must not be called twice with the same value. */ @@ -2867,6 +3136,8 @@ void rustls_web_pki_server_cert_verifier_builder_free(struct rustls_web_pki_serv * 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. * + * On error, `verifier_out` is unchanged. + * * [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier */ rustls_result rustls_platform_server_cert_verifier(struct rustls_server_cert_verifier **verifier_out); @@ -2894,7 +3165,7 @@ struct rustls_server_cert_verifier *rustls_platform_server_cert_verifier_with_pr * * If the initialization of `rustls-platform-verifier` fails, this function returns * an error and `NULL` is written to `verifier_out`. Otherwise it fills in `verifier_out` - * (whose ownership is transferred to the caller) and returns `RUSTLS_SUCCESS`. + * (whose ownership is transferred to the caller) and returns `RUSTLS_RESULT_OK`. * * 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. @@ -2906,7 +3177,8 @@ rustls_result rustls_platform_server_cert_verifier_try_with_provider(const struc /** * Free a `rustls_server_cert_verifier` previously returned from - * `rustls_server_cert_verifier_builder_build` or `rustls_platform_server_cert_verifier`. + * `rustls_web_pki_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. */ diff --git a/librustls/src/server.rs b/librustls/src/server.rs index 0201dc21..cbb0904b 100644 --- a/librustls/src/server.rs +++ b/librustls/src/server.rs @@ -32,16 +32,18 @@ use crate::verifier::rustls_client_cert_verifier; /// A server config being constructed. /// -/// A builder can be modified by, -/// e.g. rustls_server_config_builder_load_native_roots. Once you're -/// done configuring settings, call rustls_server_config_builder_build -/// to turn it into a *const rustls_server_config. +/// A builder can be modified by, e.g. `rustls_server_config_builder_set_certified_keys`. +/// Once you're done configuring settings, call `rustls_server_config_builder_build` +/// to turn it into a `rustls_server_config`. /// /// Alternatively, if an error occurs or, you don't wish to build a config, /// call `rustls_server_config_builder_free` to free the builder directly. /// /// This object is not safe for concurrent mutation. -/// +/// +/// See also the rustls documentation for [`ConfigBuilder`]. +/// +/// [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html pub struct rustls_server_config_builder { _private: [u8; 0], } @@ -67,7 +69,10 @@ pub(crate) struct ServerConfigBuilder { /// A server config that is done being constructed and is now read-only. /// /// Under the hood, this object corresponds to an `Arc`. -/// +/// +/// See also the rustls documentation for [`ServerConfig`]. +/// +/// [`ServerConfig`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html pub struct rustls_server_config { _private: [u8; 0], } @@ -78,10 +83,10 @@ impl Castable for rustls_server_config { } impl rustls_server_config_builder { - /// 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. @@ -107,24 +112,30 @@ impl rustls_server_config_builder { } } - /// Create a rustls_server_config_builder using the specified crypto provider. + /// 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` 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_versions` sets the TLS protocol versions to use when negotiating a TLS session. + /// Each value is a protocol version as defined in RFC 8446, sections 4.2.1 and 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`. /// + /// On `RUSTLS_RESULT_OK`, `builder_out` receives a builder owned by the caller. + /// It must eventually be passed to `rustls_server_config_builder_build` or freed with + /// `rustls_server_config_builder_free`. On error, `builder_out` is unchanged. + /// + /// The function borrows `provider` for the duration of the call and retains its own + /// reference afterward. + /// /// Ciphersuites are configured separately via the crypto provider. See /// `rustls_crypto_provider_builder_set_cipher_suites` for more information. #[no_mangle] @@ -165,10 +176,24 @@ impl rustls_server_config_builder { } } - /// Create a rustls_server_config_builder for TLS sessions that may verify client - /// certificates. + /// Configure a `rustls_server_config_builder` to verify client certificates. + /// Client authentication is disabled unless this function is called. /// - /// This increases the refcount of `verifier` and doesn't take ownership. + /// To require client certificates that chain to a custom set of roots: + /// + /// 1. Create a `rustls_root_cert_store_builder` with + /// `rustls_root_cert_store_builder_new`. + /// 2. Add roots with `rustls_root_cert_store_builder_add_pem` or + /// `rustls_root_cert_store_builder_load_roots_from_file`, then call + /// `rustls_root_cert_store_builder_build`. + /// 3. Pass the resulting store to + /// `rustls_web_pki_client_cert_verifier_builder_new`, then call + /// `rustls_web_pki_client_cert_verifier_builder_build`. + /// 4. Pass the resulting verifier to this function. + /// + /// This function increases the reference count of `verifier` and does not + /// take ownership. The caller must still free its verifier pointer with + /// `rustls_client_cert_verifier_free` when it is no longer needed. #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_client_verifier( builder: *mut rustls_server_config_builder, @@ -183,15 +208,16 @@ impl rustls_server_config_builder { /// 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. + /// The key material will be logged in the [NSS key log format] 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. /// /// For more control over which secrets are logged, or to customize the format, prefer /// `rustls_server_config_builder_set_key_log`. + /// + /// [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_key_log_file( builder: *mut rustls_server_config_builder, @@ -208,8 +234,7 @@ impl rustls_server_config_builder { /// 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: - /// + /// rustls documentation for [`KeyLog::log`] 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 @@ -224,6 +249,8 @@ impl rustls_server_config_builder { /// /// 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. + /// + /// [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_key_log( builder: *mut rustls_server_config_builder, @@ -246,13 +273,11 @@ impl rustls_server_config_builder { } } - /// "Free" a server_config_builder without building it into a rustls_server_config. - /// - /// Normally builders are built into rustls_server_configs via `rustls_server_config_builder_build` - /// and may not be free'd or otherwise used afterwards. + /// Free a `rustls_server_config_builder` without building it into a + /// `rustls_server_config`. /// - /// Use free only when the building of a config has to be aborted before a config - /// was created. + /// Do not call this after `rustls_server_config_builder_build`, which consumes and frees the + /// builder. Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] pub extern "C" fn rustls_server_config_builder_free(config: *mut rustls_server_config_builder) { ffi_panic_boundary! { @@ -263,7 +288,10 @@ impl rustls_server_config_builder { /// With `ignore` != 0, the server will ignore the client ordering of cipher /// suites, aka preference, during handshake and respect its own ordering /// as configured. - /// + /// + /// See also the rustls documentation for [`ServerConfig::ignore_client_order`]. + /// + /// [`ServerConfig::ignore_client_order`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html#structfield.ignore_client_order #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_ignore_client_order( builder: *mut rustls_server_config_builder, @@ -279,7 +307,10 @@ impl rustls_server_config_builder { /// Set the number of TLS 1.3 NewSessionTickets sent after a full handshake. /// /// Setting this to 0 disables session ticket issuance entirely. - /// + /// + /// See also the rustls documentation for [`ServerConfig::send_tls13_tickets`]. + /// + /// [`ServerConfig::send_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.send_tls13_tickets #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_send_tls13_tickets( builder: *mut rustls_server_config_builder, @@ -300,7 +331,9 @@ impl rustls_server_config_builder { /// 0 (the default) ignores client requests entirely, clients get the configured /// `send_tls13_tickets` count regardless. /// - /// + /// See also the rustls documentation for [`ServerConfig::max_tls13_tickets`]. + /// + /// [`ServerConfig::max_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.max_tls13_tickets #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_max_tls13_tickets( builder: *mut rustls_server_config_builder, @@ -317,13 +350,15 @@ impl rustls_server_config_builder { /// /// `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 - /// . + /// contains a single ALPN protocol from the [IANA registry]. /// /// This function makes a copy of the data in `protocols` and does not retain /// any pointers, so the caller can free the pointed-to memory after calling. /// - /// + /// See also the rustls documentation for [`ServerConfig::alpn_protocols`]. + /// + /// [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids + /// [`ServerConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.alpn_protocols #[no_mangle] pub extern "C" fn rustls_server_config_builder_set_alpn_protocols( builder: *mut rustls_server_config_builder, @@ -349,12 +384,14 @@ impl rustls_server_config_builder { /// verification capabilities. /// /// Servers that want to support both ECDSA and RSA certificates will want - /// the ECSDA to go first in the list. + /// the ECDSA certificate to go first in the list. /// - /// The built configuration will keep a reference to all certified keys - /// provided. The client may `rustls_certified_key_free()` afterwards - /// without the configuration losing them. The same certified key may also - /// be used in multiple configs. + /// In the usual case, first call `rustls_certified_key_build` with the PEM + /// certificate chain and private key, then pass the resulting + /// `rustls_certified_key` pointer to this function. The builder and built + /// configuration keep a reference to each certified key, so the caller may + /// call `rustls_certified_key_free()` after this function returns. The same + /// certified key may also be used in multiple configs. /// /// EXPERIMENTAL: installing a client_hello callback will replace any /// configured certified keys and vice versa. @@ -377,9 +414,15 @@ impl rustls_server_config_builder { } } - /// Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config + /// Turn a mutable `rustls_server_config_builder` 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`. + /// pointer when this function returns `RUSTLS_RESULT_OK`. + /// + /// This function takes ownership of `builder`. The caller must not use or free the builder + /// after calling this function, regardless of the result. + /// + /// On `RUSTLS_RESULT_OK`, `config_out` receives a config owned by the caller, which must + /// eventually be freed with `rustls_server_config_free`. On error, `config_out` is unchanged. /// /// 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 @@ -449,13 +492,13 @@ impl rustls_server_config { } } - /// "Free" a rustls_server_config previously returned from - /// rustls_server_config_builder_build. + /// Release the caller's reference to a `rustls_server_config` previously returned from + /// `rustls_server_config_builder_build`. + /// + /// Existing server connections may still hold internal references to the atomically + /// reference-counted Rust object. Regardless, the caller must not use `config` after this + /// function returns. /// - /// Since rustls_server_config is actually an - /// atomically reference-counted pointer, extant server connections may still - /// hold an internal reference to the Rust object. However, C code must - /// consider this pointer unusable after "free"ing it. /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] pub extern "C" fn rustls_server_config_free(config: *const rustls_server_config) { @@ -464,17 +507,20 @@ impl rustls_server_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 a non-error, the memory pointed to by `conn_out` is modified to point - /// at a valid rustls_connection + /// at a valid `rustls_connection` /// - /// The caller now owns the rustls_connection and must call `rustls_connection_free` when + /// The caller now owns the `rustls_connection` and must call `rustls_connection_free` when /// done with it. + /// + /// The connection retains an internal reference to `config`. This function + /// does not take ownership of the caller's config pointer. #[no_mangle] pub extern "C" fn rustls_server_connection_new( config: *const rustls_server_config, @@ -502,14 +548,14 @@ impl rustls_server_config { /// 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`. +/// connection. A mutating function call is one where the first argument is a mutable pointer to +/// `rustls_connection` (as opposed to a const pointer). 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 +/// - the connection is a server connection but the SNI extension in the ClientHello has not /// been processed during the handshake yet. Check `rustls_connection_is_handshaking`. /// - the SNI value contains null bytes. #[no_mangle] @@ -559,31 +605,34 @@ impl ResolvesServerCert for ResolvesServerCertFromChoices { } } -/// The TLS Client Hello information provided to a ClientHelloCallback function. +/// The TLS ClientHello information provided to a `rustls_client_hello_callback`. /// -/// `server_name` is the value of the ServerNameIndication extension provided +/// `server_name` is the value of the server name indication (SNI) extension provided /// by the client. If the client did not send an SNI, the length of this -/// `rustls_string` will be 0. +/// `rustls_str` 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 the rustls documentation for [`SignatureScheme`] for more information. /// /// `named_groups` carries the values of the `named_groups` extension sent by the /// client. If the client did not send a `named_groups` extension, the length of -/// this `rustls_slice_u16` will be 0. The meaning of this extension differ -/// based on TLS version. See the Rustls documentation for more information: -/// +/// this `rustls_slice_u16` will be 0. The meaning of this extension differs +/// based on TLS version. See the rustls documentation for +/// [`ClientHello::named_groups`] for more information. /// /// `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. +/// they want to access after the callback returns. /// /// 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. +/// the rustls library is re-evaluating its current approach to ClientHello handling. +/// +/// [`SignatureScheme`]: https://docs.rs/rustls/latest/rustls/enum.SignatureScheme.html +/// [`ClientHello::named_groups`]: https://rustls.dev/docs/server/struct.ClientHello.html#method.named_groups #[repr(C)] pub struct rustls_client_hello<'a> { server_name: rustls_str<'a>, @@ -603,23 +652,23 @@ pub type rustls_client_hello_userdata = *mut c_void; /// Prototype of a callback that can be installed by the application at the /// `rustls_server_config`. /// -/// This callback will be invoked by a `rustls_connection` once the TLS client -/// hello message has been received. +/// This callback will be invoked by a `rustls_connection` once the TLS ClientHello +/// message has been received. /// -/// `userdata` will be set based on rustls_connection_set_userdata. +/// `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` contains the client parameters parsed 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 +/// **Note:** +/// +/// - The passed-in `hello` and all its values are only valid during the callback invocation. +/// - The callback 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. +/// the rustls library is re-evaluating its current approach to ClientHello handling. pub type rustls_client_hello_callback = Option< unsafe extern "C" fn( userdata: rustls_client_hello_userdata, @@ -705,7 +754,7 @@ impl Debug for ClientHelloResolver { impl rustls_server_config_builder { /// Register a callback to be invoked when a connection created from this config /// sees a TLS ClientHello message. If `userdata` has been set with - /// rustls_connection_set_userdata, it will be passed to the callback. + /// `rustls_connection_set_userdata`, it will be passed to the callback. /// Otherwise the userdata param passed to the callback will be NULL. /// /// Any existing `ResolvesServerCert` implementation currently installed in the @@ -714,7 +763,7 @@ impl rustls_server_config_builder { /// 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. + /// the rustls library is re-evaluating its current approach to ClientHello handling. /// Installing a client_hello callback will replace any configured certified keys /// and vice versa. Same holds true for the set_certified_keys variant. #[no_mangle] @@ -740,10 +789,10 @@ fn sigschemes(input: &[u16]) -> Vec { } /// Select a `rustls_certified_key` from the list that matches the cryptographic -/// parameters of a TLS client hello. +/// parameters of a TLS ClientHello. /// /// Note that this does not do any SNI matching. The input certificates should -/// already have been filtered to ones matching the SNI from the client hello. +/// already have been filtered to ones matching the SNI from the ClientHello. /// /// 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 @@ -752,8 +801,14 @@ fn sigschemes(input: &[u16]) -> Vec { /// 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 +/// Return `RUSTLS_RESULT_OK` if a key was selected and `RUSTLS_RESULT_NOT_FOUND` /// if none was suitable. +/// +/// On success, `out_key` is set to one of the pointers from `certified_keys`. The function does +/// not take ownership or increment the reference count. The returned pointer remains valid only +/// while the caller keeps the corresponding input key alive and must not be freed separately. +/// +/// On error, `out_key` is unchanged. #[no_mangle] pub extern "C" fn rustls_client_hello_select_certified_key( hello: *const rustls_client_hello, @@ -788,7 +843,7 @@ impl rustls_server_config_builder { /// If `builder`, `get_cb`, or `put_cb` are NULL, this function will return /// immediately without doing anything. /// - /// If `userdata` has been set with rustls_connection_set_userdata, it + /// If `userdata` has been set with `rustls_connection_set_userdata`, it /// will be passed to the callbacks. Otherwise the userdata param passed to /// the callbacks will be NULL. #[no_mangle] diff --git a/librustls/src/session.rs b/librustls/src/session.rs index 0886d0b6..73ca2f86 100644 --- a/librustls/src/session.rs +++ b/librustls/src/session.rs @@ -13,9 +13,9 @@ pub type rustls_session_store_userdata = *mut c_void; /// `rustls_server_config` or `rustls_client_config`. /// /// This callback will be invoked by a TLS session when looking up the data -/// for a TLS session id. +/// for a TLS session ID. /// -/// `userdata` will be supplied based on rustls_{client,server}_session_set_userdata. +/// `userdata` will be supplied based on `rustls_connection_set_userdata`. /// /// The `buf` points to `count` consecutive bytes where the /// callback is expected to copy the result to. The number of copied bytes @@ -26,17 +26,17 @@ pub type rustls_session_store_userdata = *mut c_void; /// do a partial copy but instead remove the value from its store and /// act as if it was never found. /// -/// The callback should return RUSTLS_RESULT_OK to indicate that a value was -/// retrieved and written in its entirety into `buf`, or RUSTLS_RESULT_NOT_FOUND +/// The callback should return `RUSTLS_RESULT_OK` to indicate that a value was +/// retrieved and written in its entirety into `buf`, or `RUSTLS_RESULT_NOT_FOUND` /// if no session was retrieved. /// -/// When `remove_after` is != 0, the returned data needs to be removed +/// When `remove_after` is nonzero, the returned data needs to be removed /// from the store. /// -/// NOTE: the passed in `key` and `buf` are only available during the -/// callback invocation. -/// NOTE: callbacks used in several sessions via a common config -/// must be implemented thread-safe. +/// **Notes:** +/// +/// - The passed-in `key` and `buf` are only valid during the callback invocation. +/// - Callbacks shared by several sessions through a common config must be thread-safe. pub type rustls_session_store_get_callback = Option< unsafe extern "C" fn( userdata: rustls_session_store_userdata, @@ -60,19 +60,18 @@ pub(crate) type SessionStoreGetCallback = unsafe extern "C" fn( /// Prototype of a callback that can be installed by the application at the /// `rustls_server_config` or `rustls_client_config`. /// -/// This callback will be invoked by a TLS session when a TLS session -/// been created and an id for later use is handed to the client/has -/// been received from the server. +/// This callback will be invoked when a resumable TLS session has been created and a session ID +/// has either been sent to the client or received from the server. +/// +/// `userdata` will be supplied based on `rustls_connection_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. /// -/// The callback should return RUSTLS_RESULT_OK to indicate that a value was -/// successfully stored, or RUSTLS_RESULT_IO on failure. +/// **Notes:** /// -/// NOTE: the passed in `key` and `val` are only available during the -/// callback invocation. -/// NOTE: callbacks used in several sessions via a common config -/// must be implemented thread-safe. +/// - The passed-in `key` and `val` are only valid during the callback invocation. +/// - Callbacks shared by several sessions through a common config must be thread-safe. pub type rustls_session_store_put_callback = Option< unsafe extern "C" fn( userdata: rustls_session_store_userdata, diff --git a/librustls/src/userdata.rs b/librustls/src/userdata.rs index 63ee98f6..87f89357 100644 --- a/librustls/src/userdata.rs +++ b/librustls/src/userdata.rs @@ -101,7 +101,9 @@ pub(crate) enum UserdataError { /// The stack of userdata items was already empty. EmptyStack, /// The LocalKey was destroyed before this call. - /// See + /// See [`LocalKey::try_with`] for more information. + /// + /// [`LocalKey::try_with`]: https://doc.rust-lang.org/std/thread/struct.LocalKey.html#method.try_with AccessError, /// Unexpected pointer when popping. WrongData, diff --git a/librustls/src/verifier.rs b/librustls/src/verifier.rs index b9a32002..5e189e65 100644 --- a/librustls/src/verifier.rs +++ b/librustls/src/verifier.rs @@ -38,8 +38,8 @@ impl Castable for rustls_client_cert_verifier { impl rustls_client_cert_verifier { /// 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_web_pki_client_cert_verifier_builder_build`. Calling with NULL is fine. + /// Must not be called twice with the same value. #[no_mangle] pub extern "C" fn rustls_client_cert_verifier_free(verifier: *mut rustls_client_cert_verifier) { ffi_panic_boundary! { @@ -67,8 +67,9 @@ pub(crate) struct ClientCertVerifierBuilder { /// /// This object is not safe for concurrent mutation. /// -/// See -/// for more information. +/// See also the rustls documentation for [`ClientCertVerifierBuilder`]. +/// +/// [`ClientCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/server/struct.ClientCertVerifierBuilder.html pub struct rustls_web_pki_client_cert_verifier_builder { _private: [u8; 0], } @@ -86,7 +87,7 @@ impl rustls_web_pki_client_cert_verifier_builder { /// 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 + /// will require a client to 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 @@ -101,8 +102,9 @@ impl rustls_web_pki_client_cert_verifier_builder { /// Unauthenticated clients will not be permitted unless /// `rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated` is used. /// - /// This copies the contents of the `rustls_root_cert_store`. It does not take - /// ownership of the pointed-to data. + /// This does not take ownership of `store`. The builder retains its own + /// reference, so the caller may free its root certificate store pointer after + /// this function returns. #[no_mangle] pub extern "C" fn rustls_web_pki_client_cert_verifier_builder_new( store: *const rustls_root_cert_store, @@ -129,7 +131,7 @@ impl rustls_web_pki_client_cert_verifier_builder { /// 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 + /// will require a client to 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 @@ -144,8 +146,9 @@ impl rustls_web_pki_client_cert_verifier_builder { /// Unauthenticated clients will not be permitted unless /// `rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated` is used. /// - /// This copies the contents of the `rustls_root_cert_store`. It does not take - /// ownership of the pointed-to data. + /// This does not take ownership of `provider` or `store`. The builder retains + /// its own references, so the caller may free both input pointers after this + /// function returns. #[no_mangle] pub extern "C" fn rustls_web_pki_client_cert_verifier_builder_new_with_provider( provider: *const rustls_crypto_provider, @@ -174,6 +177,8 @@ impl rustls_web_pki_client_cert_verifier_builder { /// `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. + /// + /// It copies the parsed CRLs and does not retain `crl_pem`. #[no_mangle] pub extern "C" fn rustls_web_pki_client_cert_verifier_builder_add_crl( builder: *mut rustls_web_pki_client_cert_verifier_builder, @@ -313,9 +318,10 @@ impl rustls_web_pki_client_cert_verifier_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. + /// On `RUSTLS_RESULT_OK`, `verifier_out` receives a verifier owned by the caller. It can be + /// used in several `rustls_server_config` instances and must be freed with + /// `rustls_client_cert_verifier_free` when no longer needed. On error, `verifier_out` is + /// unchanged. #[no_mangle] pub extern "C" fn rustls_web_pki_client_cert_verifier_builder_build( builder: *mut rustls_web_pki_client_cert_verifier_builder, @@ -365,8 +371,8 @@ impl rustls_web_pki_client_cert_verifier_builder { } } - /// Free a `rustls_client_cert_verifier_builder` previously returned from - /// `rustls_client_cert_verifier_builder_new`. + /// Free a `rustls_web_pki_client_cert_verifier_builder` previously returned from + /// `rustls_web_pki_client_cert_verifier_builder_new`. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -386,8 +392,9 @@ impl rustls_web_pki_client_cert_verifier_builder { /// 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 -/// for more information. +/// See also the rustls documentation for [`ServerCertVerifierBuilder`]. +/// +/// [`ServerCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/client/struct.ServerCertVerifierBuilder.html pub struct rustls_web_pki_server_cert_verifier_builder { _private: [u8; 0], } @@ -414,7 +421,7 @@ impl ServerCertVerifierBuilder { /// 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 + /// will require a server to 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 @@ -426,8 +433,9 @@ impl ServerCertVerifierBuilder { /// 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. + /// This does not take ownership of `store`. The builder retains its own + /// reference, so the caller may free its root certificate store pointer after + /// this function returns. #[no_mangle] pub extern "C" fn rustls_web_pki_server_cert_verifier_builder_new( store: *const rustls_root_cert_store, @@ -451,7 +459,7 @@ impl ServerCertVerifierBuilder { /// `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 + /// will require a server to 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 @@ -464,8 +472,9 @@ impl ServerCertVerifierBuilder { /// 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. + /// This does not take ownership of `provider` or `store`. The builder retains + /// its own references, so the caller may free both input pointers after this + /// function returns. #[no_mangle] pub extern "C" fn rustls_web_pki_server_cert_verifier_builder_new_with_provider( provider: *const rustls_crypto_provider, @@ -493,6 +502,8 @@ impl ServerCertVerifierBuilder { /// `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. + /// + /// It copies the parsed CRLs and does not retain `crl_pem`. #[no_mangle] pub extern "C" fn rustls_web_pki_server_cert_verifier_builder_add_crl( builder: *mut rustls_web_pki_server_cert_verifier_builder, @@ -588,9 +599,10 @@ impl ServerCertVerifierBuilder { /// /// 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. + /// On `RUSTLS_RESULT_OK`, `verifier_out` receives a verifier owned by the caller. It can be + /// used in several `rustls_client_config` instances and must be freed with + /// `rustls_server_cert_verifier_free` when no longer needed. On error, `verifier_out` is + /// unchanged. #[no_mangle] pub extern "C" fn rustls_web_pki_server_cert_verifier_builder_build( builder: *mut rustls_web_pki_server_cert_verifier_builder, @@ -636,8 +648,8 @@ impl ServerCertVerifierBuilder { } } - /// Free a `rustls_server_cert_verifier_builder` previously returned from - /// `rustls_server_cert_verifier_builder_new`. + /// Free a `rustls_web_pki_server_cert_verifier_builder` previously returned from + /// `rustls_web_pki_server_cert_verifier_builder_new`. /// /// Calling with NULL is fine. Must not be called twice with the same value. #[no_mangle] @@ -674,6 +686,8 @@ impl rustls_server_cert_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. /// + /// On error, `verifier_out` is unchanged. + /// /// [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier #[no_mangle] pub extern "C" fn rustls_platform_server_cert_verifier( @@ -724,7 +738,7 @@ impl rustls_server_cert_verifier { /// /// If the initialization of `rustls-platform-verifier` fails, this function returns /// an error and `NULL` is written to `verifier_out`. Otherwise it fills in `verifier_out` - /// (whose ownership is transferred to the caller) and returns `RUSTLS_SUCCESS`. + /// (whose ownership is transferred to the caller) and returns `RUSTLS_RESULT_OK`. /// /// 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. @@ -750,7 +764,8 @@ impl rustls_server_cert_verifier { } /// Free a `rustls_server_cert_verifier` previously returned from - /// `rustls_server_cert_verifier_builder_build` or `rustls_platform_server_cert_verifier`. + /// `rustls_web_pki_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. #[no_mangle] diff --git a/tools/src/bin/docgen/main.rs b/tools/src/bin/docgen/main.rs index 7b4a3695..7c3a5d89 100644 --- a/tools/src/bin/docgen/main.rs +++ b/tools/src/bin/docgen/main.rs @@ -149,6 +149,13 @@ fn find_doc_items(root: Node, source_code: &[u8]) -> Result String { res.unwrap() } +fn make_anchor(name: &str) -> String { + name.replace('_', "-").to_ascii_lowercase() +} + +fn is_c_api_reference(content: &str) -> bool { + let content = content.trim_end_matches("()"); + (content.starts_with("rustls_") || content.starts_with("RUSTLS_")) + && content + .chars() + .all(|c| c.is_ascii_alphanumeric() || c == '_') +} + /// Require that a `Node` correspond to a specific kind of grammar rule. /// /// Returns an error describing the node's position and the expected vs actual @@ -891,3 +918,45 @@ fn node_text(node: Node, src: &[u8]) -> String { fn markup_text(node: Node, src: &[u8]) -> String { format!("```c\n{}\n```", node_text(node, src)) } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn crosslinks_all_documented_item_kinds() { + let anchors = HashSet::from([ + "rustls-connection-write-tls".to_string(), + "rustls-write-callback".to_string(), + "rustls-result-ok".to_string(), + "alias-rustls-io-result".to_string(), + ]); + let mut comment = Comment( + "Call `rustls_connection_write_tls()` with a `rustls_write_callback`. \ + It returns `RUSTLS_RESULT_OK` as a `rustls_io_result`." + .to_string(), + ); + + comment.crosslink(&anchors).unwrap(); + + assert_eq!( + comment.0, + "Call [`rustls_connection_write_tls()`](#rustls-connection-write-tls) with a \ + [`rustls_write_callback`](#rustls-write-callback). It returns \ + [`RUSTLS_RESULT_OK`](#rustls-result-ok) as a \ + [`rustls_io_result`](#alias-rustls-io-result)." + ); + } + + #[test] + fn rejects_unresolved_api_references() { + let mut comment = Comment("Call `rustls_function_that_does_not_exist()`.".to_string()); + + let error = comment.crosslink(&HashSet::new()).unwrap_err(); + + assert_eq!( + error.to_string(), + "unresolved API reference: `rustls_function_that_does_not_exist()`" + ); + } +} diff --git a/website/config.toml b/website/config.toml index 6498c85b..19aa1f5b 100644 --- a/website/config.toml +++ b/website/config.toml @@ -7,10 +7,8 @@ compile_sass = false # Whether to build a search index to be used later on by a JavaScript library build_search_index = false -[markdown] -# Whether to do syntax highlighting -# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola -highlight_code = true +[markdown.highlighting] +theme = "github-dark" [slugify] paths_keep_dates = true diff --git a/website/static/api.json b/website/static/api.json index 8282c5a3..79b282b4 100644 --- a/website/static/api.json +++ b/website/static/api.json @@ -2,7 +2,7 @@ "structs": [ { "anchor": "rustls-accepted", - "comment": "A parsed ClientHello produced by a rustls_acceptor.\n\n It is used to check server name indication (SNI), ALPN protocols,\n signature schemes, and cipher suites. It can be combined with a\n [`rustls_server_config`](#rustls-server-config) to build a [`rustls_connection`](#rustls-connection).", + "comment": "A parsed ClientHello produced by a [`rustls_acceptor`](#rustls-acceptor).\n\n It is used to check server name indication (SNI), ALPN protocols,\n signature schemes, and cipher suites. It can be combined with a\n [`rustls_server_config`](#rustls-server-config) to build a [`rustls_connection`](#rustls-connection).", "feature": null, "deprecation": null, "name": "rustls_accepted", @@ -18,7 +18,7 @@ }, { "anchor": "rustls-acceptor", - "comment": "A buffer and parser for ClientHello bytes.\n\n This allows reading ClientHello before choosing a rustls_server_config.\n\n It's useful when the server config will be based on parameters in the\n ClientHello: server name indication (SNI), ALPN protocols, signature\n schemes, and cipher suites.\n\n In particular, if a server wants to do some potentially expensive work\n to load a certificate for a given hostname, rustls_acceptor allows doing\n that asynchronously, as opposed to rustls_server_config_builder_set_hello_callback(),\n which doesn't work well for asynchronous I/O.\n\n The general flow is:\n - rustls_acceptor_new()\n - Loop:\n - Read bytes from the network it with rustls_acceptor_read_tls().\n - If successful, parse those bytes with rustls_acceptor_accept().\n - If that returns RUSTLS_RESULT_ACCEPTOR_NOT_READY, continue.\n - Otherwise, break.\n - If rustls_acceptor_accept() returned RUSTLS_RESULT_OK:\n - Examine the resulting rustls_accepted.\n - Create or select a rustls_server_config.\n - Call rustls_accepted_into_connection().\n - Otherwise, there was a problem with the ClientHello data and the\n connection should be rejected.", + "comment": "A buffer and parser for ClientHello bytes.\n\n This allows reading ClientHello before choosing a [`rustls_server_config`](#rustls-server-config).\n\n It's useful when the server config will be based on parameters in the\n ClientHello: server name indication (SNI), ALPN protocols, signature\n schemes, and cipher suites.\n\n In particular, if a server wants to do some potentially expensive work\n to load a certificate for a given hostname, [`rustls_acceptor`](#rustls-acceptor) allows doing\n that asynchronously, as opposed to [`rustls_server_config_builder_set_hello_callback()`](#rustls-server-config-builder-set-hello-callback),\n which doesn't work well for asynchronous I/O.\n\n The general flow is:\n\n - [`rustls_acceptor_new()`](#rustls-acceptor-new)\n - Loop:\n - Read bytes from the network with [`rustls_acceptor_read_tls()`](#rustls-acceptor-read-tls).\n - If successful, parse those bytes with [`rustls_acceptor_accept()`](#rustls-acceptor-accept).\n - If that returns [`RUSTLS_RESULT_ACCEPTOR_NOT_READY`](#rustls-result-acceptor-not-ready), continue.\n - Otherwise, break.\n - If [`rustls_acceptor_accept()`](#rustls-acceptor-accept) returned [`RUSTLS_RESULT_OK`](#rustls-result-ok):\n - Examine the resulting [`rustls_accepted`](#rustls-accepted).\n - Create or select a [`rustls_server_config`](#rustls-server-config).\n - Call [`rustls_accepted_into_connection()`](#rustls-accepted-into-connection).\n - Otherwise, there was a problem with the ClientHello data and the\n connection should be rejected.", "feature": null, "deprecation": null, "name": "rustls_acceptor", @@ -26,7 +26,7 @@ }, { "anchor": "rustls-certificate", - "comment": "An X.509 certificate, as used in rustls.\n Corresponds to `CertificateDer` in the Rust pki-types API.\n ", + "comment": "An X.509 certificate, as used in rustls.\n Corresponds to `CertificateDer` in the Rust pki-types API.\n\n See also the rustls-pki-types documentation for [`CertificateDer`].\n\n [`CertificateDer`]: https://docs.rs/rustls-pki-types/latest/rustls_pki_types/struct.CertificateDer.html", "feature": null, "deprecation": null, "name": "rustls_certificate", @@ -34,7 +34,7 @@ }, { "anchor": "rustls-certified-key", - "comment": "The complete chain of certificates to send during a TLS handshake,\n plus a private key that matches the end-entity (leaf) certificate.\n\n Corresponds to `CertifiedKey` in the Rust API.\n ", + "comment": "The complete chain of certificates to send during a TLS handshake,\n plus a private key that matches the end-entity (leaf) certificate.\n\n Corresponds to `CertifiedKey` in the Rust API.\n\n See also the rustls documentation for [`CertifiedKey`].\n\n [`CertifiedKey`]: https://docs.rs/rustls/latest/rustls/sign/struct.CertifiedKey.html", "feature": null, "deprecation": null, "name": "rustls_certified_key", @@ -50,7 +50,7 @@ }, { "anchor": "rustls-client-config", - "comment": "A client config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n ", + "comment": "A client config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n\n See also the rustls documentation for [`ClientConfig`].\n\n [`ClientConfig`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html", "feature": null, "deprecation": null, "name": "rustls_client_config", @@ -58,7 +58,7 @@ }, { "anchor": "rustls-client-config-builder", - "comment": "A client config being constructed.\n\n A builder can be modified by, e.g. `rustls_client_config_builder_load_roots_from_file`.\n Once you're done configuring settings, call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build)\n to turn it into a *rustls_client_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation. Under the hood,\n it corresponds to a `Box`.\n ", + "comment": "A client config being constructed.\n\n A builder can be modified by, e.g. [`rustls_client_config_builder_set_server_verifier`](#rustls-client-config-builder-set-server-verifier).\n Once you're done configuring settings, call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build)\n to turn it into a [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation. Under the hood,\n it corresponds to a `Box`.\n\n See also the rustls documentation for [`ConfigBuilder`].\n\n [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html", "feature": null, "deprecation": null, "name": "rustls_client_config_builder", @@ -74,7 +74,7 @@ }, { "anchor": "rustls-crypto-provider", - "comment": "A C representation of a Rustls [`CryptoProvider`].", + "comment": "A C representation of a Rustls\n [`CryptoProvider`](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html).", "feature": null, "deprecation": null, "name": "rustls_crypto_provider", @@ -98,7 +98,7 @@ }, { "anchor": "rustls-iovec", - "comment": "An alias for `struct iovec` from uio.h (on Unix) or `WSABUF` on Windows.\n\n You should cast `const struct rustls_iovec *` to `const struct iovec *` on\n Unix, or `const *LPWSABUF` on Windows. See [`std::io::IoSlice`] for details\n on interoperability with platform specific vectored IO.", + "comment": "An alias for `struct iovec` from uio.h (on Unix) or `WSABUF` on Windows.\n\n On Unix, cast `const rustls_iovec *` to `const struct iovec *`. On Windows,\n cast it to `const WSABUF *`; `LPWSABUF` is an alias for the non-const pointer\n `WSABUF *`.\n\n See [`std::io::IoSlice`] for details on interoperability with platform-specific\n vectored IO.\n\n [`std::io::IoSlice`]: https://doc.rust-lang.org/std/io/struct.IoSlice.html", "feature": null, "deprecation": null, "name": "rustls_iovec", @@ -106,7 +106,7 @@ }, { "anchor": "rustls-root-cert-store", - "comment": "A root certificate store.\n ", + "comment": "A root certificate store.\n\n See also the rustls documentation for [`RootCertStore`].\n\n [`RootCertStore`]: https://docs.rs/rustls/latest/rustls/struct.RootCertStore.html", "feature": null, "deprecation": null, "name": "rustls_root_cert_store", @@ -130,7 +130,7 @@ }, { "anchor": "rustls-server-config", - "comment": "A server config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n ", + "comment": "A server config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n\n See also the rustls documentation for [`ServerConfig`].\n\n [`ServerConfig`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html", "feature": null, "deprecation": null, "name": "rustls_server_config", @@ -138,7 +138,7 @@ }, { "anchor": "rustls-server-config-builder", - "comment": "A server config being constructed.\n\n A builder can be modified by,\n e.g. rustls_server_config_builder_load_native_roots. Once you're\n done configuring settings, call rustls_server_config_builder_build\n to turn it into a *const rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation.\n ", + "comment": "A server config being constructed.\n\n A builder can be modified by, e.g. [`rustls_server_config_builder_set_certified_keys`](#rustls-server-config-builder-set-certified-keys).\n Once you're done configuring settings, call [`rustls_server_config_builder_build`](#rustls-server-config-builder-build)\n to turn it into a [`rustls_server_config`](#rustls-server-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation.\n\n See also the rustls documentation for [`ConfigBuilder`].\n\n [`ConfigBuilder`]: https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html", "feature": null, "deprecation": null, "name": "rustls_server_config_builder", @@ -178,7 +178,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder", - "comment": "A client certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build)\n to turn it into a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier).\n\n This object is not safe for concurrent mutation.\n\n See \n for more information.", + "comment": "A client certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build)\n to turn it into a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier).\n\n This object is not safe for concurrent mutation.\n\n See also the rustls documentation for [`ClientCertVerifierBuilder`].\n\n [`ClientCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/server/struct.ClientCertVerifierBuilder.html", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder", @@ -186,7 +186,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder", - "comment": "A server certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build)\n to turn it into a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier). This object is not safe for concurrent mutation.\n\n See \n for more information.", + "comment": "A server certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build)\n to turn it into a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier). This object is not safe for concurrent mutation.\n\n See also the rustls documentation for [`ServerCertVerifierBuilder`].\n\n [`ServerCertVerifierBuilder`]: https://docs.rs/rustls/latest/rustls/client/struct.ServerCertVerifierBuilder.html", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder", @@ -194,7 +194,7 @@ }, { "anchor": "rustls-str", - "comment": "A read-only view on a Rust `&str`.\n\n The contents are guaranteed to be valid UTF-8.\n\n As an additional guarantee on top of Rust's normal UTF-8 guarantee,\n a [`rustls_str`](#rustls-str) is guaranteed not to contain internal NUL bytes, so it is\n safe to interpolate into a C string or compare using strncmp. Keep in mind\n that it is not NUL-terminated.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "comment": "A read-only view on a Rust `&str`.\n\n The contents are guaranteed to be valid UTF-8.\n\n As an additional guarantee on top of Rust's normal UTF-8 guarantee,\n a [`rustls_str`](#rustls-str) is guaranteed not to contain internal NUL bytes. Its `data`\n and `len` fields can be passed to APIs that accept an explicit byte length.\n The `data` field is not NUL-terminated and must not be passed to functions\n that expect a C string.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", "feature": null, "deprecation": null, "name": "rustls_str", @@ -202,7 +202,7 @@ }, { "anchor": "rustls-slice-bytes", - "comment": "A read-only view on a Rust byte slice.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of bytes than can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "comment": "A read-only view on a Rust byte slice.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of bytes that can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", "feature": null, "deprecation": null, "name": "rustls_slice_bytes", @@ -218,7 +218,7 @@ }, { "anchor": "rustls-log-params", - "comment": "Parameter structure passed to a `rustls_log_callback`.", + "comment": "Parameter structure passed to a [`rustls_log_callback`](#rustls-log-callback).", "feature": null, "deprecation": null, "name": "rustls_log_params", @@ -226,7 +226,7 @@ }, { "anchor": "rustls-slice-u16", - "comment": "A read-only view on a Rust slice of 16-bit integers in platform endianness.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of bytes than can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "comment": "A read-only view on a Rust slice of 16-bit integers in platform endianness.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of 16-bit integers that can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", "feature": null, "deprecation": null, "name": "rustls_slice_u16", @@ -234,7 +234,7 @@ }, { "anchor": "rustls-client-hello", - "comment": "The TLS Client Hello information provided to a ClientHelloCallback function.\n\n `server_name` is the value of the ServerNameIndication extension provided\n by the client. If the client did not send an SNI, the length of this\n `rustls_string` will be 0.\n\n `signature_schemes` carries the values supplied by the client or, if the\n client did not send this TLS extension, the default schemes in the rustls library. See:\n .\n\n `named_groups` carries the values of the `named_groups` extension sent by the\n client. If the client did not send a `named_groups` extension, the length of\n this [`rustls_slice_u16`](#rustls-slice-u16) will be 0. The meaning of this extension differ\n based on TLS version. See the Rustls documentation for more information:\n \n\n `alpn` carries the list of ALPN protocol names that the client proposed to\n the server. Again, the length of this list will be 0 if none were supplied.\n\n All this data, when passed to a callback function, is only accessible during\n the call and may not be modified. Users of this API must copy any values that\n they want to access when the callback returned.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.", + "comment": "The TLS ClientHello information provided to a [`rustls_client_hello_callback`](#rustls-client-hello-callback).\n\n `server_name` is the value of the server name indication (SNI) extension provided\n by the client. If the client did not send an SNI, the length of this\n [`rustls_str`](#rustls-str) will be 0.\n\n `signature_schemes` carries the values supplied by the client or, if the\n client did not send this TLS extension, the default schemes in the rustls library.\n See the rustls documentation for [`SignatureScheme`] for more information.\n\n `named_groups` carries the values of the `named_groups` extension sent by the\n client. If the client did not send a `named_groups` extension, the length of\n this [`rustls_slice_u16`](#rustls-slice-u16) will be 0. The meaning of this extension differs\n based on TLS version. See the rustls documentation for\n [`ClientHello::named_groups`] for more information.\n\n `alpn` carries the list of ALPN protocol names that the client proposed to\n the server. Again, the length of this list will be 0 if none were supplied.\n\n All this data, when passed to a callback function, is only accessible during\n the call and may not be modified. Users of this API must copy any values that\n they want to access after the callback returns.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating its current approach to ClientHello handling.\n\n [`SignatureScheme`]: https://docs.rs/rustls/latest/rustls/enum.SignatureScheme.html\n [`ClientHello::named_groups`]: https://rustls.dev/docs/server/struct.ClientHello.html#method.named_groups", "feature": null, "deprecation": null, "name": "rustls_client_hello", @@ -244,7 +244,7 @@ "functions": [ { "anchor": "rustls-acceptor-new", - "comment": "Create and return a new rustls_acceptor.\n\n Caller owns the pointed-to memory and must eventually free it with\n [`rustls_acceptor_free()`](#rustls-acceptor-free).", + "comment": "Create and return a new [`rustls_acceptor`](#rustls-acceptor).\n\n Caller owns the pointed-to memory and must eventually free it with\n [`rustls_acceptor_free()`](#rustls-acceptor-free).", "feature": null, "deprecation": null, "name": "rustls_acceptor_new", @@ -252,7 +252,7 @@ }, { "anchor": "rustls-acceptor-free", - "comment": "Free a rustls_acceptor.\n\n Parameters:\n\n acceptor: The rustls_acceptor to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_acceptor`](#rustls-acceptor).\n\n **Parameters:**\n\n - `acceptor`: The [`rustls_acceptor`](#rustls-acceptor) to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_acceptor_free", @@ -260,7 +260,7 @@ }, { "anchor": "rustls-acceptor-read-tls", - "comment": "Read some TLS bytes from the network into internal buffers.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer to store the\n read bytes into. You don't have to fill it up, just fill with as many\n bytes as you get in one syscall.\n\n Parameters:\n\n acceptor: The rustls_acceptor to read bytes into.\n callback: A function that will perform the actual network I/O.\n Must be valid to call with the given userdata parameter until\n this function call returns.\n userdata: An opaque parameter to be passed directly to `callback`.\n Note: this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n out_n: An output parameter. This will be passed through to `callback`,\n which should use it to store the number of bytes written.\n\n Returns:\n\n - 0: Success. You should call [`rustls_acceptor_accept()`](#rustls-acceptor-accept) next.\n - Any non-zero value: error.\n\n This function passes through return values from `callback`. Typically\n `callback` should return an errno value. See `rustls_read_callback()` for\n more details.", + "comment": "Read some TLS bytes from the network into internal buffers.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer to store the\n read bytes into. You don't have to fill it up, just fill with as many\n bytes as you get in one syscall.\n\n **Parameters:**\n\n - `acceptor`: The [`rustls_acceptor`](#rustls-acceptor) to read bytes into.\n - `callback`: A function that will perform the actual network I/O.\n It must be valid to call with the given `userdata` parameter until\n this function call returns.\n - `userdata`: An opaque parameter to be passed directly to `callback`.\n Note: this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n - `out_n`: An output parameter that receives the number of bytes read when\n this function returns 0. It is unchanged on error.\n\n **Returns:**\n\n - 0: Success. You should call [`rustls_acceptor_accept()`](#rustls-acceptor-accept) next.\n - Any non-zero value: error.\n\n This function passes through return values from `callback`. Typically\n `callback` should return an errno value. See [`rustls_read_callback()`](#rustls-read-callback) for\n more details.", "feature": null, "deprecation": null, "name": "rustls_acceptor_read_tls", @@ -268,7 +268,7 @@ }, { "anchor": "rustls-acceptor-accept", - "comment": "Parse all TLS bytes read so far.\n\n If those bytes make up a ClientHello, create a rustls_accepted from them.\n\n Parameters:\n\n acceptor: The rustls_acceptor to access.\n out_accepted: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted only when the function returns\n RUSTLS_RESULT_OK. The memory is owned by the caller and must eventually\n be freed\n out_alert: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted_alert only when the function returns\n a non-OK result. The memory is owned by the caller and must eventually\n be freed with rustls_accepted_alert_free. The caller should call\n rustls_accepted_alert_write_tls to write the alert bytes to the TLS\n connection before freeing the rustls_accepted_alert.\n\n At most one of out_accepted or out_alert will be set.\n\n Returns:\n\n - RUSTLS_RESULT_OK: a ClientHello has successfully been parsed.\n A pointer to a newly allocated rustls_accepted has been written to\n *out_accepted.\n - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been read.\n Read more TLS bytes to continue.\n - Any other rustls_result: the TLS bytes read so far cannot be parsed\n as a ClientHello, and reading additional bytes won't help.\n\n Memory and lifetimes:\n\n After this method returns RUSTLS_RESULT_OK, `acceptor` is\n still allocated and valid. It needs to be freed regardless of success\n or failure of this function.\n\n Calling [`rustls_acceptor_accept()`](#rustls-acceptor-accept) multiple times on the same\n [`rustls_acceptor`](#rustls-acceptor) is acceptable from a memory perspective but pointless\n from a protocol perspective.", + "comment": "Parse all TLS bytes read so far.\n\n If those bytes make up a ClientHello, create a [`rustls_accepted`](#rustls-accepted) from them.\n\n **Parameters:**\n\n - `acceptor`: The [`rustls_acceptor`](#rustls-acceptor) to access.\n - `out_accepted`: An output parameter. The pointed-to pointer will be set\n to a new [`rustls_accepted`](#rustls-accepted) only when the function returns\n [`RUSTLS_RESULT_OK`](#rustls-result-ok). The memory is owned by the caller and must eventually\n be freed with [`rustls_accepted_free`](#rustls-accepted-free).\n - `out_alert`: An output parameter. The pointed-to pointer will be set\n to a new [`rustls_accepted_alert`](#rustls-accepted-alert) only when a complete ClientHello is rejected.\n [`RUSTLS_RESULT_ACCEPTOR_NOT_READY`](#rustls-result-acceptor-not-ready) and earlier errors such as a NULL parameter do not\n write it. The memory is owned by the caller and must eventually\n be freed with [`rustls_accepted_alert_free`](#rustls-accepted-alert-free). The caller should call\n [`rustls_accepted_alert_write_tls`](#rustls-accepted-alert-write-tls) to write the alert bytes to the TLS\n connection before freeing the [`rustls_accepted_alert`](#rustls-accepted-alert).\n\n The function does not initialize either output pointer. It writes at most one of\n `out_accepted` and `out_alert`. The other retains its original value.\n\n **Returns:**\n\n - [`RUSTLS_RESULT_OK`](#rustls-result-ok): a ClientHello has successfully been parsed.\n A pointer to a newly allocated [`rustls_accepted`](#rustls-accepted) has been written to\n `*out_accepted`.\n - [`RUSTLS_RESULT_ACCEPTOR_NOT_READY`](#rustls-result-acceptor-not-ready): a full ClientHello has not yet been read.\n Read more TLS bytes to continue.\n - Any other [`rustls_result`](#rustls-result): the TLS bytes read so far cannot be parsed\n as a ClientHello, and reading additional bytes won't help.\n\n **Memory and lifetimes:**\n\n After this method returns [`RUSTLS_RESULT_OK`](#rustls-result-ok), `acceptor` is\n still allocated and valid. It needs to be freed regardless of success\n or failure of this function.\n\n Calling [`rustls_acceptor_accept()`](#rustls-acceptor-accept) multiple times on the same\n [`rustls_acceptor`](#rustls-acceptor) is acceptable from a memory perspective but pointless\n from a protocol perspective.", "feature": null, "deprecation": null, "name": "rustls_acceptor_accept", @@ -276,7 +276,7 @@ }, { "anchor": "rustls-accepted-server-name", - "comment": "Get the server name indication (SNI) from the ClientHello.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n\n Returns:\n\n A rustls_str containing the SNI field.\n\n The returned value is valid until rustls_accepted_into_connection or\n rustls_accepted_free is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n This will be a zero-length rustls_str in these error cases:\n\n - The SNI contains a NUL byte.\n - The `accepted` parameter was NULL.\n - The `accepted` parameter was already transformed into a connection\n with rustls_accepted_into_connection.", + "comment": "Get the server name indication (SNI) from the ClientHello.\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to access.\n\n **Returns:**\n\n A [`rustls_str`](#rustls-str) containing the SNI field.\n\n The returned value is valid until [`rustls_accepted_into_connection`](#rustls-accepted-into-connection) or\n [`rustls_accepted_free`](#rustls-accepted-free) is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n This will be a zero-length [`rustls_str`](#rustls-str) in these error cases:\n\n - The ClientHello did not contain an SNI extension.\n - The SNI contains a NUL byte.\n - The `accepted` parameter was NULL.\n - The `accepted` parameter was already transformed into a connection\n with [`rustls_accepted_into_connection`](#rustls-accepted-into-connection).", "feature": null, "deprecation": null, "name": "rustls_accepted_server_name", @@ -284,7 +284,7 @@ }, { "anchor": "rustls-accepted-signature-scheme", - "comment": "Get the i'th in the list of signature schemes offered in the ClientHello.\n\n This is useful in selecting a server certificate when there are multiple\n available for the same server name, for instance when selecting\n between an RSA and an ECDSA certificate.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n i: Fetch the signature scheme at this offset.\n\n Returns:\n\n A TLS Signature Scheme from \n\n This will be 0 in these cases:\n - i is greater than the number of available cipher suites.\n - accepted is NULL.\n - rustls_accepted_into_connection has already been called with `accepted`.", + "comment": "Get the i-th entry in the list of signature schemes offered in the ClientHello.\n\n This is useful in selecting a server certificate when there are multiple\n available for the same server name, for instance when selecting\n between an RSA and an ECDSA certificate.\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to access.\n - `i`: Fetch the signature scheme at this offset.\n\n **Returns:**\n\n A TLS Signature Scheme from the [IANA TLS SignatureScheme registry].\n\n This will be 0 in these cases:\n\n - `i` is greater than or equal to the number of offered signature schemes.\n - `accepted` is NULL.\n - [`rustls_accepted_into_connection`](#rustls-accepted-into-connection) has already been called with `accepted`.\n\n [IANA TLS SignatureScheme registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme", "feature": null, "deprecation": null, "name": "rustls_accepted_signature_scheme", @@ -292,7 +292,7 @@ }, { "anchor": "rustls-accepted-cipher-suite", - "comment": "Get the i'th in the list of cipher suites offered in the ClientHello.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n i: Fetch the cipher suite at this offset.\n\n Returns:\n\n A cipher suite value from \n\n This will be 0 in these cases:\n - i is greater than the number of available cipher suites.\n - accepted is NULL.\n - rustls_accepted_into_connection has already been called with `accepted`.\n\n Note that 0 is technically a valid cipher suite \"TLS_NULL_WITH_NULL_NULL\",\n but this library will never support null ciphers.", + "comment": "Get the i-th entry in the list of cipher suites offered in the ClientHello.\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to access.\n - `i`: Fetch the cipher suite at this offset.\n\n **Returns:**\n\n A cipher suite value from the [IANA TLS Cipher Suites registry].\n\n This will be 0 in these cases:\n\n - `i` is greater than or equal to the number of offered cipher suites.\n - `accepted` is NULL.\n - [`rustls_accepted_into_connection`](#rustls-accepted-into-connection) has already been called with `accepted`.\n\n Note that 0 is technically a valid cipher suite \"TLS_NULL_WITH_NULL_NULL\",\n but this library will never support null ciphers.\n\n [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4", "feature": null, "deprecation": null, "name": "rustls_accepted_cipher_suite", @@ -300,7 +300,7 @@ }, { "anchor": "rustls-accepted-alpn", - "comment": "Get the i'th in the list of ALPN protocols requested in the ClientHello.\n\n accepted: The rustls_accepted to access.\n i: Fetch the ALPN value at this offset.\n\n Returns:\n\n A rustls_slice_bytes containing the i'th ALPN protocol. This may\n contain internal NUL bytes and is not guaranteed to contain valid\n UTF-8.\n\n This will be a zero-length rustls_slice bytes in these cases:\n - i is greater than the number of offered ALPN protocols.\n - The client did not offer the ALPN extension.\n - The `accepted` parameter was already transformed into a connection\n with rustls_accepted_into_connection.\n\n The returned value is valid until rustls_accepted_into_connection or\n rustls_accepted_free is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n If you are calling this from Rust, note that the `'static` lifetime\n in the return signature is fake and must not be relied upon.", + "comment": "Get the i-th entry in the list of ALPN protocols requested in the ClientHello.\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to access.\n - `i`: Fetch the ALPN value at this offset.\n\n **Returns:**\n\n A [`rustls_slice_bytes`](#rustls-slice-bytes) containing the i-th ALPN protocol. This may\n contain internal NUL bytes and is not guaranteed to contain valid\n UTF-8.\n\n This will be a zero-length [`rustls_slice_bytes`](#rustls-slice-bytes) in these cases:\n\n - `i` is greater than or equal to the number of offered ALPN protocols.\n - The client did not offer the ALPN extension.\n - The `accepted` parameter was already transformed into a connection\n with [`rustls_accepted_into_connection`](#rustls-accepted-into-connection).\n\n The returned value is valid until [`rustls_accepted_into_connection`](#rustls-accepted-into-connection) or\n [`rustls_accepted_free`](#rustls-accepted-free) is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n If you are calling this from Rust, note that the `'static` lifetime\n in the return signature is fake and must not be relied upon.", "feature": null, "deprecation": null, "name": "rustls_accepted_alpn", @@ -308,7 +308,7 @@ }, { "anchor": "rustls-accepted-into-connection", - "comment": "Turn a rustls_accepted into a rustls_connection, given the provided\n rustls_server_config.\n\n Parameters:\n\n accepted: The rustls_accepted to transform.\n config: The configuration with which to create this connection.\n out_conn: An output parameter. The pointed-to pointer will be set\n to a new rustls_connection only when the function returns\n RUSTLS_RESULT_OK.\n out_alert: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted_alert when, and only when, the function returns\n a non-OK result. The memory is owned by the caller and must eventually\n be freed with rustls_accepted_alert_free. The caller should call\n rustls_accepted_alert_write_tls to write the alert bytes to\n the TLS connection before freeing the rustls_accepted_alert.\n\n At most one of out_conn or out_alert will be set.\n\n Returns:\n\n - RUSTLS_RESULT_OK: The `accepted` parameter was successfully\n transformed into a rustls_connection, and *out_conn was written to.\n - RUSTLS_RESULT_ALREADY_USED: This function was called twice on the\n same rustls_connection.\n - RUSTLS_RESULT_NULL_PARAMETER: One of the input parameters was NULL.\n\n Memory and lifetimes:\n\n In both success and failure cases, this consumes the contents of\n `accepted` but does not free its allocated memory. In either case,\n call rustls_accepted_free to avoid a memory leak.\n\n Calling accessor methods on an `accepted` after consuming it will\n return zero or default values.\n\n The rustls_connection emitted by this function in the success case\n is owned by the caller and must eventually be freed.\n\n This function does not take ownership of `config`. It does increment\n `config`'s internal reference count, indicating that the\n rustls_connection may hold a reference to it until it is done.\n See the documentation for rustls_connection for details.", + "comment": "Turn a [`rustls_accepted`](#rustls-accepted) into a [`rustls_connection`](#rustls-connection), given the provided\n [`rustls_server_config`](#rustls-server-config).\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to transform.\n - `config`: The configuration with which to create this connection.\n - `out_conn`: An output parameter. The pointed-to pointer will be set\n to a new [`rustls_connection`](#rustls-connection) only when the function returns\n [`RUSTLS_RESULT_OK`](#rustls-result-ok). The caller owns the connection and must eventually\n free it with [`rustls_connection_free`](#rustls-connection-free).\n - `out_alert`: An output parameter. The pointed-to pointer will be set\n to a new [`rustls_accepted_alert`](#rustls-accepted-alert) when constructing the connection fails\n with a TLS error. Earlier errors, such as a NULL parameter, do not write it.\n The memory is owned by the caller and must eventually\n be freed with [`rustls_accepted_alert_free`](#rustls-accepted-alert-free). The caller should call\n [`rustls_accepted_alert_write_tls`](#rustls-accepted-alert-write-tls) to write the alert bytes to\n the TLS connection before freeing the [`rustls_accepted_alert`](#rustls-accepted-alert).\n\n The function does not initialize either output pointer. It writes at most one of\n `out_conn` and `out_alert`. The other retains its original value.\n\n **Returns:**\n\n - [`RUSTLS_RESULT_OK`](#rustls-result-ok): The `accepted` parameter was successfully\n transformed into a [`rustls_connection`](#rustls-connection), and `*out_conn` was written to.\n - [`RUSTLS_RESULT_ALREADY_USED`](#rustls-result-already-used): This function was called twice on the\n same [`rustls_accepted`](#rustls-accepted).\n - [`RUSTLS_RESULT_NULL_PARAMETER`](#rustls-result-null-parameter): One of the input parameters was NULL.\n - Any other [`rustls_result`](#rustls-result): constructing the connection failed and an alert was written\n to `out_alert`.\n\n **Memory and lifetimes:**\n\n In both success and failure cases, this consumes the contents of\n `accepted` but does not free its allocated memory. In either case,\n call [`rustls_accepted_free`](#rustls-accepted-free) to avoid a memory leak.\n\n Calling accessor methods on an `accepted` after consuming it will\n return zero or default values.\n\n This function does not take ownership of `config`. It does increment\n `config`'s internal reference count, indicating that the\n [`rustls_connection`](#rustls-connection) may hold a reference to it until it is done.\n See the documentation for [`rustls_connection`](#rustls-connection) for details.", "feature": null, "deprecation": null, "name": "rustls_accepted_into_connection", @@ -316,7 +316,7 @@ }, { "anchor": "rustls-accepted-free", - "comment": "Free a rustls_accepted.\n\n Parameters:\n\n accepted: The rustls_accepted to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_accepted`](#rustls-accepted).\n\n **Parameters:**\n\n - `accepted`: The [`rustls_accepted`](#rustls-accepted) to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_accepted_free", @@ -324,7 +324,7 @@ }, { "anchor": "rustls-accepted-alert-write-tls", - "comment": "Write some TLS bytes (an alert) to the network.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer containing TLS\n bytes to send. You don't have to write them all, just as many as you can\n in one syscall.\n\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for\n more details.", + "comment": "Write some TLS bytes (an alert) to the network.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer containing TLS\n bytes to send. You don't have to write them all, just as many as you can\n in one syscall.\n\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n On success, returns 0 and writes the number of bytes written to `out_n`.\n On error, returns an errno value passed through from `callback` and leaves\n `out_n` unchanged. See [`rustls_write_callback`](#rustls-write-callback) or rustls's [`AcceptedAlert`]\n for more details.\n\n [`AcceptedAlert`]: https://docs.rs/rustls/latest/rustls/server/struct.AcceptedAlert.html", "feature": null, "deprecation": null, "name": "rustls_accepted_alert_write_tls", @@ -332,7 +332,7 @@ }, { "anchor": "rustls-accepted-alert-free", - "comment": "Free a rustls_accepted_alert.\n\n Parameters:\n\n accepted_alert: The rustls_accepted_alert to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_accepted_alert`](#rustls-accepted-alert).\n\n **Parameters:**\n\n - `accepted_alert`: The [`rustls_accepted_alert`](#rustls-accepted-alert) to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_accepted_alert_free", @@ -340,7 +340,7 @@ }, { "anchor": "rustls-certificate-get-der", - "comment": "Get the DER data of the certificate itself.\n The data is owned by the certificate and has the same lifetime.", + "comment": "Get the certificate's DER data.\n\n On success, `out_der_data` receives a borrowed pointer and `out_der_len` receives its length.\n The data remains owned by `cert` and is valid only as long as `cert`. The caller must not\n modify or free it.\n\n On error, the output parameters are unchanged.", "feature": null, "deprecation": null, "name": "rustls_certificate_get_der", @@ -348,7 +348,7 @@ }, { "anchor": "rustls-certified-key-build", - "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a private key\n and the default process-wide crypto provider.\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key in either PKCS#1, PKCS#8 or SEC#1 format when\n using `aws-lc-rs` as the crypto provider. Supported formats may vary by\n provider.\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function does not take ownership of any of its input pointers. It\n parses the pointed-to data and makes a copy of the result. You may\n free the cert_chain and private_key pointers after calling it.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", + "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a private key\n and the default process-wide crypto provider.\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key in either PKCS#1, PKCS#8, or SEC1 format when\n using `aws-lc-rs` as the crypto provider. Supported formats may vary by\n provider.\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function does not take ownership of any of its input pointers. It\n parses the pointed-to data and makes a copy of the result. You may\n free the `cert_chain` and `private_key` buffers after calling it.\n\n `certified_key_out` is unchanged if the function returns an error.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", "feature": null, "deprecation": null, "name": "rustls_certified_key_build", @@ -356,7 +356,7 @@ }, { "anchor": "rustls-certified-key-build-with-signing-key", - "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a\n [`rustls_signing_key`](#rustls-signing-key).\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `signing_key` must point to a [`rustls_signing_key`](#rustls-signing-key) loaded using a\n [`rustls_crypto_provider`](#rustls-crypto-provider) and [`rustls_crypto_provider_load_key()`](#rustls-crypto-provider-load-key).\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function does not take ownership of any of its input pointers. It\n parses the pointed-to data and makes a copy of the result. You may\n free the cert_chain and private_key pointers after calling it.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", + "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a\n [`rustls_signing_key`](#rustls-signing-key).\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `signing_key` must point to a [`rustls_signing_key`](#rustls-signing-key) loaded using a\n [`rustls_crypto_provider`](#rustls-crypto-provider) and [`rustls_crypto_provider_load_key()`](#rustls-crypto-provider-load-key).\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function copies the `cert_chain` data and does not take ownership of\n that buffer. Once the `cert_chain` pointer has been validated, the function\n takes ownership of `signing_key`, including when a later operation returns\n an error. The caller must not use or free the signing key afterward. If\n `cert_chain` is NULL, the function returns [`RUSTLS_RESULT_NULL_PARAMETER`](#rustls-result-null-parameter)\n without consuming `signing_key`.\n\n `certified_key_out` is unchanged if the function returns an error.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", "feature": null, "deprecation": null, "name": "rustls_certified_key_build_with_signing_key", @@ -364,7 +364,7 @@ }, { "anchor": "rustls-certified-key-get-certificate", - "comment": "Return the i-th rustls_certificate in the rustls_certified_key.\n\n 0 gives the end-entity certificate. 1 and higher give certificates from the chain.\n\n Indexes higher than the last available certificate return NULL.\n\n The returned certificate is valid until the rustls_certified_key is freed.", + "comment": "Return the i-th [`rustls_certificate`](#rustls-certificate) in the [`rustls_certified_key`](#rustls-certified-key).\n\n 0 gives the end-entity certificate. 1 and higher give certificates from the chain.\n\n Indexes higher than the last available certificate return NULL.\n\n The returned certificate is valid until the [`rustls_certified_key`](#rustls-certified-key) is freed.", "feature": null, "deprecation": null, "name": "rustls_certified_key_get_certificate", @@ -372,7 +372,7 @@ }, { "anchor": "rustls-certified-key-clone-with-ocsp", - "comment": "Create a copy of the rustls_certified_key with the given OCSP response data\n as DER encoded bytes.\n\n The OCSP response may be given as NULL to clear any possibly present OCSP\n data from the cloned key.\n\n The cloned key is independent from its original and needs to be freed\n by the application.", + "comment": "Create a copy of the [`rustls_certified_key`](#rustls-certified-key) with the given OCSP response data\n as DER encoded bytes.\n\n The OCSP response may be given as NULL to clear any possibly present OCSP\n data from the cloned key.\n\n The function copies `ocsp_response` and does not take ownership of either input.\n On success, `cloned_key_out` receives an independently owned key that the caller must\n free with [`rustls_certified_key_free`](#rustls-certified-key-free). On error, `cloned_key_out` is unchanged.", "feature": null, "deprecation": null, "name": "rustls_certified_key_clone_with_ocsp", @@ -380,7 +380,7 @@ }, { "anchor": "rustls-certified-key-keys-match", - "comment": "Verify the consistency of this [`rustls_certified_key`](#rustls-certified-key)'s public and private keys.\n\n This is done by performing a comparison of subject public key information (SPKI) bytes\n between the certificate and private key.\n\n If the private key matches the certificate this function returns `RUSTLS_RESULT_OK`,\n otherwise an error [`rustls_result`](#rustls-result) is returned.", + "comment": "Verify the consistency of this [`rustls_certified_key`](#rustls-certified-key)'s public and private keys.\n\n This is done by performing a comparison of subject public key information (SPKI) bytes\n between the certificate and private key.\n\n If the private key matches the certificate this function returns [`RUSTLS_RESULT_OK`](#rustls-result-ok),\n otherwise an error [`rustls_result`](#rustls-result) is returned.", "feature": null, "deprecation": null, "name": "rustls_certified_key_keys_match", @@ -388,7 +388,7 @@ }, { "anchor": "rustls-certified-key-free", - "comment": "\"Free\" a certified_key previously returned from [`rustls_certified_key_build`](#rustls-certified-key-build).\n\n Since certified_key is actually an atomically reference-counted pointer,\n extant certified_key may still hold an internal reference to the Rust object.\n\n However, C code must consider this pointer unusable after \"free\"ing it.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Release the caller's reference to a [`rustls_certified_key`](#rustls-certified-key) previously returned from\n [`rustls_certified_key_build`](#rustls-certified-key-build).\n\n Other objects may still hold internal references to the atomically reference-counted\n Rust object. Regardless, the caller must not use `key` after this function returns.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_certified_key_free", @@ -396,7 +396,7 @@ }, { "anchor": "rustls-root-cert-store-builder-new", - "comment": "Create a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder).\n\n Caller owns the memory and may free it with [`rustls_root_cert_store_free`](#rustls-root-cert-store-free), regardless of\n whether [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build) was called.\n\n If you wish to abandon the builder without calling [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build),\n it must be freed with [`rustls_root_cert_store_builder_free`](#rustls-root-cert-store-builder-free).", + "comment": "Create a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder).\n\n The caller owns the returned builder and must eventually free it with\n [`rustls_root_cert_store_builder_free`](#rustls-root-cert-store-builder-free), whether or not\n [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build) is called.", "feature": null, "deprecation": null, "name": "rustls_root_cert_store_builder_new", @@ -404,7 +404,7 @@ }, { "anchor": "rustls-root-cert-store-builder-add-pem", - "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.", + "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.\n\n This function copies the parsed certificates and does not retain `pem`.", "feature": null, "deprecation": null, "name": "rustls_root_cert_store_builder_add_pem", @@ -412,7 +412,7 @@ }, { "anchor": "rustls-root-cert-store-builder-load-roots-from-file", - "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data read from the named file.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.", + "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data read from the named file.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.\n\n `filename` must be a NUL-terminated UTF-8 string. It is borrowed for the\n duration of the call and is not retained.", "feature": null, "deprecation": null, "name": "rustls_root_cert_store_builder_load_roots_from_file", @@ -420,7 +420,7 @@ }, { "anchor": "rustls-root-cert-store-builder-build", - "comment": "Create a new [`rustls_root_cert_store`](#rustls-root-cert-store) from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The root cert store can be used in several [`rustls_web_pki_client_cert_verifier_builder_new`](#rustls-web-pki-client-cert-verifier-builder-new)\n instances and must be freed by the application when no longer needed. See the documentation of\n [`rustls_root_cert_store_free`](#rustls-root-cert-store-free) for details about lifetime.", + "comment": "Create a new [`rustls_root_cert_store`](#rustls-root-cert-store) from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n On success, `root_cert_store_out` receives a new root certificate store. The caller owns\n it and must free it with [`rustls_root_cert_store_free`](#rustls-root-cert-store-free) when no longer needed. The store can\n be used in multiple verifier builders.", "feature": null, "deprecation": null, "name": "rustls_root_cert_store_builder_build", @@ -436,7 +436,7 @@ }, { "anchor": "rustls-root-cert-store-free", - "comment": "Free a rustls_root_cert_store previously returned from rustls_root_cert_store_builder_build.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_root_cert_store`](#rustls-root-cert-store) previously returned from\n [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build).\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_root_cert_store_free", @@ -444,7 +444,7 @@ }, { "anchor": "rustls-supported-ciphersuite-get-suite", - "comment": "Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from\n .\n\n The bytes from the assignment are interpreted in network order.", + "comment": "Return a 16-bit unsigned integer corresponding to this cipher suite's assignment\n in the [IANA TLS Cipher Suites registry].\n\n The bytes from the assignment are interpreted in network order.\n\n [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4", "feature": null, "deprecation": null, "name": "rustls_supported_ciphersuite_get_suite", @@ -460,7 +460,7 @@ }, { "anchor": "rustls-supported-ciphersuite-protocol-version", - "comment": "Returns the [`rustls_tls_version`](#rustls-tls-version) of the ciphersuite.\n\n See also `RUSTLS_ALL_VERSIONS`.", + "comment": "Returns the [`rustls_tls_version`](#rustls-tls-version) of the ciphersuite.\n\n See also [`RUSTLS_ALL_VERSIONS`](#rustls-all-versions).", "feature": null, "deprecation": null, "name": "rustls_supported_ciphersuite_protocol_version", @@ -468,7 +468,7 @@ }, { "anchor": "rustls-client-config-builder-new", - "comment": "Create a rustls_client_config_builder using the process default crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key\n exchange groups, as well as safe defaults for protocol versions.\n\n This starts out with no trusted roots. Caller must add roots with\n rustls_client_config_builder_load_roots_from_file or provide a custom verifier.", + "comment": "Create a [`rustls_client_config_builder`](#rustls-client-config-builder) using the process default crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key\n exchange groups, as well as safe defaults for protocol versions.\n\n This starts out with no trusted roots. The caller must provide a verifier with\n [`rustls_client_config_builder_set_server_verifier`](#rustls-client-config-builder-set-server-verifier) or\n [`rustls_client_config_builder_dangerous_set_certificate_verifier`](#rustls-client-config-builder-dangerous-set-certificate-verifier).", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_new", @@ -476,7 +476,7 @@ }, { "anchor": "rustls-client-config-builder-new-custom", - "comment": "Create a rustls_client_config_builder using the specified crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n `tls_version` sets the TLS protocol versions to use when negotiating a TLS session.\n `tls_version` is the version of the protocol, as defined in rfc8446,\n ch. 4.2.1 and end of ch. 5.1. Some values are defined in\n [`rustls_tls_version`](#rustls-tls-version) for convenience, and the arrays\n RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t`\n pointed to by `tls_versions`.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", + "comment": "Create a [`rustls_client_config_builder`](#rustls-client-config-builder) using the specified crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n `tls_versions` sets the TLS protocol versions to use when negotiating a\n TLS session. Each value is a protocol version as defined in RFC 8446,\n sections 4.2.1 and 5.1. Some values are defined in [`rustls_tls_version`](#rustls-tls-version)\n for convenience, and the arrays\n [`RUSTLS_DEFAULT_VERSIONS`](#rustls-default-versions) or [`RUSTLS_ALL_VERSIONS`](#rustls-all-versions) can be used directly.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t`\n pointed to by `tls_versions`.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `builder_out` receives a builder owned by the caller.\n It must eventually be passed to [`rustls_client_config_builder_build`](#rustls-client-config-builder-build) or freed with\n [`rustls_client_config_builder_free`](#rustls-client-config-builder-free). On error, `builder_out` is unchanged.\n\n The function borrows `provider` for the duration of the call and retains its own\n reference afterward.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_new_custom", @@ -484,7 +484,7 @@ }, { "anchor": "rustls-client-config-builder-dangerous-set-certificate-verifier", - "comment": "Set a custom server certificate verifier using the builder crypto provider.\n Returns rustls_result::NoDefaultCryptoProvider if no process default crypto\n provider has been set, and the builder was not constructed with an explicit\n provider choice.\n\n The callback must not capture any of the pointers in its\n rustls_verify_server_cert_params.\n If `userdata` has been set with rustls_connection_set_userdata, it\n will be passed to the callback. Otherwise the userdata param passed to\n the callback will be NULL.\n\n The callback must be safe to call on any thread at any time, including\n multiple concurrent calls. So, for instance, if the callback mutates\n userdata (or other shared state), it must use synchronization primitives\n to make such mutation safe.\n\n The callback receives certificate chain information as raw bytes.\n Currently this library offers no functions to parse the certificates,\n so you'll need to bring your own certificate parsing library\n if you need to parse them.\n\n If the custom verifier accepts the certificate, it should return\n RUSTLS_RESULT_OK. Otherwise, it may return any other rustls_result error.\n Feel free to use an appropriate error from the RUSTLS_RESULT_CERT_*\n section.\n\n ", + "comment": "Set a custom server certificate verifier using the builder crypto provider.\n Returns [`RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER`](#rustls-result-no-default-crypto-provider) if no process default crypto\n provider has been set, and the builder was not constructed with an explicit\n provider choice.\n\n The callback must not capture any of the pointers in its\n [`rustls_verify_server_cert_params`](#rustls-verify-server-cert-params).\n If `userdata` has been set with [`rustls_connection_set_userdata`](#rustls-connection-set-userdata), it\n will be passed to the callback. Otherwise the userdata param passed to\n the callback will be NULL.\n\n The callback must be safe to call on any thread at any time, including\n multiple concurrent calls. So, for instance, if the callback mutates\n userdata (or other shared state), it must use synchronization primitives\n to make such mutation safe.\n\n The callback receives certificate chain information as raw bytes.\n Currently this library offers no functions to parse the certificates,\n so you'll need to bring your own certificate parsing library\n if you need to parse them.\n\n If the custom verifier accepts the certificate, it should return\n [`RUSTLS_RESULT_OK`](#rustls-result-ok). Otherwise, it may return any other [`rustls_result`](#rustls-result) error,\n including one of the certificate-related errors.\n\n See also the rustls documentation for\n [`DangerousClientConfig::set_certificate_verifier`].\n\n [`DangerousClientConfig::set_certificate_verifier`]: https://docs.rs/rustls/latest/rustls/client/struct.DangerousClientConfig.html#method.set_certificate_verifier", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_dangerous_set_certificate_verifier", @@ -492,7 +492,7 @@ }, { "anchor": "rustls-client-config-builder-set-server-verifier", - "comment": "Configure the server certificate verifier.\n\n This increases the reference count of `verifier` and does not take ownership.", + "comment": "Configure the server certificate verifier.\n\n For the usual case of verifying servers against a custom set of root\n certificates:\n\n 1. Create a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder) with\n [`rustls_root_cert_store_builder_new`](#rustls-root-cert-store-builder-new).\n 2. Add roots with [`rustls_root_cert_store_builder_add_pem`](#rustls-root-cert-store-builder-add-pem) or\n [`rustls_root_cert_store_builder_load_roots_from_file`](#rustls-root-cert-store-builder-load-roots-from-file), then call\n [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build).\n 3. Pass the resulting store to\n [`rustls_web_pki_server_cert_verifier_builder_new`](#rustls-web-pki-server-cert-verifier-builder-new), then call\n [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build).\n 4. Pass the resulting verifier to this function.\n\n Alternatively, [`rustls_platform_server_cert_verifier`](#rustls-platform-server-cert-verifier) creates a verifier\n using the platform's certificate facilities and trust store.\n\n This function increases the reference count of `verifier` and does not\n take ownership. The caller must still free its verifier pointer with\n [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when it is no longer needed.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_server_verifier", @@ -500,7 +500,7 @@ }, { "anchor": "rustls-client-config-builder-set-alpn-protocols", - "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller) with `len`\n elements.\n\n Each element of the buffer must be a rustls_slice_bytes whose\n data field points to a single ALPN protocol ID.\n\n Standard ALPN protocol IDs are defined at\n .\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n ", + "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller) with `len`\n elements.\n\n Each element of the buffer must be a [`rustls_slice_bytes`](#rustls-slice-bytes) whose\n data field points to a single ALPN protocol ID.\n\n Standard ALPN protocol IDs are defined in the [IANA registry].\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n See also the rustls documentation for [`ClientConfig::alpn_protocols`].\n\n [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids\n [`ClientConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/client/struct.ClientConfig.html#structfield.alpn_protocols", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_alpn_protocols", @@ -508,7 +508,7 @@ }, { "anchor": "rustls-client-config-builder-set-check-selected-alpn", - "comment": "Enable or disable verifying the selected ALPN was offered.\n\n The default is `true`.\n\n ", + "comment": "Enable or disable verifying the selected ALPN was offered.\n\n The default is `true`.\n\n See also the rustls documentation for [`ClientConfig::check_selected_alpn`].\n\n [`ClientConfig::check_selected_alpn`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.check_selected_alpn", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_check_selected_alpn", @@ -516,7 +516,7 @@ }, { "anchor": "rustls-client-config-builder-set-send-ticket-request", - "comment": "Request a specific number of TLS 1.3 session tickets.\n\n This is done via the RFC 9149 `ticket_request` extension.\n\n `new_session_count` is the number of tickets desired when the server\n negotiates a new connection, and `resumption_count` the number desired\n when the server resumes using a presented ticket.\n\n By default the extension is not sent. Note that servers are free to\n ignore the request, it is only a hint.\n\n ", + "comment": "Request a specific number of TLS 1.3 session tickets.\n\n This is done via the RFC 9149 `ticket_request` extension.\n\n `new_session_count` is the number of tickets desired when the server\n negotiates a new connection, and `resumption_count` the number desired\n when the server resumes using a presented ticket.\n\n By default the extension is not sent. Note that servers are free to\n ignore the request, it is only a hint.\n\n See also the rustls documentation for [`ClientConfig::send_ticket_request`].\n\n [`ClientConfig::send_ticket_request`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.send_ticket_request", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_send_ticket_request", @@ -524,7 +524,7 @@ }, { "anchor": "rustls-client-config-builder-set-enable-sni", - "comment": "Enable or disable SNI.\n ", + "comment": "Enable or disable SNI.\n\n See also the rustls documentation for [`ClientConfig::enable_sni`].\n\n [`ClientConfig::enable_sni`]: https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html#structfield.enable_sni", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_enable_sni", @@ -540,7 +540,7 @@ }, { "anchor": "rustls-client-config-builder-set-key-log-file", - "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the NSS key log format,\n and is\n compatible with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log).", + "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the [NSS key log format] and is compatible\n with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log).\n\n [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_key_log_file", @@ -548,7 +548,7 @@ }, { "anchor": "rustls-client-config-builder-set-key-log", - "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n Rustls documentation of the `KeyLog` trait for more information on possible labels:\n \n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_client_config_builder_set_key_log_file`](#rustls-client-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.", + "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n rustls documentation for [`KeyLog::log`] for more information on possible labels.\n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_client_config_builder_set_key_log_file`](#rustls-client-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.\n\n [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_set_key_log", @@ -556,7 +556,7 @@ }, { "anchor": "rustls-client-config-builder-enable-ech", - "comment": "Configure the client for Encrypted Client Hello (ECH).\n\n This requires providing a TLS encoded list of ECH configurations that should\n have been retrieved from the DNS HTTPS record for the domain you intend to connect to.\n This should be done using DNS-over-HTTPS to avoid leaking the domain name you are\n connecting to ahead of the TLS handshake.\n\n At least one of the ECH configurations must be compatible with the provided [`rustls_hpke`](#rustls-hpke)\n instance. See [`rustls_supported_hpke()`](#rustls-supported-hpke) for more information.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n The provided `ech_config_list_bytes` and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of the ECH config list TLS bytes\n and [`rustls_hpke`](#rustls-hpke) instance. This function does not retain any reference to\n `ech_config_list_bytes`.\n\n A `RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS` error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", + "comment": "Configure the client for Encrypted Client Hello (ECH).\n\n This requires providing a TLS encoded list of ECH configurations that should\n have been retrieved from the DNS HTTPS record for the domain you intend to connect to.\n This should be done using DNS-over-HTTPS to avoid leaking the domain name you are\n connecting to ahead of the TLS handshake.\n\n At least one of the ECH configurations must be compatible with the provided [`rustls_hpke`](#rustls-hpke)\n instance. See [`rustls_supported_hpke()`](#rustls-supported-hpke) for more information.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n The provided `ech_config_list_bytes` and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of the ECH config list TLS bytes\n and [`rustls_hpke`](#rustls-hpke) instance. This function does not retain any reference to\n `ech_config_list_bytes`.\n\n A [`RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS`](#rustls-result-builder-incompatible-tls-versions) error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_enable_ech", @@ -564,7 +564,7 @@ }, { "anchor": "rustls-client-config-builder-enable-ech-grease", - "comment": "Configure the client for GREASE Encrypted Client Hello (ECH).\n\n This is a feature to prevent ossification of the TLS handshake by acting as though\n ECH were configured for an imaginary ECH config generated with one of the\n [`rustls_hpke`](#rustls-hpke) supported suites, chosen at random.\n\n The provided [`rustls_client_config_builder`](#rustls-client-config-builder) and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of both the\n [`rustls_client_config_builder`](#rustls-client-config-builder) and the [`rustls_hpke`](#rustls-hpke) instance.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n A `RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS` error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", + "comment": "Configure the client for GREASE Encrypted Client Hello (ECH).\n\n This is a feature to prevent ossification of the TLS handshake by acting as though\n ECH were configured for an imaginary ECH config generated with one of the\n [`rustls_hpke`](#rustls-hpke) supported suites, chosen at random.\n\n The provided [`rustls_client_config_builder`](#rustls-client-config-builder) and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of both the\n [`rustls_client_config_builder`](#rustls-client-config-builder) and the [`rustls_hpke`](#rustls-hpke) instance.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n A [`RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS`](#rustls-result-builder-incompatible-tls-versions) error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_enable_ech_grease", @@ -572,7 +572,7 @@ }, { "anchor": "rustls-client-config-builder-build", - "comment": "Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config\n (read-only).", + "comment": "Turn a mutable [`rustls_client_config_builder`](#rustls-client-config-builder) into a const [`rustls_client_config`](#rustls-client-config)\n (read-only).\n\n This function takes ownership of `builder`. The caller must not use or free the builder\n after calling this function, regardless of the result.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `config_out` receives a config owned by the caller, which must\n eventually be freed with [`rustls_client_config_free`](#rustls-client-config-free). On error, `config_out` is unchanged.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_build", @@ -580,7 +580,7 @@ }, { "anchor": "rustls-client-config-builder-free", - "comment": "\"Free\" a client_config_builder without building it into a rustls_client_config.\n\n Normally builders are built into rustls_client_config via [`rustls_client_config_builder_build`](#rustls-client-config-builder-build)\n and may not be free'd or otherwise used afterwards.\n\n Use free only when the building of a config has to be aborted before a config\n was created.", + "comment": "Free a [`rustls_client_config_builder`](#rustls-client-config-builder) without building it into a\n [`rustls_client_config`](#rustls-client-config).\n\n Do not call this after [`rustls_client_config_builder_build`](#rustls-client-config-builder-build), which consumes and frees the\n builder. Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_client_config_builder_free", @@ -596,7 +596,7 @@ }, { "anchor": "rustls-client-config-free", - "comment": "\"Free\" a [`rustls_client_config`](#rustls-client-config) previously returned from\n [`rustls_client_config_builder_build`](#rustls-client-config-builder-build).\n\n Since [`rustls_client_config`](#rustls-client-config) is actually an atomically reference-counted pointer,\n extant client connections may still hold an internal reference to the Rust object.\n\n However, C code must consider this pointer unusable after \"free\"ing it.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Release the caller's reference to a [`rustls_client_config`](#rustls-client-config) previously returned from\n [`rustls_client_config_builder_build`](#rustls-client-config-builder-build).\n\n Existing client connections may still hold internal references to the atomically\n reference-counted Rust object. Regardless, the caller must not use `config` after this\n function returns.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_client_config_free", @@ -604,7 +604,7 @@ }, { "anchor": "rustls-client-connection-new", - "comment": "Create a new client [`rustls_connection`](#rustls-connection).\n\n If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n This function copies the contents of `server_name`.\n\n Uses the [`rustls_client_config`](#rustls-client-config) to determine ALPN protocol support. Prefer\n [`rustls_client_connection_new_alpn`](#rustls-client-connection-new-alpn) to customize this per-connection.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types.", + "comment": "Create a new client [`rustls_connection`](#rustls-connection).\n\n If this returns [`RUSTLS_RESULT_OK`](#rustls-result-ok), the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n This function copies the contents of `server_name`.\n\n The connection retains an internal reference to `config`. This function\n does not take ownership of the caller's config pointer.\n\n Uses the [`rustls_client_config`](#rustls-client-config) to determine ALPN protocol support. Prefer\n [`rustls_client_connection_new_alpn`](#rustls-client-connection-new-alpn) to customize this per-connection.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types. It must be NUL-terminated.", "feature": null, "deprecation": null, "name": "rustls_client_connection_new", @@ -612,7 +612,7 @@ }, { "anchor": "rustls-client-connection-new-alpn", - "comment": "Create a new client [`rustls_connection`](#rustls-connection) with custom ALPN protocols.\n\n Operates the same as [`rustls_client_connection_new`](#rustls-client-connection-new), but allows specifying\n custom per-connection ALPN protocols instead of inheriting ALPN protocols\n from the `rustls_clinet_config`.\n\n If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n This function copies the contents of `server_name`.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types.\n\n `alpn_protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `alpn_protocols_len` elements. Each element of the buffer must be a [`rustls_slice_bytes`](#rustls-slice-bytes)\n whose data field points to a single ALPN protocol ID. This function makes a copy of the\n data in `alpn_protocols` and does not retain any pointers, so the caller can free the\n pointed-to memory after calling.\n\n Standard ALPN protocol IDs are defined at\n .", + "comment": "Create a new client [`rustls_connection`](#rustls-connection) with custom ALPN protocols.\n\n Operates the same as [`rustls_client_connection_new`](#rustls-client-connection-new), but allows specifying\n custom per-connection ALPN protocols instead of inheriting ALPN protocols\n from the [`rustls_client_config`](#rustls-client-config).\n\n If this returns [`RUSTLS_RESULT_OK`](#rustls-result-ok), the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n This function copies the contents of `server_name`.\n\n The connection retains an internal reference to `config`. This function\n does not take ownership of the caller's config pointer.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types. It must be NUL-terminated.\n\n `alpn_protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `alpn_protocols_len` elements. Each element of the buffer must be a [`rustls_slice_bytes`](#rustls-slice-bytes)\n whose data field points to a single ALPN protocol ID. This function makes a copy of the\n data in `alpn_protocols` and does not retain any pointers, so the caller can free the\n pointed-to memory after calling.\n\n Standard ALPN protocol IDs are defined in the [IANA registry].\n\n [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids", "feature": null, "deprecation": null, "name": "rustls_client_connection_new_alpn", @@ -620,7 +620,7 @@ }, { "anchor": "rustls-connection-set-userdata", - "comment": "Set the userdata pointer associated with this connection. This will be passed\n to any callbacks invoked by the connection, if you've set up callbacks in the config.\n The pointed-to data must outlive the connection.", + "comment": "Set the userdata pointer associated with this connection. This will be passed\n to any callbacks invoked by the connection, if you've set up callbacks in the config.\n\n The pointed-to data must remain valid until the userdata is replaced or the connection\n is freed. Rustls does not take ownership of the data and will not free it.", "feature": null, "deprecation": null, "name": "rustls_connection_set_userdata", @@ -628,7 +628,7 @@ }, { "anchor": "rustls-connection-set-log-callback", - "comment": "Set the logging callback for this connection. The log callback will be invoked\n with the userdata parameter previously set by rustls_connection_set_userdata, or\n NULL if no userdata was set.", + "comment": "Set the logging callback for this connection. The log callback will be invoked\n with the userdata parameter previously set by [`rustls_connection_set_userdata`](#rustls-connection-set-userdata), or\n NULL if no userdata was set.", "feature": null, "deprecation": null, "name": "rustls_connection_set_log_callback", @@ -636,7 +636,7 @@ }, { "anchor": "rustls-connection-read-tls", - "comment": "Read some TLS bytes from the network into internal buffers. The actual network\n I/O is performed by `callback`, which you provide. Rustls will invoke your\n callback with a suitable buffer to store the read bytes into. You don't have\n to fill it up, just fill with as many bytes as you get in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_read_callback for more details.\n ", + "comment": "Read some TLS bytes from the network into internal buffers. The actual network\n I/O is performed by `callback`, which you provide. Rustls will invoke your\n callback with a suitable buffer to store the read bytes into. You don't have\n to fill it up, just fill with as many bytes as you get in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n On success, returns 0 and writes the number of bytes read to `out_n`. On error, returns\n an errno value passed through from `callback` and leaves `out_n` unchanged. See\n [`rustls_read_callback`](#rustls-read-callback) for more details.\n\n See also the rustls documentation for [`Connection::read_tls`].\n\n [`Connection::read_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.read_tls", "feature": null, "deprecation": null, "name": "rustls_connection_read_tls", @@ -644,7 +644,7 @@ }, { "anchor": "rustls-connection-write-tls", - "comment": "Write some TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with a\n suitable buffer containing TLS bytes to send. You don't have to write them\n all, just as many as you can in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_write_callback for more details.\n ", + "comment": "Write some TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with a\n suitable buffer containing TLS bytes to send. You don't have to write them\n all, just as many as you can in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n On success, returns 0 and writes the number of bytes written to `out_n`. On error,\n returns an errno value passed through from `callback` and leaves `out_n` unchanged.\n See [`rustls_write_callback`](#rustls-write-callback) for more details.\n\n See also the rustls documentation for [`Connection::write_tls`].\n\n [`Connection::write_tls`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.write_tls", "feature": null, "deprecation": null, "name": "rustls_connection_write_tls", @@ -652,7 +652,7 @@ }, { "anchor": "rustls-connection-write-tls-vectored", - "comment": "Write all available TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with an array\n of rustls_slice_bytes, each containing a buffer with TLS bytes to send.\n You don't have to write them all, just as many as you are willing.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_write_callback for more details.\n ", + "comment": "Write all available TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with an array\n of [`rustls_slice_bytes`](#rustls-slice-bytes), each containing a buffer with TLS bytes to send.\n You don't have to write them all, just as many as you are willing.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n On success, returns 0 and writes the number of bytes written to `out_n`. On error,\n returns an errno value passed through from `callback` and leaves `out_n` unchanged.\n See [`rustls_write_vectored_callback`](#rustls-write-vectored-callback) for more details.\n\n See also the rustls documentation for [`Writer::write_vectored`].\n\n [`Writer::write_vectored`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write_vectored", "feature": null, "deprecation": null, "name": "rustls_connection_write_tls_vectored", @@ -660,7 +660,7 @@ }, { "anchor": "rustls-connection-process-new-packets", - "comment": "Decrypt any available ciphertext from the internal buffer and put it\n into the internal plaintext buffer, potentially making bytes available\n for rustls_connection_read().\n ", + "comment": "Decrypt any available ciphertext from the internal buffer and put it\n into the internal plaintext buffer, potentially making bytes available\n for [`rustls_connection_read()`](#rustls-connection-read).\n\n See also the rustls documentation for [`Connection::process_new_packets`].\n\n [`Connection::process_new_packets`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.process_new_packets", "feature": null, "deprecation": null, "name": "rustls_connection_process_new_packets", @@ -668,7 +668,7 @@ }, { "anchor": "rustls-connection-wants-read", - "comment": "", + "comment": "See also the rustls documentation for [`CommonState::wants_read`].\n\n [`CommonState::wants_read`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_read", "feature": null, "deprecation": null, "name": "rustls_connection_wants_read", @@ -676,7 +676,7 @@ }, { "anchor": "rustls-connection-wants-write", - "comment": "", + "comment": "See also the rustls documentation for [`CommonState::wants_write`].\n\n [`CommonState::wants_write`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_write", "feature": null, "deprecation": null, "name": "rustls_connection_wants_write", @@ -684,7 +684,7 @@ }, { "anchor": "rustls-connection-is-handshaking", - "comment": "Returns true if the connection is currently performing the TLS handshake.\n\n Note: This may return `false` while there are still handshake packets waiting\n to be extracted and transmitted with [`rustls_connection_write_tls()`](#rustls-connection-write-tls).\n\n See the rustls documentation for more information.\n\n ", + "comment": "Returns true if the connection is currently performing the TLS handshake.\n\n Note: This may return `false` while there are still handshake packets waiting\n to be extracted and transmitted with [`rustls_connection_write_tls()`](#rustls-connection-write-tls).\n\n See also the rustls documentation for [`CommonState::is_handshaking`].\n\n [`CommonState::is_handshaking`]: https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.is_handshaking", "feature": null, "deprecation": null, "name": "rustls_connection_is_handshaking", @@ -700,15 +700,15 @@ }, { "anchor": "rustls-connection-set-buffer-limit", - "comment": "Sets a limit on the internal buffers used to buffer unsent plaintext (prior\n to completing the TLS handshake) and unsent TLS records. By default, there\n is no limit. The limit can be set at any time, even if the current buffer\n use is higher.\n ", + "comment": "Sets a limit on the internal buffers used to buffer unsent plaintext (prior\n to completing the TLS handshake) and unsent TLS records. By default, there\n is no limit. The limit can be set at any time, even if the current buffer\n use is higher.\n\n See also the rustls documentation for [`Connection::set_buffer_limit`].\n\n [`Connection::set_buffer_limit`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.set_buffer_limit", "feature": null, "deprecation": null, "name": "rustls_connection_set_buffer_limit", - "text": "```c\nvoid rustls_connection_set_buffer_limit(struct rustls_connection *conn, size_t n);\n```" + "text": "```c\nvoid rustls_connection_set_buffer_limit(struct rustls_connection *conn,\n size_t n);\n```" }, { "anchor": "rustls-connection-send-close-notify", - "comment": "Queues a close_notify fatal alert to be sent in the next write_tls call.\n ", + "comment": "Queues a close_notify alert to be sent by the next call to\n [`rustls_connection_write_tls()`](#rustls-connection-write-tls).\n\n See also the rustls documentation for [`Connection::send_close_notify`].\n\n [`Connection::send_close_notify`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.send_close_notify", "feature": null, "deprecation": null, "name": "rustls_connection_send_close_notify", @@ -716,7 +716,7 @@ }, { "anchor": "rustls-connection-refresh-traffic-keys", - "comment": "Queues a TLS1.3 key_update message to refresh a connection’s keys.\n\n Rustls internally manages key updates as required and so this function should\n seldom be used. See the Rustls documentation for important caveats and suggestions\n on occasions that merit its use.\n\n ", + "comment": "Queues a TLS1.3 key_update message to refresh a connection’s keys.\n\n Rustls internally manages key updates as required and so this function should\n seldom be used. See the rustls documentation for\n [`ConnectionCommon::refresh_traffic_keys`] for important caveats and suggestions\n on occasions that merit its use.\n\n [`ConnectionCommon::refresh_traffic_keys`]: https://docs.rs/rustls/latest/rustls/struct.ConnectionCommon.html#method.refresh_traffic_keys", "feature": null, "deprecation": null, "name": "rustls_connection_refresh_traffic_keys", @@ -724,7 +724,7 @@ }, { "anchor": "rustls-connection-get-peer-certificate", - "comment": "Return the i-th certificate provided by the peer.\n Index 0 is the end entity certificate. Higher indexes are certificates\n in the chain. Requesting an index higher than what is available returns\n NULL.\n The returned pointer is valid until the next mutating function call\n affecting the connection. A mutating function call is one where the\n first argument has type `struct rustls_connection *` (as opposed to\n `const struct rustls_connection *`).\n ", + "comment": "Return the i-th certificate provided by the peer.\n Index 0 is the end entity certificate. Higher indexes are certificates\n in the chain. Requesting an out-of-range index returns NULL.\n\n The returned pointer is valid until the next mutating function call\n affecting the connection. A mutating function call is one where the first\n argument is a mutable pointer to [`rustls_connection`](#rustls-connection) (as opposed to a const\n pointer).\n\n See also the rustls documentation for [`Connection::peer_certificates`].\n\n [`Connection::peer_certificates`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.peer_certificates", "feature": null, "deprecation": null, "name": "rustls_connection_get_peer_certificate", @@ -732,7 +732,7 @@ }, { "anchor": "rustls-connection-get-alpn-protocol", - "comment": "Get the ALPN protocol that was negotiated, if any. Stores a pointer to a\n borrowed buffer of bytes, and that buffer's len, in the output parameters.\n The borrow lives as long as the connection.\n If the connection is still handshaking, or no ALPN protocol was negotiated,\n stores NULL and 0 in the output parameters.\n The provided pointer is valid until the next mutating function call\n affecting the connection. A mutating function call is one where the\n first argument has type `struct rustls_connection *` (as opposed to\n `const struct rustls_connection *`).\n \n ", + "comment": "Get the ALPN protocol that was negotiated, if any. Stores a pointer to a\n borrowed buffer of bytes, and that buffer's length, in the output parameters.\n If the connection is still handshaking, or no ALPN protocol was negotiated,\n stores NULL and 0 in the output parameters.\n\n The borrowed buffer is owned by the connection and is valid until the next\n mutating function call affecting the connection. A mutating function call\n is one where the first argument is a mutable pointer to\n [`rustls_connection`](#rustls-connection) (as opposed to a const pointer).\n The caller must not modify or free the borrowed buffer.\n\n If `conn` or either output parameter is NULL, both output values are unchanged.\n Protocol identifiers are listed in the [IANA TLS Parameters registry]. See\n also the rustls documentation for [`Connection::alpn_protocol`].\n\n [IANA TLS Parameters registry]: https://www.iana.org/assignments/tls-parameters/\n [`Connection::alpn_protocol`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.alpn_protocol", "feature": null, "deprecation": null, "name": "rustls_connection_get_alpn_protocol", @@ -740,7 +740,7 @@ }, { "anchor": "rustls-connection-get-protocol-version", - "comment": "Return the TLS protocol version that has been negotiated. Before this\n has been decided during the handshake, this will return 0. Otherwise,\n the u16 version number as defined in the relevant RFC is returned.\n \n ", + "comment": "Return the TLS protocol version that has been negotiated. Before this\n has been decided during the handshake, this will return 0. Otherwise,\n the u16 version number as defined in the relevant RFC is returned.\n\n See also the rustls documentation for [`Connection::protocol_version`] and\n [`ProtocolVersion`].\n\n [`Connection::protocol_version`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.protocol_version\n [`ProtocolVersion`]: https://docs.rs/rustls/latest/rustls/internal/msgs/enums/enum.ProtocolVersion.html", "feature": null, "deprecation": null, "name": "rustls_connection_get_protocol_version", @@ -748,7 +748,7 @@ }, { "anchor": "rustls-connection-get-negotiated-ciphersuite", - "comment": "Retrieves the [IANA registered cipher suite identifier][IANA] agreed with the peer.\n\n This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed.\n\n [IANA]: ", + "comment": "Retrieves the [IANA registered cipher suite identifier] agreed with the peer.\n\n This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed.\n\n [IANA registered cipher suite identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4", "feature": null, "deprecation": null, "name": "rustls_connection_get_negotiated_ciphersuite", @@ -756,7 +756,7 @@ }, { "anchor": "rustls-connection-get-negotiated-ciphersuite-name", - "comment": "Retrieves the cipher suite name agreed with the peer.\n\n This returns \"\" until the ciphersuite is agreed.\n\n The lifetime of the [`rustls_str`](#rustls-str) is the lifetime of the program, it does not\n need to be freed.\n\n ", + "comment": "Retrieves the cipher suite name agreed with the peer.\n\n This returns \"\" until the ciphersuite is agreed.\n\n The lifetime of the [`rustls_str`](#rustls-str) is the lifetime of the program, it does not\n need to be freed.\n\n See also the rustls documentation for [`Connection::negotiated_cipher_suite`].\n\n [`Connection::negotiated_cipher_suite`]: https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.negotiated_cipher_suite", "feature": null, "deprecation": null, "name": "rustls_connection_get_negotiated_ciphersuite_name", @@ -764,7 +764,7 @@ }, { "anchor": "rustls-connection-get-negotiated-key-exchange-group", - "comment": "Retrieves the [IANA registered supported group identifier][IANA] agreed with the peer.\n\n This returns Reserved (0x0000) until the key exchange group is agreed.\n\n [IANA]: ", + "comment": "Retrieves the [IANA registered supported group identifier] agreed with the peer.\n\n This returns Reserved (0x0000) until the key exchange group is agreed.\n\n [IANA registered supported group identifier]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8", "feature": null, "deprecation": null, "name": "rustls_connection_get_negotiated_key_exchange_group", @@ -788,7 +788,7 @@ }, { "anchor": "rustls-connection-write", - "comment": "Write up to `count` plaintext bytes from `buf` into the [`rustls_connection`](#rustls-connection).\n This will increase the number of output bytes available to\n [`rustls_connection_write_tls`](#rustls-connection-write-tls).\n On success, store the number of bytes actually written in *out_n\n (this may be less than `count`).\n ", + "comment": "Write up to `count` plaintext bytes from `buf` into the [`rustls_connection`](#rustls-connection).\n This will increase the number of output bytes available to\n [`rustls_connection_write_tls`](#rustls-connection-write-tls).\n On success, store the number of bytes actually written in `*out_n`\n (this may be less than `count`).\n\n This function borrows `buf` for the duration of the call and does not retain it.\n On error, `out_n` is unchanged.\n\n See also the rustls documentation for [`Writer::write`].\n\n [`Writer::write`]: https://docs.rs/rustls/latest/rustls/struct.Writer.html#method.write", "feature": null, "deprecation": null, "name": "rustls_connection_write", @@ -796,7 +796,7 @@ }, { "anchor": "rustls-connection-read", - "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in *out_n (this may be less\n than `count`). A success with *out_n set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to rustls_connection_read_tls and\n rustls_connection_process_new_packets.\"\n\n Subtle note: Even though this function only writes to `buf` and does not\n read from it, the memory in `buf` must be initialized before the call (for\n Rust-internal reasons). Initializing a buffer once and then using it\n multiple times without zeroizing before each call is fine.\n ", + "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in `*out_n` (this may be less\n than `count`). A success with `*out_n` set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to [`rustls_connection_read_tls`](#rustls-connection-read-tls) and\n [`rustls_connection_process_new_packets`](#rustls-connection-process-new-packets).\n\n Subtle note: Even though this function only writes to `buf` and does not\n read from it, the memory in `buf` must be initialized before the call (for\n Rust-internal reasons). Initializing a buffer once and then using it\n multiple times without zeroizing before each call is fine.\n\n The function does not retain `buf`. On error, `out_n` is unchanged.\n\n See also the rustls documentation for [`Reader::read`].\n\n [`Reader::read`]: https://docs.rs/rustls/latest/rustls/struct.Reader.html#method.read", "feature": null, "deprecation": null, "name": "rustls_connection_read", @@ -804,7 +804,7 @@ }, { "anchor": "rustls-connection-read-2", - "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in *out_n (this may be less\n than `count`). A success with *out_n set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to rustls_connection_read_tls and\n rustls_connection_process_new_packets.\"\n\n This experimental API is only available when using a nightly Rust compiler\n and enabling the `read_buf` Cargo feature. It will be deprecated and later\n removed in future versions.\n\n Unlike with [`rustls_connection_read`](#rustls-connection-read), this function may be called with `buf`\n pointing to an uninitialized memory buffer.", + "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in `*out_n` (this may be less\n than `count`). A success with `*out_n` set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to [`rustls_connection_read_tls`](#rustls-connection-read-tls) and\n [`rustls_connection_process_new_packets`](#rustls-connection-process-new-packets).\n\n This experimental API is only available when using a nightly Rust compiler\n and enabling the `read_buf` Cargo feature. It will be deprecated and later\n removed in future versions.\n\n Unlike with [`rustls_connection_read`](#rustls-connection-read), this function may be called with `buf`\n pointing to an uninitialized memory buffer.\n\n The function does not retain `buf`. On error, `out_n` is unchanged.", "feature": "read_buf", "deprecation": null, "name": "rustls_connection_read_2", @@ -820,7 +820,7 @@ }, { "anchor": "rustls-connection-free", - "comment": "Free a rustls_connection. Calling with NULL is fine.\n Must not be called twice with the same value.", + "comment": "Free a [`rustls_connection`](#rustls-connection). Calling with NULL is fine.\n Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_connection_free", @@ -828,7 +828,7 @@ }, { "anchor": "rustls-crypto-provider-builder-new-from-default", - "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the process-wide default crypto\n provider as the base crypto provider to be customized.\n\n When this function returns `rustls_result::Ok` a pointer to the [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder)\n is written to `builder_out`. It returns `rustls_result::NoDefaultCryptoProvider` if no default\n provider has been registered.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n This function is typically used for customizing the default crypto provider for specific\n connections. For example, a typical workflow might be to:\n\n * Either:\n * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is built with based on\n the `CRYPTO_PROVIDER` build variable.\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with the desired provider, and\n then install it as the process default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n * Afterward, as required for customization:\n * Use [`rustls_crypto_provider_builder_new_from_default`](#rustls-crypto-provider-builder-new-from-default) to get a builder backed by the\n default crypto provider.\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", + "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the process-wide default crypto\n provider as the base crypto provider to be customized.\n\n When this function returns [`RUSTLS_RESULT_OK`](#rustls-result-ok), a pointer to the\n [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) is written to `builder_out`. It returns\n [`RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER`](#rustls-result-no-default-crypto-provider) if no default provider has been registered.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n On error, `builder_out` is unchanged.\n\n This function is typically used for customizing the default crypto provider for specific\n connections. For example, a typical workflow might be to:\n\n * Either:\n * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is built with based on\n the `CRYPTO_PROVIDER` build variable.\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with the desired provider, and\n then install it as the process default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n * Afterward, as required for customization:\n * Use [`rustls_crypto_provider_builder_new_from_default`](#rustls-crypto-provider-builder-new-from-default) to get a builder backed by the\n default crypto provider.\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_builder_new_from_default", @@ -836,7 +836,7 @@ }, { "anchor": "rustls-crypto-provider-builder-new-with-base", - "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the given [`rustls_crypto_provider`](#rustls-crypto-provider)\n as the base crypto provider to be customized.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n This function can be used for setting the default process wide crypto provider,\n or for constructing a custom crypto provider for a specific connection. A typical\n workflow could be to:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Install the custom provider as the process-wide default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n\n Or, for per-connection customization:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", + "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the given [`rustls_crypto_provider`](#rustls-crypto-provider)\n as the base crypto provider to be customized.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n This function does not take ownership of `base`. The builder retains its own\n reference.\n\n This function can be used for setting the default process wide crypto provider,\n or for constructing a custom crypto provider for a specific connection. A typical\n workflow could be to:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Install the custom provider as the process-wide default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n\n Or, for per-connection customization:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_builder_new_with_base", @@ -852,7 +852,7 @@ }, { "anchor": "rustls-crypto-provider-builder-build", - "comment": "Builds a [`rustls_crypto_provider`](#rustls-crypto-provider) from the builder and returns it. Returns an error if the\n builder has already been built.\n\n The [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) builder is consumed and should not be used\n for further calls, except to [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free). The caller must\n still free the builder after a successful build.", + "comment": "Builds a [`rustls_crypto_provider`](#rustls-crypto-provider) from the builder and returns it. Returns an error if the\n builder has already been built.\n\n The [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) builder is consumed and should not be used\n for further calls, except to [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free). The caller must\n still free the builder after a successful build.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `provider_out` receives a provider owned by the caller, which must\n eventually be freed with [`rustls_crypto_provider_free`](#rustls-crypto-provider-free). On error, `provider_out` is unchanged.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_builder_build", @@ -900,7 +900,7 @@ }, { "anchor": "rustls-crypto-provider-default", - "comment": "Retrieve a pointer to the process default [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This may return `NULL` if no process default provider has been set using\n `rustls_crypto_provider_builder_build_default`.\n\n Caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it w/ [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).", + "comment": "Retrieve a pointer to the process default [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This may return `NULL` if no process default provider has been set using\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n\n The caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it with\n [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_default", @@ -908,7 +908,7 @@ }, { "anchor": "rustls-crypto-provider-ciphersuites-len", - "comment": "Returns the number of ciphersuites the [`rustls_crypto_provider`](#rustls-crypto-provider) supports.\n\n You can use this to know the maximum allowed index for use with\n [`rustls_crypto_provider_ciphersuites_get`](#rustls-crypto-provider-ciphersuites-get).\n\n This function will return 0 if the `provider` is NULL.", + "comment": "Returns the number of cipher suites the [`rustls_crypto_provider`](#rustls-crypto-provider) supports.\n\n Valid indices for [`rustls_crypto_provider_ciphersuites_get`](#rustls-crypto-provider-ciphersuites-get) range from 0 (inclusive) to the\n returned length (exclusive).\n\n This function will return 0 if the `provider` is NULL.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_ciphersuites_len", @@ -916,7 +916,7 @@ }, { "anchor": "rustls-crypto-provider-ciphersuites-get", - "comment": "Retrieve a pointer to a supported ciphersuite of the [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This function will return NULL if the `provider` is NULL, or if the index is out of bounds\n with respect to [`rustls_crypto_provider_ciphersuites_len`](#rustls-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is equal to the lifetime of the\n `provider` and should not be used after the `provider` is freed.", + "comment": "Retrieve a pointer to a supported cipher suite of the [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This function will return NULL if the `provider` is NULL, or if the index is out of bounds\n with respect to [`rustls_crypto_provider_ciphersuites_len`](#rustls-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is equal to the lifetime of the\n `provider` and should not be used after the `provider` is freed. The returned pointer is\n borrowed and must not be freed.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_ciphersuites_get", @@ -924,7 +924,7 @@ }, { "anchor": "rustls-crypto-provider-load-key", - "comment": "Load a private key from the provided PEM content using the crypto provider.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key. The exact formats supported will differ based on\n the crypto provider in use. The default providers support PKCS#1, PKCS#8 or\n SEC1 formats.\n\n When this function returns `rustls_result::Ok` a pointer to a [`rustls_signing_key`](#rustls-signing-key)\n is written to `signing_key_out`. The caller owns the returned [`rustls_signing_key`](#rustls-signing-key)\n and must free it with [`rustls_signing_key_free`](#rustls-signing-key-free).", + "comment": "Load a private key from the provided PEM content using the crypto provider.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key. The exact formats supported will differ based on\n the crypto provider in use. The default providers support PKCS#1, PKCS#8 or\n SEC1 formats.\n\n When this function returns [`RUSTLS_RESULT_OK`](#rustls-result-ok), a pointer to a [`rustls_signing_key`](#rustls-signing-key)\n is written to `signing_key_out`. The caller owns the returned [`rustls_signing_key`](#rustls-signing-key)\n and must free it with [`rustls_signing_key_free`](#rustls-signing-key-free).\n\n The function copies the private key data and does not retain `private_key`. On error,\n `signing_key_out` is unchanged.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_load_key", @@ -932,7 +932,7 @@ }, { "anchor": "rustls-crypto-provider-random", - "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure.", + "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns [`RUSTLS_RESULT_OK`](#rustls-result-ok) on success, or [`RUSTLS_RESULT_GET_RANDOM_FAILED`](#rustls-result-get-random-failed) on failure.", "feature": null, "deprecation": null, "name": "rustls_crypto_provider_random", @@ -956,7 +956,7 @@ }, { "anchor": "rustls-default-crypto-provider-ciphersuites-len", - "comment": "Returns the number of ciphersuites the default process-wide crypto provider supports.\n\n You can use this to know the maximum allowed index for use with\n [`rustls_default_crypto_provider_ciphersuites_get`](#rustls-default-crypto-provider-ciphersuites-get).\n\n This function will return 0 if no process-wide default [`rustls_crypto_provider`](#rustls-crypto-provider) is available.", + "comment": "Returns the number of cipher suites the default process-wide crypto provider supports.\n\n Valid indices for [`rustls_default_crypto_provider_ciphersuites_get`](#rustls-default-crypto-provider-ciphersuites-get) range from 0 (inclusive)\n to the returned length (exclusive).\n\n This function will return 0 if no process-wide default [`rustls_crypto_provider`](#rustls-crypto-provider) is available.", "feature": null, "deprecation": null, "name": "rustls_default_crypto_provider_ciphersuites_len", @@ -964,7 +964,7 @@ }, { "anchor": "rustls-default-crypto-provider-ciphersuites-get", - "comment": "Retrieve a pointer to a supported ciphersuite of the default process-wide crypto provider.\n\n This function will return NULL if the `provider` is NULL, or if the index is out of bounds\n with respect to [`rustls_default_crypto_provider_ciphersuites_len`](#rustls-default-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is static, as the process-wide\n default provider lives for as long as the process.", + "comment": "Retrieve a pointer to a supported cipher suite of the default process-wide crypto provider.\n\n This function returns NULL if no process-wide default provider is available or if `index` is\n out of bounds with respect to [`rustls_default_crypto_provider_ciphersuites_len`](#rustls-default-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is static, as the process-wide\n default provider lives for as long as the process. The returned pointer is borrowed and must\n not be freed.", "feature": null, "deprecation": null, "name": "rustls_default_crypto_provider_ciphersuites_get", @@ -972,7 +972,7 @@ }, { "anchor": "rustls-default-crypto-provider-random", - "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the process-wide\n default crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns `RUSTLS_RESULT_OK` on success, and one of `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER`\n or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure.", + "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the process-wide\n default crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns [`RUSTLS_RESULT_OK`](#rustls-result-ok) on success, and one of [`RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER`](#rustls-result-no-default-crypto-provider)\n or [`RUSTLS_RESULT_GET_RANDOM_FAILED`](#rustls-result-get-random-failed) on failure.", "feature": null, "deprecation": null, "name": "rustls_default_crypto_provider_random", @@ -1004,7 +1004,7 @@ }, { "anchor": "rustls-error", - "comment": "After a rustls function returns an error, you may call\n this to get a pointer to a buffer containing a detailed error\n message.\n\n The contents of the error buffer will be out_n bytes long,\n UTF-8 encoded, and not NUL-terminated.", + "comment": "After a rustls function returns an error, you may call this to write a detailed error\n message into the caller-provided `buf`.\n\n This writes at most `len` bytes and stores the number written in `out_n`. If the full\n message is longer than `len`, it is truncated. The output is UTF-8 encoded and is not\n NUL-terminated.\n\n If `buf` or `out_n` is NULL, this function does nothing. The caller retains ownership of\n `buf`, and the function does not retain it.", "feature": null, "deprecation": null, "name": "rustls_error", @@ -1012,7 +1012,7 @@ }, { "anchor": "rustls-result-is-cert-error", - "comment": "Returns true if the `result` is a certificate related error.", + "comment": "Returns true if the `result` is a certificate-related error.", "feature": null, "deprecation": null, "name": "rustls_result_is_cert_error", @@ -1020,7 +1020,7 @@ }, { "anchor": "rustls-log-level-str", - "comment": "Return a rustls_str containing the stringified version of a log level.", + "comment": "Return a [`rustls_str`](#rustls-str) containing the stringified version of a log level.\n\n The returned string has static lifetime and does not need to be freed.", "feature": null, "deprecation": null, "name": "rustls_log_level_str", @@ -1036,7 +1036,7 @@ }, { "anchor": "rustls-slice-slice-bytes-get", - "comment": "Retrieve the nth element from the input slice of slices.\n\n If the input pointer is NULL, or n is greater than the length\n of the [`rustls_slice_slice_bytes`](#rustls-slice-slice-bytes), returns rustls_slice_bytes{NULL, 0}.", + "comment": "Retrieve the nth element from the input slice of slices.\n\n If the input pointer is NULL, or `n` is greater than or equal to the length\n of the [`rustls_slice_slice_bytes`](#rustls-slice-slice-bytes), returns a [`rustls_slice_bytes`](#rustls-slice-bytes) with a NULL data pointer\n and a length of 0.\n\n Otherwise, the returned byte slice borrows its data from `input`. It remains valid for the\n same lifetime as `input` and must not be freed.", "feature": null, "deprecation": null, "name": "rustls_slice_slice_bytes_get", @@ -1052,7 +1052,7 @@ }, { "anchor": "rustls-slice-str-get", - "comment": "Retrieve the nth element from the input slice of `&str`s.\n\n If the input pointer is NULL, or n is greater than the length of the\n rustls_slice_str, returns rustls_str{NULL, 0}.", + "comment": "Retrieve the nth element from the input slice of `&str`s.\n\n If the input pointer is NULL, or `n` is greater than or equal to the length of the\n [`rustls_slice_str`](#rustls-slice-str), returns a [`rustls_str`](#rustls-str) with a NULL data pointer and a length of 0.\n\n Otherwise, the returned string borrows its data from `input`. It remains valid for the same\n lifetime as `input` and must not be freed.", "feature": null, "deprecation": null, "name": "rustls_slice_str_get", @@ -1060,7 +1060,7 @@ }, { "anchor": "rustls-server-config-builder-new", - "comment": "Create a rustls_server_config_builder using the process default crypto provider.\n\n Caller owns the memory and must eventually call rustls_server_config_builder_build,\n then free the resulting rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key exchange\n groups, as well as safe defaults for protocol versions.", + "comment": "Create a [`rustls_server_config_builder`](#rustls-server-config-builder) using the process default crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_server_config_builder_build`](#rustls-server-config-builder-build),\n then free the resulting [`rustls_server_config`](#rustls-server-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key exchange\n groups, as well as safe defaults for protocol versions.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_new", @@ -1068,7 +1068,7 @@ }, { "anchor": "rustls-server-config-builder-new-custom", - "comment": "Create a rustls_server_config_builder using the specified crypto provider.\n\n Caller owns the memory and must eventually call rustls_server_config_builder_build,\n then free the resulting rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n `tls_versions` set the TLS protocol versions to use when negotiating a TLS session.\n\n `tls_versions` is the version of the protocol, as defined in rfc8446,\n ch. 4.2.1 and end of ch. 5.1. Some values are defined in\n [`rustls_tls_version`](#rustls-tls-version) for convenience.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t` pointed\n to by `tls_versions`.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", + "comment": "Create a [`rustls_server_config_builder`](#rustls-server-config-builder) using the specified crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_server_config_builder_build`](#rustls-server-config-builder-build),\n then free the resulting [`rustls_server_config`](#rustls-server-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n `tls_versions` sets the TLS protocol versions to use when negotiating a TLS session.\n Each value is a protocol version as defined in RFC 8446, sections 4.2.1 and 5.1.\n Some values are defined in\n [`rustls_tls_version`](#rustls-tls-version) for convenience.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t` pointed\n to by `tls_versions`.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `builder_out` receives a builder owned by the caller.\n It must eventually be passed to [`rustls_server_config_builder_build`](#rustls-server-config-builder-build) or freed with\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free). On error, `builder_out` is unchanged.\n\n The function borrows `provider` for the duration of the call and retains its own\n reference afterward.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_new_custom", @@ -1076,7 +1076,7 @@ }, { "anchor": "rustls-server-config-builder-set-client-verifier", - "comment": "Create a rustls_server_config_builder for TLS sessions that may verify client\n certificates.\n\n This increases the refcount of `verifier` and doesn't take ownership.", + "comment": "Configure a [`rustls_server_config_builder`](#rustls-server-config-builder) to verify client certificates.\n Client authentication is disabled unless this function is called.\n\n To require client certificates that chain to a custom set of roots:\n\n 1. Create a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder) with\n [`rustls_root_cert_store_builder_new`](#rustls-root-cert-store-builder-new).\n 2. Add roots with [`rustls_root_cert_store_builder_add_pem`](#rustls-root-cert-store-builder-add-pem) or\n [`rustls_root_cert_store_builder_load_roots_from_file`](#rustls-root-cert-store-builder-load-roots-from-file), then call\n [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build).\n 3. Pass the resulting store to\n [`rustls_web_pki_client_cert_verifier_builder_new`](#rustls-web-pki-client-cert-verifier-builder-new), then call\n [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build).\n 4. Pass the resulting verifier to this function.\n\n This function increases the reference count of `verifier` and does not\n take ownership. The caller must still free its verifier pointer with\n [`rustls_client_cert_verifier_free`](#rustls-client-cert-verifier-free) when it is no longer needed.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_client_verifier", @@ -1084,7 +1084,7 @@ }, { "anchor": "rustls-server-config-builder-set-key-log-file", - "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the NSS key log format,\n and is\n compatible with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log).", + "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the [NSS key log format] and is compatible\n with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log).\n\n [NSS key log format]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_key_log_file", @@ -1092,7 +1092,7 @@ }, { "anchor": "rustls-server-config-builder-set-key-log", - "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n Rustls documentation of the `KeyLog` trait for more information on possible labels:\n \n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_server_config_builder_set_key_log_file`](#rustls-server-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.", + "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n rustls documentation for [`KeyLog::log`] for more information on possible labels.\n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_server_config_builder_set_key_log_file`](#rustls-server-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.\n\n [`KeyLog::log`]: https://docs.rs/rustls/latest/rustls/trait.KeyLog.html#tymethod.log", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_key_log", @@ -1100,7 +1100,7 @@ }, { "anchor": "rustls-server-config-builder-free", - "comment": "\"Free\" a server_config_builder without building it into a rustls_server_config.\n\n Normally builders are built into rustls_server_configs via [`rustls_server_config_builder_build`](#rustls-server-config-builder-build)\n and may not be free'd or otherwise used afterwards.\n\n Use free only when the building of a config has to be aborted before a config\n was created.", + "comment": "Free a [`rustls_server_config_builder`](#rustls-server-config-builder) without building it into a\n [`rustls_server_config`](#rustls-server-config).\n\n Do not call this after [`rustls_server_config_builder_build`](#rustls-server-config-builder-build), which consumes and frees the\n builder. Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_free", @@ -1108,7 +1108,7 @@ }, { "anchor": "rustls-server-config-builder-set-ignore-client-order", - "comment": "With `ignore` != 0, the server will ignore the client ordering of cipher\n suites, aka preference, during handshake and respect its own ordering\n as configured.\n ", + "comment": "With `ignore` != 0, the server will ignore the client ordering of cipher\n suites, aka preference, during handshake and respect its own ordering\n as configured.\n\n See also the rustls documentation for [`ServerConfig::ignore_client_order`].\n\n [`ServerConfig::ignore_client_order`]: https://docs.rs/rustls/latest/rustls/struct.ServerConfig.html#structfield.ignore_client_order", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_ignore_client_order", @@ -1116,7 +1116,7 @@ }, { "anchor": "rustls-server-config-builder-set-send-tls13-tickets", - "comment": "Set the number of TLS 1.3 NewSessionTickets sent after a full handshake.\n\n Setting this to 0 disables session ticket issuance entirely.\n ", + "comment": "Set the number of TLS 1.3 NewSessionTickets sent after a full handshake.\n\n Setting this to 0 disables session ticket issuance entirely.\n\n See also the rustls documentation for [`ServerConfig::send_tls13_tickets`].\n\n [`ServerConfig::send_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.send_tls13_tickets", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_send_tls13_tickets", @@ -1124,7 +1124,7 @@ }, { "anchor": "rustls-server-config-builder-set-max-tls13-tickets", - "comment": "Set the upper bound on the number of TLS 1.3 tickets sent in response to a client.\n\n This modifies the server's response to a client's RFC 9149 `ticket_request` extension.\n\n A client requesting `n` tickets receives `min(n, max)`. Setting this to\n 0 (the default) ignores client requests entirely, clients get the configured\n `send_tls13_tickets` count regardless.\n\n ", + "comment": "Set the upper bound on the number of TLS 1.3 tickets sent in response to a client.\n\n This modifies the server's response to a client's RFC 9149 `ticket_request` extension.\n\n A client requesting `n` tickets receives `min(n, max)`. Setting this to\n 0 (the default) ignores client requests entirely, clients get the configured\n `send_tls13_tickets` count regardless.\n\n See also the rustls documentation for [`ServerConfig::max_tls13_tickets`].\n\n [`ServerConfig::max_tls13_tickets`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.max_tls13_tickets", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_max_tls13_tickets", @@ -1132,7 +1132,7 @@ }, { "anchor": "rustls-server-config-builder-set-alpn-protocols", - "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `len` elements. Each element of the buffer must point to a slice of bytes that\n contains a single ALPN protocol from\n .\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n ", + "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `len` elements. Each element of the buffer must point to a slice of bytes that\n contains a single ALPN protocol from the [IANA registry].\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n See also the rustls documentation for [`ServerConfig::alpn_protocols`].\n\n [IANA registry]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids\n [`ServerConfig::alpn_protocols`]: https://docs.rs/rustls/latest/rustls/server/struct.ServerConfig.html#structfield.alpn_protocols", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_alpn_protocols", @@ -1140,7 +1140,7 @@ }, { "anchor": "rustls-server-config-builder-set-certified-keys", - "comment": "Provide the configuration a list of certificates where the connection\n will select the first one that is compatible with the client's signature\n verification capabilities.\n\n Servers that want to support both ECDSA and RSA certificates will want\n the ECSDA to go first in the list.\n\n The built configuration will keep a reference to all certified keys\n provided. The client may [`rustls_certified_key_free()`](#rustls-certified-key-free) afterwards\n without the configuration losing them. The same certified key may also\n be used in multiple configs.\n\n EXPERIMENTAL: installing a client_hello callback will replace any\n configured certified keys and vice versa.", + "comment": "Provide the configuration a list of certificates where the connection\n will select the first one that is compatible with the client's signature\n verification capabilities.\n\n Servers that want to support both ECDSA and RSA certificates will want\n the ECDSA certificate to go first in the list.\n\n In the usual case, first call [`rustls_certified_key_build`](#rustls-certified-key-build) with the PEM\n certificate chain and private key, then pass the resulting\n [`rustls_certified_key`](#rustls-certified-key) pointer to this function. The builder and built\n configuration keep a reference to each certified key, so the caller may\n call [`rustls_certified_key_free()`](#rustls-certified-key-free) after this function returns. The same\n certified key may also be used in multiple configs.\n\n EXPERIMENTAL: installing a client_hello callback will replace any\n configured certified keys and vice versa.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_certified_keys", @@ -1148,7 +1148,7 @@ }, { "anchor": "rustls-server-config-builder-build", - "comment": "Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config\n (read-only). The constructed [`rustls_server_config`](#rustls-server-config) will be written to the `config_out`\n pointer when this function returns `rustls_result::Ok`.\n\n This function may return an error if no process default crypto provider has been set\n and the builder was constructed using [`rustls_server_config_builder_new`](#rustls-server-config-builder-new), or if no\n certificate resolver was set.", + "comment": "Turn a mutable [`rustls_server_config_builder`](#rustls-server-config-builder) into a const [`rustls_server_config`](#rustls-server-config)\n (read-only). The constructed [`rustls_server_config`](#rustls-server-config) will be written to the `config_out`\n pointer when this function returns [`RUSTLS_RESULT_OK`](#rustls-result-ok).\n\n This function takes ownership of `builder`. The caller must not use or free the builder\n after calling this function, regardless of the result.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `config_out` receives a config owned by the caller, which must\n eventually be freed with [`rustls_server_config_free`](#rustls-server-config-free). On error, `config_out` is unchanged.\n\n This function may return an error if no process default crypto provider has been set\n and the builder was constructed using [`rustls_server_config_builder_new`](#rustls-server-config-builder-new), or if no\n certificate resolver was set.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_build", @@ -1164,7 +1164,7 @@ }, { "anchor": "rustls-server-config-free", - "comment": "\"Free\" a rustls_server_config previously returned from\n rustls_server_config_builder_build.\n\n Since rustls_server_config is actually an\n atomically reference-counted pointer, extant server connections may still\n hold an internal reference to the Rust object. However, C code must\n consider this pointer unusable after \"free\"ing it.\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Release the caller's reference to a [`rustls_server_config`](#rustls-server-config) previously returned from\n [`rustls_server_config_builder_build`](#rustls-server-config-builder-build).\n\n Existing server connections may still hold internal references to the atomically\n reference-counted Rust object. Regardless, the caller must not use `config` after this\n function returns.\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_server_config_free", @@ -1172,7 +1172,7 @@ }, { "anchor": "rustls-server-connection-new", - "comment": "Create a new rustls_connection containing a server connection, and return it.\n\n It is returned in the output parameter `conn_out`.\n\n If this returns an error code, the memory pointed to by `conn_out` remains unchanged.\n\n If this returns a non-error, the memory pointed to by `conn_out` is modified to point\n at a valid rustls_connection\n\n The caller now owns the rustls_connection and must call [`rustls_connection_free`](#rustls-connection-free) when\n done with it.", + "comment": "Create a new [`rustls_connection`](#rustls-connection) containing a server connection, and return it.\n\n It is returned in the output parameter `conn_out`.\n\n If this returns an error code, the memory pointed to by `conn_out` remains unchanged.\n\n If this returns a non-error, the memory pointed to by `conn_out` is modified to point\n at a valid [`rustls_connection`](#rustls-connection)\n\n The caller now owns the [`rustls_connection`](#rustls-connection) and must call [`rustls_connection_free`](#rustls-connection-free) when\n done with it.\n\n The connection retains an internal reference to `config`. This function\n does not take ownership of the caller's config pointer.", "feature": null, "deprecation": null, "name": "rustls_server_connection_new", @@ -1180,7 +1180,7 @@ }, { "anchor": "rustls-server-connection-get-server-name", - "comment": "Returns a [`rustls_str`](#rustls-str) reference to the server name sent by the client in a server name\n indication (SNI) extension.\n\n The returned [`rustls_str`](#rustls-str) is valid until the next mutating function call affecting the\n connection. A mutating function call is one where the first argument has type\n `struct rustls_connection *` (as opposed to `const struct rustls_connection *`). The caller\n does not need to free the [`rustls_str`](#rustls-str).\n\n Returns a zero-length [`rustls_str`](#rustls-str) if:\n\n - the connection is not a server connection.\n - the connection is a server connection but the SNI extension in the client hello has not\n been processed during the handshake yet. Check [`rustls_connection_is_handshaking`](#rustls-connection-is-handshaking).\n - the SNI value contains null bytes.", + "comment": "Returns a [`rustls_str`](#rustls-str) reference to the server name sent by the client in a server name\n indication (SNI) extension.\n\n The returned [`rustls_str`](#rustls-str) is valid until the next mutating function call affecting the\n connection. A mutating function call is one where the first argument is a mutable pointer to\n [`rustls_connection`](#rustls-connection) (as opposed to a const pointer). The caller does not need to free the\n [`rustls_str`](#rustls-str).\n\n Returns a zero-length [`rustls_str`](#rustls-str) if:\n\n - the connection is not a server connection.\n - the connection is a server connection but the SNI extension in the ClientHello has not\n been processed during the handshake yet. Check [`rustls_connection_is_handshaking`](#rustls-connection-is-handshaking).\n - the SNI value contains null bytes.", "feature": null, "deprecation": null, "name": "rustls_server_connection_get_server_name", @@ -1188,7 +1188,7 @@ }, { "anchor": "rustls-server-config-builder-set-hello-callback", - "comment": "Register a callback to be invoked when a connection created from this config\n sees a TLS ClientHello message. If `userdata` has been set with\n rustls_connection_set_userdata, it will be passed to the callback.\n Otherwise the userdata param passed to the callback will be NULL.\n\n Any existing `ResolvesServerCert` implementation currently installed in the\n [`rustls_server_config`](#rustls-server-config) will be replaced. This also means registering twice\n will overwrite the first registration. It is not permitted to pass a NULL\n value for `callback`.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.\n Installing a client_hello callback will replace any configured certified keys\n and vice versa. Same holds true for the set_certified_keys variant.", + "comment": "Register a callback to be invoked when a connection created from this config\n sees a TLS ClientHello message. If `userdata` has been set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata), it will be passed to the callback.\n Otherwise the userdata param passed to the callback will be NULL.\n\n Any existing `ResolvesServerCert` implementation currently installed in the\n [`rustls_server_config`](#rustls-server-config) will be replaced. This also means registering twice\n will overwrite the first registration. It is not permitted to pass a NULL\n value for `callback`.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating its current approach to ClientHello handling.\n Installing a client_hello callback will replace any configured certified keys\n and vice versa. Same holds true for the set_certified_keys variant.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_hello_callback", @@ -1196,7 +1196,7 @@ }, { "anchor": "rustls-client-hello-select-certified-key", - "comment": "Select a [`rustls_certified_key`](#rustls-certified-key) from the list that matches the cryptographic\n parameters of a TLS client hello.\n\n Note that this does not do any SNI matching. The input certificates should\n already have been filtered to ones matching the SNI from the client hello.\n\n This is intended for servers that are configured with several keys for the\n same domain name(s), for example ECDSA and RSA types. The presented keys are\n inspected in the order given and keys first in the list are given preference,\n all else being equal. However rustls is free to choose whichever it considers\n to be the best key with its knowledge about security issues and possible future\n extensions of the protocol.\n\n Return RUSTLS_RESULT_OK if a key was selected and RUSTLS_RESULT_NOT_FOUND\n if none was suitable.", + "comment": "Select a [`rustls_certified_key`](#rustls-certified-key) from the list that matches the cryptographic\n parameters of a TLS ClientHello.\n\n Note that this does not do any SNI matching. The input certificates should\n already have been filtered to ones matching the SNI from the ClientHello.\n\n This is intended for servers that are configured with several keys for the\n same domain name(s), for example ECDSA and RSA types. The presented keys are\n inspected in the order given and keys first in the list are given preference,\n all else being equal. However rustls is free to choose whichever it considers\n to be the best key with its knowledge about security issues and possible future\n extensions of the protocol.\n\n Return [`RUSTLS_RESULT_OK`](#rustls-result-ok) if a key was selected and [`RUSTLS_RESULT_NOT_FOUND`](#rustls-result-not-found)\n if none was suitable.\n\n On success, `out_key` is set to one of the pointers from `certified_keys`. The function does\n not take ownership or increment the reference count. The returned pointer remains valid only\n while the caller keeps the corresponding input key alive and must not be freed separately.\n\n On error, `out_key` is unchanged.", "feature": null, "deprecation": null, "name": "rustls_client_hello_select_certified_key", @@ -1204,7 +1204,7 @@ }, { "anchor": "rustls-server-config-builder-set-persistence", - "comment": "Register callbacks for persistence of TLS session IDs and secrets. Both\n keys and values are highly sensitive data, containing enough information\n to break the security of the connections involved.\n\n If `builder`, `get_cb`, or `put_cb` are NULL, this function will return\n immediately without doing anything.\n\n If `userdata` has been set with rustls_connection_set_userdata, it\n will be passed to the callbacks. Otherwise the userdata param passed to\n the callbacks will be NULL.", + "comment": "Register callbacks for persistence of TLS session IDs and secrets. Both\n keys and values are highly sensitive data, containing enough information\n to break the security of the connections involved.\n\n If `builder`, `get_cb`, or `put_cb` are NULL, this function will return\n immediately without doing anything.\n\n If `userdata` has been set with [`rustls_connection_set_userdata`](#rustls-connection-set-userdata), it\n will be passed to the callbacks. Otherwise the userdata param passed to\n the callbacks will be NULL.", "feature": null, "deprecation": null, "name": "rustls_server_config_builder_set_persistence", @@ -1212,7 +1212,7 @@ }, { "anchor": "rustls-client-cert-verifier-free", - "comment": "Free a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier) previously returned from\n `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must not be\n called twice with the same value.", + "comment": "Free a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier) previously returned from\n [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build). Calling with NULL is fine.\n Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_client_cert_verifier_free", @@ -1220,7 +1220,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder-new", - "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the process-wide default\n cryptography provider.\n\n Caller owns the memory and may eventually call [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free)\n to free it, whether or not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the process-wide default\n cryptography provider.\n\n Caller owns the memory and may eventually call [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free)\n to free it, whether or not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client to present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This does not take ownership of `store`. The builder retains its own\n reference, so the caller may free its root certificate store pointer after\n this function returns.", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder_new", @@ -1228,7 +1228,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder-new-with-provider", - "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the specified\n cryptography provider.\n\n Caller owns the memory and may eventually call\n [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free) to free it, whether or\n not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the specified\n cryptography provider.\n\n Caller owns the memory and may eventually call\n [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free) to free it, whether or\n not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client to present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This does not take ownership of `provider` or `store`. The builder retains\n its own references, so the caller may free both input pointers after this\n function returns.", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder_new_with_provider", @@ -1236,7 +1236,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder-add-crl", - "comment": "Add one or more certificate revocation lists (CRLs) to the client certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.", + "comment": "Add one or more certificate revocation lists (CRLs) to the client certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.\n\n It copies the parsed CRLs and does not retain `crl_pem`.", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder_add_crl", @@ -1284,7 +1284,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder-build", - "comment": "Create a new client certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The verifier can be used in several [`rustls_server_config`](#rustls-server-config) instances and must be\n freed by the application when no longer needed. See the documentation of\n [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free) for details about lifetime.", + "comment": "Create a new client certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `verifier_out` receives a verifier owned by the caller. It can be\n used in several [`rustls_server_config`](#rustls-server-config) instances and must be freed with\n [`rustls_client_cert_verifier_free`](#rustls-client-cert-verifier-free) when no longer needed. On error, `verifier_out` is\n unchanged.", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder_build", @@ -1292,7 +1292,7 @@ }, { "anchor": "rustls-web-pki-client-cert-verifier-builder-free", - "comment": "Free a `rustls_client_cert_verifier_builder` previously returned from\n `rustls_client_cert_verifier_builder_new`.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) previously returned from\n [`rustls_web_pki_client_cert_verifier_builder_new`](#rustls-web-pki-client-cert-verifier-builder-new).\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_web_pki_client_cert_verifier_builder_free", @@ -1300,7 +1300,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder-new", - "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the process-wide default\n crypto provider.\n\n Caller owns the memory and may free it with [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free),\n regardless of whether [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the process-wide default\n crypto provider.\n\n Caller owns the memory and may free it with [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free),\n regardless of whether [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server to present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n This does not take ownership of `store`. The builder retains its own\n reference, so the caller may free its root certificate store pointer after\n this function returns.", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder_new", @@ -1308,7 +1308,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder-new-with-provider", - "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the specified\n crypto provider. Caller owns the memory and may free it with\n [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free), regardless of whether\n [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used. Expired CRLs will not be treated as an error unless\n [`rustls_web_pki_server_cert_verifier_enforce_revocation_expiry`](#rustls-web-pki-server-cert-verifier-enforce-revocation-expiry) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the specified\n crypto provider. Caller owns the memory and may free it with\n [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free), regardless of whether\n [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server to present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used. Expired CRLs will not be treated as an error unless\n [`rustls_web_pki_server_cert_verifier_enforce_revocation_expiry`](#rustls-web-pki-server-cert-verifier-enforce-revocation-expiry) is used.\n\n This does not take ownership of `provider` or `store`. The builder retains\n its own references, so the caller may free both input pointers after this\n function returns.", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder_new_with_provider", @@ -1316,7 +1316,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder-add-crl", - "comment": "Add one or more certificate revocation lists (CRLs) to the server certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.", + "comment": "Add one or more certificate revocation lists (CRLs) to the server certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.\n\n It copies the parsed CRLs and does not retain `crl_pem`.", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder_add_crl", @@ -1348,7 +1348,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder-build", - "comment": "Create a new server certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be\n freed by the application when no longer needed. See the documentation of\n [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free) for details about lifetime.", + "comment": "Create a new server certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n On [`RUSTLS_RESULT_OK`](#rustls-result-ok), `verifier_out` receives a verifier owned by the caller. It can be\n used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed with\n [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed. On error, `verifier_out` is\n unchanged.", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder_build", @@ -1356,7 +1356,7 @@ }, { "anchor": "rustls-web-pki-server-cert-verifier-builder-free", - "comment": "Free a `rustls_server_cert_verifier_builder` previously returned from\n `rustls_server_cert_verifier_builder_new`.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) previously returned from\n [`rustls_web_pki_server_cert_verifier_builder_new`](#rustls-web-pki-server-cert-verifier-builder-new).\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_web_pki_server_cert_verifier_builder_free", @@ -1364,7 +1364,7 @@ }, { "anchor": "rustls-platform-server-cert-verifier", - "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][].\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", + "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][].\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n On error, `verifier_out` is unchanged.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", "feature": null, "deprecation": null, "name": "rustls_platform_server_cert_verifier", @@ -1380,7 +1380,7 @@ }, { "anchor": "rustls-platform-server-cert-verifier-try-with-provider", - "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][] and the specified crypto provider.\n\n If the initialization of `rustls-platform-verifier` fails, this function returns\n an error and `NULL` is written to `verifier_out`. Otherwise it fills in `verifier_out`\n (whose ownership is transferred to the caller) and returns `RUSTLS_SUCCESS`.\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", + "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][] and the specified crypto provider.\n\n If the initialization of `rustls-platform-verifier` fails, this function returns\n an error and `NULL` is written to `verifier_out`. Otherwise it fills in `verifier_out`\n (whose ownership is transferred to the caller) and returns [`RUSTLS_RESULT_OK`](#rustls-result-ok).\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", "feature": null, "deprecation": null, "name": "rustls_platform_server_cert_verifier_try_with_provider", @@ -1388,7 +1388,7 @@ }, { "anchor": "rustls-server-cert-verifier-free", - "comment": "Free a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier) previously returned from\n `rustls_server_cert_verifier_builder_build` or [`rustls_platform_server_cert_verifier`](#rustls-platform-server-cert-verifier).\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "comment": "Free a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier) previously returned from\n [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) or\n [`rustls_platform_server_cert_verifier`](#rustls-platform-server-cert-verifier).\n\n Calling with NULL is fine. Must not be called twice with the same value.", "feature": null, "deprecation": null, "name": "rustls_server_cert_verifier_free", @@ -1405,31 +1405,31 @@ ], "callbacks": [ { - "anchor": "rustls_read_callback", - "comment": "A callback for [`rustls_connection_read_tls`](#rustls-connection-read-tls).\n\n An implementation of this callback should attempt to read up to n bytes from the\n network, storing them in `buf`. If any bytes were stored, the implementation should\n set out_n to the number of bytes stored and return 0.\n\n If there was an error, the implementation should return a nonzero rustls_io_result,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one read attempt to the network per call. Additional reads will\n be triggered by subsequent calls to one of the `_read_tls` methods.\n\n `userdata` is set to the value provided to [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n In most cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The buf and out_n pointers are borrowed and should not be retained across calls.", + "anchor": "rustls-read-callback", + "comment": "A callback for [`rustls_connection_read_tls`](#rustls-connection-read-tls).\n\n An implementation of this callback should attempt to read up to `n` bytes from the\n network, storing them in `buf`. If any bytes were stored, the implementation should\n set `out_n` to the number of bytes stored and return 0.\n\n If there was an error, the implementation should return a nonzero [`rustls_io_result`](#alias-rustls-io-result),\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one read attempt to the network per call. Additional reads will\n be triggered by subsequent calls to one of the `_read_tls` methods.\n\n `userdata` is the value passed to the function invoking this callback. In most cases that\n should point to a struct containing, at a minimum, a file descriptor.\n\n The `buf` and `out_n` pointers are borrowed and should not be retained across calls.", "feature": null, "deprecation": null, "name": "rustls_read_callback", "text": "```c\ntypedef rustls_io_result (*rustls_read_callback)(void *userdata,\n uint8_t *buf,\n size_t n,\n size_t *out_n);\n```" }, { - "anchor": "rustls_write_callback", - "comment": "A callback for [`rustls_connection_write_tls`](#rustls-connection-write-tls) or [`rustls_accepted_alert_write_tls`](#rustls-accepted-alert-write-tls).\n\n An implementation of this callback should attempt to write the `n` bytes in buf\n to the network.\n\n If any bytes were written, the implementation should set `out_n` to the number of\n bytes stored and return 0.\n\n If there was an error, the implementation should return a nonzero `rustls_io_result`,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional writes will\n be triggered by subsequent calls to rustls_connection_write_tls.\n\n `userdata` is set to the value provided to [`rustls_connection_set_userdata`](#rustls-connection-set-userdata). In most\n cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The buf and out_n pointers are borrowed and should not be retained across calls.", + "anchor": "rustls-write-callback", + "comment": "A callback for [`rustls_connection_write_tls`](#rustls-connection-write-tls) or [`rustls_accepted_alert_write_tls`](#rustls-accepted-alert-write-tls).\n\n An implementation of this callback should attempt to write the `n` bytes in `buf`\n to the network.\n\n If any bytes were written, the implementation should set `out_n` to the number of\n bytes written and return 0.\n\n If there was an error, the implementation should return a nonzero [`rustls_io_result`](#alias-rustls-io-result),\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional writes will\n be triggered by subsequent calls to [`rustls_connection_write_tls`](#rustls-connection-write-tls).\n\n `userdata` is the value passed to the function invoking this callback. In most cases that\n should point to a struct containing, at a minimum, a file descriptor.\n\n The `buf` and `out_n` pointers are borrowed and should not be retained across calls.", "feature": null, "deprecation": null, "name": "rustls_write_callback", "text": "```c\ntypedef rustls_io_result (*rustls_write_callback)(void *userdata,\n const uint8_t *buf,\n size_t n,\n size_t *out_n);\n```" }, { - "anchor": "rustls_verify_server_cert_callback", - "comment": "A callback that is invoked to verify a server certificate.", + "anchor": "rustls-verify-server-cert-callback", + "comment": "A callback that is invoked to verify a server certificate.\n\n `userdata` is the value set with [`rustls_connection_set_userdata`](#rustls-connection-set-userdata). `params` and all data\n referenced by its fields are borrowed and valid only for the duration of the callback.\n\n See [`rustls_client_config_builder_dangerous_set_certificate_verifier`](#rustls-client-config-builder-dangerous-set-certificate-verifier) for return values and\n thread-safety requirements.", "feature": null, "deprecation": null, "name": "rustls_verify_server_cert_callback", "text": "```c\ntypedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata,\n const struct rustls_verify_server_cert_params *params);\n```" }, { - "anchor": "rustls_keylog_log_callback", + "anchor": "rustls-keylog-log-callback", "comment": "An optional callback for logging key material.\n\n See the documentation on [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log) and\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log) for more information about the\n lifetimes of the parameters.", "feature": null, "deprecation": null, @@ -1437,7 +1437,7 @@ "text": "```c\ntypedef void (*rustls_keylog_log_callback)(struct rustls_str label,\n const uint8_t *client_random,\n size_t client_random_len,\n const uint8_t *secret,\n size_t secret_len);\n```" }, { - "anchor": "rustls_keylog_will_log_callback", + "anchor": "rustls-keylog-will-log-callback", "comment": "An optional callback for deciding if key material will be logged.\n\n See the documentation on [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log) and\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log) for more information about the\n lifetimes of the parameters.", "feature": null, "deprecation": null, @@ -1445,40 +1445,40 @@ "text": "```c\ntypedef int (*rustls_keylog_will_log_callback)(struct rustls_str label);\n```" }, { - "anchor": "rustls_log_callback", - "comment": "A callback that is invoked for messages logged by rustls.", + "anchor": "rustls-log-callback", + "comment": "A callback that is invoked for messages logged by rustls.\n\n `params` and the message it references are borrowed and valid only for the duration of the\n callback. `userdata` is the value set with [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).", "feature": null, "deprecation": null, "name": "rustls_log_callback", "text": "```c\ntypedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params);\n```" }, { - "anchor": "rustls_write_vectored_callback", - "comment": "A callback for [`rustls_connection_write_tls_vectored`](#rustls-connection-write-tls-vectored).\n\n An implementation of this callback should attempt to write the bytes in\n the given `count` iovecs to the network.\n\n If any bytes were written, the implementation should set out_n to the number of\n bytes written and return 0.\n\n If there was an error, the implementation should return a nonzero rustls_io_result,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional write will\n be triggered by subsequent calls to one of the `_write_tls` methods.\n\n `userdata` is set to the value provided to `rustls_*_session_set_userdata`. In most\n cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The iov and out_n pointers are borrowed and should not be retained across calls.", + "anchor": "rustls-write-vectored-callback", + "comment": "A callback for [`rustls_connection_write_tls_vectored`](#rustls-connection-write-tls-vectored).\n\n An implementation of this callback should attempt to write the bytes in\n the given `count` iovecs to the network.\n\n If any bytes were written, the implementation should set `out_n` to the number of\n bytes written and return 0.\n\n If there was an error, the implementation should return a nonzero [`rustls_io_result`](#alias-rustls-io-result),\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional writes will\n be triggered by subsequent calls to one of the `_write_tls` methods.\n\n `userdata` is the value passed to the function invoking this callback. In most cases that\n should point to a struct containing, at a minimum, a file descriptor.\n\n The `iov` and `out_n` pointers are borrowed and should not be retained across calls.", "feature": null, "deprecation": null, "name": "rustls_write_vectored_callback", "text": "```c\ntypedef rustls_io_result (*rustls_write_vectored_callback)(void *userdata,\n const struct rustls_iovec *iov,\n size_t count,\n size_t *out_n);\n```" }, { - "anchor": "rustls_client_hello_callback", - "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config).\n\n This callback will be invoked by a [`rustls_connection`](#rustls-connection) once the TLS client\n hello message has been received.\n\n `userdata` will be set based on rustls_connection_set_userdata.\n\n `hello` gives the value of the available client announcements, as interpreted\n by rustls. See the definition of [`rustls_client_hello`](#rustls-client-hello) for details.\n\n NOTE:\n - the passed in `hello` and all its values are only available during the\n callback invocations.\n - the passed callback function must be safe to call multiple times concurrently\n with the same userdata, unless there is only a single config and connection\n where it is installed.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.", + "anchor": "rustls-client-hello-callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config).\n\n This callback will be invoked by a [`rustls_connection`](#rustls-connection) once the TLS ClientHello\n message has been received.\n\n `userdata` will be set based on [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n `hello` contains the client parameters parsed by rustls. See the definition of\n [`rustls_client_hello`](#rustls-client-hello) for details.\n\n **Note:**\n\n - The passed-in `hello` and all its values are only valid during the callback invocation.\n - The callback must be safe to call multiple times concurrently\n with the same `userdata`, unless there is only a single config and connection\n where it is installed.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating its current approach to ClientHello handling.", "feature": null, "deprecation": null, "name": "rustls_client_hello_callback", "text": "```c\ntypedef const struct rustls_certified_key *(*rustls_client_hello_callback)(rustls_client_hello_userdata userdata,\n const struct rustls_client_hello *hello);\n```" }, { - "anchor": "rustls_session_store_get_callback", - "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked by a TLS session when looking up the data\n for a TLS session id.\n\n `userdata` will be supplied based on rustls_{client,server}_session_set_userdata.\n\n The `buf` points to `count` consecutive bytes where the\n callback is expected to copy the result to. The number of copied bytes\n needs to be written to `out_n`. The callback should not read any\n data from `buf`.\n\n If the value to copy is larger than `count`, the callback should never\n do a partial copy but instead remove the value from its store and\n act as if it was never found.\n\n The callback should return RUSTLS_RESULT_OK to indicate that a value was\n retrieved and written in its entirety into `buf`, or RUSTLS_RESULT_NOT_FOUND\n if no session was retrieved.\n\n When `remove_after` is != 0, the returned data needs to be removed\n from the store.\n\n NOTE: the passed in `key` and `buf` are only available during the\n callback invocation.\n NOTE: callbacks used in several sessions via a common config\n must be implemented thread-safe.", + "anchor": "rustls-session-store-get-callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked by a TLS session when looking up the data\n for a TLS session ID.\n\n `userdata` will be supplied based on [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n The `buf` points to `count` consecutive bytes where the\n callback is expected to copy the result to. The number of copied bytes\n needs to be written to `out_n`. The callback should not read any\n data from `buf`.\n\n If the value to copy is larger than `count`, the callback should never\n do a partial copy but instead remove the value from its store and\n act as if it was never found.\n\n The callback should return [`RUSTLS_RESULT_OK`](#rustls-result-ok) to indicate that a value was\n retrieved and written in its entirety into `buf`, or [`RUSTLS_RESULT_NOT_FOUND`](#rustls-result-not-found)\n if no session was retrieved.\n\n When `remove_after` is nonzero, the returned data needs to be removed\n from the store.\n\n **Notes:**\n\n - The passed-in `key` and `buf` are only valid during the callback invocation.\n - Callbacks shared by several sessions through a common config must be thread-safe.", "feature": null, "deprecation": null, "name": "rustls_session_store_get_callback", "text": "```c\ntypedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userdata userdata,\n const struct rustls_slice_bytes *key,\n int remove_after,\n uint8_t *buf,\n size_t count,\n size_t *out_n);\n```" }, { - "anchor": "rustls_session_store_put_callback", - "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked by a TLS session when a TLS session\n been created and an id for later use is handed to the client/has\n been received from the server.\n\n `userdata` will be supplied based on rustls_{client,server}_session_set_userdata.\n\n The callback should return RUSTLS_RESULT_OK to indicate that a value was\n successfully stored, or RUSTLS_RESULT_IO on failure.\n\n NOTE: the passed in `key` and `val` are only available during the\n callback invocation.\n NOTE: callbacks used in several sessions via a common config\n must be implemented thread-safe.", + "anchor": "rustls-session-store-put-callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked when a resumable TLS session has been created and a session ID\n has either been sent to the client or received from the server.\n\n `userdata` will be supplied based on [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n The callback should return [`RUSTLS_RESULT_OK`](#rustls-result-ok) to indicate that a value was\n successfully stored, or [`RUSTLS_RESULT_IO`](#rustls-result-io) on failure.\n\n **Notes:**\n\n - The passed-in `key` and `val` are only valid during the callback invocation.\n - Callbacks shared by several sessions through a common config must be thread-safe.", "feature": null, "deprecation": null, "name": "rustls_session_store_put_callback", @@ -2311,13 +2311,13 @@ }, { "anchor": "rustls-handshake-kind-full", - "comment": "A full TLS handshake.\n\n This is the typical TLS connection initiation process when resumption is\n not yet unavailable, and the initial client hello was accepted by the server.", + "comment": "A full TLS handshake.\n\n This is the typical TLS connection initiation process when resumption is\n unavailable and the initial ClientHello is accepted by the server.", "name": "RUSTLS_HANDSHAKE_KIND_FULL", "value": "1" }, { "anchor": "rustls-handshake-kind-full-with-hello-retry-request", - "comment": "A full TLS handshake, with an extra round-trip for a hello retry request.\n\n The server can respond with a hello retry request (HRR) if the initial client\n hello is unacceptable for several reasons, the most likely if no supported key\n shares were offered by the client.", + "comment": "A full TLS handshake, with an extra round-trip for a hello retry request.\n\n The server can respond with a hello retry request (HRR) if the initial ClientHello\n is unacceptable for several reasons, the most likely being that the client offered\n no supported key shares.", "name": "RUSTLS_HANDSHAKE_KIND_FULL_WITH_HELLO_RETRY_REQUEST", "value": "2" }, @@ -2333,7 +2333,7 @@ "externs": [ { "anchor": "rustls-all-versions", - "comment": "Rustls' list of supported protocol versions. The length of the array is\n given by `RUSTLS_ALL_VERSIONS_LEN`.", + "comment": "Rustls' list of supported protocol versions. The length of the array is\n given by [`RUSTLS_ALL_VERSIONS_LEN`](#rustls-all-versions-len).", "feature": null, "deprecation": null, "name": "RUSTLS_ALL_VERSIONS", @@ -2341,7 +2341,7 @@ }, { "anchor": "rustls-all-versions-len", - "comment": "The length of the array `RUSTLS_ALL_VERSIONS`.", + "comment": "The length of the array [`RUSTLS_ALL_VERSIONS`](#rustls-all-versions).", "feature": null, "deprecation": null, "name": "RUSTLS_ALL_VERSIONS_LEN", @@ -2349,7 +2349,7 @@ }, { "anchor": "rustls-default-versions", - "comment": "Rustls' default list of protocol versions. The length of the array is\n given by `RUSTLS_DEFAULT_VERSIONS_LEN`.", + "comment": "Rustls' default list of protocol versions. The length of the array is\n given by [`RUSTLS_DEFAULT_VERSIONS_LEN`](#rustls-default-versions-len).", "feature": null, "deprecation": null, "name": "RUSTLS_DEFAULT_VERSIONS", @@ -2357,7 +2357,7 @@ }, { "anchor": "rustls-default-versions-len", - "comment": "The length of the array `RUSTLS_DEFAULT_VERSIONS`.", + "comment": "The length of the array [`RUSTLS_DEFAULT_VERSIONS`](#rustls-default-versions).", "feature": null, "deprecation": null, "name": "RUSTLS_DEFAULT_VERSIONS_LEN", diff --git a/website/static/style.css b/website/static/style.css index 60408ad1..48a0ead3 100644 --- a/website/static/style.css +++ b/website/static/style.css @@ -77,8 +77,8 @@ pre { } code { - word-break: break-all; - word-wrap: break-word; + overflow-wrap: break-word; + word-break: normal; } /* Components */ diff --git a/website/templates/_api_section.html b/website/templates/_api_section.html index 680bc63d..10bbc9ac 100644 --- a/website/templates/_api_section.html +++ b/website/templates/_api_section.html @@ -1,11 +1,11 @@ -{% macro render_section(section_id, title, items) %} +{% component api.render_section(section_id: string, title: string, items: array) %}
- {{ macros::section_header(id=section_id, title=title) }} - {{ macros::toc_list(items=items) }} + {{}} + {{}} {% for item in items %}
- {{ macros::item_header(anchor=item.anchor, name=item.name) }} + {{}} {% if item.feature %}
@@ -42,8 +42,8 @@ {{ item.text | markdown | safe }} {% endif %} - {{ macros::back_to_top() }} + {{}}
{% endfor %}
-{% endmacro render_section %} +{% endcomponent api.render_section %} diff --git a/website/templates/base.html b/website/templates/base.html index ba04bd01..a750c7be 100644 --- a/website/templates/base.html +++ b/website/templates/base.html @@ -1,6 +1,6 @@ - rustls: {{ page.title | default (value="C FFI bindings for Rustls") }} + rustls: {{ page?.title or section?.title or "C FFI bindings for Rustls" }} diff --git a/website/templates/index.html b/website/templates/index.html index 7fed53e9..dbccd4e2 100644 --- a/website/templates/index.html +++ b/website/templates/index.html @@ -1,6 +1,4 @@ {% extends "base.html" %} -{% import "macros.html" as macros %} -{% import "_api_section.html" as api_section %} {% block content %} {% set data = load_data(path="static/api.json") %} @@ -23,11 +21,10 @@

Table of Contents

{% for id in section_ids %} {% if data[id] %} - {{ api_section::render_section( - section_id=id, - title=section_titles[loop.index0], - items=data[id]) - }} + {{}} {% endif %} {% endfor %} diff --git a/website/templates/macros.html b/website/templates/macros.html index ae107421..eee034f4 100644 --- a/website/templates/macros.html +++ b/website/templates/macros.html @@ -1,18 +1,18 @@ -{% macro section_header(id, title) %} +{% component api.section_header(id: string, title: string) %}

# {{ title }}

-{% endmacro section_header %} +{% endcomponent api.section_header %} -{% macro item_header(anchor, name) %} +{% component api.item_header(anchor: string, name: string) %}

# {{ name }}

-{% endmacro item_header %} +{% endcomponent api.item_header %} -{% macro toc_list(items) %} +{% component api.toc_list(items: array) %}
    {% for item in items %} @@ -27,8 +27,8 @@

    {% endfor %}

-{% endmacro toc_list %} +{% endcomponent api.toc_list %} -{% macro back_to_top() %} +{% component api.back_to_top() %}

Back to top ↑

-{% endmacro back_to_top %} +{% endcomponent api.back_to_top %}