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. 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.
Any context information the callback will receive when invoked.
A return value for a function that may return either success (0) or a non-zero value representing an error. The values should match socket error numbers for your operating system - for example, the integers for ETIMEDOUT, EAGAIN, or similar.
A callback for rustls_connection_read_tls. An implementation of this callback should attempt to read up to n bytes from the network, storing them in buf. If any bytes were stored, the implementation should set out_n to the number of bytes stored and return 0. If there was an error, the implementation should return a nonzero rustls_io_result, which will be passed through to the caller. On POSIX systems, returning errno is convenient. On other systems, any appropriate error code works. It's best to make one read attempt to the network per call. Additional reads will be triggered by subsequent calls to one of the _read_tls methods. userdata is set to the value provided to rustls_connection_set_userdata. In most cases that should be a struct that contains, at a minimum, a file descriptor. The buf and out_n pointers are borrowed and should not be retained across calls.
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 looking up the data for a TLS session id. userdata will be supplied based on rustls_{client,server}_session_set_userdata.
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 has been created and an id for later use is handed to the client/has been received from the server. userdata will be supplied based on rustls_{client,server}_session_set_userdata.
Any context information the callback will receive when invoked.
User-provided input to a custom certificate verifier callback. See rustls_client_config_builder_dangerous_set_certificate_verifier().
A callback for rustls_connection_write_tls. An implementation of this callback should attempt to write the n bytes in buf to the network. If any bytes were written, the implementation should set out_n to the number of bytes stored and return 0. If there was an error, the implementation should return a nonzero rustls_io_result, which will be passed through to the caller. On POSIX systems, returning errno is convenient. On other systems, any appropriate error code works. It's best to make one write attempt to the network per call. Additional writes will be triggered by subsequent calls to rustls_connection_write_tls. userdata is set to the value provided to rustls_connection_set_userdata. In most cases that should be a struct that contains, at a minimum, a file descriptor. The buf and out_n pointers are borrowed and should not be retained across calls.
A callback for rustls_connection_write_tls_vectored. An implementation of this callback should attempt to write the bytes in the given count iovecs to the network. If any bytes were written, the implementation should set out_n to the number of bytes written and return 0. If there was an error, the implementation should return a nonzero rustls_io_result, which will be passed through to the caller. On POSIX systems, returning errno is convenient. On other systems, any appropriate error code works. It's best to make one write attempt to the network per call. Additional write will be triggered by subsequent calls to one of the _write_tls methods. userdata is set to the value provided to rustls_*_session_set_userdata. In most cases that should be a struct that contains, at a minimum, a file descriptor. The buf and out_n pointers are borrowed and should not be retained across calls.
Definitions of known TLS protocol versions.
Get a pointer to a member of rustls' list of supported cipher suites. This will return non-NULL for i < rustls_all_ciphersuites_len(). The returned pointer is valid for the lifetime of the program and may be used directly when building a ClientConfig or ServerConfig.
Return the length of rustls' list of supported cipher suites.
Get the DER data of the certificate itself. The data is owned by the certificate and has the same lifetime.
Build a rustls_certified_key from a certificate chain and a private key. cert_chain must point to a buffer of cert_chain_len bytes, containing a series of PEM-encoded certificates, with the end-entity (leaf) certificate first.
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.
"Free" a certified_key previously returned from rustls_certified_key_build. Since certified_key is actually an atomically reference-counted pointer, extant certified_key may still hold an internal reference to the Rust object. 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.
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.
"Free" a verifier previously returned from rustls_client_cert_verifier_new. Since rustls_client_cert_verifier is actually an atomically reference-counted pointer, extant server_configs 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.
Create a new client certificate verifier for the root store. The verifier can be used in several rustls_server_config instances. Must be freed by the application when no longer needed. See the documentation of rustls_client_cert_verifier_free for details about lifetime. This copies the contents of the rustls_root_cert_store. It does not take ownership of the pointed-to memory.
"Free" a verifier previously returned from rustls_client_cert_verifier_optional_new. Since rustls_client_cert_verifier_optional is actually an atomically reference-counted pointer, extant server_configs 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.
Create a new rustls_client_cert_verifier_optional for the root store. The verifier can be used in several rustls_server_config instances. Must be freed by the application when no longer needed. See the documentation of rustls_client_cert_verifier_optional_free for details about lifetime. This copies the contents of the rustls_root_cert_store. It does not take ownership of the pointed-to data.
Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config (read-only).
Set a custom server certificate verifier.
"Free" a client_config_builder without building it into a rustls_client_config. Normally builders are built into rustls_client_config via rustls_client_config_builder_build and may not be free'd or otherwise used afterwards. Use free only when the building of a config has to be aborted before a config was created.
Add trusted root certificates from the named file, which should contain PEM-formatted certificates.
Create a rustls_client_config_builder. Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config. This uses rustls safe default values for the cipher suites, key exchange groups and protocol versions. This starts out with no trusted roots. Caller must add roots with rustls_client_config_builder_load_roots_from_file or provide a custom verifier.
Create a rustls_client_config_builder. Caller owns the memory and must eventually call rustls_client_config_builder_build, then free the resulting rustls_client_config. Specify cipher suites in preference order; the cipher_suites parameter must point to an array containing len pointers to rustls_supported_ciphersuite previously obtained from rustls_all_ciphersuites_get_entry(), or to a provided array, RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES. Set the TLS protocol versions to use when negotiating a TLS session.
Set the ALPN protocol list to the given protocols. protocols must point to a buffer of rustls_slice_bytes (built by the caller) with len elements. Each element of the buffer must be a rustls_slice_bytes whose data field points to a single ALPN protocol ID. Standard ALPN protocol IDs are defined at <https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids>.
Provide the configuration a list of certificates where the connection will select the first one that is compatible with the server's signature verification capabilities. Clients that want to support both ECDSA and RSA certificates will want the ECSDA to go first in the list.
Enable or disable SNI. <https://docs.rs/rustls/0.20.0/rustls/struct.ClientConfig.html#structfield.enable_sni>
Use the trusted root certificates from the provided store.
"Free" a rustls_client_config previously returned from rustls_client_config_builder_build. Since rustls_client_config is actually an atomically reference-counted pointer, extant client connections may still hold an internal reference to the Rust object. 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.
Create a new rustls_connection containing a client connection and return it in the output parameter 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. The caller now owns the rustls_connection and must call rustls_connection_free when done with it.
Select a rustls_certified_key from the list that matches the cryptographic parameters of a TLS client hello. 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.
Free a rustls_connection. Calling with NULL is fine. Must not be called twice with the same value.
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. 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 *). <https://www.iana.org/assignments/tls-parameters/> <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.alpn_protocol>
Retrieves the cipher suite agreed with the peer. This returns NULL until the ciphersuite is agreed. The returned pointer lives as long as the program. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.negotiated_cipher_suite>
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. 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 *). <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.peer_certificates>
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. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.protocol_version> <https://docs.rs/rustls/0.20.0/rustls/internal/msgs/enums/enum.ProtocolVersion.html>
Decrypt any available ciphertext from the internal buffer and put it into the internal plaintext buffer, potentially making bytes available for rustls_connection_read(). <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.process_new_packets>
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 available have been read, but more bytes may become available after subsequent calls to rustls_connection_read_tls and rustls_connection_process_new_packets."
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 available have been read, but more bytes may become available after subsequent calls to rustls_connection_read_tls and rustls_connection_process_new_packets."
Read some TLS bytes from the network into internal buffers. The actual network I/O is performed by callback, which you provide. Rustls will invoke your callback with a suitable buffer to store the read bytes into. You don't have to fill it up, just fill with as many bytes as you get in one syscall. The userdata parameter is passed through directly to callback. Note that this is distinct from the userdata parameter set with rustls_connection_set_userdata. Returns 0 for success, or an errno value on error. Passes through return values from callback. See rustls_read_callback for more details. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.read_tls>
Queues a close_notify fatal alert to be sent in the next write_tls call. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.send_close_notify>
Sets a limit on the internal buffers used to buffer unsent plaintext (prior 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. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.set_buffer_limit>
Set the logging callback for this connection. The log callback will be invoked with the userdata parameter previously set by rustls_connection_set_userdata, or NULL if no userdata was set.
Set the 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.
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 (this may be less than count). <https://docs.rs/rustls/0.20.0/rustls/struct.Writer.html#method.write>
Write some TLS bytes to the network. The actual network I/O is performed by callback, which you provide. Rustls will invoke your callback with a suitable buffer containing TLS bytes to send. You don't have to write them all, just as many as you can in one syscall. The userdata parameter is passed through directly to callback. Note that this is distinct from the userdata parameter set with rustls_connection_set_userdata. Returns 0 for success, or an errno value on error. Passes through return values from callback. See rustls_write_callback for more details. <https://docs.rs/rustls/0.20.0/rustls/enum.Connection.html#method.write_tls>
Write all available TLS bytes to the network. The actual network I/O is performed by callback, which you provide. Rustls will invoke your callback with an array of rustls_slice_bytes, each containing a buffer with TLS bytes to send. You don't have to write them all, just as many as you are willing. The userdata parameter is passed through directly to callback. Note that this is distinct from the userdata parameter set with rustls_connection_set_userdata. Returns 0 for success, or an errno value on error. Passes through return values from callback. See rustls_write_callback for more details. <https://docs.rs/rustls/0.20.0/rustls/struct.Writer.html#method.write_vectored>
Get a pointer to a member of rustls' list of supported cipher suites. This will return non-NULL for i < rustls_default_ciphersuites_len(). The returned pointer is valid for the lifetime of the program and may be used directly when building a ClientConfig or ServerConfig.
Return the length of rustls' list of default cipher suites.
After a rustls function returns an error, you may call this to get a pointer to a buffer containing a detailed error message. The contents of the error buffer will be out_n bytes long, UTF-8 encoded, and not NUL-terminated.
Return a rustls_str containing the stringified version of a log level.
Add one or more certificates to the root cert store using PEM encoded data.
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.
Create a rustls_root_cert_store. Caller owns the memory and must eventually call rustls_root_cert_store_free. The store starts out empty. Caller must add root certificates with rustls_root_cert_store_add_pem. <https://docs.rs/rustls/0.20.0/rustls/struct.RootCertStore.html#method.empty>
Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config (read-only).
"Free" a server_config_builder without building it into a rustls_server_config. Normally builders are built into rustls_server_configs via rustls_server_config_builder_build and may not be free'd or otherwise used afterwards. Use free only when the building of a config has to be aborted before a config was created.
Create a rustls_server_config_builder. Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config. This uses rustls safe default values for the cipher suites, key exchange groups and protocol versions.
Create a rustls_server_config_builder. Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config. Specify cipher suites in preference order; the cipher_suites parameter must point to an array containing len pointers to rustls_supported_ciphersuite previously obtained from rustls_all_ciphersuites_get_entry(). Set the TLS protocol versions to use when negotiating a TLS session.
Set the ALPN protocol list to the given protocols. protocols must point to a buffer of rustls_slice_bytes (built by the caller) with len elements. Each element of the buffer must point to a slice of bytes that contains a single ALPN protocol from <https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids>.
Provide the configuration a list of certificates where the connection will select the first one that is compatible with the client's signature verification capabilities. Servers that want to support both ECDSA and RSA certificates will want the ECSDA to go first in the list.
Create a rustls_server_config_builder for TLS sessions that require valid client certificates. The passed rustls_client_cert_verifier may be used in several builders. For memory lifetime, see rustls_server_config_builder_new.
Create a rustls_server_config_builder for TLS sessions that accept valid client certificates, but do not require them. The passed rustls_client_cert_verifier_optional may be used in several builders. For memory lifetime, see rustls_server_config_builder_new.
Register a callback to be invoked when a connection created from this config sees a TLS ClientHello message. If userdata has been set with rustls_connection_set_userdata, it will be passed to the callback. Otherwise the userdata param passed to the callback will be NULL.
With ignore != 0, the server will ignore the client ordering of cipher suites, aka preference, during handshake and respect its own ordering as configured. <https://docs.rs/rustls/0.20.0/rustls/struct.ServerConfig.html#structfield.ignore_client_order>
Register callbacks for persistence of TLS session IDs and secrets. Both keys and values are highly sensitive data, containing enough information to break the security of the connections involved.
"Free" a rustls_server_config previously returned from rustls_server_config_builder_build. 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.
Copy the SNI hostname to buf which can hold up to count bytes, and the length of that hostname in out_n. The string is stored in UTF-8 with no terminating NUL byte. Returns RUSTLS_RESULT_INSUFFICIENT_SIZE if the SNI hostname is longer than count. Returns Ok with *out_n == 0 if there is no SNI hostname available on this connection because it hasn't been processed yet, or because the client did not send SNI. <https://docs.rs/rustls/0.20.0/rustls/server/struct.ServerConnection.html#method.sni_hostname>
Create a new rustls_connection containing a server connection, and return it in the output parameter 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. The caller now owns the rustls_connection and must call rustls_connection_free when done with it.
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}.
Return the length of the outer slice. If the input pointer is NULL, returns 0.
Retrieve the nth element from the input slice of &strs. If the input pointer is NULL, or n is greater than the length of the rustls_slice_str, returns rustls_str{NULL, 0}.
Return the length of the outer slice. If the input pointer is NULL, returns 0.
Returns the name of the ciphersuite as a rustls_str. If the provided ciphersuite is invalid, the rustls_str will contain the empty string. The lifetime of the rustls_str is the lifetime of the program, it does not need to be freed.
Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4>. The bytes from the assignment are interpreted in network order.
Returns a static string containing the rustls-ffi version as well as the rustls version. The string is alive for the lifetime of the program and does not need to be freed.
An X.509 certificate, as used in rustls. Corresponds to Certificate in the Rust API. <https://docs.rs/rustls/0.20.0/rustls/struct.Certificate.html>
The complete chain of certificates to send during a TLS handshake, plus a private key that matches the end-entity (leaf) certificate. Corresponds to CertifiedKey in the Rust API. <https://docs.rs/rustls/0.20.0/rustls/sign/struct.CertifiedKey.html>
A verifier of client certificates that requires all certificates to be trusted based on a given rustls_root_cert_store. Usable in building server configurations. Connections without such a client certificate will not be accepted.
Alternative to rustls_client_cert_verifier that allows connections with or without a client certificate. If the client offers a certificate, it will be verified (and rejected if it is not valid). If the client does not offer a certificate, the connection will succeed.
A client config that is done being constructed and is now read-only. Under the hood, this object corresponds to an Arc<ClientConfig>. <https://docs.rs/rustls/0.20.0/rustls/struct.ClientConfig.html>
A client config being constructed. A builder can be modified by, e.g. rustls_client_config_builder_load_roots_from_file. Once you're done configuring settings, call rustls_client_config_builder_build to turn it into a *rustls_client_config. This object is not safe for concurrent mutation. Under the hood, it corresponds to a Box<ClientConfig>. <https://docs.rs/rustls/0.20.0/rustls/struct.ConfigBuilder.html>
The TLS Client Hello information provided to a ClientHelloCallback function. sni_name is the SNI servername provided by the client. If the client did not provide an SNI, the length of this rustls_string will be 0. The signature_schemes carries the values supplied by the client or, should the client not use this TLS extension, the default schemes in the rustls library. See: <https://docs.rs/rustls/0.20.0/rustls/internal/msgs/enums/enum.SignatureScheme.html>. 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.
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.
A root certificate store. <https://docs.rs/rustls/0.20.0/rustls/struct.RootCertStore.html>
A server config that is done being constructed and is now read-only. Under the hood, this object corresponds to an Arc<ServerConfig>. <https://docs.rs/rustls/0.20.0/rustls/struct.ServerConfig.html>
A server config being constructed. A builder can be modified by, e.g. rustls_server_config_builder_load_native_roots. Once you're done configuring settings, call rustls_server_config_builder_build to turn it into a *const rustls_server_config. This object is not safe for concurrent mutation. <https://docs.rs/rustls/0.20.0/rustls/struct.ConfigBuilder.html>
A read-only view on a Rust byte slice.
A read-only view of a slice of Rust byte slices.
A read-only view of a slice of multiple Rust &str's (that is, multiple strings). Like rustls_str, this guarantees that each string contains UTF-8 and no NUL bytes. Strings are not NUL-terminated.
A read-only view on a Rust slice of 16-bit integers in platform endianness.
A read-only view on a Rust &str. 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 cipher suite supported by rustls.
Input to a custom certificate verifier callback. See rustls_client_config_builder_dangerous_set_certificate_verifier().