diff options
Diffstat (limited to '')
| -rw-r--r-- | security/nss/lib/ssl/sslt.h | 588 |
1 files changed, 588 insertions, 0 deletions
diff --git a/security/nss/lib/ssl/sslt.h b/security/nss/lib/ssl/sslt.h new file mode 100644 index 0000000000..133ae6a296 --- /dev/null +++ b/security/nss/lib/ssl/sslt.h @@ -0,0 +1,588 @@ +/* -*- 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; + +#endif /* __sslt_h_ */ |