/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* * This file contains prototypes for the public SSL functions. * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef __sslt_h_ #define __sslt_h_ #include "certt.h" #include "keyhi.h" #include "prtypes.h" #include "secitem.h" typedef enum { ssl_hs_hello_request = 0, ssl_hs_client_hello = 1, ssl_hs_server_hello = 2, ssl_hs_hello_verify_request = 3, ssl_hs_new_session_ticket = 4, ssl_hs_end_of_early_data = 5, ssl_hs_hello_retry_request = 6, ssl_hs_encrypted_extensions = 8, ssl_hs_certificate = 11, ssl_hs_server_key_exchange = 12, ssl_hs_certificate_request = 13, ssl_hs_server_hello_done = 14, ssl_hs_certificate_verify = 15, ssl_hs_client_key_exchange = 16, ssl_hs_finished = 20, ssl_hs_certificate_status = 22, ssl_hs_key_update = 24, ssl_hs_compressed_certificate = 25, ssl_hs_next_proto = 67, ssl_hs_message_hash = 254, /* Not a real message. */ ssl_hs_ech_outer_client_hello = 257, /* Not a real message. */ } SSLHandshakeType; typedef enum { ssl_ct_change_cipher_spec = 20, ssl_ct_alert = 21, ssl_ct_handshake = 22, ssl_ct_application_data = 23, ssl_ct_ack = 26 } SSLContentType; typedef enum { ssl_secret_read = 1, ssl_secret_write = 2, } SSLSecretDirection; typedef struct SSL3StatisticsStr { /* statistics from ssl3_SendClientHello (sch) */ long sch_sid_cache_hits; long sch_sid_cache_misses; long sch_sid_cache_not_ok; /* statistics from ssl3_HandleServerHello (hsh) */ long hsh_sid_cache_hits; long hsh_sid_cache_misses; long hsh_sid_cache_not_ok; /* statistics from ssl3_HandleClientHello (hch) */ long hch_sid_cache_hits; long hch_sid_cache_misses; long hch_sid_cache_not_ok; /* statistics related to stateless resume */ long sch_sid_stateless_resumes; long hsh_sid_stateless_resumes; long hch_sid_stateless_resumes; long hch_sid_ticket_parse_failures; } SSL3Statistics; /* Key Exchange algorithm values */ typedef enum { ssl_kea_null = 0, ssl_kea_rsa = 1, ssl_kea_dh = 2, ssl_kea_fortezza = 3, /* deprecated, now unused */ ssl_kea_ecdh = 4, ssl_kea_ecdh_psk = 5, ssl_kea_dh_psk = 6, ssl_kea_tls13_any = 7, ssl_kea_ecdh_hybrid = 8, ssl_kea_ecdh_hybrid_psk = 9, ssl_kea_size /* number of ssl_kea_ algorithms */ } SSLKEAType; /* The following defines are for backwards compatibility. ** They will be removed in a forthcoming release to reduce namespace pollution. ** programs that use the kt_ symbols should convert to the ssl_kt_ symbols ** soon. */ #define kt_null ssl_kea_null #define kt_rsa ssl_kea_rsa #define kt_dh ssl_kea_dh #define kt_fortezza ssl_kea_fortezza /* deprecated, now unused */ #define kt_ecdh ssl_kea_ecdh #define kt_kea_size ssl_kea_size /* Values of this enum match the SignatureAlgorithm enum from * https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1 */ typedef enum { ssl_sign_null = 0, /* "anonymous" in TLS */ ssl_sign_rsa = 1, ssl_sign_dsa = 2, ssl_sign_ecdsa = 3 } SSLSignType; /* Values of this enum match the HashAlgorithm enum from * https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1 */ typedef enum { /* ssl_hash_none is used internally to mean the pre-1.2 combination of MD5 * and SHA1. The other values are only used in TLS 1.2. */ ssl_hash_none = 0, ssl_hash_md5 = 1, ssl_hash_sha1 = 2, ssl_hash_sha224 = 3, ssl_hash_sha256 = 4, ssl_hash_sha384 = 5, ssl_hash_sha512 = 6 } SSLHashType; /* Deprecated */ typedef struct SSLSignatureAndHashAlgStr { SSLHashType hashAlg; SSLSignType sigAlg; } SSLSignatureAndHashAlg; typedef enum { ssl_sig_none = 0, ssl_sig_rsa_pkcs1_sha1 = 0x0201, ssl_sig_rsa_pkcs1_sha256 = 0x0401, ssl_sig_rsa_pkcs1_sha384 = 0x0501, ssl_sig_rsa_pkcs1_sha512 = 0x0601, /* For ECDSA, the pairing of the hash with a specific curve is only enforced * in TLS 1.3; in TLS 1.2 any curve can be used with each of these. */ ssl_sig_ecdsa_secp256r1_sha256 = 0x0403, ssl_sig_ecdsa_secp384r1_sha384 = 0x0503, ssl_sig_ecdsa_secp521r1_sha512 = 0x0603, ssl_sig_rsa_pss_rsae_sha256 = 0x0804, ssl_sig_rsa_pss_rsae_sha384 = 0x0805, ssl_sig_rsa_pss_rsae_sha512 = 0x0806, ssl_sig_ed25519 = 0x0807, ssl_sig_ed448 = 0x0808, ssl_sig_rsa_pss_pss_sha256 = 0x0809, ssl_sig_rsa_pss_pss_sha384 = 0x080a, ssl_sig_rsa_pss_pss_sha512 = 0x080b, ssl_sig_dsa_sha1 = 0x0202, ssl_sig_dsa_sha256 = 0x0402, ssl_sig_dsa_sha384 = 0x0502, ssl_sig_dsa_sha512 = 0x0602, ssl_sig_ecdsa_sha1 = 0x0203, /* The following value (which can't be used in the protocol), represents * the RSA signature using SHA-1 and MD5 that is used in TLS 1.0 and 1.1. * This is reported as a signature scheme when TLS 1.0 or 1.1 is used. * This should not be passed to SSL_SignatureSchemePrefSet(); this * signature scheme is always used and cannot be disabled. */ ssl_sig_rsa_pkcs1_sha1md5 = 0x10101, } SSLSignatureScheme; /* Deprecated names maintained only for source compatibility. */ #define ssl_sig_rsa_pss_sha256 ssl_sig_rsa_pss_rsae_sha256 #define ssl_sig_rsa_pss_sha384 ssl_sig_rsa_pss_rsae_sha384 #define ssl_sig_rsa_pss_sha512 ssl_sig_rsa_pss_rsae_sha512 /* ** SSLAuthType describes the type of key that is used to authenticate a ** connection. That is, the type of key in the end-entity certificate. */ typedef enum { ssl_auth_null = 0, ssl_auth_rsa_decrypt = 1, /* RSA key exchange. */ ssl_auth_dsa = 2, ssl_auth_kea = 3, /* unused */ ssl_auth_ecdsa = 4, ssl_auth_ecdh_rsa = 5, /* ECDH cert with an RSA signature. */ ssl_auth_ecdh_ecdsa = 6, /* ECDH cert with an ECDSA signature. */ ssl_auth_rsa_sign = 7, /* RSA signing with an rsaEncryption key. */ ssl_auth_rsa_pss = 8, /* RSA signing with a PSS key. */ ssl_auth_psk = 9, ssl_auth_tls13_any = 10, ssl_auth_size /* number of authentication types */ } SSLAuthType; typedef enum { ssl_psk_none = 0, ssl_psk_resume = 1, ssl_psk_external = 2, } SSLPskType; /* This is defined for backward compatibility reasons */ #define ssl_auth_rsa ssl_auth_rsa_decrypt typedef enum { ssl_calg_null = 0, ssl_calg_rc4 = 1, ssl_calg_rc2 = 2, ssl_calg_des = 3, ssl_calg_3des = 4, ssl_calg_idea = 5, ssl_calg_fortezza = 6, /* deprecated, now unused */ ssl_calg_aes = 7, ssl_calg_camellia = 8, ssl_calg_seed = 9, ssl_calg_aes_gcm = 10, ssl_calg_chacha20 = 11 } SSLCipherAlgorithm; typedef enum { ssl_mac_null = 0, ssl_mac_md5 = 1, ssl_mac_sha = 2, ssl_hmac_md5 = 3, /* TLS HMAC version of mac_md5 */ ssl_hmac_sha = 4, /* TLS HMAC version of mac_sha */ ssl_hmac_sha256 = 5, ssl_mac_aead = 6, ssl_hmac_sha384 = 7 } SSLMACAlgorithm; typedef enum { ssl_compression_null = 0, ssl_compression_deflate = 1 /* RFC 3749 */ } SSLCompressionMethod; typedef enum { ssl_grp_ec_sect163k1 = 1, ssl_grp_ec_sect163r1 = 2, ssl_grp_ec_sect163r2 = 3, ssl_grp_ec_sect193r1 = 4, ssl_grp_ec_sect193r2 = 5, ssl_grp_ec_sect233k1 = 6, ssl_grp_ec_sect233r1 = 7, ssl_grp_ec_sect239k1 = 8, ssl_grp_ec_sect283k1 = 9, ssl_grp_ec_sect283r1 = 10, ssl_grp_ec_sect409k1 = 11, ssl_grp_ec_sect409r1 = 12, ssl_grp_ec_sect571k1 = 13, ssl_grp_ec_sect571r1 = 14, ssl_grp_ec_secp160k1 = 15, ssl_grp_ec_secp160r1 = 16, ssl_grp_ec_secp160r2 = 17, ssl_grp_ec_secp192k1 = 18, ssl_grp_ec_secp192r1 = 19, ssl_grp_ec_secp224k1 = 20, ssl_grp_ec_secp224r1 = 21, ssl_grp_ec_secp256k1 = 22, ssl_grp_ec_secp256r1 = 23, ssl_grp_ec_secp384r1 = 24, ssl_grp_ec_secp521r1 = 25, ssl_grp_ec_curve25519 = 29, /* RFC4492 */ ssl_grp_ffdhe_2048 = 256, /* RFC7919 */ ssl_grp_ffdhe_3072 = 257, ssl_grp_ffdhe_4096 = 258, ssl_grp_ffdhe_6144 = 259, ssl_grp_ffdhe_8192 = 260, ssl_grp_kem_xyber768d00 = 25497, /* draft-tls-westerbaan-xyber768d00-02 */ ssl_grp_none = 65537, /* special value */ ssl_grp_ffdhe_custom = 65538 /* special value */ } SSLNamedGroup; typedef struct SSLExtraServerCertDataStr { /* When this struct is passed to SSL_ConfigServerCert, and authType is set * to a value other than ssl_auth_null, this limits the use of the key to * the type defined; otherwise, the certificate is configured for all * compatible types. */ SSLAuthType authType; /* The remainder of the certificate chain. */ const CERTCertificateList* certChain; /* A set of one or more stapled OCSP responses for the certificate. This is * used to generate the OCSP stapling answer provided by the server. */ const SECItemArray* stapledOCSPResponses; /* A serialized sign_certificate_timestamp extension, used to answer * requests from clients for this data. */ const SECItem* signedCertTimestamps; /* Delegated credentials. * * A serialized delegated credential (DC) to use for authentication to peers * who indicate support for this extension (ietf-drafts-tls-subcerts). DCs * are used opportunistically if (1) the client indicates support, (2) TLS * 1.3 or higher is negotiated, and (3) the selected certificate is * configured with a DC. * * Note that it's the caller's responsibility to ensure that the DC is * well-formed. */ const SECItem* delegCred; /* The secret key corresponding to the |delegCred|. * * Note that it's the caller's responsibility to ensure that this matches * the DC public key. */ const SECKEYPrivateKey* delegCredPrivKey; } SSLExtraServerCertData; typedef struct SSLChannelInfoStr { /* On return, SSL_GetChannelInfo sets |length| to the smaller of * the |len| argument and the length of the struct used by NSS. * Callers must ensure the application uses a version of NSS that * isn't older than the version used at compile time. */ PRUint32 length; PRUint16 protocolVersion; PRUint16 cipherSuite; /* The strength of the key used to authenticate the peer. Before * interpreting this value, check authType, signatureScheme, and * peerDelegCred, to determine the type of the key and how it was used. * * Typically, this is the length of the key from the peer's end-entity * certificate. If delegated credentials are used (i.e., peerDelegCred is * PR_TRUE), then this is the strength of the delegated credential key. */ PRUint32 authKeyBits; /* key exchange algorithm info */ PRUint32 keaKeyBits; /* session info */ PRUint32 creationTime; /* seconds since Jan 1, 1970 */ PRUint32 lastAccessTime; /* seconds since Jan 1, 1970 */ PRUint32 expirationTime; /* seconds since Jan 1, 1970 */ PRUint32 sessionIDLength; /* up to 32 */ PRUint8 sessionID[32]; /* The following fields are added in NSS 3.12.5. */ /* compression method info */ const char* compressionMethodName; SSLCompressionMethod compressionMethod; /* The following fields are added in NSS 3.21. * This field only has meaning in TLS < 1.3 and will be set to * PR_FALSE in TLS 1.3. */ PRBool extendedMasterSecretUsed; /* The following fields were added in NSS 3.25. * This field only has meaning in TLS >= 1.3, and indicates on the * client side that the server accepted early (0-RTT) data. */ PRBool earlyDataAccepted; /* The following fields were added in NSS 3.28. */ /* These fields have the same meaning as in SSLCipherSuiteInfo. */ SSLKEAType keaType; SSLNamedGroup keaGroup; SSLCipherAlgorithm symCipher; SSLMACAlgorithm macAlgorithm; SSLAuthType authType; SSLSignatureScheme signatureScheme; /* The following fields were added in NSS 3.34. */ /* When the session was resumed this holds the key exchange group of the * original handshake. */ SSLNamedGroup originalKeaGroup; /* This field is PR_TRUE when the session is resumed and PR_FALSE * otherwise. */ PRBool resumed; /* Indicates whether the peer used a delegated credential (DC) for * authentication. */ PRBool peerDelegCred; /* The following fields were added in NSS 3.54. */ /* Indicates what type of PSK, if any, was used in a handshake. */ SSLPskType pskType; /* The following fields were added in NSS 3.60 */ /* This field is PR_TRUE when the connection is established * with TLS 1.3 Encrypted Client Hello. */ PRBool echAccepted; /* The following field was added in NSS 3.66 */ /* This filed is PR_TRUE if the FIPS indicator is true for the * current connection */ PRBool isFIPS; /* When adding new fields to this structure, please document the * NSS version in which they were added. */ } SSLChannelInfo; /* Preliminary channel info */ #define ssl_preinfo_version (1U << 0) #define ssl_preinfo_cipher_suite (1U << 1) #define ssl_preinfo_0rtt_cipher_suite (1U << 2) /* ssl_preinfo_peer_auth covers peerDelegCred, authKeyBits, * and scheme. Not included in ssl_preinfo_all as it is client-only. */ #define ssl_preinfo_peer_auth (1U << 3) #define ssl_preinfo_ech (1U << 4) /* ssl_preinfo_all doesn't contain ssl_preinfo_0rtt_cipher_suite because that * field is only set if 0-RTT is sent (client) or accepted (server). */ #define ssl_preinfo_all (ssl_preinfo_version | ssl_preinfo_cipher_suite | ssl_preinfo_ech) typedef struct SSLPreliminaryChannelInfoStr { /* On return, SSL_GetPreliminaryChannelInfo sets |length| to the smaller of * the |len| argument and the length of the struct used by NSS. * Callers must ensure the application uses a version of NSS that * isn't older than the version used at compile time. */ PRUint32 length; /* A bitfield over SSLPreliminaryValueSet that describes which * preliminary values are set (see ssl_preinfo_*). */ PRUint32 valuesSet; /* Protocol version: test (valuesSet & ssl_preinfo_version) */ PRUint16 protocolVersion; /* Cipher suite: test (valuesSet & ssl_preinfo_cipher_suite) */ PRUint16 cipherSuite; /* The following fields were added in NSS 3.29. */ /* |canSendEarlyData| is true when a 0-RTT is enabled. This can only be * true after sending the ClientHello and before the handshake completes. */ PRBool canSendEarlyData; /* The following fields were added in NSS 3.31. */ /* The number of early data octets that a client is permitted to send on * this connection. The value will be zero if the connection was not * resumed or early data is not permitted. For a client, this value only * has meaning if |canSendEarlyData| is true. For a server, this indicates * the value that was advertised in the session ticket that was used to * resume this session. */ PRUint32 maxEarlyDataSize; /* The following fields were added in NSS 3.43. */ /* This reports the cipher suite used for 0-RTT if it sent or accepted. For * a client, this is set earlier than |cipherSuite|, and will match that * value if 0-RTT is accepted by the server. The server only sets this * after accepting 0-RTT, so this will contain the same value. */ PRUint16 zeroRttCipherSuite; /* The following fields were added in NSS 3.48. */ /* These fields contain information about the key that will be used in * the CertificateVerify message. If Delegated Credentials are being used, * this is the DC-contained SPKI, else the EE-cert SPKI. These fields are * valid only after the Certificate message is handled. This can be determined * by checking the valuesSet field against |ssl_preinfo_peer_auth|. */ PRBool peerDelegCred; PRUint32 authKeyBits; SSLSignatureScheme signatureScheme; /* The following fields were added in NSS 3.60. */ PRBool echAccepted; /* If the application configured ECH but |!echAccepted|, authCertificate * should use the following hostname extracted from the ECHConfig. */ const char* echPublicName; /* The following field was added in NSS 3.88. */ PRBool ticketSupportsEarlyData; /* When adding new fields to this structure, please document the * NSS version in which they were added. */ } SSLPreliminaryChannelInfo; typedef struct SSLCipherSuiteInfoStr { /* On return, SSL_GetCipherSuitelInfo sets |length| to the smaller of * the |len| argument and the length of the struct used by NSS. * Callers must ensure the application uses a version of NSS that * isn't older than the version used at compile time. */ PRUint16 length; PRUint16 cipherSuite; /* Cipher Suite Name */ const char* cipherSuiteName; /* server authentication info */ const char* authAlgorithmName; SSLAuthType authAlgorithm; /* deprecated, use |authType| */ /* key exchange algorithm info */ const char* keaTypeName; SSLKEAType keaType; /* symmetric encryption info */ const char* symCipherName; SSLCipherAlgorithm symCipher; PRUint16 symKeyBits; PRUint16 symKeySpace; PRUint16 effectiveKeyBits; /* MAC info */ /* AEAD ciphers don't have a MAC. For an AEAD cipher, macAlgorithmName * is "AEAD", macAlgorithm is ssl_mac_aead, and macBits is the length in * bits of the authentication tag. */ const char* macAlgorithmName; SSLMACAlgorithm macAlgorithm; PRUint16 macBits; PRUintn isFIPS : 1; PRUintn isExportable : 1; /* deprecated, don't use */ PRUintn nonStandard : 1; PRUintn reservedBits : 29; /* The following fields were added in NSS 3.24. */ /* This reports the correct authentication type for the cipher suite, use * this instead of |authAlgorithm|. */ SSLAuthType authType; /* The following fields were added in NSS 3.43. */ /* This reports the hash function used in the TLS KDF, or HKDF for TLS 1.3. * For suites defined for versions of TLS earlier than TLS 1.2, this reports * ssl_hash_none. */ SSLHashType kdfHash; /* When adding new fields to this structure, please document the * NSS version in which they were added. */ } SSLCipherSuiteInfo; typedef enum { ssl_variant_stream = 0, ssl_variant_datagram = 1 } SSLProtocolVariant; typedef struct SSLVersionRangeStr { PRUint16 min; PRUint16 max; } SSLVersionRange; typedef enum { SSL_sni_host_name = 0, SSL_sni_type_total } SSLSniNameType; /* Supported extensions. */ /* Update SSL_MAX_EXTENSIONS whenever a new extension type is added. */ typedef enum { ssl_server_name_xtn = 0, ssl_cert_status_xtn = 5, ssl_supported_groups_xtn = 10, ssl_ec_point_formats_xtn = 11, ssl_signature_algorithms_xtn = 13, ssl_use_srtp_xtn = 14, ssl_app_layer_protocol_xtn = 16, /* signed_certificate_timestamp extension, RFC 6962 */ ssl_signed_cert_timestamp_xtn = 18, ssl_padding_xtn = 21, ssl_extended_master_secret_xtn = 23, ssl_certificate_compression_xtn = 27, ssl_record_size_limit_xtn = 28, ssl_delegated_credentials_xtn = 34, ssl_session_ticket_xtn = 35, /* 40 was used in draft versions of TLS 1.3; it is now reserved. */ ssl_tls13_pre_shared_key_xtn = 41, ssl_tls13_early_data_xtn = 42, ssl_tls13_supported_versions_xtn = 43, ssl_tls13_cookie_xtn = 44, ssl_tls13_psk_key_exchange_modes_xtn = 45, ssl_tls13_ticket_early_data_info_xtn = 46, /* Deprecated. */ ssl_tls13_certificate_authorities_xtn = 47, ssl_tls13_post_handshake_auth_xtn = 49, ssl_signature_algorithms_cert_xtn = 50, ssl_tls13_key_share_xtn = 51, /* TLS 1.3 GREASE extension dummy type for builders. */ ssl_tls13_grease_xtn = 0x0a0a, ssl_next_proto_nego_xtn = 13172, /* Deprecated. */ ssl_renegotiation_info_xtn = 0xff01, ssl_tls13_short_header_xtn = 0xff03, /* Deprecated. */ ssl_tls13_outer_extensions_xtn = 0xfd00, ssl_tls13_encrypted_client_hello_xtn = 0xfe0d, ssl_tls13_encrypted_sni_xtn = 0xffce, /* Deprecated. */ } SSLExtensionType; /* This is the old name for the supported_groups extensions. */ #define ssl_elliptic_curves_xtn ssl_supported_groups_xtn /* SSL_MAX_EXTENSIONS includes the maximum number of extensions that are * supported for any single message type. That is, a ClientHello; ServerHello * and TLS 1.3 NewSessionTicket and HelloRetryRequest extensions have fewer. */ #define SSL_MAX_EXTENSIONS 22 /* Deprecated */ typedef enum { ssl_dhe_group_none = 0, ssl_ff_dhe_2048_group = 1, ssl_ff_dhe_3072_group = 2, ssl_ff_dhe_4096_group = 3, ssl_ff_dhe_6144_group = 4, ssl_ff_dhe_8192_group = 5, ssl_dhe_group_max } SSLDHEGroupType; /* RFC 8879: TLS Certificate Compression - 3. Negotiating Certificate Compression ** enum { ** zlib(1), ** brotli(2), ** zstd(3), ** (65535) ** } CertificateCompressionAlgorithm; */ typedef PRUint16 SSLCertificateCompressionAlgorithmID; typedef struct SSLCertificateCompressionAlgorithmStr { SSLCertificateCompressionAlgorithmID id; const char* name; SECStatus (*encode)(const SECItem* input, SECItem* output); SECStatus (*decode)(const SECItem* input, SECItem* output, size_t expectedLenDecodedCertificate); } SSLCertificateCompressionAlgorithm; #endif /* __sslt_h_ */