thistle-sdk
Thistle SDK documentation
|
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
Go to the source code of this file.
Data Structures | |
struct | rustls_str |
struct | rustls_slice_bytes |
struct | rustls_verify_server_cert_params |
struct | rustls_log_params |
struct | rustls_slice_u16 |
struct | rustls_client_hello |
Variables | |
const struct rustls_supported_ciphersuite * | RUSTLS_ALL_CIPHER_SUITES [9] |
const size_t | RUSTLS_ALL_CIPHER_SUITES_LEN |
const struct rustls_supported_ciphersuite * | RUSTLS_DEFAULT_CIPHER_SUITES [9] |
const size_t | RUSTLS_DEFAULT_CIPHER_SUITES_LEN |
const uint16_t | RUSTLS_ALL_VERSIONS [2] |
const size_t | RUSTLS_ALL_VERSIONS_LEN |
const uint16_t | RUSTLS_DEFAULT_VERSIONS [2] |
const size_t | RUSTLS_DEFAULT_VERSIONS_LEN |
typedef struct rustls_accepted rustls_accepted |
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 rustls_server_config to build a rustls_connection.
typedef struct rustls_acceptor rustls_acceptor |
A buffer and parser for ClientHello bytes. 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(), which doesn't work well for asynchronous I/O.
The general flow is:
typedef struct rustls_certificate rustls_certificate |
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
typedef struct rustls_certified_key rustls_certified_key |
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
typedef struct rustls_client_cert_verifier rustls_client_cert_verifier |
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.
The application can retrieve the certificate, if any, with rustls_connection_get_peer_certificate.
typedef struct rustls_client_config rustls_client_config |
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
typedef struct rustls_client_config_builder rustls_client_config_builder |
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
typedef struct rustls_client_hello rustls_client_hello |
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.
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.
EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as the rustls library is re-evaluating their current approach to client hello handling.
typedef const struct rustls_certified_key *(* rustls_client_hello_callback) (rustls_client_hello_userdata userdata, const struct rustls_client_hello *hello) |
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.
NOTE:
hello
and all its values are only available during the callback invocations.EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as the rustls library is re-evaluating their current approach to client hello handling.
typedef void* rustls_client_hello_userdata |
Any context information the callback will receive when invoked.
typedef struct rustls_connection rustls_connection |
typedef int rustls_io_result |
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.
typedef struct rustls_iovec rustls_iovec |
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.
typedef void(* rustls_log_callback) (void *userdata, const struct rustls_log_params *params) |
typedef size_t rustls_log_level |
typedef struct rustls_log_params rustls_log_params |
typedef rustls_io_result(* rustls_read_callback) (void *userdata, uint8_t *buf, size_t n, size_t *out_n) |
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.
typedef uint32_t rustls_result |
typedef struct rustls_root_cert_store rustls_root_cert_store |
A root certificate store. https://docs.rs/rustls/0.20.0/rustls/struct.RootCertStore.html
typedef struct rustls_server_config rustls_server_config |
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
typedef struct rustls_server_config_builder rustls_server_config_builder |
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
typedef uint32_t(* rustls_session_store_get_callback) (rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, int remove_after, uint8_t *buf, size_t count, size_t *out_n) |
Prototype of a callback that can be installed by the application at the 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.
The buf
points to count
consecutive bytes where the callback is expected to copy the result to. The number of copied bytes needs to be written to out_n
. The callback should not read any data from buf
.
If the value to copy is larger than count
, the callback should never 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 if no session was retrieved.
When remove_after
is != 0, 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.
typedef uint32_t(* rustls_session_store_put_callback) (rustls_session_store_userdata userdata, const struct rustls_slice_bytes *key, const struct rustls_slice_bytes *val) |
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.
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.
typedef void* rustls_session_store_userdata |
Any context information the callback will receive when invoked.
typedef struct rustls_slice_bytes rustls_slice_bytes |
A read-only view on a Rust byte slice.
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.
The memory exposed is available as specified by the function using this in its signature. For instance, when this is a parameter to a callback, the lifetime will usually be the duration of the callback. Functions that receive one of these must not dereference the data pointer beyond the allowed lifetime.
typedef struct rustls_slice_slice_bytes rustls_slice_slice_bytes |
A read-only view of a slice of Rust byte slices.
This is used to pass data from rustls-ffi to callback functions provided by the user of the API. Because Vec and slice are not #[repr(C)]
, we provide access via a pointer to an opaque struct and an accessor method that acts on that struct to get entries of type rustls_slice_bytes
. Internally, the pointee is a &[&[u8]]
.
The memory exposed is available as specified by the function using this in its signature. For instance, when this is a parameter to a callback, the lifetime will usually be the duration of the callback. Functions that receive one of these must not call its methods beyond the allowed lifetime.
typedef struct rustls_slice_str rustls_slice_str |
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.
This is used to pass data from rustls-ffi to callback functions provided by the user of the API. Because Vec and slice are not #[repr(C)]
, we can't provide a straightforward data
and len
structure. Instead, we provide access via a pointer to an opaque struct and accessor methods. Internally, the pointee is a &[&str]
.
The memory exposed is available as specified by the function using this in its signature. For instance, when this is a parameter to a callback, the lifetime will usually be the duration of the callback. Functions that receive one of these must not call its methods beyond the allowed lifetime.
typedef struct rustls_slice_u16 rustls_slice_u16 |
A read-only view on a Rust slice of 16-bit integers in platform endianness.
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.
The memory exposed is available as specified by the function using this in its signature. For instance, when this is a parameter to a callback, the lifetime will usually be the duration of the callback. Functions that receive one of these must not dereference the data pointer beyond the allowed lifetime.
typedef struct rustls_str rustls_str |
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.
The memory exposed is available as specified by the function using this in its signature. For instance, when this is a parameter to a callback, the lifetime will usually be the duration of the callback. Functions that receive one of these must not dereference the data pointer beyond the allowed lifetime.
typedef struct rustls_supported_ciphersuite rustls_supported_ciphersuite |
A cipher suite supported by rustls.
typedef enum rustls_tls_version rustls_tls_version |
Definitions of known TLS protocol versions.
typedef uint32_t(* rustls_verify_server_cert_callback) (rustls_verify_server_cert_user_data userdata, const struct rustls_verify_server_cert_params *params) |
typedef struct rustls_verify_server_cert_params rustls_verify_server_cert_params |
Input to a custom certificate verifier callback. See rustls_client_config_builder_dangerous_set_certificate_verifier().
typedef void* rustls_verify_server_cert_user_data |
User-provided input to a custom certificate verifier callback. See rustls_client_config_builder_dangerous_set_certificate_verifier().
typedef rustls_io_result(* rustls_write_callback) (void *userdata, const uint8_t *buf, size_t n, size_t *out_n) |
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.
typedef rustls_io_result(* rustls_write_vectored_callback) (void *userdata, const struct rustls_iovec *iov, size_t count, size_t *out_n) |
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.
enum rustls_result |
enum rustls_tls_version |
Definitions of known TLS protocol versions.
Enumerator | |
---|---|
RUSTLS_TLS_VERSION_SSLV2 | |
RUSTLS_TLS_VERSION_SSLV3 | |
RUSTLS_TLS_VERSION_TLSV1_0 | |
RUSTLS_TLS_VERSION_TLSV1_1 | |
RUSTLS_TLS_VERSION_TLSV1_2 | |
RUSTLS_TLS_VERSION_TLSV1_3 |
struct rustls_slice_bytes rustls_accepted_alpn | ( | const struct rustls_accepted * | accepted, |
size_t | i | ||
) |
Get the i'th in the list of ALPN protocols requested in the ClientHello.
accepted: The rustls_accepted to access. i: Fetch the ALPN value at this offset.
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:
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 by the caller and does not need to be freed.
If you are calling this from Rust, note that the 'static
lifetime in the return signature is fake and must not be relied upon.
uint16_t rustls_accepted_cipher_suite | ( | const struct rustls_accepted * | accepted, |
size_t | i | ||
) |
Get the i'th in the list of cipher suites offered in the ClientHello.
Parameters:
accepted: The rustls_accepted to access. i: Fetch the cipher suite at this offset.
Returns:
A cipher suite value from https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4.
This will be 0 in these cases:
accepted
.Note that 0 is technically a valid cipher suite "TLS_NULL_WITH_NULL_NULL", but this library will never support null ciphers.
void rustls_accepted_free | ( | struct rustls_accepted * | accepted | ) |
Free a rustls_accepted.
Parameters:
accepted: The rustls_accepted to free.
Calling with NULL is fine. Must not be called twice with the same value.
rustls_result rustls_accepted_into_connection | ( | struct rustls_accepted * | accepted, |
const struct rustls_server_config * | config, | ||
struct rustls_connection ** | out_conn | ||
) |
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.
Returns:
accepted
parameter was successfully transformed into a rustls_connection, and *out_conn was written to.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.
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.
struct rustls_str rustls_accepted_server_name | ( | const struct rustls_accepted * | accepted | ) |
Get the server name indication (SNI) from the ClientHello.
Parameters:
accepted: The rustls_accepted to access.
Returns:
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 by the caller and does not need to be freed.
This will be a zero-length rustls_str in these error cases:
accepted
parameter was NULL.accepted
parameter was already transformed into a connection with rustls_accepted_into_connection. uint16_t rustls_accepted_signature_scheme | ( | const struct rustls_accepted * | accepted, |
size_t | i | ||
) |
Get the i'th 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:
accepted: The rustls_accepted to access. i: Fetch the signature scheme at this offset.
Returns:
A TLS Signature Scheme from https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-signaturescheme
This will be 0 in these cases:
accepted
. rustls_result rustls_acceptor_accept | ( | struct rustls_acceptor * | acceptor, |
struct rustls_accepted ** | out_accepted | ||
) |
Parse all TLS bytes read so far. If those bytes make up a ClientHello, create a rustls_accepted from them.
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.
Returns:
Memory and lifetimes:
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.
Calling rustls_acceptor_accept()
multiple times on the same rustls_acceptor
is acceptable from a memory perspective but pointless from a protocol perspective.
void rustls_acceptor_free | ( | struct rustls_acceptor * | acceptor | ) |
Free a rustls_acceptor.
Parameters:
acceptor: The rustls_acceptor to free.
Calling with NULL is fine. Must not be called twice with the same value.
struct rustls_acceptor * rustls_acceptor_new | ( | void | ) |
Create and return a new rustls_acceptor.
Caller owns the pointed-to memory and must eventually free it with rustls_acceptor_free()
.
rustls_io_result rustls_acceptor_read_tls | ( | struct rustls_acceptor * | acceptor, |
rustls_read_callback | callback, | ||
void * | userdata, | ||
size_t * | out_n | ||
) |
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.
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 this function call returns. 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.
Returns:
rustls_acceptor_accept()
next.This function passes through return values from callback
. Typically callback
should return an errno value. See rustls_read_callback()
for more details.
const struct rustls_supported_ciphersuite * rustls_all_ciphersuites_get_entry | ( | size_t | i | ) |
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.
size_t rustls_all_ciphersuites_len | ( | void | ) |
Return the length of rustls' list of supported cipher suites.
rustls_result rustls_certificate_get_der | ( | const struct rustls_certificate * | cert, |
const uint8_t ** | out_der_data, | ||
size_t * | out_der_len | ||
) |
Get the DER data of the certificate itself. The data is owned by the certificate and has the same lifetime.
rustls_result rustls_certified_key_build | ( | const uint8_t * | cert_chain, |
size_t | cert_chain_len, | ||
const uint8_t * | private_key, | ||
size_t | private_key_len, | ||
const struct rustls_certified_key ** | certified_key_out | ||
) |
Build a rustls_certified_key
from a certificate chain and a 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.
private_key
must point to a buffer of private_key_len
bytes, containing a PEM-encoded private key in either PKCS#1 or PKCS#8 format.
On success, this writes a pointer to the newly created rustls_certified_key
in certified_key_out
. That pointer must later be freed with rustls_certified_key_free
to avoid memory leaks. Note that internally, this is an atomically reference-counted pointer, so even after the original caller has called rustls_certified_key_free
, other objects 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.
Typically, you will build a rustls_certified_key
, use it to create a rustls_server_config
(which increments the reference count), and then immediately call rustls_certified_key_free
. That leaves the rustls_server_config
in possession of the sole reference, so the rustls_certified_key
's memory will automatically be released when the rustls_server_config
is freed.
rustls_result rustls_certified_key_clone_with_ocsp | ( | const struct rustls_certified_key * | certified_key, |
const struct rustls_slice_bytes * | ocsp_response, | ||
const struct rustls_certified_key ** | cloned_key_out | ||
) |
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.
void rustls_certified_key_free | ( | const struct rustls_certified_key * | key | ) |
"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.
const struct rustls_certificate * rustls_certified_key_get_certificate | ( | const struct rustls_certified_key * | certified_key, |
size_t | i | ||
) |
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.
void rustls_client_cert_verifier_free | ( | const struct rustls_client_cert_verifier * | verifier | ) |
"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.
const struct rustls_client_cert_verifier * rustls_client_cert_verifier_new | ( | const struct rustls_root_cert_store * | store | ) |
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.
void rustls_client_cert_verifier_optional_free | ( | const struct rustls_client_cert_verifier_optional * | verifier | ) |
"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.
const struct rustls_client_cert_verifier_optional * rustls_client_cert_verifier_optional_new | ( | const struct rustls_root_cert_store * | store | ) |
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.
const struct rustls_client_config * rustls_client_config_builder_build | ( | struct rustls_client_config_builder * | builder | ) |
Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config (read-only).
rustls_result rustls_client_config_builder_dangerous_set_certificate_verifier | ( | struct rustls_client_config_builder * | config_builder, |
rustls_verify_server_cert_callback | callback | ||
) |
Set a custom server certificate verifier.
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 will be passed to the callback. Otherwise the userdata param passed to the callback will be NULL.
The callback must be safe to call on any thread at any time, including multiple concurrent calls. So, for instance, if the callback mutates userdata (or other shared state), it must use synchronization primitives to make such mutation safe.
The callback receives certificate chain information as raw bytes. Currently this library offers no functions for C code to parse the certificates, so you'll need to bring your own certificate parsing library if you need to parse them.
If you intend to write a verifier that accepts all certificates, be aware that special measures are required for IP addresses. Rustls currently (0.20.0) doesn't support building a ClientConnection with an IP address (because it's not a valid DnsNameRef). One workaround is to detect IP addresses and rewrite them to example.invalid
, and also to disable SNI via rustls_client_config_builder_set_enable_sni (IP addresses don't need SNI).
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.
void rustls_client_config_builder_free | ( | struct rustls_client_config_builder * | config | ) |
"Free" a client_config_builder without building it into a rustls_client_config. Normally builders are built into rustls_client_config via rustls_client_config_builder_build
and may not be free'd or otherwise used afterwards. Use free only when the building of a config has to be aborted before a config was created.
rustls_result rustls_client_config_builder_load_roots_from_file | ( | struct rustls_client_config_builder * | config_builder, |
const char * | filename | ||
) |
Add trusted root certificates from the named file, which should contain PEM-formatted certificates.
struct rustls_client_config_builder * rustls_client_config_builder_new | ( | void | ) |
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.
rustls_result rustls_client_config_builder_new_custom | ( | const struct rustls_supported_ciphersuite *const * | cipher_suites, |
size_t | cipher_suites_len, | ||
const uint16_t * | tls_versions, | ||
size_t | tls_versions_len, | ||
struct rustls_client_config_builder ** | builder_out | ||
) |
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.
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.
versions
will only be used during the call and the application retains ownership. len
is the number of consecutive uint16_t
pointed to by versions
.
rustls_result rustls_client_config_builder_set_alpn_protocols | ( | struct rustls_client_config_builder * | builder, |
const struct rustls_slice_bytes * | protocols, | ||
size_t | len | ||
) |
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.
This function makes a copy of the data in protocols
and does not retain any pointers, so the caller can free the pointed-to memory after calling.
https://docs.rs/rustls/0.20.0/rustls/client/struct.ClientConfig.html#structfield.alpn_protocols
rustls_result rustls_client_config_builder_set_certified_key | ( | struct rustls_client_config_builder * | builder, |
const struct rustls_certified_key *const * | certified_keys, | ||
size_t | certified_keys_len | ||
) |
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.
The built configuration will keep a reference to all certified keys provided. The client may rustls_certified_key_free()
afterwards without the configuration losing them. The same certified key may also be used in multiple configs.
EXPERIMENTAL: installing a client authentication callback will replace any configured certified keys and vice versa.
void rustls_client_config_builder_set_enable_sni | ( | struct rustls_client_config_builder * | config, |
bool | enable | ||
) |
Enable or disable SNI. https://docs.rs/rustls/0.20.0/rustls/struct.ClientConfig.html#structfield.enable_sni
rustls_result rustls_client_config_builder_use_roots | ( | struct rustls_client_config_builder * | config_builder, |
const struct rustls_root_cert_store * | roots | ||
) |
Use the trusted root certificates from the provided store.
This replaces any trusted roots already configured with copies from roots
. This adds 1 to the refcount for roots
. When you call rustls_client_config_free or rustls_client_config_builder_free, those will subtract 1 from the refcount for roots
.
void rustls_client_config_free | ( | const struct rustls_client_config * | config | ) |
"Free" a rustls_client_config previously returned from rustls_client_config_builder_build. Since rustls_client_config is actually an atomically reference-counted pointer, extant client connections may still hold an internal reference to the Rust object. 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.
rustls_result rustls_client_connection_new | ( | const struct rustls_client_config * | config, |
const char * | hostname, | ||
struct rustls_connection ** | conn_out | ||
) |
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.
rustls_result rustls_client_hello_select_certified_key | ( | const struct rustls_client_hello * | hello, |
const struct rustls_certified_key *const * | certified_keys, | ||
size_t | certified_keys_len, | ||
const struct rustls_certified_key ** | out_key | ||
) |
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.
This is intended for servers that are configured with several keys for the same domain name(s), for example ECDSA and RSA types. The presented keys are inspected in the order given and keys first in the list are given preference, all else being equal. However rustls is free to choose whichever it considers to be the best key with its knowledge about security issues and possible future extensions of the protocol.
Return RUSTLS_RESULT_OK if a key was selected and RUSTLS_RESULT_NOT_FOUND if none was suitable.
void rustls_connection_free | ( | struct rustls_connection * | conn | ) |
Free a rustls_connection. Calling with NULL is fine. Must not be called twice with the same value.
void rustls_connection_get_alpn_protocol | ( | const struct rustls_connection * | conn, |
const uint8_t ** | protocol_out, | ||
size_t * | protocol_out_len | ||
) |
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
const struct rustls_supported_ciphersuite * rustls_connection_get_negotiated_ciphersuite | ( | const struct rustls_connection * | conn | ) |
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
const struct rustls_certificate * rustls_connection_get_peer_certificate | ( | const struct rustls_connection * | conn, |
size_t | i | ||
) |
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
uint16_t rustls_connection_get_protocol_version | ( | 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. 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
bool rustls_connection_is_handshaking | ( | const struct rustls_connection * | conn | ) |
rustls_result rustls_connection_process_new_packets | ( | struct rustls_connection * | conn | ) |
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
rustls_result rustls_connection_read | ( | struct rustls_connection * | conn, |
uint8_t * | buf, | ||
size_t | count, | ||
size_t * | out_n | ||
) |
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."
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. https://docs.rs/rustls/0.20.0/rustls/struct.Reader.html#method.read
rustls_io_result rustls_connection_read_tls | ( | struct rustls_connection * | conn, |
rustls_read_callback | callback, | ||
void * | userdata, | ||
size_t * | out_n | ||
) |
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
void rustls_connection_send_close_notify | ( | struct rustls_connection * | conn | ) |
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
void rustls_connection_set_buffer_limit | ( | struct rustls_connection * | conn, |
size_t | n | ||
) |
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
void rustls_connection_set_log_callback | ( | struct rustls_connection * | conn, |
rustls_log_callback | cb | ||
) |
Set the logging callback for this connection. The log callback will be invoked with the userdata parameter previously set by rustls_connection_set_userdata, or NULL if no userdata was set.
void rustls_connection_set_userdata | ( | struct rustls_connection * | conn, |
void * | userdata | ||
) |
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.
bool rustls_connection_wants_read | ( | const struct rustls_connection * | conn | ) |
bool rustls_connection_wants_write | ( | const struct rustls_connection * | conn | ) |
rustls_result rustls_connection_write | ( | struct rustls_connection * | conn, |
const uint8_t * | buf, | ||
size_t | count, | ||
size_t * | out_n | ||
) |
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
rustls_io_result rustls_connection_write_tls | ( | struct rustls_connection * | conn, |
rustls_write_callback | callback, | ||
void * | userdata, | ||
size_t * | out_n | ||
) |
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
rustls_io_result rustls_connection_write_tls_vectored | ( | struct rustls_connection * | conn, |
rustls_write_vectored_callback | callback, | ||
void * | userdata, | ||
size_t * | out_n | ||
) |
Write all available TLS bytes to the network. The actual network I/O is performed by callback
, which you provide. Rustls will invoke your callback with an array of rustls_slice_bytes, each containing a buffer with TLS bytes to send. You don't have to write them all, just as many as you are willing. 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
const struct rustls_supported_ciphersuite * rustls_default_ciphersuites_get_entry | ( | size_t | i | ) |
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.
size_t rustls_default_ciphersuites_len | ( | void | ) |
Return the length of rustls' list of default cipher suites.
void rustls_error | ( | unsigned int | result, |
char * | buf, | ||
size_t | len, | ||
size_t * | out_n | ||
) |
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.
struct rustls_str rustls_log_level_str | ( | rustls_log_level | level | ) |
Return a rustls_str containing the stringified version of a log level.
bool rustls_result_is_cert_error | ( | unsigned int | result | ) |
rustls_result rustls_root_cert_store_add_pem | ( | struct rustls_root_cert_store * | store, |
const uint8_t * | pem, | ||
size_t | pem_len, | ||
bool | strict | ||
) |
Add one or more certificates to the root cert store using PEM encoded data.
When strict
is true an error will return a CertificateParseError
result. So will an attempt to parse data that has zero certificates.
When strict
is false, unparseable root certificates will be ignored. This may be useful on systems that have syntactically invalid root certificates.
void rustls_root_cert_store_free | ( | struct rustls_root_cert_store * | store | ) |
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.
struct rustls_root_cert_store * rustls_root_cert_store_new | ( | void | ) |
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
const struct rustls_server_config * rustls_server_config_builder_build | ( | struct rustls_server_config_builder * | builder | ) |
Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config (read-only).
void rustls_server_config_builder_free | ( | struct rustls_server_config_builder * | config | ) |
"Free" a server_config_builder without building it into a rustls_server_config. Normally builders are built into rustls_server_configs via rustls_server_config_builder_build
and may not be free'd or otherwise used afterwards. Use free only when the building of a config has to be aborted before a config was created.
struct rustls_server_config_builder * rustls_server_config_builder_new | ( | void | ) |
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.
rustls_result rustls_server_config_builder_new_custom | ( | const struct rustls_supported_ciphersuite *const * | cipher_suites, |
size_t | cipher_suites_len, | ||
const uint16_t * | tls_versions, | ||
size_t | tls_versions_len, | ||
struct rustls_server_config_builder ** | builder_out | ||
) |
Create a rustls_server_config_builder. Caller owns the memory and must eventually call rustls_server_config_builder_build, then free the resulting rustls_server_config. Specify cipher suites in preference order; the cipher_suites
parameter must point to an array containing len
pointers to rustls_supported_ciphersuite
previously obtained from rustls_all_ciphersuites_get_entry()
. Set the TLS protocol versions to use when negotiating a TLS session.
tls_version
is the version of the protocol, as defined in rfc8446, ch. 4.2.1 and end of ch. 5.1. Some values are defined in rustls_tls_version
for convenience.
versions
will only be used during the call and the application retains ownership. len
is the number of consecutive uint16_t
pointed to by versions
.
rustls_result rustls_server_config_builder_set_alpn_protocols | ( | struct rustls_server_config_builder * | builder, |
const struct rustls_slice_bytes * | protocols, | ||
size_t | len | ||
) |
Set the ALPN protocol list to the given protocols. protocols
must point to a buffer of rustls_slice_bytes
(built by the caller) with len
elements. Each element of the buffer must point to a slice of bytes that contains a single ALPN protocol from https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids.
This function makes a copy of the data in protocols
and does not retain any pointers, so the caller can free the pointed-to memory after calling.
https://docs.rs/rustls/0.20.0/rustls/server/struct.ServerConfig.html#structfield.alpn_protocols
rustls_result rustls_server_config_builder_set_certified_keys | ( | struct rustls_server_config_builder * | builder, |
const struct rustls_certified_key *const * | certified_keys, | ||
size_t | certified_keys_len | ||
) |
Provide the configuration a list of certificates where the connection will select the first one that is compatible with the client's signature verification capabilities. Servers that want to support both ECDSA and RSA certificates will want the ECSDA to go first in the list.
The built configuration will keep a reference to all certified keys provided. The client may rustls_certified_key_free()
afterwards without the configuration losing them. The same certified key may also be used in multiple configs.
EXPERIMENTAL: installing a client_hello callback will replace any configured certified keys and vice versa.
void rustls_server_config_builder_set_client_verifier | ( | struct rustls_server_config_builder * | builder, |
const struct rustls_client_cert_verifier * | verifier | ||
) |
Create a rustls_server_config_builder for TLS sessions that require valid client certificates. The passed rustls_client_cert_verifier may be used in several builders. For memory lifetime, see rustls_server_config_builder_new.
void rustls_server_config_builder_set_client_verifier_optional | ( | struct rustls_server_config_builder * | builder, |
const struct rustls_client_cert_verifier_optional * | verifier | ||
) |
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.
rustls_result rustls_server_config_builder_set_hello_callback | ( | struct rustls_server_config_builder * | builder, |
rustls_client_hello_callback | callback | ||
) |
Register a callback to be invoked when a connection created from this config sees a TLS ClientHello message. If userdata
has been set with rustls_connection_set_userdata, it will be passed to the callback. Otherwise the userdata param passed to the callback will be NULL.
Any existing ResolvesServerCert
implementation currently installed in the rustls_server_config
will be replaced. This also means registering twice will overwrite the first registration. It is not permitted to pass a NULL value for callback
.
EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as the rustls library is re-evaluating their current approach to client hello handling. Installing a client_hello callback will replace any configured certified keys and vice versa. Same holds true for the set_certified_keys variant.
rustls_result rustls_server_config_builder_set_ignore_client_order | ( | struct rustls_server_config_builder * | builder, |
bool | ignore | ||
) |
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
rustls_result rustls_server_config_builder_set_persistence | ( | struct rustls_server_config_builder * | builder, |
rustls_session_store_get_callback | get_cb, | ||
rustls_session_store_put_callback | put_cb | ||
) |
Register callbacks for persistence of TLS session IDs and secrets. Both keys and values are highly sensitive data, containing enough information to break the security of the connections involved.
If userdata
has been set with rustls_connection_set_userdata, it will be passed to the callbacks. Otherwise the userdata param passed to the callbacks will be NULL.
void rustls_server_config_free | ( | const struct rustls_server_config * | config | ) |
"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.
rustls_result rustls_server_connection_get_sni_hostname | ( | const struct rustls_connection * | conn, |
uint8_t * | buf, | ||
size_t | count, | ||
size_t * | out_n | ||
) |
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
rustls_result rustls_server_connection_new | ( | const struct rustls_server_config * | config, |
struct rustls_connection ** | conn_out | ||
) |
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.
struct rustls_slice_bytes rustls_slice_slice_bytes_get | ( | const struct rustls_slice_slice_bytes * | input, |
size_t | n | ||
) |
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}.
size_t rustls_slice_slice_bytes_len | ( | const struct rustls_slice_slice_bytes * | input | ) |
Return the length of the outer slice. If the input pointer is NULL, returns 0.
struct rustls_str rustls_slice_str_get | ( | const struct rustls_slice_str * | input, |
size_t | n | ||
) |
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}.
size_t rustls_slice_str_len | ( | const struct rustls_slice_str * | input | ) |
Return the length of the outer slice. If the input pointer is NULL, returns 0.
struct rustls_str rustls_supported_ciphersuite_get_name | ( | const struct rustls_supported_ciphersuite * | supported_ciphersuite | ) |
Returns the name of the ciphersuite as a rustls_str
. If the provided ciphersuite is invalid, the rustls_str will contain the empty string. The lifetime of the rustls_str
is the lifetime of the program, it does not need to be freed.
uint16_t rustls_supported_ciphersuite_get_suite | ( | const struct rustls_supported_ciphersuite * | supported_ciphersuite | ) |
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.
struct rustls_str rustls_version | ( | void | ) |
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.
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |