Struct rustls_accepted

pub struct rustls_accepted { /* private fields */ }

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.

Implementations

impl rustls_accepted

#[no_mangle]

pub extern "C" fn rustls_accepted_server_name( accepted: *const rustls_accepted, ) -> rustls_str<'static>

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:

• 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_signature_scheme( accepted: *const rustls_accepted, i: usize, ) -> u16

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:

• i is greater than the number of available cipher suites.
• accepted is NULL.
• rustls_accepted_into_connection has already been called with accepted.

#[no_mangle]

pub extern "C" fn rustls_accepted_cipher_suite( accepted: *const rustls_accepted, i: usize, ) -> u16

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:

• i is greater than the number of available 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.

#[no_mangle]

pub extern "C" fn rustls_accepted_alpn( accepted: *const rustls_accepted, i: usize, ) -> rustls_slice_bytes<'static>

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:

• 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.

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.

#[no_mangle]

pub extern "C" fn rustls_accepted_into_connection( accepted: *mut rustls_accepted, config: *const rustls_server_config, out_conn: *mut *mut rustls_connection, out_alert: *mut *mut rustls_accepted_alert, ) -> rustls_result

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.

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.

#[no_mangle]

pub extern "C" fn rustls_accepted_free(accepted: *mut rustls_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.