rust/bssl-tls/src/sessions.rs - boringssl.git - Git at Google

 // Copyright 2026 The BoringSSL Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 //! TLS Session support for BoringSSL.

 use alloc::vec::Vec;
 use core::ptr::{
     NonNull,
     null_mut, //
 };

 use crate::{
     call_slice_getter,
     config::ProtocolVersion,
     context::TlsContext,
     errors::Error,
     ffi::{
         Alloc,
         sanitize_slice,
         slice_into_ffi_raw_parts, //
     }, //
 };

 /// A TLS session.
 ///
 /// See [RFC 8446 Section 2.2](https://datatracker.ietf.org/doc/html/rfc8446#section-2.2).
 ///
 /// # Example
 ///
 /// ```rust,no_run
 /// # use bssl_tls::{context::TlsContext, sessions::TlsSession};
 /// # use bssl_tls::context::{Client, TlsMode};
 /// # use bssl_tls::connection::lifecycle::EstablishedTlsConnection;
 /// // Assuming `conn` is an `EstablishedTlsConnection`
 /// # let conn: EstablishedTlsConnection<'_, Client, TlsMode> = todo!();
 /// # let ctx: TlsContext = todo!();
 /// if let Some(session) = conn.get_session() {
 ///     // Serialize the session to store it
 ///     let session_bytes = session.to_bytes().unwrap();
 ///
 ///     // Deserialize the session to resume it later
 ///     let recovered_session = TlsSession::from_bytes(&session_bytes, &ctx).unwrap();
 /// }
 /// ```
 pub struct TlsSession(pub(crate) NonNull<bssl_sys::SSL_SESSION>);

 // Safety: once constructed an `SSL_SESSION` is immutable and has no thread-local data.
 unsafe impl Send for TlsSession {}
 unsafe impl Sync for TlsSession {}

 impl Drop for TlsSession {
     fn drop(&mut self) {
         unsafe {
             // Safety: self.ptr() is valid and we own a reference.
             bssl_sys::SSL_SESSION_free(self.ptr());
         }
     }
 }

 impl Clone for TlsSession {
     fn clone(&self) -> Self {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_up_ref(self.ptr());
         }
         Self(self.0)
     }
 }

 impl TlsSession {
     pub(crate) fn ptr(&self) -> *mut bssl_sys::SSL_SESSION {
         self.0.as_ptr()
     }

     /// Serializes the session into a newly allocated buffer.
     pub fn to_bytes(&self) -> Result<Vec<u8>, Error> {
         let mut out_data: *mut u8 = core::ptr::null_mut();
         let mut out_len: usize = 0;
         let rc = unsafe {
             // Safety: `self.ptr()` is still valid.
             bssl_sys::SSL_SESSION_to_bytes(self.ptr(), &raw mut out_data, &raw mut out_len)
         };
         if rc != 1 {
             return Err(Error::extract_lib_err());
         }
         let out_data = Alloc(out_data);
         let slice = unsafe {
             // Safety: out_data.0 and out_len are returned by BoringSSL and are valid.
             sanitize_slice(out_data.0, out_len).unwrap()
         };
         Ok(slice.to_vec())
     }

     /// Serializes the session for a ticket, excluding the session ID.
     pub fn to_bytes_for_ticket(&self) -> Result<Vec<u8>, Error> {
         let mut out_data: *mut u8 = core::ptr::null_mut();
         let mut out_len: usize = 0;
         let rc = unsafe {
             // Safety: `self.ptr()` is still valid.
             bssl_sys::SSL_SESSION_to_bytes_for_ticket(self.ptr(), &mut out_data, &mut out_len)
         };
         if rc != 1 {
             return Err(Error::extract_lib_err());
         }
         let out_data = Alloc(out_data);
         let slice = unsafe {
             // Safety: out_data.0 and out_len are returned by BoringSSL and are valid.
             sanitize_slice(out_data.0, out_len).unwrap()
         };
         Ok(slice.to_vec())
     }

     /// Parses a serialized session from bytes.
     pub fn from_bytes<M>(bytes: &[u8], ctx: &TlsContext<M>) -> Result<Self, Error> {
         let (ptr, len) = slice_into_ffi_raw_parts(bytes);
         let ptr = unsafe {
             // Safety: bytes is a valid slice and the context is still valid.
             bssl_sys::SSL_SESSION_from_bytes(ptr, len, ctx.ptr())
         };
         let ptr = NonNull::new(ptr).ok_or_else(|| Error::extract_lib_err())?;
         Ok(Self(ptr))
     }

     /// Get the protocol version of the session.
     pub fn get_protocol_version(&self) -> Option<ProtocolVersion> {
         let version = unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get_protocol_version(self.ptr())
         };
         version.try_into().ok()
     }

     /// Get the session creation time in seconds since the epoch.
     pub fn get_time(&self) -> u64 {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get_time(self.ptr())
         }
     }

     /// Get the session timeout in seconds.
     pub fn get_timeout(&self) -> u64 {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get_timeout(self.ptr()).into()
         }
     }

     /// Get the peer certificates as a list of DER-encoded certificates.
     pub fn get_peer_certificates(&self) -> Result<Vec<Vec<u8>>, Error> {
         let sk = unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get0_peer_certificates(self.ptr())
         };
         if sk.is_null() {
             return Ok(Vec::new());
         }
         let len = unsafe {
             // Safety: `sk` is valid.
             bssl_sys::sk_CRYPTO_BUFFER_num(sk)
         };
         let mut res = Vec::new();
         for i in 0..len {
             let buf = unsafe {
                 // Safety: `sk` is valid and `i` is in bounds.
                 bssl_sys::sk_CRYPTO_BUFFER_value(sk, i)
             };
             if buf.is_null() {
                 continue;
             }
             let (data, len) = unsafe {
                 // Safety: `buf` is valid.
                 (
                     bssl_sys::CRYPTO_BUFFER_data(buf),
                     bssl_sys::CRYPTO_BUFFER_len(buf),
                 )
             };
             let Some(slice) = (unsafe {
                 // Safety: data and len are valid.
                 sanitize_slice(data, len)
             }) else {
                 continue;
             };
             res.push(slice.to_vec());
         }
         Ok(res)
     }

     // TODO(@xfding): Implement SSL_SESSION_get0_peer_rpk when needed.

     /// Get the signed certificate timestamp list, if any.
     pub fn get0_signed_cert_timestamp_list(&self) -> Option<&[u8]> {
         call_slice_getter!(
             bssl_sys::SSL_SESSION_get0_signed_cert_timestamp_list,
             self.ptr()
         )
     }

     /// Get the OCSP response, if any.
     ///
     /// See [RFC 8446 §4.4.2.1](https://datatracker.ietf.org/doc/html/rfc8446#section-4.4.2.1).
     pub fn get_ocsp_response(&self) -> Option<&[u8]> {
         call_slice_getter!(bssl_sys::SSL_SESSION_get0_ocsp_response, self.ptr())
     }

     /// Get the master key.
     ///
     /// In TLS 1.3, this returns the **Resumption Master Secret**.
     /// See [RFC 8446 §7.1](https://datatracker.ietf.org/doc/html/rfc8446#section-7.1).
     ///
     /// BoringSSL uses this secret to automatically derive the Pre-Shared Key (PSK) for
     /// session resumption. Users should not attempt to manually expand this secret or
     /// perform manual cryptography; BoringSSL handles the key expansion internally when
     /// a session is configured for resumption.
     ///
     /// # Example
     ///
     /// If you need to derive a PSK for external use (e.g. for external PSK resumption),
     /// you can use `bssl_crypto::hkdf`:
     ///
     /// ```rust,no_run
     /// # use bssl_tls::sessions::TlsSession;
     /// # // Assuming `session` is a `TlsSession`
     /// # let session: TlsSession = todo!();
     /// let master_key = session.get_master_key();
     ///
     /// // Treat the master key as a PRK in HKDF
     /// let prk = bssl_crypto::hkdf::Prk::new::<bssl_crypto::digest::Sha256>(&master_key)
     ///     .expect("Invalid master key length");
     ///
     /// // Expand it to derive a PSK
     /// let mut psk = vec![0u8; 32];
     /// prk.expand_into(b"resumption psk", &mut psk)
     ///     .expect("HKDF expansion failed");
     /// ```
     pub fn get_master_key(&self) -> Vec<u8> {
         let len = unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get_master_key(self.ptr(), null_mut(), 0)
         };
         let mut out = vec![0u8; len];
         let len = unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_get_master_key(self.ptr(), out.as_mut_ptr(), out.len())
         };
         out.truncate(len);
         out
     }

     /// Check if the session should be single use.
     pub fn should_be_single_use(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_should_be_single_use(self.ptr()) == 1
         }
     }

     /// Check if the session is resumable.
     pub fn is_resumable(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_is_resumable(self.ptr()) == 1
         }
     }

     /// Check if the session has a ticket.
     pub fn has_ticket(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_has_ticket(self.ptr()) == 1
         }
     }

     /// Get the ticket, if any.
     pub fn get_ticket(&self) -> Option<&[u8]> {
         call_slice_getter!(bssl_sys::SSL_SESSION_get0_ticket, self.ptr())
     }

     /// Check if the session has a peer SHA256.
     pub fn has_peer_sha256(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_has_peer_sha256(self.ptr()) == 1
         }
     }

     /// Get the peer SHA256, if any.
     pub fn get_peer_sha256(&self) -> Option<&[u8]> {
         call_slice_getter!(bssl_sys::SSL_SESSION_get0_peer_sha256, self.ptr())
     }

     /// Check if the session is resumable across names.
     pub fn is_resumable_across_names(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_is_resumable_across_names(self.ptr()) == 1
         }
     }

     /// Check if the session is early data capable.
     pub fn early_data_capable(&self) -> bool {
         unsafe {
             // Safety: self.ptr() is valid.
             bssl_sys::SSL_SESSION_early_data_capable(self.ptr()) == 1
         }
     }
 }

 #[cfg(test)]
 mod tests {
     use core::pin::Pin;

     use futures::future::try_join;

     use super::*;

     use crate::tests::create_mock_pipe;
     use crate::{
         context::TlsContextBuilder,
         credentials::{
             PskHash,
             TlsCredential, //
         }, //
     };

     const TEST_KEY: &[u8; 32] = b"0123456789abcdef0123456789abcdef";
     const TEST_IDENTITY: &[u8] = b"test-identity";
     const TEST_CONTEXT: &[u8] = b"test-context";

     #[test]
     fn test_session_ops() {
         let ctx = TlsContextBuilder::new_tls().build();
         let dummy_bytes = vec![0u8; 32];
         let res = TlsSession::from_bytes(&dummy_bytes, &ctx);
         assert!(res.is_err());
     }

     #[test]
     fn test_psk_resumption() {
         let cred_client = TlsCredential::new_pre_shared_key(
             TEST_KEY,
             TEST_IDENTITY,
             PskHash::Sha256,
             TEST_CONTEXT,
         )
         .unwrap();
         let cred_server = TlsCredential::new_pre_shared_key(
             TEST_KEY,
             TEST_IDENTITY,
             PskHash::Sha256,
             TEST_CONTEXT,
         )
         .unwrap();

         let mut ctx_client = TlsContextBuilder::new_tls();
         ctx_client.with_credential(cred_client).unwrap();
         let ctx_client = ctx_client.build();

         let mut ctx_server = TlsContextBuilder::new_tls();
         ctx_server.with_credential(cred_server).unwrap();
         let ctx_server = ctx_server.build();

         let mut conn_client = ctx_client.new_client_connection(None).unwrap().build();
         let mut conn_server = ctx_server.new_server_connection(None).unwrap().build();

         let (sock_client, sock_server, mut executor) = create_mock_pipe();

         conn_client.set_io(sock_client).unwrap();
         conn_server.set_io(sock_server).unwrap();

         executor
             .run(try_join(
                 conn_client.in_handshake().unwrap().async_handshake(),
                 conn_server.in_handshake().unwrap().async_handshake(),
             ))
             .unwrap();

         let est_client = conn_client.established().unwrap();
         let session = est_client.get_session().unwrap();

         let session_bytes = session.to_bytes().unwrap();
         assert!(!session_bytes.is_empty());

         let session_recovered = TlsSession::from_bytes(&session_bytes, &ctx_client).unwrap();

         let session_bytes_2 = session_recovered.to_bytes().unwrap();
         assert_eq!(session_bytes, session_bytes_2);
     }

     #[test]
     fn test_ticket_based_resumption() {
         let cred_client = TlsCredential::new_pre_shared_key(
             TEST_KEY,
             TEST_IDENTITY,
             PskHash::Sha256,
             TEST_CONTEXT,
         )
         .unwrap();
         let cred_server = TlsCredential::new_pre_shared_key(
             TEST_KEY,
             TEST_IDENTITY,
             PskHash::Sha256,
             TEST_CONTEXT,
         )
         .unwrap();

         let mut ctx_client = TlsContextBuilder::new_tls();
         ctx_client.with_credential(cred_client).unwrap();
         let ctx_client = ctx_client.build();

         let mut ctx_server = TlsContextBuilder::new_tls();
         ctx_server.with_credential(cred_server).unwrap();
         let ctx_server = ctx_server.build();
         let mut conn_client = ctx_client.new_client_connection(None).unwrap().build();
         let mut conn_server = ctx_server.new_server_connection(None).unwrap().build();

         let (sock_client, sock_server, mut executor) = create_mock_pipe();

         conn_client.set_io(sock_client).unwrap();
         conn_server.set_io(sock_server).unwrap();

         executor
             .run(try_join(
                 conn_client.in_handshake().unwrap().async_handshake(),
                 conn_server.in_handshake().unwrap().async_handshake(),
             ))
             .unwrap();

         let est_client = conn_client.established().unwrap();
         let session = est_client.get_session().unwrap();
         let peer = session.get_peer_sha256().unwrap();

         // === SESSION RESUMPTION ===
         // Use the session for a new connection
         let (sock_client_2, sock_server_2, mut executor) = create_mock_pipe();

         let mut builder_client_2 = ctx_client.new_client_connection(None).unwrap();
         builder_client_2.with_session(&session);
         let mut conn_client_2 = builder_client_2.build();

         let builder_server_2 = ctx_server.new_server_connection(None).unwrap();
         let mut conn_server_2 = builder_server_2.build();

         conn_client_2.set_io(sock_client_2).unwrap();
         conn_server_2.set_io(sock_server_2).unwrap();

         executor
             .run(try_join(
                 Pin::new(&mut conn_client_2).async_write(b"hello"),
                 Pin::new(&mut conn_server_2).async_write(b"world"),
             ))
             .unwrap();
         // The peer identity should be the same as before
         assert_eq!(
             conn_client_2
                 .established()
                 .unwrap()
                 .get_session()
                 .unwrap()
                 .get_peer_sha256()
                 .unwrap(),
             peer
         );
     }
 }
	// Copyright 2026 The BoringSSL Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	//! TLS Session support for BoringSSL.

	use alloc::vec::Vec;
	use core::ptr::{
	NonNull,
	null_mut, //
	};

	use crate::{
	call_slice_getter,
	config::ProtocolVersion,
	context::TlsContext,
	errors::Error,
	ffi::{
	Alloc,
	sanitize_slice,
	slice_into_ffi_raw_parts, //
	}, //
	};

	/// A TLS session.
	///
	/// See [RFC 8446 Section 2.2](https://datatracker.ietf.org/doc/html/rfc8446#section-2.2).
	///
	/// # Example
	///
	/// ```rust,no_run
	/// # use bssl_tls::{context::TlsContext, sessions::TlsSession};
	/// # use bssl_tls::context::{Client, TlsMode};
	/// # use bssl_tls::connection::lifecycle::EstablishedTlsConnection;
	/// // Assuming `conn` is an `EstablishedTlsConnection`
	/// # let conn: EstablishedTlsConnection<'_, Client, TlsMode> = todo!();
	/// # let ctx: TlsContext = todo!();
	/// if let Some(session) = conn.get_session() {
	/// // Serialize the session to store it
	/// let session_bytes = session.to_bytes().unwrap();
	///
	/// // Deserialize the session to resume it later
	/// let recovered_session = TlsSession::from_bytes(&session_bytes, &ctx).unwrap();
	/// }
	/// ```
	pub struct TlsSession(pub(crate) NonNull<bssl_sys::SSL_SESSION>);

	// Safety: once constructed an `SSL_SESSION` is immutable and has no thread-local data.
	unsafe impl Send for TlsSession {}
	unsafe impl Sync for TlsSession {}

	impl Drop for TlsSession {
	fn drop(&mut self) {
	unsafe {
	// Safety: self.ptr() is valid and we own a reference.
	bssl_sys::SSL_SESSION_free(self.ptr());
	}
	}
	}

	impl Clone for TlsSession {
	fn clone(&self) -> Self {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_up_ref(self.ptr());
	}
	Self(self.0)
	}
	}

	impl TlsSession {
	pub(crate) fn ptr(&self) -> *mut bssl_sys::SSL_SESSION {
	self.0.as_ptr()
	}

	/// Serializes the session into a newly allocated buffer.
	pub fn to_bytes(&self) -> Result<Vec<u8>, Error> {
	let mut out_data: *mut u8 = core::ptr::null_mut();
	let mut out_len: usize = 0;
	let rc = unsafe {
	// Safety: `self.ptr()` is still valid.
	bssl_sys::SSL_SESSION_to_bytes(self.ptr(), &raw mut out_data, &raw mut out_len)
	};
	if rc != 1 {
	return Err(Error::extract_lib_err());
	}
	let out_data = Alloc(out_data);
	let slice = unsafe {
	// Safety: out_data.0 and out_len are returned by BoringSSL and are valid.
	sanitize_slice(out_data.0, out_len).unwrap()
	};
	Ok(slice.to_vec())
	}

	/// Serializes the session for a ticket, excluding the session ID.
	pub fn to_bytes_for_ticket(&self) -> Result<Vec<u8>, Error> {
	let mut out_data: *mut u8 = core::ptr::null_mut();
	let mut out_len: usize = 0;
	let rc = unsafe {
	// Safety: `self.ptr()` is still valid.
	bssl_sys::SSL_SESSION_to_bytes_for_ticket(self.ptr(), &mut out_data, &mut out_len)
	};
	if rc != 1 {
	return Err(Error::extract_lib_err());
	}
	let out_data = Alloc(out_data);
	let slice = unsafe {
	// Safety: out_data.0 and out_len are returned by BoringSSL and are valid.
	sanitize_slice(out_data.0, out_len).unwrap()
	};
	Ok(slice.to_vec())
	}

	/// Parses a serialized session from bytes.
	pub fn from_bytes<M>(bytes: &[u8], ctx: &TlsContext<M>) -> Result<Self, Error> {
	let (ptr, len) = slice_into_ffi_raw_parts(bytes);
	let ptr = unsafe {
	// Safety: bytes is a valid slice and the context is still valid.
	bssl_sys::SSL_SESSION_from_bytes(ptr, len, ctx.ptr())
	};
	let ptr = NonNull::new(ptr).ok_or_else(\|\| Error::extract_lib_err())?;
	Ok(Self(ptr))
	}

	/// Get the protocol version of the session.
	pub fn get_protocol_version(&self) -> Option<ProtocolVersion> {
	let version = unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get_protocol_version(self.ptr())
	};
	version.try_into().ok()
	}

	/// Get the session creation time in seconds since the epoch.
	pub fn get_time(&self) -> u64 {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get_time(self.ptr())
	}
	}

	/// Get the session timeout in seconds.
	pub fn get_timeout(&self) -> u64 {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get_timeout(self.ptr()).into()
	}
	}

	/// Get the peer certificates as a list of DER-encoded certificates.
	pub fn get_peer_certificates(&self) -> Result<Vec<Vec<u8>>, Error> {
	let sk = unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get0_peer_certificates(self.ptr())
	};
	if sk.is_null() {
	return Ok(Vec::new());
	}
	let len = unsafe {
	// Safety: `sk` is valid.
	bssl_sys::sk_CRYPTO_BUFFER_num(sk)
	};
	let mut res = Vec::new();
	for i in 0..len {
	let buf = unsafe {
	// Safety: `sk` is valid and `i` is in bounds.
	bssl_sys::sk_CRYPTO_BUFFER_value(sk, i)
	};
	if buf.is_null() {
	continue;
	}
	let (data, len) = unsafe {
	// Safety: `buf` is valid.
	(
	bssl_sys::CRYPTO_BUFFER_data(buf),
	bssl_sys::CRYPTO_BUFFER_len(buf),
	)
	};
	let Some(slice) = (unsafe {
	// Safety: data and len are valid.
	sanitize_slice(data, len)
	}) else {
	continue;
	};
	res.push(slice.to_vec());
	}
	Ok(res)
	}

	// TODO(@xfding): Implement SSL_SESSION_get0_peer_rpk when needed.

	/// Get the signed certificate timestamp list, if any.
	pub fn get0_signed_cert_timestamp_list(&self) -> Option<&[u8]> {
	call_slice_getter!(
	bssl_sys::SSL_SESSION_get0_signed_cert_timestamp_list,
	self.ptr()
	)
	}

	/// Get the OCSP response, if any.
	///
	/// See [RFC 8446 §4.4.2.1](https://datatracker.ietf.org/doc/html/rfc8446#section-4.4.2.1).
	pub fn get_ocsp_response(&self) -> Option<&[u8]> {
	call_slice_getter!(bssl_sys::SSL_SESSION_get0_ocsp_response, self.ptr())
	}

	/// Get the master key.
	///
	/// In TLS 1.3, this returns the Resumption Master Secret.
	/// See [RFC 8446 §7.1](https://datatracker.ietf.org/doc/html/rfc8446#section-7.1).
	///
	/// BoringSSL uses this secret to automatically derive the Pre-Shared Key (PSK) for
	/// session resumption. Users should not attempt to manually expand this secret or
	/// perform manual cryptography; BoringSSL handles the key expansion internally when
	/// a session is configured for resumption.
	///
	/// # Example
	///
	/// If you need to derive a PSK for external use (e.g. for external PSK resumption),
	/// you can use `bssl_crypto::hkdf`:
	///
	/// ```rust,no_run
	/// # use bssl_tls::sessions::TlsSession;
	/// # // Assuming `session` is a `TlsSession`
	/// # let session: TlsSession = todo!();
	/// let master_key = session.get_master_key();
	///
	/// // Treat the master key as a PRK in HKDF
	/// let prk = bssl_crypto::hkdf::Prk::new::<bssl_crypto::digest::Sha256>(&master_key)
	/// .expect("Invalid master key length");
	///
	/// // Expand it to derive a PSK
	/// let mut psk = vec![0u8; 32];
	/// prk.expand_into(b"resumption psk", &mut psk)
	/// .expect("HKDF expansion failed");
	/// ```
	pub fn get_master_key(&self) -> Vec<u8> {
	let len = unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get_master_key(self.ptr(), null_mut(), 0)
	};
	let mut out = vec![0u8; len];
	let len = unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_get_master_key(self.ptr(), out.as_mut_ptr(), out.len())
	};
	out.truncate(len);
	out
	}

	/// Check if the session should be single use.
	pub fn should_be_single_use(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_should_be_single_use(self.ptr()) == 1
	}
	}

	/// Check if the session is resumable.
	pub fn is_resumable(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_is_resumable(self.ptr()) == 1
	}
	}

	/// Check if the session has a ticket.
	pub fn has_ticket(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_has_ticket(self.ptr()) == 1
	}
	}

	/// Get the ticket, if any.
	pub fn get_ticket(&self) -> Option<&[u8]> {
	call_slice_getter!(bssl_sys::SSL_SESSION_get0_ticket, self.ptr())
	}

	/// Check if the session has a peer SHA256.
	pub fn has_peer_sha256(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_has_peer_sha256(self.ptr()) == 1
	}
	}

	/// Get the peer SHA256, if any.
	pub fn get_peer_sha256(&self) -> Option<&[u8]> {
	call_slice_getter!(bssl_sys::SSL_SESSION_get0_peer_sha256, self.ptr())
	}

	/// Check if the session is resumable across names.
	pub fn is_resumable_across_names(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_is_resumable_across_names(self.ptr()) == 1
	}
	}

	/// Check if the session is early data capable.
	pub fn early_data_capable(&self) -> bool {
	unsafe {
	// Safety: self.ptr() is valid.
	bssl_sys::SSL_SESSION_early_data_capable(self.ptr()) == 1
	}
	}
	}

	#[cfg(test)]
	mod tests {
	use core::pin::Pin;

	use futures::future::try_join;

	use super::*;

	use crate::tests::create_mock_pipe;
	use crate::{
	context::TlsContextBuilder,
	credentials::{
	PskHash,
	TlsCredential, //
	}, //
	};

	const TEST_KEY: &[u8; 32] = b"0123456789abcdef0123456789abcdef";
	const TEST_IDENTITY: &[u8] = b"test-identity";
	const TEST_CONTEXT: &[u8] = b"test-context";

	#[test]
	fn test_session_ops() {
	let ctx = TlsContextBuilder::new_tls().build();
	let dummy_bytes = vec![0u8; 32];
	let res = TlsSession::from_bytes(&dummy_bytes, &ctx);
	assert!(res.is_err());
	}

	#[test]
	fn test_psk_resumption() {
	let cred_client = TlsCredential::new_pre_shared_key(
	TEST_KEY,
	TEST_IDENTITY,
	PskHash::Sha256,
	TEST_CONTEXT,
	)
	.unwrap();
	let cred_server = TlsCredential::new_pre_shared_key(
	TEST_KEY,
	TEST_IDENTITY,
	PskHash::Sha256,
	TEST_CONTEXT,
	)
	.unwrap();

	let mut ctx_client = TlsContextBuilder::new_tls();
	ctx_client.with_credential(cred_client).unwrap();
	let ctx_client = ctx_client.build();

	let mut ctx_server = TlsContextBuilder::new_tls();
	ctx_server.with_credential(cred_server).unwrap();
	let ctx_server = ctx_server.build();

	let mut conn_client = ctx_client.new_client_connection(None).unwrap().build();
	let mut conn_server = ctx_server.new_server_connection(None).unwrap().build();

	let (sock_client, sock_server, mut executor) = create_mock_pipe();

	conn_client.set_io(sock_client).unwrap();
	conn_server.set_io(sock_server).unwrap();

	executor
	.run(try_join(
	conn_client.in_handshake().unwrap().async_handshake(),
	conn_server.in_handshake().unwrap().async_handshake(),
	))
	.unwrap();

	let est_client = conn_client.established().unwrap();
	let session = est_client.get_session().unwrap();

	let session_bytes = session.to_bytes().unwrap();
	assert!(!session_bytes.is_empty());

	let session_recovered = TlsSession::from_bytes(&session_bytes, &ctx_client).unwrap();

	let session_bytes_2 = session_recovered.to_bytes().unwrap();
	assert_eq!(session_bytes, session_bytes_2);
	}

	#[test]
	fn test_ticket_based_resumption() {
	let cred_client = TlsCredential::new_pre_shared_key(
	TEST_KEY,
	TEST_IDENTITY,
	PskHash::Sha256,
	TEST_CONTEXT,
	)
	.unwrap();
	let cred_server = TlsCredential::new_pre_shared_key(
	TEST_KEY,
	TEST_IDENTITY,
	PskHash::Sha256,
	TEST_CONTEXT,
	)
	.unwrap();

	let mut ctx_client = TlsContextBuilder::new_tls();
	ctx_client.with_credential(cred_client).unwrap();
	let ctx_client = ctx_client.build();

	let mut ctx_server = TlsContextBuilder::new_tls();
	ctx_server.with_credential(cred_server).unwrap();
	let ctx_server = ctx_server.build();
	let mut conn_client = ctx_client.new_client_connection(None).unwrap().build();
	let mut conn_server = ctx_server.new_server_connection(None).unwrap().build();

	let (sock_client, sock_server, mut executor) = create_mock_pipe();

	conn_client.set_io(sock_client).unwrap();
	conn_server.set_io(sock_server).unwrap();

	executor
	.run(try_join(
	conn_client.in_handshake().unwrap().async_handshake(),
	conn_server.in_handshake().unwrap().async_handshake(),
	))
	.unwrap();

	let est_client = conn_client.established().unwrap();
	let session = est_client.get_session().unwrap();
	let peer = session.get_peer_sha256().unwrap();

	// === SESSION RESUMPTION ===
	// Use the session for a new connection
	let (sock_client_2, sock_server_2, mut executor) = create_mock_pipe();

	let mut builder_client_2 = ctx_client.new_client_connection(None).unwrap();
	builder_client_2.with_session(&session);
	let mut conn_client_2 = builder_client_2.build();

	let builder_server_2 = ctx_server.new_server_connection(None).unwrap();
	let mut conn_server_2 = builder_server_2.build();

	conn_client_2.set_io(sock_client_2).unwrap();
	conn_server_2.set_io(sock_server_2).unwrap();

	executor
	.run(try_join(
	Pin::new(&mut conn_client_2).async_write(b"hello"),
	Pin::new(&mut conn_server_2).async_write(b"world"),
	))
	.unwrap();
	// The peer identity should be the same as before
	assert_eq!(
	conn_client_2
	.established()
	.unwrap()
	.get_session()
	.unwrap()
	.get_peer_sha256()
	.unwrap(),
	peer
	);
	}
	}