# Struct openssl::ssl::SslContextBuilder [−] [src]

    pub struct SslContextBuilder(_);

A builder for `SslContext`s.

## Implementations

### `impl SslContextBuilder` [src]

#### `pub fn new(method: SslMethod) -> Result<SslContextBuilder, ErrorStack>` [src]

Creates a new `SslContextBuilder`.

This corresponds to `SSL_CTX_new`.

#### `pub unsafe fn from_ptr(ctx: *mut SSL_CTX) -> SslContextBuilder` [src]

Creates an `SslContextBuilder` from a pointer to a raw OpenSSL value.

# Safety

The caller must ensure that the pointer is valid and uniquely owned by the builder.

#### `pub fn as_ptr(&self) -> *mut SSL_CTX` [src]

Returns a pointer to the raw OpenSSL value.

#### `pub fn set_verify(&mut self, mode: SslVerifyMode)` [src]

Configures the certificate verification method for new connections.

This corresponds to `SSL_CTX_set_verify`.

#### `pub fn set_verify_callback<F>(&mut self, mode: SslVerifyMode, verify: F) where
F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send,` [src]

Configures the certificate verification method for new connections and registers a verification callback.

The callback is passed a boolean indicating if OpenSSL’s internal verification succeeded as well as a reference to the `X509StoreContext` which can be used to examine the certificate chain. It should return a boolean indicating if verification succeeded.

This corresponds to `SSL_CTX_set_verify`.

#### `pub fn set_servername_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &mut SslAlert) -> Result<(), SniError> + 'static + Sync + Send,` [src]

Configures the server name indication (SNI) callback for new connections.

SNI is used to allow a single server to handle requests for multiple domains, each of which has its own certificate chain and configuration.

Obtain the server name with the `servername` method and then set the corresponding context with `set_ssl_context`

This corresponds to `SSL_CTX_set_tlsext_servername_callback`.

#### `pub fn set_verify_depth(&mut self, depth: u32)` [src]

Sets the certificate verification depth.

If the peer’s certificate chain is longer than this value, verification will fail.

This corresponds to `SSL_CTX_set_verify_depth`.

#### `pub fn set_verify_cert_store(
&mut self,
cert_store: X509Store
) -> Result<(), ErrorStack>` [src]

Sets a custom certificate store for verifying peer certificates.

Requires OpenSSL 1.0.2 or newer.

This corresponds to `SSL_CTX_set0_verify_cert_store`.

#### `pub fn set_cert_store(&mut self, cert_store: X509Store)` [src]

Replaces the context’s certificate store.

This corresponds to `SSL_CTX_set_cert_store`.

#### `pub fn set_read_ahead(&mut self, read_ahead: bool)` [src]

Controls read ahead behavior.

If enabled, OpenSSL will read as much data as is available from the underlying stream, instead of a single record at a time.

It has no effect when used with DTLS.

This corresponds to `SSL_CTX_set_read_ahead`.

#### `pub fn set_mode(&mut self, mode: SslMode) -> SslMode` [src]

Sets the mode used by the context, returning the previous mode.

This corresponds to `SSL_CTX_set_mode`.

#### `pub fn set_tmp_dh(&mut self, dh: &DhRef<Params>) -> Result<(), ErrorStack>` [src]

Sets the parameters to be used during ephemeral Diffie-Hellman key exchange.

This corresponds to `SSL_CTX_set_tmp_dh`.

#### `pub fn set_tmp_dh_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, bool, u32) -> Result<Dh<Params>, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback which will generate parameters to be used during ephemeral Diffie-Hellman key exchange.

The callback is provided with a reference to the `Ssl` for the session, as well as a boolean indicating if the selected cipher is export-grade, and the key length. The export and key length options are archaic and should be ignored in almost all cases.

This corresponds to `SSL_CTX_set_tmp_dh_callback`.

#### `pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef<Params>) -> Result<(), ErrorStack>` [src]

Sets the parameters to be used during ephemeral elliptic curve Diffie-Hellman key exchange.

This corresponds to `SSL_CTX_set_tmp_ecdh`.

#### `pub fn set_default_verify_paths(&mut self) -> Result<(), ErrorStack>` [src]

Use the default locations of trusted certificates for verification.

These locations are read from the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables if present, or defaults specified at OpenSSL build time otherwise.

This corresponds to `SSL_CTX_set_default_verify_paths`.

#### `pub fn set_ca_file<P: AsRef<Path>>(&mut self, file: P) -> Result<(), ErrorStack>` [src]

Loads trusted root certificates from a file.

The file should contain a sequence of PEM-formatted CA certificates.

This corresponds to `SSL_CTX_load_verify_locations`.

#### `pub fn set_client_ca_list(&mut self, list: Stack<X509Name>)` [src]

Sets the list of CA names sent to the client.

The CA certificates must still be added to the trust root - they are not automatically set as trusted by this method.

This corresponds to `SSL_CTX_set_client_CA_list`.

#### `pub fn add_client_ca(&mut self, cacert: &X509Ref) -> Result<(), ErrorStack>` [src]

Add the provided CA certificate to the list sent by the server to the client when requesting client-side TLS authentication.

This corresponds to `SSL_CTX_add_client_CA`.

#### `pub fn set_session_id_context(
&mut self,
sid_ctx: &[u8]
) -> Result<(), ErrorStack>` [src]

Set the context identifier for sessions.

This value identifies the server’s session cache to clients, telling them when they’re able to reuse sessions. It should be set to a unique value per server, unless multiple servers share a session cache.

This value should be set when using client certificates, or each request will fail its handshake and need to be restarted.

This corresponds to `SSL_CTX_set_session_id_context`.

#### `pub fn set_certificate_file<P: AsRef<Path>>(
&mut self,
file: P,
file_type: SslFiletype
) -> Result<(), ErrorStack>` [src]

Loads a leaf certificate from a file.

Only a single certificate will be loaded - use `add_extra_chain_cert` to add the remainder of the certificate chain, or `set_certificate_chain_file` to load the entire chain from a single file.

This corresponds to `SSL_CTX_use_certificate_file`.

#### `pub fn set_certificate_chain_file<P: AsRef<Path>>(
&mut self,
file: P
) -> Result<(), ErrorStack>` [src]

Loads a certificate chain from a file.

The file should contain a sequence of PEM-formatted certificates, the first being the leaf certificate, and the remainder forming the chain of certificates up to and including the trusted root certificate.

This corresponds to `SSL_CTX_use_certificate_chain_file`.

#### `pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack>` [src]

Sets the leaf certificate.

Use `add_extra_chain_cert` to add the remainder of the certificate chain.

This corresponds to `SSL_CTX_use_certificate`.

#### `pub fn add_extra_chain_cert(&mut self, cert: X509) -> Result<(), ErrorStack>` [src]

Appends a certificate to the certificate chain.

This chain should contain all certificates necessary to go from the certificate specified by `set_certificate` to a trusted root.

This corresponds to `SSL_CTX_add_extra_chain_cert`.

#### `pub fn set_private_key_file<P: AsRef<Path>>(
&mut self,
file: P,
file_type: SslFiletype
) -> Result<(), ErrorStack>` [src]

Loads the private key from a file.

This corresponds to `SSL_CTX_use_PrivateKey_file`.

#### `pub fn set_private_key<T>(&mut self, key: &PKeyRef<T>) -> Result<(), ErrorStack> where
T: HasPrivate,` [src]

Sets the private key.

This corresponds to `SSL_CTX_use_PrivateKey`.

#### `pub fn set_cipher_list(&mut self, cipher_list: &str) -> Result<(), ErrorStack>` [src]

Sets the list of supported ciphers for protocols before TLSv1.3.

The `set_ciphersuites` method controls the cipher suites for TLSv1.3.

See `ciphers` for details on the format.

This corresponds to `SSL_CTX_set_cipher_list`.

#### `pub fn set_ciphersuites(&mut self, cipher_list: &str) -> Result<(), ErrorStack>` [src]

Sets the list of supported ciphers for the TLSv1.3 protocol.

The `set_cipher_list` method controls the cipher suites for protocols before TLSv1.3.

The format consists of TLSv1.3 ciphersuite names separated by `:` characters in order of preference.

Requires OpenSSL 1.1.1 or newer.

This corresponds to `SSL_CTX_set_ciphersuites`.

#### `pub fn set_options(&mut self, option: SslOptions) -> SslOptions` [src]

Sets the options used by the context, returning the old set.

This corresponds to `SSL_CTX_set_options`.

# Note

This enables the specified options, but does not disable unspecified options. Use `clear_options` for that.

#### `pub fn options(&self) -> SslOptions` [src]

Returns the options used by the context.

This corresponds to `SSL_CTX_get_options`.

#### `pub fn clear_options(&mut self, option: SslOptions) -> SslOptions` [src]

Clears the options used by the context, returning the old set.

This corresponds to `SSL_CTX_clear_options`.

#### `pub fn set_min_proto_version(
&mut self,
version: Option<SslVersion>
) -> Result<(), ErrorStack>` [src]

Sets the minimum supported protocol version.

A value of `None` will enable protocol versions down the the lowest version supported by OpenSSL.

This corresponds to `SSL_CTX_set_min_proto_version`.

Requires OpenSSL 1.1.0 or LibreSSL 2.6.1 or newer.

#### `pub fn set_max_proto_version(
&mut self,
version: Option<SslVersion>
) -> Result<(), ErrorStack>` [src]

Sets the maximum supported protocol version.

A value of `None` will enable protocol versions down the the highest version supported by OpenSSL.

This corresponds to `SSL_CTX_set_max_proto_version`.

Requires OpenSSL 1.1.0 or or LibreSSL 2.6.1 or newer.

#### `pub fn min_proto_version(&mut self) -> Option<SslVersion>` [src]

Gets the minimum supported protocol version.

A value of `None` indicates that all versions down the the lowest version supported by OpenSSL are enabled.

This corresponds to `SSL_CTX_get_min_proto_version`.

Requires OpenSSL 1.1.0g or LibreSSL 2.7.0 or newer.

#### `pub fn max_proto_version(&mut self) -> Option<SslVersion>` [src]

Gets the maximum supported protocol version.

A value of `None` indicates that all versions down the the highest version supported by OpenSSL are enabled.

This corresponds to `SSL_CTX_get_max_proto_version`.

Requires OpenSSL 1.1.0g or LibreSSL 2.7.0 or newer.

#### `pub fn set_alpn_protos(&mut self, protocols: &[u8]) -> Result<(), ErrorStack>` [src]

Sets the protocols to sent to the server for Application Layer Protocol Negotiation (ALPN).

The input must be in ALPN “wire format”. It consists of a sequence of supported protocol names prefixed by their byte length. For example, the protocol list consisting of `spdy/1` and `http/1.1` is encoded as `b"\x06spdy/1\x08http/1.1"`. The protocols are ordered by preference.

This corresponds to `SSL_CTX_set_alpn_protos`.

Requires OpenSSL 1.0.2 or LibreSSL 2.6.1 or newer.

#### `pub fn set_tlsext_use_srtp(&mut self, protocols: &str) -> Result<(), ErrorStack>` [src]

Enables the DTLS extension “use_srtp” as defined in RFC5764.

This corresponds to `SSL_CTX_set_tlsext_use_srtp`.

#### `pub fn set_alpn_select_callback<F>(&mut self, callback: F) where
F: for<'a> Fn(&mut SslRef, &'a [u8]) -> Result<&'a [u8], AlpnError> + 'static + Sync + Send,` [src]

Sets the callback used by a server to select a protocol for Application Layer Protocol Negotiation (ALPN).

The callback is provided with the client’s protocol list in ALPN wire format. See the documentation for `SslContextBuilder::set_alpn_protos` for details. It should return one of those protocols on success. The `select_next_proto` function implements the standard protocol selection algorithm.

This corresponds to `SSL_CTX_set_alpn_select_cb`.

Requires OpenSSL 1.0.2 or LibreSSL 2.6.1 or newer.

#### `pub fn check_private_key(&self) -> Result<(), ErrorStack>` [src]

Checks for consistency between the private key and certificate.

This corresponds to `SSL_CTX_check_private_key`.

#### `pub fn cert_store(&self) -> &X509StoreBuilderRef` [src]

Returns a shared reference to the context’s certificate store.

This corresponds to `SSL_CTX_get_cert_store`.

#### `pub fn cert_store_mut(&mut self) -> &mut X509StoreBuilderRef` [src]

Returns a mutable reference to the context’s certificate store.

This corresponds to `SSL_CTX_get_cert_store`.

#### `pub fn verify_param(&self) -> &X509VerifyParamRef` [src]

Returns a reference to the X509 verification configuration.

Requires OpenSSL 1.0.2 or newer.

This corresponds to `SSL_CTX_get0_param`.

#### `pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef` [src]

Returns a mutable reference to the X509 verification configuration.

Requires OpenSSL 1.0.2 or newer.

This corresponds to `SSL_CTX_get0_param`.

#### `pub fn set_status_callback<F>(&mut self, callback: F) -> Result<(), ErrorStack> where
F: Fn(&mut SslRef) -> Result<bool, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback dealing with OCSP stapling.

On the client side, this callback is responsible for validating the OCSP status response returned by the server. The status may be retrieved with the `SslRef::ocsp_status` method. A response of `Ok(true)` indicates that the OCSP status is valid, and a response of `Ok(false)` indicates that the OCSP status is invalid and the handshake should be terminated.

On the server side, this callback is resopnsible for setting the OCSP status response to be returned to clients. The status may be set with the `SslRef::set_ocsp_status` method. A response of `Ok(true)` indicates that the OCSP status should be returned to the client, and `Ok(false)` indicates that the status should not be returned to the client.

This corresponds to `SSL_CTX_set_tlsext_status_cb`.

#### `pub fn set_psk_client_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8], &mut [u8]) -> Result<usize, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback for providing an identity and pre-shared key for a TLS-PSK client.

The callback will be called with the SSL context, an identity hint if one was provided by the server, a mutable slice for each of the identity and pre-shared key bytes. The identity must be written as a null-terminated C string.

This corresponds to `SSL_CTX_set_psk_client_callback`.

#### `pub fn set_psk_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8], &mut [u8]) -> Result<usize, ErrorStack> + 'static + Sync + Send,` [src]

👎 Deprecated since 0.10.10:

renamed to `set_psk_client_callback`

#### `pub fn set_psk_server_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8]) -> Result<usize, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback for providing an identity and pre-shared key for a TLS-PSK server.

The callback will be called with the SSL context, an identity provided by the client, and, a mutable slice for the pre-shared key bytes. The callback returns the number of bytes in the pre-shared key.

This corresponds to `SSL_CTX_set_psk_server_callback`.

#### `pub fn set_new_session_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, SslSession) + 'static + Sync + Send,` [src]

Sets the callback which is called when new sessions are negotiated.

This can be used by clients to implement session caching. While in TLSv1.2 the session is available to access via `SslRef::session` immediately after the handshake completes, this is not the case for TLSv1.3. There, a session is not generally available immediately, and the server may provide multiple session tokens to the client over a single session. The new session callback is a portable way to deal with both cases.

Note that session caching must be enabled for the callback to be invoked, and it defaults off for clients. `set_session_cache_mode` controls that behavior.

This corresponds to `SSL_CTX_sess_set_new_cb`.

#### `pub fn set_remove_session_callback<F>(&mut self, callback: F) where
F: Fn(&SslContextRef, &SslSessionRef) + 'static + Sync + Send,` [src]

Sets the callback which is called when sessions are removed from the context.

Sessions can be removed because they have timed out or because they are considered faulty.

This corresponds to `SSL_CTX_sess_set_remove_cb`.

#### `pub unsafe fn set_get_session_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &[u8]) -> Option<SslSession> + 'static + Sync + Send,` [src]

Sets the callback which is called when a client proposed to resume a session but it was not found in the internal cache.

The callback is passed a reference to the session ID provided by the client. It should return the session corresponding to that ID if available. This is only used for servers, not clients.

This corresponds to `SSL_CTX_sess_set_get_cb`.

# Safety

The returned `SslSession` must not be associated with a different `SslContext`.

#### `pub fn set_keylog_callback<F>(&mut self, callback: F) where
F: Fn(&SslRef, &str) + 'static + Sync + Send,` [src]

Sets the TLS key logging callback.

The callback is invoked whenever TLS key material is generated, and is passed a line of NSS SSLKEYLOGFILE-formatted text. This can be used by tools like Wireshark to decrypt message traffic. The line does not contain a trailing newline.

Requires OpenSSL 1.1.1 or newer.

This corresponds to `SSL_CTX_set_keylog_callback`.

#### `pub fn set_session_cache_mode(
&mut self,
mode: SslSessionCacheMode
) -> SslSessionCacheMode` [src]

Sets the session caching mode use for connections made with the context.

Returns the previous session caching mode.

This corresponds to `SSL_CTX_set_session_cache_mode`.

#### `pub fn set_stateless_cookie_generate_cb<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &mut [u8]) -> Result<usize, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback for generating an application cookie for TLS1.3 stateless handshakes.

The callback will be called with the SSL context and a slice into which the cookie should be written. The callback should return the number of bytes written.

This corresponds to `SSL_CTX_set_stateless_cookie_generate_cb`.

#### `pub fn set_stateless_cookie_verify_cb<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &[u8]) -> bool + 'static + Sync + Send,` [src]

Sets the callback for verifying an application cookie for TLS1.3 stateless handshakes.

The callback will be called with the SSL context and the cookie supplied by the client. It should return true if and only if the cookie is valid.

Note that the OpenSSL implementation independently verifies the integrity of application cookies using an HMAC before invoking the supplied callback.

This corresponds to `SSL_CTX_set_stateless_cookie_verify_cb`.

#### `pub fn set_cookie_generate_cb<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &mut [u8]) -> Result<usize, ErrorStack> + 'static + Sync + Send,` [src]

Sets the callback for generating a DTLSv1 cookie

The callback will be called with the SSL context and a slice into which the cookie should be written. The callback should return the number of bytes written.

This corresponds to `SSL_CTX_set_cookie_generate_cb`.

#### `pub fn set_cookie_verify_cb<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &[u8]) -> bool + 'static + Sync + Send,` [src]

Sets the callback for verifying a DTLSv1 cookie

The callback will be called with the SSL context and the cookie supplied by the client. It should return true if and only if the cookie is valid.

This corresponds to `SSL_CTX_set_cookie_verify_cb`.

#### `pub fn set_ex_data<T>(&mut self, index: Index<SslContext, T>, data: T)` [src]

Sets the extra data at the specified index.

This can be used to provide data to callbacks registered with the context. Use the `SslContext::new_ex_index` method to create an `Index`.

This corresponds to `SSL_CTX_set_ex_data`.

#### `pub fn add_custom_ext<AddFn, ParseFn, T>(
&mut self,
ext_type: u16,
context: ExtensionContext,
add_cb: AddFn,
parse_cb: ParseFn
) -> Result<(), ErrorStack> where
AddFn: Fn(&mut SslRef, ExtensionContext, Option<(usize, &X509Ref)>) -> Result<Option<T>, SslAlert> + 'static + Sync + Send,
T: AsRef<[u8]> + 'static + Sync + Send,
ParseFn: Fn(&mut SslRef, ExtensionContext, &[u8], Option<(usize, &X509Ref)>) -> Result<(), SslAlert> + 'static + Sync + Send,` [src]

Adds a custom extension for a TLS/DTLS client or server for all supported protocol versions.

Requires OpenSSL 1.1.1 or newer.

This corresponds to `SSL_CTX_add_custom_ext`.

#### `pub fn set_max_early_data(&mut self, bytes: u32) -> Result<(), ErrorStack>` [src]

Sets the maximum amount of early data that will be accepted on incoming connections.

Defaults to 0.

Requires OpenSSL 1.1.1 or newer.

This corresponds to `SSL_CTX_set_max_early_data`.

#### `pub fn set_client_hello_callback<F>(&mut self, callback: F) where
F: Fn(&mut SslRef, &mut SslAlert) -> Result<ClientHelloResponse, ErrorStack> + 'static + Sync + Send,` [src]

Sets a callback which will be invoked just after the client’s hello message is received.

Requires OpenSSL 1.1.1 or newer.

This corresponds to `SSL_CTX_set_client_hello_cb`.

#### `pub fn set_session_cache_size(&mut self, size: i32) -> i64` [src]

Sets the context’s session cache size limit, returning the previous limit.

A value of 0 means that the cache size is unbounded.

This corresponds to `SSL_CTX_sess_get_cache_size`.

#### `pub fn set_sigalgs_list(&mut self, sigalgs: &str) -> Result<(), ErrorStack>` [src]

Sets the context’s supported signature algorithms.

This corresponds to `SSL_CTX_set1_sigalgs_list`.

Requires OpenSSL 1.0.2 or newer.

#### `pub fn set_groups_list(&mut self, groups: &str) -> Result<(), ErrorStack>` [src]

Sets the context’s supported elliptic curve groups.

This corresponds to `SSL_CTX_set1_groups_list`.

Requires OpenSSL 1.1.1 or newer.

#### `pub fn build(self) -> SslContext` [src]

Consumes the builder, returning a new `SslContext`.

## Auto Trait Implementations

### `impl RefUnwindSafe for SslContextBuilder`

### `impl Send for SslContextBuilder`

### `impl Sync for SslContextBuilder`

### `impl Unpin for SslContextBuilder`

### `impl UnwindSafe for SslContextBuilder`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.