Struct rustls_connection

pub struct rustls_connection { /* private fields */ }

A C representation of a Rustls Connection.

Implementations

impl rustls_connection

#[no_mangle]

pub extern "C" fn rustls_connection_set_userdata( conn: *mut rustls_connection, userdata: *mut c_void, )

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.

#[no_mangle]

pub extern "C" fn rustls_connection_set_log_callback( conn: *mut rustls_connection, cb: rustls_log_callback, )

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.

#[no_mangle]

pub extern "C" fn rustls_connection_read_tls( conn: *mut rustls_connection, callback: rustls_read_callback, userdata: *mut c_void, out_n: *mut size_t, ) -> rustls_io_result

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/latest/rustls/enum.Connection.html#method.read_tls

#[no_mangle]

pub extern "C" fn rustls_connection_write_tls( conn: *mut rustls_connection, callback: rustls_write_callback, userdata: *mut c_void, out_n: *mut size_t, ) -> rustls_io_result

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/latest/rustls/enum.Connection.html#method.write_tls

#[no_mangle]

pub extern "C" fn rustls_connection_write_tls_vectored( conn: *mut rustls_connection, callback: rustls_write_vectored_callback, userdata: *mut c_void, out_n: *mut size_t, ) -> rustls_io_result

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/latest/rustls/struct.Writer.html#method.write_vectored

#[no_mangle]

pub extern "C" fn rustls_connection_process_new_packets( conn: *mut rustls_connection, ) -> rustls_result

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/latest/rustls/enum.Connection.html#method.process_new_packets

#[no_mangle]

pub extern "C" fn rustls_connection_wants_read( conn: *const rustls_connection, ) -> bool

https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_read

#[no_mangle]

pub extern "C" fn rustls_connection_wants_write( conn: *const rustls_connection, ) -> bool

https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.wants_write

#[no_mangle]

pub extern "C" fn rustls_connection_is_handshaking( conn: *const rustls_connection, ) -> bool

Returns true if the connection is currently performing the TLS handshake.

Note: This may return false while there are still handshake packets waiting to be extracted and transmitted with rustls_connection_write_tls().

See the rustls documentation for more information.

https://docs.rs/rustls/latest/rustls/struct.CommonState.html#method.is_handshaking

#[no_mangle]

pub extern "C" fn rustls_connection_handshake_kind( conn: *const rustls_connection, ) -> rustls_handshake_kind

Returns a rustls_handshake_kind describing the rustls_connection.

#[no_mangle]

pub extern "C" fn rustls_connection_set_buffer_limit( conn: *mut rustls_connection, n: usize, )

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/latest/rustls/enum.Connection.html#method.set_buffer_limit

#[no_mangle]

pub extern "C" fn rustls_connection_send_close_notify( conn: *mut rustls_connection, )

Queues a close_notify fatal alert to be sent in the next write_tls call. https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.send_close_notify

#[no_mangle]

pub extern "C" fn rustls_connection_refresh_traffic_keys( conn: *mut rustls_connection, ) -> rustls_result

Queues a TLS1.3 key_update message to refresh a connection’s keys.

Rustls internally manages key updates as required and so this function should seldom be used. See the Rustls documentation for important caveats and suggestions on occasions that merit its use.

https://docs.rs/rustls/latest/rustls/struct.ConnectionCommon.html#method.refresh_traffic_keys

#[no_mangle]

pub extern "C" fn rustls_connection_get_peer_certificate<'a>( conn: *const rustls_connection, i: size_t, ) -> *const rustls_certificate<'a>

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/latest/rustls/enum.Connection.html#method.peer_certificates

#[no_mangle]

pub extern "C" fn rustls_connection_get_alpn_protocol( conn: *const rustls_connection, protocol_out: *mut *const u8, protocol_out_len: *mut usize, )

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/latest/rustls/enum.Connection.html#method.alpn_protocol

#[no_mangle]

pub extern "C" fn rustls_connection_get_protocol_version( conn: *const rustls_connection, ) -> u16

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/latest/rustls/enum.Connection.html#method.protocol_version https://docs.rs/rustls/latest/rustls/internal/msgs/enums/enum.ProtocolVersion.html

#[no_mangle]

pub extern "C" fn rustls_connection_get_negotiated_ciphersuite( conn: *const rustls_connection, ) -> u16

Retrieves the IANA registered cipher suite identifier agreed with the peer.

This returns TLS_NULL_WITH_NULL_NULL (0x0000) until the ciphersuite is agreed.

#[no_mangle]

pub extern "C" fn rustls_connection_get_negotiated_ciphersuite_name( conn: *const rustls_connection, ) -> rustls_str<'static>

Retrieves the cipher suite name agreed with the peer.

This returns “” until the ciphersuite is agreed.

The lifetime of the rustls_str is the lifetime of the program, it does not need to be freed.

https://docs.rs/rustls/latest/rustls/enum.Connection.html#method.negotiated_cipher_suite

#[no_mangle]

pub extern "C" fn rustls_connection_get_negotiated_key_exchange_group( conn: *const rustls_connection, ) -> u16

Retrieves the IANA registered supported group identifier agreed with the peer.

This returns Reserved (0x0000) until the key exchange group is agreed.

#[no_mangle]

pub extern "C" fn rustls_connection_get_negotiated_key_exchange_group_name( conn: *const rustls_connection, ) -> rustls_str<'static>

Retrieves the key exchange group name agreed with the peer.

This returns “” until the key exchange group is agreed.

The lifetime of the rustls_str is the lifetime of the program, it does not need to be freed.

#[no_mangle]

pub extern "C" fn rustls_connection_write( conn: *mut rustls_connection, buf: *const u8, count: size_t, out_n: *mut size_t, ) -> rustls_result

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/latest/rustls/struct.Writer.html#method.write

#[no_mangle]

pub extern "C" fn rustls_connection_read( conn: *mut rustls_connection, buf: *mut u8, count: size_t, out_n: *mut size_t, ) -> rustls_result

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/latest/rustls/struct.Reader.html#method.read

#[no_mangle]

pub extern "C" fn rustls_connection_fips( conn: *const rustls_connection, ) -> bool

Returns true if the rustls_connection was made with a rustls_client_config or rustls_server_config that is FIPS compatible.

This is different from rustls_crypto_provider_fips which is concerned only with cryptography, whereas this also covers TLS-level configuration that NIST recommends, as well as ECH HPKE suites if applicable.

#[no_mangle]

pub extern "C" fn rustls_connection_free(conn: *mut rustls_connection)

Free a rustls_connection. Calling with NULL is fine. Must not be called twice with the same value.