Struct libtls::config::TlsConfig

pub struct TlsConfig(_);

The TLS configuration context for Tls connections.

Before a Tls connection is created, a configuration must be created. Several methods exist to change the options of the configuration; see set_protocols, ocsp_require_stapling, verify.

Methods

impl TlsConfig

pub fn new() -> Result<Self>

Create a new configuration.

The new function allocates, initializes, and returns a new default configuration object that can be used for future Tls connections.

Errors

Returns an io::Error on error or an out of memory condition.

Example

let config = TlsConfig::new()?;

See also

tls_config_new(3)

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

Wrap a raw C tls_config 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 config is a null pointer.

pub fn add_keypair_file<P: AsRef<Path>>(
    &mut self,
    cert_file: P,
    key_file: P
) -> Result<()>

Add additional files of a public and private key pair.

The add_keypair_file method adds an additional public certificate, and private key from the specified files, used as an alternative certificate for Server Name Indication (server only).

Example

let mut config = TlsConfig::new()?;
assert!(config.add_keypair_file("does_not_exist.crt", "does_not_exist.key").is_err());

See also

tls_config_add_keypair_file(3)

pub fn add_keypair_mem(&mut self, cert: &[u8], key: &[u8]) -> Result<()>

Add an additional public and private key pair from memory.

The add_keypair_mem method adds an additional public certificate, and private key from memory, used as an alternative certificate for Server Name Indication (server only).

Example

let mut config = TlsConfig::new()?;
let valid_cert = include_bytes!("../tests/eccert.crt");
let valid_key = include_bytes!("../tests/eccert.key");
config.add_keypair_mem(valid_cert, valid_key)?;

See also

tls_config_add_keypair_mem(3)

pub fn add_keypair_ocsp_file<P: AsRef<Path>>(
    &mut self,
    cert_file: P,
    key_file: P,
    ocsp_staple_file: P
) -> Result<()>

Add additional files of a public and private key pair and an OCSP staple.

The add_keypair_ocsp_file method adds an additional public certificate, private key, and DER-encoded OCSP staple from the specified files, used as an alternative certificate for Server Name Indication (server only).

See also

add_keypair_file, tls_config_add_keypair_ocsp_file(3)

pub fn add_keypair_ocsp_mem(
    &mut self,
    cert: &[u8],
    key: &[u8],
    ocsp_staple: &[u8]
) -> Result<()>

Add an additional public and private key pair and OCSP staple from memory.

The add_keypair_ocsp_mem method adds an additional public certificate, private key, and DER-encoded OCSP staple from memory, used as an alternative certificate for Server Name Indication (server only).

See also

add_keypair_mem, tls_config_add_keypair_ocsp_mem(3)

pub fn set_alpn(&mut self, alpn: &str) -> Result<()>

Set the ALPN protocols that are supported.

The set_alpn method sets the ALPN protocols that are supported. The alpn string is a comma separated list of protocols, in order of preference.

Example

let mut config = TlsConfig::new()?;

// The `h2` ALPN is used by HTTP/2:
config.set_alpn("h2")?;

See also

tls_config_set_alpn(3)

pub fn set_ca_file<P: AsRef<Path>>(&mut self, ca_file: P) -> Result<()>

Set the CA file.

The set_ca_file method sets the filename used to load a file containing the root certificates. The default filename can be returned with the default_ca_cert_file function.

See also

add_keypair_file, tls_config_set_ca_file(3)

pub fn set_ca_path<P: AsRef<Path>>(&mut self, ca_path: P) -> Result<()>

Set the path that should be searched for the CA files.

The set_ca_path method sets sets the path (directory) which should be searched for root certificates.

See also

set_ca_file, tls_config_set_ca_path(3)

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

Set the CA from memory.

The set_ca_mem method directly sets the root certificates directly from memory.

See also

add_keypair_mem, tls_config_set_ca_mem(3)

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

Set the CA file from memory.

The set_ca_mem method sets the root certificates directly from memory.

See also

add_keypair_mem, tls_config_set_ca_mem(3)

pub fn set_cert_file<P: AsRef<Path>>(&mut self, cert_file: P) -> Result<()>

Set the public certificate file.

The set_cert_file method sets file from which the public certificate will be read.

See also

add_keypair_file, tls_config_set_cert_file(3)

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

Set the public certificate from memory.

The set_cert_mem method sets the public certificate directly from memory.

See also

add_keypair_mem, tls_config_set_cert_mem(3)

pub fn set_ciphers(&mut self, ciphers: &str) -> Result<()>

Set the list of cipher that may be used.

The set_ciphers method sets the list of ciphers that may be used. Lists of ciphers are specified by name, and the permitted names are:

• secure (or alias default)
• compat
• legacy
• insecure (or alias all)

Alternatively, libssl cipher strings can be specified. See the CIPHERS section of openssl(1) for further information.

Example

let mut config = TlsConfig::new()?;

// Only use `compat` if you run into problems with the `secure` default!
config.set_ciphers("compat")?;

See also

openssl(1), tls_config_set_ciphers(3)

pub fn set_crl_file<P: AsRef<Path>>(&mut self, crl_file: P) -> Result<()>

Set the CRL file.

The set_crl_file method sets the filename used to load a file containing the Certificate Revocation List (CRL).

See also

add_keypair_file, tls_config_set_crl_file(3)

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

Set the CRL from memory.

The set_crl_mem method sets the Certificate Revocation List (CRL) directly from memory.

See also

add_keypair_mem, tls_config_set_crl_mem(3)

pub fn set_dheparams(&mut self, dheparams: &str) -> Result<()>

Set the parameters of an Diffie-Hellman Ephemeral (DHE) key exchange.

The set_dheparams method specifies the parameters that will be used during Diffie-Hellman Ephemeral (DHE) key exchange. Possible values are none, auto and legacy. In auto mode, the key size for the ephemeral key is automatically selected based on the size of the private key being used for signing. In legacy mode, 1024 bit ephemeral keys are used. The default value is none, which disables DHE key exchange.

Example

let mut config = TlsConfig::new()?;
config.set_dheparams("auto")?;

See also

tls_config_set_dheparams(3)

pub fn set_ecdhecurve(&mut self, ecdhecurve: &str) -> Result<()>

Deprecated since 2.6.1-LibreSSL:

Replaced by set_ecdhecurves.

The set_ecdhecurve method was replaced by set_ecdhecurves.

pub fn set_ecdhecurves(&mut self, ecdhecurves: &str) -> Result<()>

Set the curves of an Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange.

The set_ecdhecurves method specifies the names of the elliptic curves that may be used during Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. This is a comma separated list, given in order of preference. The special value of "default" will use the default curves (currently X25519, P-256 and P-384). This function replaces set_ecdhecurve, which is deprecated.

Example

let mut config = TlsConfig::new()?;
config.set_ecdhecurves("X25519,P-384")?;

See also

tls_config_set_ecdhecurves(3)

pub fn set_key_file<P: AsRef<Path>>(&mut self, key_file: P) -> Result<()>

Set the private key file.

The set_key_file method sets the file from which the private key will be read.

See also

add_keypair_file, tls_config_set_key_file(3)

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

Set the private key from memory.

The set_key_mem method directly sets the private key from memory.

See also

add_keypair_mem, tls_config_set_key_mem(3)

pub fn set_keypair_file<P: AsRef<Path>>(
    &mut self,
    cert_file: P,
    key_file: P
) -> Result<()>

Set the files of the public and private key pair.

The set_keypair_file method sets the files from which the public certificate, and private key will be read.

See also

add_keypair_file, tls_config_set_keypair_file(3)

pub fn set_keypair_mem(&mut self, cert: &[u8], key: &[u8]) -> Result<()>

Set the public and private key pair from memory.

The set_keypair_mem method directly sets the public certificate, and private key from memory.

See also

add_keypair_mem, tls_config_set_keypair_mem(3)

pub fn set_keypair_ocsp_file<P: AsRef<Path>>(
    &mut self,
    cert_file: P,
    key_file: P,
    ocsp_staple_file: P
) -> Result<()>

Set the files of a public and private key pair and an OCSP staple.

The set_keypair_ocsp_file method sets the public certificate, private key, and DER-encoded OCSP staple from the specified files.

See also

add_keypair_ocsp_file, tls_config_set_keypair_ocsp_file(3)

pub fn set_keypair_ocsp_mem(
    &mut self,
    cert: &[u8],
    key: &[u8],
    ocsp_staple: &[u8]
) -> Result<()>

Set the public and private key pair and an OCSP staple from memory.

The set_keypair_ocsp_mem method sets the public certificate, private key, and DER-encoded OCSP staple directly from memory.

See also

add_keypair_ocsp_mem, tls_config_set_keypair_ocsp_mem(3)

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

Set the OCSP staple from memory.

The set_keypair_ocsp_mem method sets a DER-encoded OCSP response to be stapled during the TLS handshake from memory.

See also

add_keypair_mem, tls_config_set_ocsp_staple_mem(3)

pub fn set_ocsp_staple_file<P: AsRef<Path>>(
    &mut self,
    ocsp_staple_file: P
) -> Result<()>

Set the OCSP staple file.

The set_keypair_ocsp_mem method sets a DER-encoded OCSP response to be stapled during the TLS handshake from the specified file.

See also

add_keypair_file, tls_config_set_ocsp_staple_file(3)

pub fn set_protocols(&mut self, protocols: u32) -> Result<()>

Set which versions of the TLS protocol may be used.

The set_protocols method specifies which versions of the TLS protocol may be used. Possible values are the bitwise OR of:

• TLS_PROTOCOL_TLSv1_0
• TLS_PROTOCOL_TLSv1_1
• TLS_PROTOCOL_TLSv1_2

Additionally, the values TLS_PROTOCOL_TLSv1 (TLSv1.0, TLSv1.1 and TLSv1.2), TLS_PROTOCOLS_ALL (all supported protocols) and TLS_PROTOCOLS_DEFAULT (TLSv1.2 only) may be used.

Example

let mut config = TlsConfig::new()?;
let protocols = config::parse_protocols("tlsv1.1,tlsv1.2")?;
config.set_protocols(protocols)?;

See also

parse_protocols, tls_config_set_protocols(3)

pub fn set_session_fd(&mut self, session_fd: RawFd) -> Result<()>

Set a file descriptor to manage data for TLS sessions.

The set_session_fd method sets a file descriptor to be used to manage data for TLS sessions (client only). The given file descriptor must be a regular file and be owned by the current user, with permissions being restricted to only allow the owner to read and write the file (0600). If the file has a non-zero length, the client will attempt to read session data from this file and resume the previous TLS session with the server. Upon a successful handshake the file will be updated with current session data, if available. The caller is responsible for closing this file descriptor, after all TLS contexts that have been configured to use it have been dropped.

See also

tls_config_set_session_fd(3)

pub fn set_verify_depth(&mut self, verify_depth: usize) -> Result<()>

Set the certificate verification depth.

The set_verify_depth method limits the number of intermediate certificates that will be followed during certificate validation.

See also

tls_config_set_verify_depth(3)

pub fn prefer_ciphers_client(&mut self)

Prefer ciphers in the client's cipher list.

The prefer_ciphers_client method prefers ciphers in the client's cipher list when selecting a cipher suite (server only). This is considered to be less secure than preferring the server's list.

See also

tls_config_prefer_ciphers_client(3)

pub fn prefer_ciphers_server(&mut self)

Prefer ciphers in the servers's cipher list.

The prefer_ciphers_server method prefers ciphers in the server's cipher list when selecting a cipher suite (server only). This is considered to be more secure than preferring the client's list and is the default.

See also

tls_config_prefer_ciphers_server(3)

pub fn insecure_noverifycert(&mut self)

Disable certificate verification.

The insecure_noverifycert method disables certificate verification and OCSP validation.

See also

tls_config_insecure_noverifycert(3)

pub fn insecure_noverifyname(&mut self)

Disable server name verification.

The insecure_noverifyname method disables server name verification (client only).

See also

tls_config_insecure_noverifyname(3)

pub fn insecure_noverifytime(&mut self)

Disable certificate validity checking.

The insecure_noverifytime method disables validity checking of certificates and OCSP validation.

See also

tls_config_insecure_noverifytime(3)

pub fn verify(&mut self)

Enable all certificate verification.

The verify method reenables server name and certificate verification.

See also

tls_config_verify(3)

pub fn ocsp_require_stapling(&mut self)

Require OCSP stapling.

The ocsp_require_stapling method requires that a valid stapled OCSP response be provided during the TLS handshake.

See also

tls_config_ocsp_require_stapling(3)

pub fn verify_client(&mut self)

Enable client certificate verification.

The verify_client method enables client certificate verification, requiring the client to send a certificate (server only).

See also

tls_config_verify_client(3)

pub fn verify_client_optional(&mut self)

Enable optional client certificate verification.

The verify_client_optional method enables client certificate verification, without requiring the client to send a certificate (server only).

See also

tls_config_verify_client_optional(3)

pub fn clear_keys(&mut self)

Securely clear secret keys.

The clear_keys method clears any secret keys from memory.

See also

tls_config_clear_keys(3)

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

Set the session identifier for TLS sessions.

The set_session_id method sets the session identifier that will be used by the TLS server when sessions are enabled (server only). By default a random value is used.

Example

let mut session_id = [0; TLS_MAX_SESSION_ID_LENGTH as usize];
thread_rng().fill(&mut session_id[..]);

let mut config = TlsConfig::new()?;
config.set_session_id(&session_id[..])?;

See also

tls_config_set_session_id(3)

pub fn set_session_lifetime(&mut self, lifetime: usize) -> Result<()>

Set the lifetime for TLS sessions.

The set_session_lifetime method sets the lifetime to be used for TLS sessions (server only). Session support is disabled if a lifetime of zero is specified, which is the default.

See also

tls_config_set_session_lifetime(3)

pub fn add_ticket_key(&mut self, keyrev: u32, key: &mut [u8]) -> Result<()>

Add a key for the encryption and authentication of TLS tickets.

The add_ticket_key method adds a key used for the encryption and authentication of TLS tickets (server only). By default keys are generated and rotated automatically based on their lifetime. This function should only be used to synchronise ticket encryption key across multiple processes. Re-adding a known key will result in an error, unless it is the most recently added key.

Example

let mut key = [0; TLS_TICKET_KEY_SIZE as usize];
thread_rng().fill(&mut key[..]);

let mut config = TlsConfig::new()?;
config.add_ticket_key(1, &mut key[..])?;

See also

tls_config_add_ticket_key(3)

Trait Implementations

impl LastError for TlsConfig

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

Returns the configuration last error.

The last_error method returns an error if no error occurred with config at all, or if memory allocation failed while trying to assemble the string describing the most recent error related to config.

See also

tls_config_error(3)

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

Returns the error string as an error object.

impl Send for TlsConfig

impl Drop for TlsConfig

fn drop(&mut self)

Free the configuration object. This should only happen when no more Tls contexts are to be configured.

See also

tls_config_free(3)

impl Sync for TlsConfig

impl Debug for TlsConfig

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

Formats the value using the given formatter.