Struct libtls::tls::Tls

pub struct Tls(_, _);

TLS connection clients and servers.

A TLS connection is represented as a Tls object called a "context". A new context is created by either the Tls::client or Tls::server functions. Tls::client is used in TLS client programs, Tls::server in TLS server programs.

The context can then be configured with the configure method. The same Config object can be used to configure multiple contexts.

After configuration, connect can be called on objects created with Tls::client, and accept_socket on objects created with Tls::server.

After use, a TLS context should be closed with tls_close, which is also called when the object is dropped. A TLS context can be reset by calling reset, allowing for it to be reused.

Methods

impl Tls

pub fn client() -> Result<Self>

Create a new TLS client.

The client is used to create connections in TLS client programs.

See also

tls_client(3)

pub fn server() -> Result<Self>

Create a new TLS server.

The server is used to accept connections in TLS server programs.

See also

tls_server(3)

pub fn configure(&mut self, config: &Config) -> Result<()>

Configure the TLS context.

The configure method configures a TLS connection. The same Config object can be used to configure multiple contexts.

See also

tls_configure(3)

pub unsafe fn from_sys(tls: *mut tls) -> Self

Wrap a raw C tls object.

Safety

This function assumes that the raw pointer is valid, and takes ownership of the libtls object. Do not call tls_free yourself, since the drop destructor will take care of it.

Panics

Panics if tls is a null pointer.

pub fn reset(&mut self)

Reset the TLS connection.

A TLS context can be reset, allowing for it to be reused.

See also

tls_reset(3)

pub fn accept_fds(&mut self, fd_read: RawFd, fd_write: RawFd) -> Result<Tls>

Accept a new TLS connection on a pair of existing file descriptors.

The accept_fds method can accept a new client connection on a pair of existing file descriptors.

See also

tls_accept_fds(3)

pub fn accept_socket(&mut self, socket: RawFd) -> Result<Tls>

Accept a new TLS connection on a socket.

The accept_socket method can accept a new client connection on an already established socket connection. The socket RawFd is not closed after dropping the object.

See also

accept_io tls_accept_socket(3)

pub fn accept_raw_fd<T>(&mut self, raw_fd: &T) -> Result<Tls> where
    T: AsRawFd, 

Accept a new TLS connection on an established connection.

The accept_raw_fd method can accept a new client connection on an already established connection that implements the AsRawFd trait, e.g. TcpStream. It is a wrapper function on top of accept_socket.

See also

accept_socket

pub unsafe fn accept_cbs(
    &mut self,
    read_cb: TlsReadCb,
    write_cb: TlsWriteCb,
    cb_arg: Option<*mut c_void>
) -> Result<Tls>

Accept a new TLS connection with custom I/O callbacks.

The accept_cbs method allows read and write callback functions to handle data transfers. The specified cb_arg parameter is passed back to the functions, and can contain a pointer to any caller-specified data.

Safety

Use this function with caution and only when there's no better alternative. The optional cb_arg is an unsafe pointer to an arbitrary data object and the read_cb and write_cb callbacks are C-style function pointers.

See also

tls_accept_cbs(3)

pub fn connect(&mut self, host: &str, port: Option<&str>) -> Result<()>

Initiate a new TLS connection.

The connect method initiates a new client connection on a Tls object that has been configured with configure. This method will create a new socket, connect to the specified host and port, and then establish a secure connection. The port may be numeric or a service name. If it is None, then a host of the format "hostname:port" is permitted. The name to use for verification is inferred from the host value.

See also

tls_connect(3)

pub fn connect_fds(
    &mut self,
    fd_read: RawFd,
    fd_write: RawFd,
    servername: &str
) -> Result<()>

Initiate a new TLS connection over a pair of existing file descriptors.

The connect_fds method is a variant of connect that establishes a secure connection over a pair of existing file descriptors. The servername argument is used for verification of the TLS server name.

See also

tls_connect_fds(3)

pub fn connect_servername<A: ToSocketAddrs>(
    &mut self,
    host: A,
    servername: &str
) -> Result<()>

Initiate a new TLS connection with a specified server name.

The connect_servername method has the same behaviour as connect, however the name to use for verification is explicitly provided, for the case where the TLS server name differs from the DNS name.

See also

tls_connect_servername(3)

pub fn connect_socket(&mut self, socket: RawFd, servername: &str) -> Result<()>

Initiate a new TLS connection over an established socket.

The connect_socket method is a variant of connect_servername that can upgrade an already existing socket to TLS. The socket RawFd is not closed after dropping the object.

See also

tls_connect_socket(3)

pub fn connect_raw_fd<T>(&mut self, raw_fd: &T, servername: &str) -> Result<()> where
    T: AsRawFd, 

Initiate a new TLS connection over an established connection.

The connect_raw_fd method can upgrade a connection to TLS on an already established connection that implements the AsRawFd] trait, e.g. [TcpStream]. It is a wrapper function on top of [connect_socket`.

See also

connect_socket

pub unsafe fn connect_cbs(
    &mut self,
    read_cb: TlsReadCb,
    write_cb: TlsWriteCb,
    cb_arg: Option<*mut c_void>,
    servername: &str
) -> Result<()>

Initiate a new TLS connection with custom I/O callbacks.

The connect_cbs method allows read and write callback functions to handle data transfers. The specified cb_arg parameter is passed back to the functions, and can contain a pointer to any caller-specified data. The servername is used to validate the TLS server name.

Safety

Use this function with caution and only when there's no better alternative. The optional cb_arg is an unsafe pointer to an arbitrary data object and the read_cb and write_cb callbacks are C-style function pointers.

See also

tls_connect_cbs(3)

pub fn tls_handshake(&mut self) -> Result<isize>

Explicitly perform the TLS handshake.

The tls_handshake method explicitly performs the TLS handshake. It is only necessary to call this method if you need to guarantee that the handshake has completed, as both tls_read and tls_write automatically perform the TLS handshake when necessary.

The tls_read, tls_write, tls_handshake, and tls_close methods return -1 on error and also have two special return values:

• TLS_WANT_POLLIN: The underlying read file descriptor needs to be readable in order to continue.
• TLS_WANT_POLLOUT: The underlying write file descriptor needs to be writeable in order to continue.

In the case of blocking file descriptors, the same function call should be repeated immediately. In the case of non-blocking file descriptors, the same function call should be repeated when the required condition has been met.

On success, the tls_read and tls_write methods return a size and the tls_handshake and tls_close methods return 0.

See also

tls_handshake(3)

pub fn tls_read(&mut self, buf: &mut [u8]) -> Result<isize>

Read bytes from the TLS connection.

The tls_read method reads bytes of data from the connection into buf. It returns the amount of data read or an error as described in tls_handshake.

This function is provided for the completeness of the API, programs should use the implemented read function of the Read trait instead.

See also

tls_handshake, read, tls_read(3)

pub fn tls_write(&mut self, buf: &[u8]) -> Result<isize>

Write bytes to the TLS connection.

The tls_write method writes bytes of data from buf to connection. It returns the amount of data written or an error as described in tls_handshake.

This function is provided for the completeness of the API, programs should use the implemented write function of the Write trait instead.

See also

tls_handshake, write, tls_write(3)

pub fn tls_close(&mut self) -> Result<isize>

Close the TLS connection.

The tls_close method closes a connection after use. Only the TLS layer will be shut down and the caller is responsible for closing the file descriptors, unless the connection was established using connect or connect_servername.

It returns 0 on success or an error as decribed in tls_handshake.

See also

tls_handshake, tls_write(3)

pub fn close(&mut self) -> Result<()>

Close the TLS connection.

The close method closes a connection after use. It calls tls_close and converts the result into an io::Error.

See also

tls_close

pub fn peer_cert_provided(&mut self) -> bool

Check for peer certificate.

The peer_cert_provided methods checks if the peer has provided a certificate.

See also

tls_peer_cert_provided(3)

pub fn peer_cert_contains_name(&mut self, name: &str) -> Result<bool>

Check if the peer certificate includes a matching name.

The peer_cert_contains_name method checks if the peer has provided a certificate that contains a SAN or CN that matches name.

See also

tls_peer_cert_contains_name(3)

pub fn peer_cert_hash(&mut self) -> Result<String>

Return hash of the peer certificate.

The peer_cert_hash method returns a string corresponding to a hash of the raw peer certificate prefixed by a hash name followed by a colon. The hash currently used is SHA256, though this could change in the future.

The hash string for a certificate in file mycert.crt can be generated using the commands:

h=$(openssl x509 -outform der -in mycert.crt | sha256)
printf "SHA256:${h}\n"

See also

tls_peer_cert_hash(3)

pub fn peer_cert_issuer(&mut self) -> Result<String>

Return the issuer of the peer certificate.

The peer_cert_issuer method returns a string corresponding to the issuer of the peer certificate.

See also

tls_peer_cert_issuer(3)

pub fn peer_cert_subject(&mut self) -> Result<String>

Return the subject of the peer certificate.

The peer_cert_subject method returns a string corresponding to the subject of the peer certificate.

See also

tls_peer_cert_subject(3)

pub fn peer_cert_notbefore(&mut self) -> Result<SystemTime>

Return the start of the validity period of the peer certififcate.

The peer_cert_notbefore method returns the time corresponding to the start of the validity period of the peer certificate.

See also

tls_peer_cert_notbefore(3)

pub fn peer_cert_notafter(&mut self) -> Result<SystemTime>

Return the end of the validity period of the peer certififcate.

The peer_cert_notafter method returns the time corresponding to the end of the validity period of the peer certificate.

The peer_cert_notafter method

See also

tls_peer_cert_notafter(3)

pub fn peer_cert_chain_pem(&mut self) -> Result<Vec<u8>>

Return the PEM-encoded peer certificate.

The peer_cert_chain_pem method returns a vector of memory containing a PEM- encoded certificate chain for the peer certificate.

See also

tls_peer_cert_chain_pem(3)

pub fn conn_alpn_selected(&mut self) -> Option<String>

Return the selected ALPN protocol.

The conn_alpn_selected method returns a string that specifies the ALPN protocol selected for use with the peer. If no protocol was selected then None is returned.

See also

tls_conn_alpn_selected(3)

pub fn conn_cipher(&mut self) -> Result<String>

Return the negotiated cipher suite.

The conn_cipher method returns a string corresponding to the cipher suite negotiated with the peer.

See also

tls_conn_cipher(3)

pub fn conn_cipher_strength(&mut self) -> Result<usize>

Return the symmetric cipher strength.

The conn_cipher_strength method returns the strength in bits for the symmetric cipher that is being used with the peer.

See also

tls_conn_cipher_strength(3)

pub fn conn_servername(&mut self) -> Result<String>

Return the client's server name.

The conn_servername method returns a string corresponding to the servername that the client connected to the server requested by sending a TLS Server Name Indication extension (server only).

See also

tls_conn_servername(3)

pub fn conn_session_resumed(&mut self) -> bool

Check if a TLS session has been resumed.

The conn_session_resumed method indicates whether a TLS session has been resumed during the handshake with the server connected to the client (client only).

See also

tls_conn_session_resumed(3)

pub fn conn_version(&mut self) -> Result<String>

Return the negotiated TLS version as a string.

The conn_version method returns a string corresponding to a TLS version negotiated with the peer.

See also

tls_conn_version(3)

pub fn ocsp_process_response(&mut self, response: &[u8]) -> Result<()>

Process a raw OCSP response.

The ocsp_process_response method processes a raw OCSP response in response of size size to check the revocation status of the peer certificate. A successful result indicates that the certificate has not been revoked.

See also

tls_ocsp_process_response(3)

pub fn peer_ocsp_cert_status(&mut self) -> Result<isize>

OCSP certificate status.

The peer_ocsp_cert_status method returns the OCSP certificate status code as per RFC 6960 section 2.2.

See also

tls_peer_ocsp_cert_status(3)

pub fn peer_ocsp_crl_reason(&mut self) -> Result<isize>

OCSP certificate revocation reason.

The peer_ocsp_crl_reason method returns the OCSP certificate revocation reason status code as per RFC 5280 section 5.3.1.

See also

tls_peer_ocsp_crl_reason(3)

pub fn peer_ocsp_next_update(&mut self) -> Result<SystemTime>

OCSP next update time.

The peer_ocsp_next_update method returns the OCSP next update time.

See also

tls_peer_ocsp_next_update(3)

pub fn peer_ocsp_response_status(&mut self) -> Result<isize>

OCSP response status.

The peer_ocsp_response_status method returns the OCSP response status as per RFC 6960 section 2.3.

See also

tls_peer_ocsp_response_status(3)

pub fn peer_ocsp_result(&mut self) -> Result<String>

Textual representation of the OCSP status code.

The peer_ocsp_result method returns a textual representation of the OCSP status code returned by one of the previous three functions. If the OCSP response was valid and the certificate was not revoked, the string indicates the OCSP certificate status. Otherwise, the string indicates the OCSP certificate revocation reason or the OCSP error.

See also

tls_peer_ocsp_result(3)

pub fn peer_ocsp_revocation_time(&mut self) -> Result<SystemTime>

OCSP revocation time.

The peer_ocsp_revocation_time method returns the OCSP revocation time.

See also

tls_peer_ocsp_revocation_time(3)

pub fn peer_ocsp_this_update(&mut self) -> Result<SystemTime>

OCSP this update time.

The peer_ocsp_this_update method returns the OCSP this update time.

See also

tls_peer_ocsp_this_update(3)

pub fn peer_ocsp_url(&mut self) -> Result<String>

OCSP validation URL.

The peer_ocsp_url method returns the URL for OCSP validation of the peer certificate.

See also

tls_peer_ocsp_url(3)

Trait Implementations

impl AsRawFd for Tls

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Tls

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Drop for Tls

fn drop(&mut self)

The drop method frees the Tls context and forcibly closes the connection.

Please note that it calls both tls_close(3) and tls_free(3) internally to avoid leaking the internal socket file descriptor. libtls itself does not close the socket when calling tls_free(3) and requires the program to call tls_close(3) itself but this would be unsafe in Rust when applied to the Drop trait.

See also

tls_close(3), tls_free(3)

impl LastError for Tls

fn last_error(&self) -> Result<String>

Returns the last error of the TLS context.

The last_error method returns an error if no error occurred with the TLS context during or since the last call to tls_handshake, tls_read, tls_write, tls_close, or reset involving the context, or if memory allocation failed while trying to assemble the string describing the most recent error related to the context.

See also

tls_error(3)

fn to_error<T>(errstr: String) -> Result<T>

Returns the error string as an error object.

impl Read for Tls

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Read from the TLS connection.

The read method reads bytes of data from the connection into buf.

See also

tls_read

fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl Send for Tls

impl Sync for Tls

impl Write for Tls

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write to the TLS connection.

The write method writes bytes of data from buf to the connection.

See also

tls_write

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.