Struct Ssl 

pub struct Ssl(/* private fields */);

Available on crate feature boring only.

The state of an SSL/TLS session.

Ssl objects are created from an SslContext, which provides configuration defaults. These defaults can be overridden on a per-Ssl basis, however.

Implementations

impl Ssl

pub fn new_ex_index<T>() -> Result<Index<Ssl, T>, ErrorStack>

where T: 'static + Sync + Send,

Returns a new extra data index.

Each invocation of this function is guaranteed to return a distinct index. These can be used to store data in the context that can be retrieved later by callbacks, for example.

This corresponds to SSL_get_ex_new_index.

pub fn new(ctx: &SslContextRef) -> Result<Ssl, ErrorStack>

Creates a new Ssl.

This corresponds to SSL_new.

pub fn setup_connect<S>(self, stream: S) -> MidHandshakeSslStream<S>

where S: Read + Write,

Initiates a client-side TLS handshake, returning a MidHandshakeSslStream.

This method is guaranteed to return without calling any callback defined in the internal Ssl or SslContext.

See SslStreamBuilder::setup_connect for more details.

Warning

BoringSSL’s default configuration is insecure. It is highly recommended to use SslConnector rather than Ssl directly, as it manages that configuration.

pub fn connect<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>

where S: Read + Write,

Attempts a client-side TLS handshake.

This is a convenience method which combines Self::setup_connect and MidHandshakeSslStream::handshake.

Warning

OpenSSL’s default configuration is insecure. It is highly recommended to use SslConnector rather than Ssl directly, as it manages that configuration.

pub fn setup_accept<S>(self, stream: S) -> MidHandshakeSslStream<S>

where S: Read + Write,

Initiates a server-side TLS handshake.

This method is guaranteed to return without calling any callback defined in the internal Ssl or SslContext.

See SslStreamBuilder::setup_accept for more details.

Warning

BoringSSL’s default configuration is insecure. It is highly recommended to use SslAcceptor rather than Ssl directly, as it manages that configuration.

pub fn accept<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>

where S: Read + Write,

Attempts a server-side TLS handshake.

This is a convenience method which combines Self::setup_accept and MidHandshakeSslStream::handshake.

Warning

OpenSSL’s default configuration is insecure. It is highly recommended to use SslAcceptor rather than Ssl directly, as it manages that configuration.

Methods from Deref<Target = SslRef>

pub fn set_async_certificate_callback<F>(&mut self, callback: F)

where F: Fn(&mut CertificateSelection<'_>) -> Result<Pin<Box<dyn Future<Output = Result<Box<dyn FnOnce(CertificateSelection<'_>) -> Result<(), AsyncSelectCertError>>, AsyncSelectCertError>> + Send>>, AsyncSelectCertError> + Send + Sync + 'static,

Overrides this connection’s async certificate selection. See SslContextBuilder::set_async_certificate_callback.

pub fn set_async_custom_verify_callback<F>( &mut self, mode: SslVerifyMode, callback: F, )

where F: Fn(&mut SslRef) -> Result<Pin<Box<dyn Future<Output = Result<Box<dyn FnOnce(&mut SslRef) -> Result<(), SslAlert>>, SslAlert>> + Send>>, SslAlert> + Send + Sync + 'static,

Sets a per-connection asynchronous verifier with the same contract as SslContextBuilder::set_async_custom_verify_callback.

pub fn set_task_waker(&mut self, waker: Option<Waker>)

Sets the task waker for async callbacks. rama-boring-tokio sets it per poll. Without one, async factories and finish closures are not called, and pending futures are dropped. Selection, verification and signing report failure; async session lookup reports a cache miss, allowing a full handshake.

pub fn set_certificate_callback<F>(&mut self, callback: F)

where F: Fn(CertificateSelection<'_>) -> Result<(), SelectCertError> + Send + Sync + 'static,

Overrides this connection’s certificate-selection callback. Changing SSL contexts replaces this override and the credential configuration. Replacing an active async selection aborts the handshake. See SslContextBuilder::set_certificate_callback.

This corresponds to SSL_set_cert_cb.

pub fn clear_certificates(&mut self)

Removes all credential candidates, including the inherited legacy certificate chain and private key. The SSL context is unchanged.

This corresponds to SSL_certs_clear.

pub fn set_msg_callback<F>(&mut self, callback: F)

where F: Fn(&SslRef, SslMessage<'_>) + 'static + Sync + Send,

Observes this connection’s protocol messages, replacing any context callback. See SslContextBuilder::set_msg_callback.

This corresponds to SSL_set_msg_callback.

pub fn set_raw_cipher_list( &mut self, cipher_list: &[u16], ) -> Result<(), ErrorStack>

Sets the cipher suite values this client offers, in order, replacing the context’s list for this connection only. See SslContextBuilder::set_raw_cipher_list: the list is exact, and its GREASE codepoints are its only GREASE slots.

A client must set it before writing its ClientHello, a server before its handshake completes.

This corresponds to RAMA_SSL_set_raw_cipher_list.

pub fn set_cipher_list(&mut self, cipher_list: &str) -> Result<(), ErrorStack>

Like SslContextBuilder::set_cipher_list, for this connection only.

A client must set it before writing its ClientHello, a server before its handshake completes.

This corresponds to SSL_set_cipher_list.

pub fn set_strict_cipher_list( &mut self, cipher_list: &str, ) -> Result<(), ErrorStack>

Like SslContextBuilder::set_strict_cipher_list, for this connection only. A server uses it as its cipher preference, so it can pin the cipher a relay negotiated on its other leg.

A client must set it before writing its ClientHello, a server before its handshake completes.

This corresponds to SSL_set_strict_cipher_list.

pub fn set_server_extension_order( &mut self, ids: &[u16], ) -> Result<(), ErrorStack>

Orders this server’s response extensions within its ServerHello and EncryptedExtensions: listed extensions first, in order, then the rest natively. A relay can mirror the order its origin used. Only what the server answers is ordered; extensions the client did not send are never added. It takes effect when set before the ServerHello is written, for example from the early ClientHello callback. Fails once the handshake completed or for more than 256 IDs.

This corresponds to RAMA_SSL_set_server_extension_order.

pub fn set_tls13_server_ciphers( &mut self, cipher_ids: &[u16], ) -> Result<(), ErrorStack>

Sets this server’s TLS 1.3 cipher preference: the first listed cipher the client offered is selected, otherwise the native choice applies. An empty list restores the native choice. To accept only these ciphers, see Self::set_strict_tls13_server_ciphers.

Has no effect on a client. Fails once the handshake completed or for an ID that is not a TLS 1.3 cipher suite. TLS 1.2 ciphers follow Self::set_strict_cipher_list.

This corresponds to RAMA_SSL_set_tls13_server_ciphers.

pub fn set_strict_tls13_server_ciphers( &mut self, cipher_ids: &[u16], ) -> Result<(), ErrorStack>

Like Self::set_tls13_server_ciphers, but the handshake fails when the client offered none of these ciphers. A relay pins the cipher its other leg negotiated this way. Fails for an empty list.

This corresponds to RAMA_SSL_set_tls13_server_ciphers.

pub fn set_num_tickets(&mut self, num_tickets: usize) -> Result<(), ErrorStack>

Sets how many TLS 1.3 session tickets this server issues after its handshake, capped at 16, replacing SslContextBuilder::set_num_tickets for this connection; zero disables tickets. Has no effect on a client. Fails once the handshake completed.

This corresponds to RAMA_SSL_set_num_tickets.

pub fn set_certificate_compression_algorithms( &mut self, algorithms: &[CertificateCompressionAlgorithm], ) -> Result<(), ErrorStack>

Selects which of the context’s registered certificate compression algorithms this connection uses, in preference order: a client offers them in this order, and only accepts certificates compressed with one of them; a server prefers them in this order. An empty list disables certificate compression for this connection.

Fails for an algorithm the context did not register or a repeated one, for a client once it wrote its ClientHello, and for a server once its handshake completed.

This corresponds to RAMA_SSL_set_cert_compression_algs.

pub fn set_client_hello_shape( &mut self, shape: &ClientHelloShape, ) -> Result<(), ErrorStack>

Applies a ClientHelloShape to this client before its handshake starts, replacing any shape applied earlier as a whole.

Everything is validated first: on error, nothing changes. Fails for a server, once the ClientHello was written, for an extension body BoringSSL builds itself, or for a body over 65535 bytes.

This corresponds to RAMA_SSL_set_client_hello_shape.

pub fn set_raw_supported_groups( &mut self, groups: &[u16], ) -> Result<(), ErrorStack>

Sets the groups this client lists in supported_groups, exactly as on the wire, repeats included: GREASE codepoints are GREASE slots, and groups it cannot negotiate follow UnknownValues. The supported ones also become the groups this connection negotiates. Fails if none is supported. A later Self::set_curves or Self::set_curves_list replaces this list.

This corresponds to RAMA_SSL_set_raw_supported_groups.

pub fn set_raw_key_shares(&mut self, groups: &[u16]) -> Result<(), ErrorStack>

Sets the groups this client sends key shares for, in order, exactly as on the wire: GREASE codepoints are GREASE key shares. A group must also be a supported group; others are never sent (they need a key), whatever the UnknownValues policy, and later repeats of a group are dropped (RFC 8446 forbids them). With no key share left, the client sends an empty list, asking the server for a HelloRetryRequest.

This corresponds to RAMA_SSL_set_raw_key_shares.

pub fn set_raw_supported_versions( &mut self, versions: &[u16], ) -> Result<(), ErrorStack>

Sets the versions this client lists in supported_versions, exactly as on the wire, repeats included: GREASE codepoints are GREASE slots, and versions outside the configured minimum and maximum follow UnknownValues.

This corresponds to RAMA_SSL_set_raw_supported_versions.

pub fn set_raw_signature_algorithms( &mut self, algorithms: &[u16], ) -> Result<(), ErrorStack>

Sets the signature algorithms this client lists, exactly as on the wire, repeats included (Safari repeats one): GREASE codepoints are GREASE slots, and algorithms BoringSSL does not implement follow UnknownValues. The server’s choice is still checked against Self::set_verify_algorithm_prefs.

This corresponds to RAMA_SSL_set_raw_signature_algorithms.

pub fn enable_signed_cert_timestamps(&mut self)

Requests signed certificate timestamps from the server.

This corresponds to SSL_enable_signed_cert_timestamps.

pub fn enable_ocsp_stapling(&mut self)

Requests an OCSP response from the server.

This corresponds to SSL_enable_ocsp_stapling.

pub fn set_max_send_fragment(&mut self, max: usize)

Caps the plaintext size of records this connection sends, clamped to 512..=16384 bytes.

This corresponds to SSL_set_max_send_fragment.

pub fn set_renegotiate_mode(&mut self, mode: SslRenegotiateMode)

Sets how this client answers a TLS 1.2 server’s renegotiation request.

This corresponds to SSL_set_renegotiate_mode.

pub fn set_shed_handshake_config(&mut self, enabled: bool)

Frees the handshake configuration once the handshake completes, saving memory on long-lived connections. Disables renegotiation.

This corresponds to SSL_set_shed_handshake_config.

pub fn set_jdk11_workaround(&mut self, enabled: bool)

Lets a server avoid a TLS 1.3 interoperability bug of JDK 11 clients.

This corresponds to SSL_set_jdk11_workaround.

pub fn set_quic_use_legacy_codepoint(&mut self, enabled: bool)

Uses the QUIC draft transport parameters codepoint (0xffa5) instead of 57.

This corresponds to SSL_set_quic_use_legacy_codepoint.

pub fn early_data_reason(&self) -> SslEarlyDataReason

Why 0-RTT data was accepted or rejected.

This corresponds to SSL_get_early_data_reason.

pub fn peer_full_cert_chain(&self) -> Option<&StackRef<X509>>

The peer’s certificate chain, leaf included, on clients and servers alike.

This corresponds to SSL_get_peer_full_cert_chain.

pub fn extended_master_secret_support(&self) -> bool

Whether the connection uses the extended master secret (TLS 1.2 and earlier; always true for TLS 1.3).

This corresponds to SSL_get_extms_support.

pub fn secure_renegotiation_support(&self) -> bool

Whether the peer supports secure renegotiation (RFC 5746).

This corresponds to SSL_get_secure_renegotiation_support.

pub fn group_id(&self) -> Option<u16>

The IANA ID of the group the handshake negotiated, if any: the raw value behind Self::curve, including groups without a name here.

This corresponds to SSL_get_group_id.

pub fn ticket_age_skew(&self) -> i32

Seconds between the client’s and server’s view of a resumed ticket’s age.

This corresponds to SSL_get_ticket_age_skew.

pub fn set_options(&mut self, option: SslOptions) -> SslOptions

Sets the options used by the ongoing session, returning the old set.

Note

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

This corresponds to SSL_set_options.

pub fn clear_options(&mut self, option: SslOptions) -> SslOptions

Clears the options used by the ongoing session, returning the old set.

This corresponds to SSL_clear_options.

pub fn set_curves_list(&mut self, curves: &str) -> Result<(), ErrorStack>

Like SslContextBuilder::set_curves_list, for this connection only. It replaces a list set with Self::set_raw_supported_groups.

A client must set it before writing its ClientHello, a server before its handshake completes.

This corresponds to SSL_set1_curves_list.

pub fn set_curves(&mut self, curves: &[SslCurve]) -> Result<(), ErrorStack>

Like SslContextBuilder::set_curves, for this connection only: a native list, so GREASE follows the connection’s (or context’s) GREASE settings, see GreaseLists::GROUPS. It replaces a list set with Self::set_raw_supported_groups. An empty list restores the default curves.

A client must set it before writing its ClientHello, a server before its handshake completes.

This corresponds to SSL_set1_group_ids.

pub fn set_verify_algorithm_prefs( &mut self, prefs: &[SslSignatureAlgorithm], ) -> Result<(), ErrorStack>

Set per-connection verification schemes advertised in ClientHello or CertificateRequest.

This corresponds to SSL_set_verify_algorithm_prefs.

pub fn curve(&self) -> Option<SslCurve>

Returns the SslCurve used for this SslRef.

This corresponds to SSL_get_curve_id.

pub fn curve_name(&self) -> Option<&'static str>

Returns the curve name used for this SslRef.

This corresponds to SSL_get_curve_name.

pub fn used_hello_retry_request(&self) -> bool

Whether TLS 1.3 sent or received a HelloRetryRequest.

This corresponds to SSL_used_hello_retry_request.

pub fn error_code(&self, ret: i32) -> ErrorCode

Returns an ErrorCode value for the most recent operation on this SslRef.

This corresponds to SSL_get_error.

pub fn set_verify(&mut self, mode: SslVerifyMode)

Like SslContextBuilder::set_verify.

This corresponds to SSL_set_verify.

pub fn set_verify_depth(&mut self, depth: u32)

Sets the certificate verification depth.

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

This corresponds to SSL_set_verify_depth.

pub fn verify_mode(&self) -> SslVerifyMode

Returns the verify mode that was set using set_verify.

This corresponds to SSL_get_verify_mode.

pub fn set_verify_callback<F>(&mut self, mode: SslVerifyMode, callback: F)

where F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send,

Like SslContextBuilder::set_verify_callback.

Warning: This callback does not replace the default certificate verification process and is, instead, called multiple times in the course of that process. It is very difficult to implement this callback correctly, without inadvertently relying on implementation details or making incorrect assumptions about when the callback is called.

Instead, use SslContextBuilder::set_custom_verify_callback to customize certificate verification. Those callbacks can inspect the peer-sent chain, call X509StoreContextRef::verify_cert and inspect the result, or perform other operations more straightforwardly.

Panics

This method panics if this Ssl is associated with a RPK context.

This corresponds to SSL_set_verify.

pub fn set_verify_cert_store( &mut self, cert_store: X509Store, ) -> Result<(), ErrorStack>

Sets a custom certificate store for verifying peer certificates.

This corresponds to SSL_set0_verify_cert_store.

pub fn set_custom_verify_callback<F>( &mut self, mode: SslVerifyMode, callback: F, )

where F: Fn(&mut SslRef) -> Result<(), SslVerifyError> + 'static + Sync + Send,

Like SslContextBuilder::set_custom_verify_callback.

Panics

This method panics if this Ssl is associated with a RPK context.

This corresponds to SSL_set_custom_verify.

pub fn set_tmp_dh(&mut self, dh: &DhRef<Params>) -> Result<(), ErrorStack>

Like SslContextBuilder::set_tmp_dh.

This corresponds to SSL_set_tmp_dh.

pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef<Params>) -> Result<(), ErrorStack>

Like SslContextBuilder::set_tmp_ecdh.

This corresponds to SSL_set_tmp_ecdh.

pub fn set_server_padding_request(&mut self, num_bytes: u16)

Requests num_bytes of server handshake padding on this client connection.

This is a temporary BoringSSL TLS 1.3 experiment (extension 0x12e0), not a permanent IANA assignment. It also works with QUIC TLS 1.3. By default no request is sent. Zero sends an explicit zero-byte request; there is no native API to restore absence. Repeated calls replace the request. All u16 values are sent unchanged, even in a TLS 1.2 ClientHello, but bundled servers only respond in TLS 1.3, on non-resumed handshakes, and only for requests at most 16,384 bytes. Larger requests are ignored.

Configure before starting the handshake. Native setters update retained configuration without a handshake-state check: a late call does not rewrite an already emitted ClientHello and may change response validation. If native configuration has been shed, the call does nothing. Use a fresh SSL to omit a previously configured request. ClientHelloShape ordering can position this native extension, but cannot supply an opaque body for it.

This corresponds to SSL_set_server_padding_request.

pub fn set_server_padding_enabled(&mut self, enabled: bool)

Enables this server connection to answer experimental server-padding requests.

Disabled by default. Repeated calls replace the policy. The bundled server responds only on full TLS 1.3 handshakes (including QUIC), for requests of zero through 16,384 bytes, in EncryptedExtensions. Configure before the handshake; late changes cannot rewrite a response already sent and are ignored if native configuration has been shed. See Self::set_server_padding_request for the experiment’s limitations.

This corresponds to SSL_set_server_padding_enabled.

pub fn server_sent_requested_padding(&self) -> bool

Whether this client received the requested experimental server padding.

False initially and when no response is received (including TLS 1.2, resumption, disabled servers, and oversized requests). An acknowledged zero-byte request counts as true. Inspect after a successful handshake; this flag alone does not establish handshake success.

This corresponds to SSL_server_sent_requested_padding.

pub fn set_permute_extensions(&mut self, enabled: bool)

Configures whether ClientHello extensions should be permuted.

This corresponds to SSL_set_permute_extensions.

pub fn set_extension_order(&mut self, ids: &[u16]) -> Result<(), ErrorStack>

Sets this client’s ClientHello extension order before its handshake starts.

Unlike SslContextBuilder::set_extension_order, this leaves the shared context and its session cache untouched and overrides both context ordering and random permutation. The order is a prefix: listed extensions are emitted first in the requested order, and the other extensions this connection enables follow in native canonical order. It decides order, not which extensions are sent; listing an extension the connection does not enable sends nothing for it. An empty slice selects canonical order.

GREASE is exact: a GREASE codepoint is a GREASE extension at that position (its value and body follow ClientHelloShape), and there are no other GREASE extensions, even for an empty order. IDs BoringSSL does not implement follow UnknownValues (dropped by default), duplicates are ignored, and padding and pre_shared_key keep their native positions. A later call replaces the order.

Fails for a server, once the ClientHello was written, for more than 256 IDs, or for more than 16 GREASE codepoints (each GREASE extension needs a distinct value).

This corresponds to RAMA_SSL_set_extension_order.

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

Like SslContextBuilder::set_alpn_protos.

This corresponds to SSL_set_alpn_protos.

pub fn set_record_size_limit(&mut self, value: u16) -> Result<(), ErrorStack>

This corresponds to SSL_set_record_size_limit.

pub fn set_delegated_credential_schemes( &mut self, schemes: &[SslSignatureAlgorithm], ) -> Result<(), ErrorStack>

This corresponds to SSL_set_delegated_credential_schemes.

pub fn ciphers(&self) -> &StackRef<SslCipher>

Returns the stack of available SslCiphers for SSL, sorted by preference.

This corresponds to SSL_get_ciphers.

pub fn current_cipher(&self) -> Option<&SslCipherRef>

Returns the current cipher if the session is active.

This corresponds to SSL_get_current_cipher.

pub fn peer_signature_algorithm(&self) -> Option<SslSignatureAlgorithm>

Peer signature scheme, absent when no signature was produced (including resumption).

This corresponds to SSL_get_peer_signature_algorithm.

pub fn signature_algorithm_used(&self) -> Option<SslSignatureAlgorithm>

Local signature scheme during the handshake. To retain it, capture it in the HANDSHAKE_DONE info callback before BoringSSL discards it.

This corresponds to SSL_get_signature_algorithm_used.

pub fn state_string(&self) -> &'static str

Returns a short string describing the state of the session.

This corresponds to SSL_state_string.

pub fn state_string_long(&self) -> &'static str

Returns a longer string describing the state of the session.

Returns empty string if the state wasn’t valid UTF-8.

This corresponds to SSL_state_string_long.

pub fn set_hostname(&mut self, hostname: &str) -> Result<(), ErrorStack>

Sets the host name to be sent to the server for Server Name Indication (SNI).

It has no effect for a server-side connection.

This corresponds to SSL_set_tlsext_host_name.

pub fn peer_certificate(&self) -> Option<X509>

Returns the peer’s certificate, if present.

This corresponds to SSL_get_peer_certificate.

pub fn peer_cert_chain(&self) -> Option<&StackRef<X509>>

Returns the certificate chain of the peer, if present.

On the client side, the chain includes the leaf certificate, but on the server side it does not. Fun!

This corresponds to SSL_get_peer_certificate.

pub fn certificate(&self) -> Option<&X509Ref>

Like [SslContext::certificate].

This corresponds to SSL_get_certificate.

pub fn private_key(&self) -> Option<&PKeyRef<Private>>

Like [SslContext::private_key].

This corresponds to SSL_get_privatekey.

pub fn version(&self) -> Option<SslVersion>

Returns the protocol version of the session.

This corresponds to SSL_version.

pub fn version_str(&self) -> &'static str

Returns a string describing the protocol version of the session.

This may panic if the string isn’t valid UTF-8 for some reason. Use [Self::version2] instead.

This corresponds to SSL_get_version.

pub fn set_min_proto_version( &mut self, version: Option<SslVersion>, ) -> Result<(), ErrorStack>

Sets the minimum supported protocol version.

If version is None, the default minimum version is used. For BoringSSL this defaults to TLS 1.0.

This corresponds to SSL_set_min_proto_version.

pub fn set_max_proto_version( &mut self, version: Option<SslVersion>, ) -> Result<(), ErrorStack>

Sets the maximum supported protocol version.

If version is None, the default maximum version is used. For BoringSSL this is TLS 1.3.

This corresponds to SSL_set_max_proto_version.

pub fn min_proto_version(&mut self) -> Option<SslVersion>

Gets the minimum supported protocol version.

This corresponds to SSL_get_min_proto_version.

pub fn max_proto_version(&self) -> Option<SslVersion>

Gets the maximum supported protocol version.

This corresponds to SSL_get_max_proto_version.

pub fn selected_alpn_protocol(&self) -> Option<&[u8]>

Returns the protocol selected via Application Layer Protocol Negotiation (ALPN).

The protocol’s name is returned is an opaque sequence of bytes. It is up to the client to interpret it.

This corresponds to SSL_get0_alpn_selected.

pub fn set_tlsext_use_srtp(&mut self, protocols: &str) -> Result<(), ErrorStack>

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

This corresponds to SSL_set_tlsext_use_srtp.

pub fn srtp_profiles(&self) -> Option<&StackRef<SrtpProtectionProfile>>

Gets all SRTP profiles that are enabled for handshake via set_tlsext_use_srtp

DTLS extension “use_srtp” as defined in RFC5764 has to be enabled.

This corresponds to SSL_get_strp_profiles.

pub fn selected_srtp_profile(&self) -> Option<&SrtpProtectionProfileRef>

Gets the SRTP profile selected by handshake.

DTLS extension “use_srtp” as defined in RFC5764 has to be enabled.

This corresponds to SSL_get_selected_srtp_profile.

pub fn pending(&self) -> usize

Returns the number of bytes remaining in the currently processed TLS record.

If this is greater than 0, the next call to read will not call down to the underlying stream.

This corresponds to SSL_pending.

pub fn servername(&self, type_: NameType) -> Option<&str>

Returns the servername sent by the client via Server Name Indication (SNI).

It is only useful on the server side.

Note

While the SNI specification requires that servernames be valid domain names (and therefore ASCII), OpenSSL does not enforce this restriction. If the servername provided by the client is not valid UTF-8, this function will return None. The servername_raw method returns the raw bytes and does not have this restriction.

This corresponds to SSL_get_servername.

pub fn servername_raw(&self, type_: NameType) -> Option<&[u8]>

Returns the servername sent by the client via Server Name Indication (SNI).

It is only useful on the server side.

Note

Unlike servername, this method does not require the name be valid UTF-8.

This corresponds to SSL_get_servername.

pub fn set_ssl_context(&mut self, ctx: &SslContextRef) -> Result<(), ErrorStack>

Changes the context corresponding to the current connection.

It is most commonly used in the Server Name Indication (SNI) callback. A different context replaces the certificate callback and configured credentials, including their per-connection overrides. An already selected credential and its signer stay selected for the current handshake.

Verification mode and callbacks installed with set_verify_callback or set_custom_verify_callback are preserved. Re-apply them explicitly after routing when the destination requires a different client-auth policy. Verification parameters (depth, X.509 flags, purpose and hostname) and preferences for verifying peer signatures are also preserved. Apply the destination’s policy explicitly on the connection after routing. The context-level SslContextBuilder::set_cert_verify_callback hook instead follows ctx, as does its default certificate store. Routing also replaces the per-connection verification store and session ID context with ctx’s values. Apply any per-connection trust-store override after routing. Ticket-key and PSK callbacks retain their original context. An active async certificate selection or custom verification is cancelled and the handshake will fail. Pending early ClientHello callbacks are also cancelled; route in their finish closure. Returns an error without changing the connection if the contexts differ in X.509 support.

This corresponds to SSL_set_SSL_CTX.

pub fn ssl_context(&self) -> &SslContextRef

Returns the context corresponding to the current connection.

This corresponds to SSL_get_SSL_CTX.

pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef

Returns a mutable reference to the X509 verification configuration.

This corresponds to SSL_get0_param.

pub fn param_mut(&mut self) -> &mut X509VerifyParamRef

See Self::verify_param_mut.

pub fn verify_result(&self) -> Result<(), X509VerifyError>

Returns the certificate verification result.

This corresponds to SSL_get_verify_result.

pub fn session(&self) -> Option<&SslSessionRef>

Returns a shared reference to the SSL session.

This corresponds to SSL_get_session.

pub fn client_random(&self, buf: &mut [u8]) -> usize

Copies the client_random value sent by the client in the TLS handshake into a buffer.

Returns the number of bytes copied, or if the buffer is empty, the size of the client_random value.

This corresponds to SSL_get_client_random.

pub fn server_random(&self, buf: &mut [u8]) -> usize

Copies the server_random value sent by the server in the TLS handshake into a buffer.

Returns the number of bytes copied, or if the buffer is empty, the size of the server_random value.

This corresponds to SSL_get_server_random.

pub fn export_keying_material( &self, out: &mut [u8], label: &str, context: Option<&[u8]>, ) -> Result<(), ErrorStack>

Derives keying material for application use in accordance to RFC 5705.

This corresponds to SSL_export_keying_material.

pub fn export_keying_material_bytes( &self, out: &mut [u8], label: &[u8], context: Option<&[u8]>, ) -> Result<(), ErrorStack>

Derive application keying material with a byte-oriented exporter label.

This corresponds to SSL_export_keying_material.

pub unsafe fn set_session( &mut self, session: &SslSessionRef, ) -> Result<(), ErrorStack>

Sets the session to be used.

This should be called before the handshake to attempt to reuse a previously established session. If the server is not willing to reuse the session, a new one will be transparently negotiated.

Safety

The caller of this method is responsible for ensuring that the session is associated with the same SslContext as this Ssl.

This corresponds to SSL_set_session.

pub fn session_reused(&self) -> bool

Determines if the session provided to set_session was successfully reused.

This corresponds to SSL_session_reused.

pub fn set_status_type(&mut self, type_: StatusType) -> Result<(), ErrorStack>

Sets the status response a client wishes the server to reply with.

This corresponds to SSL_set_tlsext_status_type.

pub fn ocsp_status(&self) -> Option<&[u8]>

Returns the server’s OCSP response, if present.

This corresponds to SSL_get_tlsext_status_ocsp_resp.

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

Sets the OCSP response to be returned to the client.

This corresponds to SSL_set_ocsp_response.

pub fn is_server(&self) -> bool

Determines if this Ssl is configured for server-side or client-side use.

This corresponds to SSL_is_server.

pub fn set_ex_data<T>(&mut self, index: Index<Ssl, T>, data: T)

Sets the extra data at the specified index.

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

Note that if this method is called multiple times with the same index, any previous value stored in the SslContextBuilder will be leaked.

This corresponds to SSL_set_ex_data.

pub fn replace_ex_data<T>(&mut self, index: Index<Ssl, T>, data: T) -> Option<T>

Sets or overwrites the extra data at the specified index.

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

The previous value, if any, will be returned.

This corresponds to SSL_set_ex_data.

pub fn ex_data<T>(&self, index: Index<Ssl, T>) -> Option<&T>

Returns a reference to the extra data at the specified index.

This corresponds to SSL_get_ex_data.

pub fn ex_data_mut<T>(&mut self, index: Index<Ssl, T>) -> Option<&mut T>

Returns a mutable reference to the extra data at the specified index.

This corresponds to SSL_get_ex_data.

pub fn finished(&self, buf: &mut [u8]) -> usize

Copies the contents of the last Finished message sent to the peer into the provided buffer.

The total size of the message is returned, so this can be used to determine the size of the buffer required.

This corresponds to SSL_get_finished.

pub fn peer_finished(&self, buf: &mut [u8]) -> usize

Copies the contents of the last Finished message received from the peer into the provided buffer.

The total size of the message is returned, so this can be used to determine the size of the buffer required.

This corresponds to SSL_get_peer_finished.

pub fn is_init_finished(&self) -> bool

Determines if the initial handshake has been completed.

This corresponds to SSL_is_init_finished.

pub fn set_mtu(&mut self, mtu: u32) -> Result<(), ErrorStack>

Sets the MTU used for DTLS connections.

This corresponds to SSL_set_mtu.

pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack>

Sets the certificate.

This corresponds to SSL_use_certificate.

pub fn set_client_ca_list(&mut self, list: Stack<X509Name>)

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

pub fn set_private_key<T>(&mut self, key: &PKeyRef<T>) -> Result<(), ErrorStack>

where T: HasPrivate,

Sets the private key.

This corresponds to SSL_use_PrivateKey.

pub fn set_mode(&mut self, mode: SslMode) -> SslMode

Enables all modes set in mode in SSL. Returns a bitmask representing the resulting enabled modes.

This corresponds to SSL_set_mode.

pub fn clear_mode(&mut self, mode: SslMode) -> SslMode

Disables all modes set in mode in SSL. Returns a bitmask representing the resulting enabled modes.

This corresponds to SSL_clear_mode.

pub fn add_chain_cert(&mut self, cert: &X509Ref) -> Result<(), ErrorStack>

Appends cert to the chain associated with the current certificate of SSL.

This corresponds to SSL_add1_chain_cert.

pub fn signed_cert_timestamp_list(&self) -> Option<&[u8]>

Returns the server’s stapled SignedCertificateTimestampList, including its outer u16 length. Returns None if no list was received.

Intended for clients after the handshake. These bytes are not guaranteed to be well formed or valid; applications must validate them before relying on them.

This corresponds to SSL_get0_signed_cert_timestamp_list.

pub fn set_client_key_shares( &mut self, curves: &[SslCurve], ) -> Result<(), ErrorStack>

Sends TLS 1.3 key shares for exactly curves, in order, in the initial ClientHello.

The curves must be unique and an ordered subset of the configured groups, so finish configuring groups first. With GREASE enabled a GREASE key share is added as well. An empty slice sends no real key share, which costs a HelloRetryRequest. Without this call, BoringSSL sends at most two key shares, at most one of them post-quantum. A server supported groups hint, when set, takes precedence over this selection.

This corresponds to SSL_set1_client_key_shares.

pub fn set_requested_trust_anchors( &mut self, ids: &[u8], ) -> Result<(), ErrorStack>

Sets the requested trust anchor IDs for this connection, overriding its context.

See SslContextBuilder::set_requested_trust_anchors for the encoding and retry requirements. An empty slice sends a present-empty extension. The native API copies the input. Certificate verification is unchanged.

Configure this before starting the handshake. If BoringSSL has discarded the connection’s handshake configuration, this returns an error without adding a diagnostic to the native error queue; the error stack may be empty.

This corresponds to SSL_set1_requested_trust_anchors.

pub fn set_available_trust_anchors( &mut self, ids: &[u8], ) -> Result<(), ErrorStack>

Overrides the server’s advertised available trust anchor IDs for this connection.

See SslContextBuilder::set_available_trust_anchors for the wire encoding and when an explicit list is needed.

Configure this before starting the handshake. If BoringSSL has discarded the connection’s handshake configuration, this returns an error without adding a diagnostic to the native error queue; the error stack may be empty.

This corresponds to SSL_set1_available_trust_anchors.

pub fn peer_available_trust_anchors(&self) -> &[u8]

Returns the server’s available trust anchor IDs as a u8-length-prefixed list.

This is available only during the handshake, normally in certificate verification callbacks. Copy it there if it is needed to retry a failed connection. An empty slice means no list is available. The list only guides selection: retries must use an independently trusted anchor and still verify the server’s certificate and identity.

This corresponds to SSL_get0_peer_available_trust_anchors.

pub fn peer_matched_trust_anchor(&self) -> bool

Whether the peer reports that its chain matches a requested trust anchor.

Available only during the handshake, typically in a verification callback; returns false outside it. This is not a verification result. A verifier may validate the supplied chain as a pre-built path, but must still validate its signatures, trust anchor, identity, and other certificate policy.

This corresponds to SSL_peer_matched_trust_anchor.

pub fn set_ca_names( &mut self, names: &StackRef<X509Name>, ) -> Result<(), ErrorStack>

Configures the CA distinguished names advertised in ClientHello’s certificate_authorities extension. An empty stack disables the extension.

The names are copied. This is separate from the CA list a server sends when requesting client certificates, and does not modify certificate verification.

This corresponds to SSL_set0_CA_names.

pub fn selected_credential(&self) -> Option<&SslCredentialRef>

Returns the credential selected for the current handshake, if available.

Intended for handshake callbacks, including custom private key methods, to access credential-specific extra data. Legacy certificate configuration may return an internal credential without application extra data.

This corresponds to SSL_get0_selected_credential.

pub fn set_ech_config_list( &mut self, ech_config_list: &[u8], ) -> Result<(), ErrorStack>

Configures ech_config_list on SSL for offering ECH during handshakes. If the server cannot decrypt the encrypted ClientHello, SSL will instead handshake using the cleartext parameters of the ClientHelloOuter.

Clients should use get_ech_name_override to verify the server certificate in case of ECH rejection, and follow up with get_ech_retry_configs to retry the connection with a fresh set of ECHConfigs. If the retry also fails, clients should report a connection failure.

This corresponds to SSL_set1_ech_config_list.

pub fn get_ech_retry_configs(&self) -> Option<&[u8]>

This function returns a serialized ECHConfigList as provided by the server, if one exists.

Clients should call this function when handling an SSL_R_ECH_REJECTED error code to recover from potential key mismatches. If the result is Some, the client should retry the connection using the returned ECHConfigList.

This corresponds to SSL_get0_ech_retry_configs.

pub fn get_ech_name_override(&self) -> Option<&[u8]>

If SSL is a client and the server rejects ECH, this function returns the public name associated with the ECHConfig that was used to attempt ECH.

Clients should call this function during the certificate verification callback to ensure the server’s certificate is valid for the public name, which is required to authenticate retry configs.

This corresponds to SSL_get0_ech_name_override.

pub fn ech_accepted(&self) -> bool

This corresponds to SSL_ech_accepted.

pub fn set_enable_ech_grease(&self, enable: bool)

Enables ECH GREASE when TLS 1.3 is offered and no usable real ECH configuration is selected. Configure before starting the handshake. Defaults to disabled. ClientHelloShape::set_ech_grease optionally controls its algorithms and lengths without enabling it.

This corresponds to SSL_set_enable_ech_grease.

pub fn set_compliance_policy( &mut self, policy: CompliancePolicy, ) -> Result<(), ErrorStack>

Sets the compliance policy on SSL.

This corresponds to SSL_set_compliance_policy.

pub fn add_credential( &mut self, credential: &SslCredentialRef, ) -> Result<(), ErrorStack>

Adds a credential.

This corresponds to SSL_add1_credential.

pub fn set_alps_use_new_codepoint(&mut self, use_new_codepoint: bool)

Sets whether to use the new ALPS codepoint for SSL.

This corresponds to SSL_set_alps_use_new_codepoint.

pub fn add_application_settings( &mut self, alps: &[u8], ) -> Result<(), ErrorStack>

Adds application settings for the given protocol to be sent via ALPS.

This corresponds to SSL_add_application_settings.

pub fn add_application_settings_value( &mut self, protocol: &[u8], value: &[u8], ) -> Result<(), ErrorStack>

Enables ALPS for protocol, sending value as this endpoint’s settings.

The protocol must also be negotiable through ALPN. A server can configure only the protocol it selects, from its ALPN select callback.

This corresponds to SSL_add_application_settings.

pub fn peer_application_settings(&self) -> Option<&[u8]>

The settings the peer sent through ALPS, or None when ALPS was not negotiated.

This corresponds to SSL_get0_peer_application_settings.

pub fn certificate_compression_algorithm( &self, ) -> Option<CertificateCompressionAlgorithm>

The algorithm this endpoint compressed its own certificate with.

pub fn peer_certificate_compression_algorithm( &self, ) -> Option<CertificateCompressionAlgorithm>

The algorithm the peer compressed its certificate with.

Trait Implementations

impl AsMut<SslRef> for Ssl

fn as_mut(&mut self) -> &mut SslRef

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<SslRef> for Ssl

fn as_ref(&self) -> &SslRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<SslRef> for Ssl

fn borrow(&self) -> &SslRef

Immutably borrows from an owned value.

impl BorrowMut<SslRef> for Ssl

fn borrow_mut(&mut self) -> &mut SslRef

Mutably borrows from an owned value.

impl Debug for Ssl

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for Ssl

type Target = SslRef

The resulting type after dereferencing.

fn deref(&self) -> &SslRef

Dereferences the value.

impl DerefMut for Ssl

fn deref_mut(&mut self) -> &mut SslRef

Mutably dereferences the value.

impl Drop for Ssl

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl ForeignType for Ssl

type CType = ssl_st

The raw C type.

type Ref = SslRef

The type representing a reference to this type.

unsafe fn from_ptr(ptr: *mut ssl_st) -> Ssl

Constructs an instance of this type from its raw type.

fn as_ptr(&self) -> *mut ssl_st

Returns a raw pointer to the wrapped value.

fn into_ptr(self) -> *mut Self::CType

Consumes the wrapper and returns the raw pointer.

impl Send for Ssl

impl Sync for Ssl