| // 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 Configurations |
| |
| use alloc::string::String; |
| use core::ffi::c_int; |
| |
| use bssl_macros::bssl_enum; |
| |
| bssl_enum! { |
| /// Protocol version for TLS or DTLS |
| #[derive(Clone, Copy, PartialEq, Eq)] |
| pub enum ProtocolVersion: u16 { |
| /// TLS version 1.2 |
| Tls12 = bssl_sys::TLS1_2_VERSION as u16, |
| /// TLS version 1.3 |
| Tls13 = bssl_sys::TLS1_3_VERSION as u16, |
| /// DTLS version 1.2 |
| Dtls12 = bssl_sys::DTLS1_2_VERSION as u16, |
| /// DTLS version 1.3 |
| Dtls13 = bssl_sys::DTLS1_3_VERSION as u16, |
| } |
| } |
| |
| impl TryFrom<c_int> for ProtocolVersion { |
| type Error = c_int; |
| |
| fn try_from(version: c_int) -> Result<Self, Self::Error> { |
| let Ok(val) = u16::try_from(version) else { |
| return Err(version); |
| }; |
| if let Ok(version) = ProtocolVersion::try_from(val) { |
| Ok(version) |
| } else { |
| Err(version) |
| } |
| } |
| } |
| |
| bitflags::bitflags! { |
| #[derive(Debug, Copy, Clone)] |
| pub(crate) struct ConnectionMode: u32 { |
| /// Deny session creation. |
| const MODE_NO_SESSION_CREATION = bssl_sys::SSL_MODE_NO_SESSION_CREATION as u32; |
| /// Allow moving write buffer. |
| /// This is indispensable for async I/O because the future could be freely cancelled. |
| const ACCEPT_MOVING_WRITE_BUFFER = bssl_sys::SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER as u32; |
| } |
| } |
| |
| bssl_enum! { |
| /// Key exchange groups for TLS or DTLS |
| #[derive(Clone, Copy, PartialEq, Eq)] |
| pub enum KeyExchangeGroups: u16 { |
| /// Key exchange using `ECDH-P256` |
| Secp256r1 = bssl_sys::SSL_GROUP_SECP256R1 as u16, |
| /// Key exchange using `ECDH-P384` |
| Secp384r1 = bssl_sys::SSL_GROUP_SECP384R1 as u16, |
| /// Key exchange using `ECDH-P521` |
| Secp521r1 = bssl_sys::SSL_GROUP_SECP521R1 as u16, |
| /// Key exchange using `X25519` |
| X25519 = bssl_sys::SSL_GROUP_X25519 as u16, |
| /// Key exchange using post-quantum hybrid scheme `X25519MLKEM768` |
| X25519Mlkem768 = bssl_sys::SSL_GROUP_X25519_MLKEM768 as u16, |
| /// Key exchange using `MLKEM-1024` |
| Mlkem1024 = bssl_sys::SSL_GROUP_MLKEM1024 as u16, |
| } |
| } |
| |
| bitflags::bitflags! { |
| /// Flags to control how key exchange group could be chosen |
| #[repr(transparent)] |
| #[derive(Debug, Copy, Clone)] |
| pub struct KeyExchangeGroupFlag: u32 { |
| /// `EQUAL_PREFERENCE_WITH_NEXT` indicates that the corresponding group has equal preference |
| /// with the next member of the list of groups being configured. |
| const EQUAL_PREFERENCE_WITH_NEXT = 0x01; |
| } |
| } |
| |
| /// Configuration errors |
| #[derive(Debug)] |
| pub enum ConfigurationError { |
| /// Some parameters are specified twice in the list. |
| DuplicatedParameters, |
| /// Some string is not acceptable. |
| InvalidString, |
| /// Session ID context data is too large. |
| SessionIdContextTooLarge, |
| /// Preshared Key is too long. |
| PskTooLong, |
| /// Value is out of range. |
| ValueOutOfRange, |
| /// Mismatching private and public key pair. |
| MismatchingKeyPair, |
| /// IP address is invalid. |
| /// It should either be 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. |
| InvalidIp, |
| /// Invalid parameters. |
| InvalidParameters, |
| } |
| |
| impl core::fmt::Display for ConfigurationError { |
| fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { |
| match self { |
| ConfigurationError::DuplicatedParameters => f.write_str("duplicated parameters"), |
| ConfigurationError::InvalidString => f.write_str("invalid string"), |
| ConfigurationError::SessionIdContextTooLarge => { |
| f.write_str("session ID context data is too large") |
| } |
| ConfigurationError::PskTooLong => f.write_str("preshared key is too long"), |
| ConfigurationError::MismatchingKeyPair => { |
| f.write_str("mismatching private and public key pair") |
| } |
| ConfigurationError::ValueOutOfRange => f.write_str("value is out of range"), |
| ConfigurationError::InvalidIp => f.write_str("invalid IP address"), |
| ConfigurationError::InvalidParameters => f.write_str("invalid parameters"), |
| } |
| } |
| } |
| |
| /// Cipher information |
| #[derive(Clone)] |
| #[non_exhaustive] |
| pub struct CipherInfo { |
| /// Protocol ID as assigned by [IANA](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4) |
| pub id: u32, |
| /// IETF Name of the cipher |
| pub ietf_name: String, |
| /// Indicates whether this cipher is an AEAD cipher |
| pub is_aead: bool, |
| /// Indicates whether this cipher is a block cipher |
| pub is_block_cipher: bool, |
| /// Cipher strength in bits |
| pub strength: u16, |
| } |
| |
| /// Supported cipher suites as registered with [IANA]. |
| /// |
| /// The following cipher suite values are assigned by IANA and correspond to |
| /// both TLS 1.3 and TLS 1.2 suites. |
| /// TLS 1.3 suites are mentioned again in [RFC 8446]. |
| /// TLS 1.2 suites are defined in the relevant RFCs for each algorithm family. |
| /// |
| /// [IANA]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4 |
| /// [RFC 8446]: https://www.rfc-editor.org/rfc/rfc8446 |
| /// [RFC 5489]: https://www.rfc-editor.org/rfc/rfc5489 |
| /// [RFC 8422]: https://www.rfc-editor.org/rfc/rfc8422 |
| /// [RFC 7905]: https://www.rfc-editor.org/rfc/rfc7905 |
| /// [RFC 5288]: https://www.rfc-editor.org/rfc/rfc5288 |
| /// [RFC 5246]: https://www.rfc-editor.org/rfc/rfc5246 |
| /// [RFC 4279]: https://www.rfc-editor.org/rfc/rfc4279 |
| #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)] |
| pub struct CipherSuite(pub u16); |
| |
| #[allow(non_upper_case_globals)] |
| impl CipherSuite { |
| /// TLS 1.3 cipher suite `TLS_AES_128_GCM_SHA256`. |
| pub const Aes128GcmSha256: Self = Self(bssl_sys::SSL_CIPHER_AES_128_GCM_SHA256 as u16); |
| /// TLS 1.3 cipher suite `TLS_AES_256_GCM_SHA384`. |
| pub const Aes256GcmSha384: Self = Self(bssl_sys::SSL_CIPHER_AES_256_GCM_SHA384 as u16); |
| /// TLS 1.3 cipher suite `TLS_CHACHA20_POLY1305_SHA256`. |
| pub const Chacha20Poly1305Sha256: Self = |
| Self(bssl_sys::SSL_CIPHER_CHACHA20_POLY1305_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` from RFC 5288. |
| pub const EcdheEcdsaWithAes128GcmSha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` from RFC 5288. |
| pub const EcdheEcdsaWithAes256GcmSha384: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` from RFC 5288. |
| pub const EcdheRsaWithAes128GcmSha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_AES_128_GCM_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` from RFC 5288. |
| pub const EcdheRsaWithAes256GcmSha384: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_AES_256_GCM_SHA384 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` from RFC 7905. |
| pub const EcdheRsaWithChacha20Poly1305Sha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` from RFC 7905. |
| pub const EcdheEcdsaWithChacha20Poly1305Sha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 as u16); |
| /// TLS cipher suite `TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256` from RFC 7905. |
| pub const EcdhePskWithChacha20Poly1305Sha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA` from RFC 8422. |
| pub const EcdheEcdsaWithAes128CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA` from RFC 8422. |
| pub const EcdheEcdsaWithAes256CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_AES_256_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA` from RFC 8422. |
| pub const EcdheRsaWithAes128CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA` from RFC 8422. |
| pub const EcdheRsaWithAes256CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_AES_256_CBC_SHA as u16); |
| /// TLS cipher suite `TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA` from RFC 5489. |
| pub const EcdhePskWithAes128CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_PSK_WITH_AES_128_CBC_SHA as u16); |
| /// TLS cipher suite `TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA` from RFC 5489. |
| pub const EcdhePskWithAes256CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_PSK_WITH_AES_256_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` from RFC 5289. |
| pub const EcdheEcdsaWithAes128CbcSha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` from RFC 5289. |
| pub const EcdheRsaWithAes128CbcSha256: Self = |
| Self(bssl_sys::SSL_CIPHER_ECDHE_RSA_WITH_AES_128_CBC_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_RSA_WITH_AES_128_GCM_SHA256` from RFC 5288. |
| pub const RsaWithAes128GcmSha256: Self = |
| Self(bssl_sys::SSL_CIPHER_RSA_WITH_AES_128_GCM_SHA256 as u16); |
| /// TLS 1.2 cipher suite `TLS_RSA_WITH_AES_256_GCM_SHA384` from RFC 5288. |
| pub const RsaWithAes256GcmSha384: Self = |
| Self(bssl_sys::SSL_CIPHER_RSA_WITH_AES_256_GCM_SHA384 as u16); |
| /// TLS 1.2 cipher suite `TLS_RSA_WITH_AES_128_CBC_SHA` from RFC 5246. |
| pub const RsaWithAes128CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_RSA_WITH_AES_128_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_RSA_WITH_AES_256_CBC_SHA` from RFC 5246. |
| pub const RsaWithAes256CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_RSA_WITH_AES_256_CBC_SHA as u16); |
| /// TLS cipher suite `TLS_PSK_WITH_AES_128_CBC_SHA` from RFC 4279. |
| pub const PskWithAes128CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_PSK_WITH_AES_128_CBC_SHA as u16); |
| /// TLS cipher suite `TLS_PSK_WITH_AES_256_CBC_SHA` from RFC 4279. |
| pub const PskWithAes256CbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_PSK_WITH_AES_256_CBC_SHA as u16); |
| /// TLS 1.2 cipher suite `TLS_RSA_WITH_3DES_EDE_CBC_SHA` from RFC 5246. |
| pub const RsaWith3desEdeCbcSha: Self = |
| Self(bssl_sys::SSL_CIPHER_RSA_WITH_3DES_EDE_CBC_SHA as u16); |
| } |
| |
| bssl_enum! { |
| /// Compliance Policy. |
| #[derive(Clone, Copy, PartialEq, Eq)] |
| pub enum CompliancePolicy: u8 { |
| /// FIPS 202205 |
| /// |
| /// This policy configures a TLS connection to use: |
| /// - TLS 1.2 or 1.3; |
| /// - For TLS 1.2, only `ECDHE_[RSA|ECDSA]_WITH_AES_*_GCM_SHA*`; |
| /// - For TLS 1.3, only `AES-GCM`; |
| /// - P-256 or P-384 for key agreement; |
| /// - For server signatures, only PKCS#1/PSS with SHA256/384/512, |
| /// or ECDSA with P-256 or P-384 and SHA256/SHA384. |
| Fips202205 = bssl_sys::ssl_compliance_policy_t_ssl_compliance_policy_fips_202205 as u8, |
| /// WPA3-192 202304 |
| /// |
| /// This policy configures a TLS connection to use: |
| /// - TLS 1.2 or 1.3. |
| /// - For TLS 1.2, only `TLS_ECDHE_[ECDSA|RSA]_WITH_AES_256_GCM_SHA384`. |
| /// - For TLS 1.3, only `AES-256-GCM`. |
| /// - P-384 for key agreement. |
| /// - For handshake signatures, only ECDSA with P-384 and SHA-384, or RSA |
| /// with SHA-384 or SHA-512. |
| /// |
| /// No limitations on the certificate chain nor leaf public key are imposed, |
| /// other than by the supported signature algorithms. |
| /// But WPA3's "192-bit" mode requires at least P-384 or 3072-bit RSA along the chain. |
| /// The caller must enforce this themselves on the verified chain using functions such as |
| /// [`crate::credentials::TlsCredentialBuilder::with_certificate_chain`]. |
| /// |
| /// Note that this setting is less secure than the default. |
| /// The implementation risks of using a more obscure primitive like P-384 dominate other |
| /// considerations. |
| Wpa3_192_202304 = bssl_sys::ssl_compliance_policy_t_ssl_compliance_policy_wpa3_192_202304 as u8, |
| /// CNSA 202407 |
| /// |
| /// This policy configures a TLS connection to use: |
| /// - For TLS 1.3, AES-256-GCM over AES-128-GCM over ChaCha20-Poly1305. |
| /// |
| /// I.e. it ensures that AES-GCM will be used whenever the client supports it. |
| /// The cipher suite configuration mini-language can be used to similarly |
| /// configure prior TLS versions if they are enabled. |
| Cnsa202407 = bssl_sys::ssl_compliance_policy_t_ssl_compliance_policy_cnsa_202407 as u8, |
| } |
| } |
