diff options
Diffstat (limited to 'nss/lib/ssl/ssl.h')
-rw-r--r-- | nss/lib/ssl/ssl.h | 676 |
1 files changed, 426 insertions, 250 deletions
diff --git a/nss/lib/ssl/ssl.h b/nss/lib/ssl/ssl.h index 2a52769..b4af0e1 100644 --- a/nss/lib/ssl/ssl.h +++ b/nss/lib/ssl/ssl.h @@ -15,7 +15,7 @@ #include "cert.h" #include "keyt.h" -#include "sslt.h" /* public ssl data types */ +#include "sslt.h" /* public ssl data types */ #if defined(_WIN32) && !defined(IN_LIBSSL) && !defined(NSS_USE_STATIC_LIBS) #define SSL_IMPORT extern __declspec(dllimport) @@ -25,7 +25,7 @@ SEC_BEGIN_PROTOS -/* constant table enumerating all implemented SSL 2 and 3 cipher suites. */ +/* constant table enumerating all implemented cipher suites. */ SSL_IMPORT const PRUint16 SSL_ImplementedCiphers[]; /* the same as the above, but is a function */ @@ -38,7 +38,7 @@ SSL_IMPORT const PRUint16 SSL_NumImplementedCiphers; SSL_IMPORT PRUint16 SSL_GetNumImplementedCiphers(void); /* Macro to tell which ciphers in table are SSL2 vs SSL3/TLS. */ -#define SSL_IS_SSL2_CIPHER(which) (((which) & 0xfff0) == 0xff00) +#define SSL_IS_SSL2_CIPHER(which) (((which)&0xfff0) == 0xff00) /* ** Imports fd into SSL, returning a new socket. Copies SSL configuration @@ -55,72 +55,69 @@ SSL_IMPORT PRFileDesc *DTLS_ImportFD(PRFileDesc *model, PRFileDesc *fd); /* ** Enable/disable an ssl mode ** -** SSL_SECURITY: -** enable/disable use of SSL security protocol before connect +** SSL_SECURITY: +** enable/disable use of SSL security protocol before connect ** -** SSL_SOCKS: -** enable/disable use of socks before connect -** (No longer supported). +** SSL_SOCKS: +** enable/disable use of socks before connect +** (No longer supported). ** -** SSL_REQUEST_CERTIFICATE: -** require a certificate during secure connect +** SSL_REQUEST_CERTIFICATE: +** require a certificate during secure connect */ /* options */ -#define SSL_SECURITY 1 /* (on by default) */ -#define SSL_SOCKS 2 /* (off by default) */ -#define SSL_REQUEST_CERTIFICATE 3 /* (off by default) */ -#define SSL_HANDSHAKE_AS_CLIENT 5 /* force accept to hs as client */ - /* (off by default) */ -#define SSL_HANDSHAKE_AS_SERVER 6 /* force connect to hs as server */ - /* (off by default) */ +#define SSL_SECURITY 1 /* (on by default) */ +#define SSL_SOCKS 2 /* (off by default) */ +#define SSL_REQUEST_CERTIFICATE 3 /* (off by default) */ +#define SSL_HANDSHAKE_AS_CLIENT 5 /* force accept to hs as client */ + /* (off by default) */ +#define SSL_HANDSHAKE_AS_SERVER 6 /* force connect to hs as server */ + /* (off by default) */ /* OBSOLETE: SSL v2 is obsolete and may be removed soon. */ -#define SSL_ENABLE_SSL2 7 /* enable ssl v2 (off by default) */ +#define SSL_ENABLE_SSL2 7 /* enable ssl v2 (off by default) */ /* OBSOLETE: See "SSL Version Range API" below for the replacement and a ** description of the non-obvious semantics of using SSL_ENABLE_SSL3. */ -#define SSL_ENABLE_SSL3 8 /* enable ssl v3 (on by default) */ +#define SSL_ENABLE_SSL3 8 /* enable ssl v3 (on by default) */ -#define SSL_NO_CACHE 9 /* don't use the session cache */ - /* (off by default) */ -#define SSL_REQUIRE_CERTIFICATE 10 /* (SSL_REQUIRE_FIRST_HANDSHAKE */ - /* by default) */ -#define SSL_ENABLE_FDX 11 /* permit simultaneous read/write */ - /* (off by default) */ +#define SSL_NO_CACHE 9 /* don't use the session cache */ + /* (off by default) */ +#define SSL_REQUIRE_CERTIFICATE 10 /* (SSL_REQUIRE_FIRST_HANDSHAKE */ + /* by default) */ +#define SSL_ENABLE_FDX 11 /* permit simultaneous read/write */ + /* (off by default) */ /* OBSOLETE: SSL v2 compatible hellos are not accepted by some TLS servers ** and cannot negotiate extensions. SSL v2 is obsolete. This option may be ** removed soon. */ -#define SSL_V2_COMPATIBLE_HELLO 12 /* send v3 client hello in v2 fmt */ - /* (off by default) */ +#define SSL_V2_COMPATIBLE_HELLO 12 /* send v3 client hello in v2 fmt */ + /* (off by default) */ /* OBSOLETE: See "SSL Version Range API" below for the replacement and a ** description of the non-obvious semantics of using SSL_ENABLE_TLS. */ -#define SSL_ENABLE_TLS 13 /* enable TLS (on by default) */ - -#define SSL_ROLLBACK_DETECTION 14 /* for compatibility, default: on */ -#define SSL_NO_STEP_DOWN 15 /* Disable export cipher suites */ - /* if step-down keys are needed. */ - /* default: off, generate */ - /* step-down keys if needed. */ -#define SSL_BYPASS_PKCS11 16 /* use PKCS#11 for pub key only */ -#define SSL_NO_LOCKS 17 /* Don't use locks for protection */ -#define SSL_ENABLE_SESSION_TICKETS 18 /* Enable TLS SessionTicket */ - /* extension (off by default) */ -#define SSL_ENABLE_DEFLATE 19 /* Enable TLS compression with */ - /* DEFLATE (off by default) */ -#define SSL_ENABLE_RENEGOTIATION 20 /* Values below (default: never) */ -#define SSL_REQUIRE_SAFE_NEGOTIATION 21 /* Peer must send Signaling */ - /* Cipher Suite Value (SCSV) or */ - /* Renegotiation Info (RI) */ - /* extension in ALL handshakes. */ - /* default: off */ -#define SSL_ENABLE_FALSE_START 22 /* Enable SSL false start (off by */ - /* default, applies only to */ - /* clients). False start is a */ +#define SSL_ENABLE_TLS 13 /* enable TLS (on by default) */ + +#define SSL_ROLLBACK_DETECTION 14 /* for compatibility, default: on */ +#define SSL_NO_STEP_DOWN 15 /* (unsupported, deprecated, off) */ +#define SSL_BYPASS_PKCS11 16 /* (unsupported, deprecated, off) */ +#define SSL_NO_LOCKS 17 /* Don't use locks for protection */ +#define SSL_ENABLE_SESSION_TICKETS 18 /* Enable TLS SessionTicket */ + /* extension (off by default) */ +#define SSL_ENABLE_DEFLATE 19 /* Enable TLS compression with */ + /* DEFLATE (off by default) */ +#define SSL_ENABLE_RENEGOTIATION 20 /* Values below (default: never) */ +#define SSL_REQUIRE_SAFE_NEGOTIATION 21 /* Peer must send Signaling */ + /* Cipher Suite Value (SCSV) or */ + /* Renegotiation Info (RI) */ + /* extension in ALL handshakes. */ + /* default: off */ +#define SSL_ENABLE_FALSE_START 22 /* Enable SSL false start (off by */ + /* default, applies only to */ + /* clients). False start is a */ /* mode where an SSL client will start sending application data before * verifying the server's Finished message. This means that we could end up * sending data to an imposter. However, the data will be encrypted and @@ -160,7 +157,7 @@ SSL_IMPORT PRFileDesc *DTLS_ImportFD(PRFileDesc *model, PRFileDesc *fd); * accept fragmented alerts). */ #define SSL_CBC_RANDOM_IV 23 -#define SSL_ENABLE_OCSP_STAPLING 24 /* Request OCSP stapling (client) */ +#define SSL_ENABLE_OCSP_STAPLING 24 /* Request OCSP stapling (client) */ /* SSL_ENABLE_NPN controls whether the NPN extension is enabled for the initial * handshake when application layer protocol negotiation is used. @@ -189,8 +186,8 @@ SSL_IMPORT PRFileDesc *DTLS_ImportFD(PRFileDesc *model, PRFileDesc *fd); */ #define SSL_REUSE_SERVER_ECDHE_KEY 27 -#define SSL_ENABLE_FALLBACK_SCSV 28 /* Send fallback SCSV in - * handshakes. */ +#define SSL_ENABLE_FALLBACK_SCSV 28 /* Send fallback SCSV in \ + * handshakes. */ /* SSL_ENABLE_SERVER_DHE controls whether DHE is enabled for the server socket. */ @@ -203,8 +200,46 @@ SSL_IMPORT PRFileDesc *DTLS_ImportFD(PRFileDesc *model, PRFileDesc *fd); */ #define SSL_ENABLE_EXTENDED_MASTER_SECRET 30 +/* Request Signed Certificate Timestamps via TLS extension (client) */ +#define SSL_ENABLE_SIGNED_CERT_TIMESTAMPS 31 -#ifdef SSL_DEPRECATED_FUNCTION +/* Ordinarily, when negotiating a TLS_DHE_* cipher suite the server picks the + * group. draft-ietf-tls-negotiated-ff-dhe changes this to use supported_groups + * (formerly supported_curves) to signal which pre-defined groups are OK. + * + * This option causes an NSS client to use this extension and demand that those + * groups be used. A client will signal any enabled DHE groups in the + * supported_groups extension and reject groups that don't match what it has + * enabled. A server will only negotiate TLS_DHE_* cipher suites if the + * client includes the extension. + * + * See SSL_NamedGroupConfig() for how to control which groups are enabled. + * + * This option cannot be enabled if NSS is not compiled with ECC support. + */ +#define SSL_REQUIRE_DH_NAMED_GROUPS 32 + +/* Allow 0-RTT data (for TLS 1.3). + * + * When this option is set, the server's session tickets will contain + * a flag indicating that it accepts 0-RTT. When resuming such a + * session, PR_Write() on the client will be allowed immediately after + * starting the handshake and PR_Read() on the server will be allowed + * on the server to read that data. Calls to + * SSL_GetPreliminaryChannelInfo() and SSL_GetNextProto() + * can be made used during this period to learn about the channel + * parameters [TODO(ekr@rtfm.com): This hasn't landed yet]. + * + * The transition between the 0-RTT and 1-RTT modes is marked by the + * handshake callback. + * + * WARNING: 0-RTT data has different anti-replay and PFS properties than + * the rest of the TLS data. See [draft-ietf-tls-tls13; Section 6.2.3] + * for more details. + */ +#define SSL_ENABLE_0RTT_DATA 33 + +#ifdef SSL_DEPRECATED_FUNCTION /* Old deprecated function names */ SSL_IMPORT SECStatus SSL_Enable(PRFileDesc *fd, int option, PRBool on); SSL_IMPORT SECStatus SSL_EnableDefault(int option, PRBool on); @@ -227,13 +262,13 @@ SSL_IMPORT SECStatus SSL_CertDBHandleSet(PRFileDesc *fd, CERTCertDBHandle *dbHan * * The callback must return SECFailure or SECSuccess (not SECWouldBlock). */ -typedef SECStatus (PR_CALLBACK *SSLNextProtoCallback)( +typedef SECStatus(PR_CALLBACK *SSLNextProtoCallback)( void *arg, PRFileDesc *fd, - const unsigned char* protos, + const unsigned char *protos, unsigned int protosLen, - unsigned char* protoOut, - unsigned int* protoOutLen, + unsigned char *protoOut, + unsigned int *protoOutLen, unsigned int protoMaxOut); /* SSL_SetNextProtoCallback sets a callback function to handle Next Protocol @@ -261,14 +296,15 @@ SSL_IMPORT SECStatus SSL_SetNextProtoCallback(PRFileDesc *fd, * The supported protocols are specified in |data| in wire-format (8-bit * length-prefixed). For example: "\010http/1.1\006spdy/2". */ SSL_IMPORT SECStatus SSL_SetNextProtoNego(PRFileDesc *fd, - const unsigned char *data, - unsigned int length); - -typedef enum SSLNextProtoState { - SSL_NEXT_PROTO_NO_SUPPORT = 0, /* No peer support */ - SSL_NEXT_PROTO_NEGOTIATED = 1, /* Mutual agreement */ - SSL_NEXT_PROTO_NO_OVERLAP = 2, /* No protocol overlap found */ - SSL_NEXT_PROTO_SELECTED = 3 /* Server selected proto (ALPN) */ + const unsigned char *data, + unsigned int length); + +typedef enum SSLNextProtoState { + SSL_NEXT_PROTO_NO_SUPPORT = 0, /* No peer support */ + SSL_NEXT_PROTO_NEGOTIATED = 1, /* Mutual agreement */ + SSL_NEXT_PROTO_NO_OVERLAP = 2, /* No protocol overlap found */ + SSL_NEXT_PROTO_SELECTED = 3, /* Server selected proto (ALPN) */ + SSL_NEXT_PROTO_EARLY_VALUE = 4 /* We are in 0-RTT using this value. */ } SSLNextProtoState; /* SSL_GetNextProto can be used in the HandshakeCallback or any time after @@ -279,19 +315,19 @@ typedef enum SSLNextProtoState { * returned. Otherwise, the negotiated protocol, if any, is written into buf, * and SECSuccess is returned. */ SSL_IMPORT SECStatus SSL_GetNextProto(PRFileDesc *fd, - SSLNextProtoState *state, - unsigned char *buf, - unsigned int *bufLen, - unsigned int bufLenMax); + SSLNextProtoState *state, + unsigned char *buf, + unsigned int *bufLen, + unsigned int bufLenMax); /* ** Control ciphers that SSL uses. If on is non-zero then the named cipher -** is enabled, otherwise it is disabled. +** is enabled, otherwise it is disabled. ** The "cipher" values are defined in sslproto.h (the SSL_EN_* values). ** EnableCipher records user preferences. ** SetPolicy sets the policy according to the policy module. */ -#ifdef SSL_DEPRECATED_FUNCTION +#ifdef SSL_DEPRECATED_FUNCTION /* Old deprecated function names */ SSL_IMPORT SECStatus SSL_EnableCipher(long which, PRBool enabled); SSL_IMPORT SECStatus SSL_SetPolicy(long which, int policy); @@ -306,46 +342,87 @@ SSL_IMPORT SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy); SSL_IMPORT SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy); /* -** Control for TLS signature algorithms for TLS 1.2 only. +** Control for TLS signature schemes for TLS 1.2 and 1.3. ** -** This governs what signature algorithms are sent by a client in the -** signature_algorithms extension. A client will not accept a signature from a -** server unless it uses an enabled algorithm. +** This governs what signature schemes (or algorithms) are sent by a client in +** the signature_algorithms extension. A client will not accept a signature +** from a server unless it uses an enabled algorithm. ** ** This also governs what the server sends in the supported_signature_algorithms -** field of a CertificateRequest. It also changes what the server uses to sign -** ServerKeyExchange: a server uses the first entry from this list that is -** compatible with the client's advertised signature_algorithms extension and -** the selected server certificate. +** field of a CertificateRequest. +** +** This changes what the server uses to sign ServerKeyExchange and +** CertificateVerify messages. An endpoint uses the first entry from this list +** that is compatible with both its certificate and its peer's supported +** values. +** +** NSS uses the strict signature schemes from TLS 1.3 in TLS 1.2. That means +** that if a peer indicates support for SHA-384 and ECDSA, NSS will not +** generate a signature if it has a P-256 key, even though that is permitted in +** TLS 1.2. ** -** Omitting SHA-256 from this list might be foolish. Support is mandatory in -** TLS 1.2 and there might be interoperability issues. For a server, NSS only -** supports SHA-256 for verifying a TLS 1.2 CertificateVerify. This list needs -** to include SHA-256 if client authentication is requested or required, or -** creating a CertificateRequest will fail. +** Omitting SHA-256 schemes from this list might be foolish. Support is +** mandatory in TLS 1.2 and 1.3 and there might be interoperability issues. */ +SSL_IMPORT SECStatus SSL_SignatureSchemePrefSet( + PRFileDesc *fd, const SSLSignatureScheme *schemes, unsigned int count); + +/* Deprecated, use SSL_SignatureSchemePrefSet() instead. */ SSL_IMPORT SECStatus SSL_SignaturePrefSet( PRFileDesc *fd, const SSLSignatureAndHashAlg *algorithms, unsigned int count); /* -** Get the currently configured signature algorithms. +** Get the currently configured signature schemes. ** -** The algorithms are written to |algorithms| but not if there are more than -** |maxCount| values configured. The number of algorithms that are in use are +** The schemes are written to |schemes| but not if there are more than +** |maxCount| values configured. The number of schemes that are in use are ** written to |count|. This fails if |maxCount| is insufficiently large. */ +SSL_IMPORT SECStatus SSL_SignatureSchemePrefGet( + PRFileDesc *fd, SSLSignatureScheme *algorithms, unsigned int *count, + unsigned int maxCount); + +/* Deprecated, use SSL_SignatureSchemePrefGet() instead. */ SSL_IMPORT SECStatus SSL_SignaturePrefGet( PRFileDesc *fd, SSLSignatureAndHashAlg *algorithms, unsigned int *count, unsigned int maxCount); /* ** Returns the maximum number of signature algorithms that are supported and -** can be set or retrieved using SSL_SignaturePrefSet or SSL_SignaturePrefGet. +** can be set or retrieved using SSL_SignatureSchemePrefSet or +** SSL_SignatureSchemePrefGet. */ SSL_IMPORT unsigned int SSL_SignatureMaxCount(); -/* SSL_DHEGroupPrefSet is used to configure the set of allowed/enabled DHE group +/* +** Define custom priorities for EC and FF groups used in DH key exchange and EC +** groups for ECDSA. This only changes the order of enabled lists (and thus +** their priorities) and enables all groups in |groups| while disabling all other +** groups. +*/ +SSL_IMPORT SECStatus SSL_NamedGroupConfig(PRFileDesc *fd, + const SSLNamedGroup *groups, + unsigned int num_groups); + +/* +** Configure the socket to configure additional key shares. Normally when a TLS +** 1.3 ClientHello is sent, just one key share is included using the first +** preference group (as set by SSL_NamedGroupConfig). If the server decides to +** pick a different group for key exchange, it is forced to send a +** HelloRetryRequest, which adds an entire round trip of latency. +** +** This function can be used to configure libssl to generate additional key +** shares when sending a TLS 1.3 ClientHello. If |count| is set to a non-zero +** value, then additional key shares are generated. Shares are added in the +** preference order set in SSL_NamedGroupConfig. |count| can be set to any +** value; NSS limits the number of shares to the number of supported groups. +*/ +SSL_IMPORT SECStatus SSL_SendAdditionalKeyShares(PRFileDesc *fd, + unsigned int count); + +/* Deprecated: use SSL_NamedGroupConfig() instead. +** SSL_DHEGroupPrefSet is used to configure the set of allowed/enabled DHE group ** parameters that can be used by NSS for the given server socket. ** The first item in the array is used as the default group, if no other ** selection criteria can be used by NSS. @@ -354,7 +431,7 @@ SSL_IMPORT unsigned int SSL_SignatureMaxCount(); ** For example, a TLS extension sent by the client might indicate a preference. */ SSL_IMPORT SECStatus SSL_DHEGroupPrefSet(PRFileDesc *fd, - SSLDHEGroupType *groups, + const SSLDHEGroupType *groups, PRUint16 num_groups); /* Enable the use of a DHE group that's smaller than the library default, @@ -375,13 +452,11 @@ SSL_IMPORT SECStatus SSL_DHEGroupPrefSet(PRFileDesc *fd, ** on sockets. The function needs to be called again for every socket that ** should use the weak group. ** -** It is allowed to use this API in combination with the SSL_DHEGroupPrefSet API. -** If both APIs have been called, the weakest group will be used, -** unless it is certain that the client supports larger group parameters. -** The weak group will be used as the default group, overriding the preference -** for the first group potentially set with a call to SSL_DHEGroupPrefSet -** (The first group set using SSL_DHEGroupPrefSet will still be enabled, but -** it's no longer the default group.) +** It is allowed to use this API in combination with the SSL_NamedGroupConfig API. +** If both APIs have been called, the weakest group will be used, unless it is +** certain that the client supports larger group parameters. The weak group will +** be used as the default group for TLS <= 1.2, overriding the preference for +** the first group potentially set with a call to SSL_NamedGroupConfig. */ SSL_IMPORT SECStatus SSL_EnableWeakDHEPrimeGroup(PRFileDesc *fd, PRBool enabled); @@ -449,34 +524,46 @@ SSL_IMPORT SECStatus SSL_VersionRangeSetDefault( /* Returns, in |*vrange|, the range of enabled SSL3/TLS versions for |fd|. */ SSL_IMPORT SECStatus SSL_VersionRangeGet(PRFileDesc *fd, - SSLVersionRange *vrange); + SSLVersionRange *vrange); /* Sets the range of enabled SSL3/TLS versions for |fd| to |*vrange|. */ SSL_IMPORT SECStatus SSL_VersionRangeSet(PRFileDesc *fd, - const SSLVersionRange *vrange); - + const SSLVersionRange *vrange); + +/* Sets the version to check the server random against for the + * fallback check defined in [draft-ietf-tls-tls13-11 Section 6.3.1.1]. + * This function is provided to allow for detection of forced downgrade + * attacks against client-side reconnect-and-fallback outside of TLS + * by setting |version| to be that of the original connection, rather + * than that of the new connection. + * + * The default, which can also be enabled by setting |version| to + * zero, is just to check against the max version in the + * version range (see SSL_VersionRangeSet). */ +SSL_IMPORT SECStatus SSL_SetDowngradeCheckVersion(PRFileDesc *fd, + PRUint16 version); /* Values for "policy" argument to SSL_CipherPolicySet */ /* Values returned by SSL_CipherPolicyGet. */ -#define SSL_NOT_ALLOWED 0 /* or invalid or unimplemented */ -#define SSL_ALLOWED 1 -#define SSL_RESTRICTED 2 /* only with "Step-Up" certs. */ +#define SSL_NOT_ALLOWED 0 /* or invalid or unimplemented */ +#define SSL_ALLOWED 1 +#define SSL_RESTRICTED 2 /* only with "Step-Up" certs. */ /* Values for "on" with SSL_REQUIRE_CERTIFICATE. */ -#define SSL_REQUIRE_NEVER ((PRBool)0) -#define SSL_REQUIRE_ALWAYS ((PRBool)1) +#define SSL_REQUIRE_NEVER ((PRBool)0) +#define SSL_REQUIRE_ALWAYS ((PRBool)1) #define SSL_REQUIRE_FIRST_HANDSHAKE ((PRBool)2) -#define SSL_REQUIRE_NO_ERROR ((PRBool)3) +#define SSL_REQUIRE_NO_ERROR ((PRBool)3) /* Values for "on" with SSL_ENABLE_RENEGOTIATION */ /* Never renegotiate at all. */ -#define SSL_RENEGOTIATE_NEVER ((PRBool)0) +#define SSL_RENEGOTIATE_NEVER ((PRBool)0) /* Renegotiate without restriction, whether or not the peer's client hello */ /* bears the renegotiation info extension. Vulnerable, as in the past. */ #define SSL_RENEGOTIATE_UNRESTRICTED ((PRBool)1) /* Only renegotiate if the peer's hello bears the TLS renegotiation_info */ /* extension. This is safe renegotiation. */ -#define SSL_RENEGOTIATE_REQUIRES_XTN ((PRBool)2) +#define SSL_RENEGOTIATE_REQUIRES_XTN ((PRBool)2) /* Disallow unsafe renegotiation in server sockets only, but allow clients */ /* to continue to renegotiate with vulnerable servers. */ /* This value should only be used during the transition period when few */ @@ -514,22 +601,22 @@ SSL_IMPORT SECStatus SSL_ForceHandshakeWithTimeout(PRFileDesc *fd, ** by the caller, and need to be freed with PORT_Free. */ SSL_IMPORT SECStatus SSL_SecurityStatus(PRFileDesc *fd, int *on, char **cipher, - int *keySize, int *secretKeySize, - char **issuer, char **subject); + int *keySize, int *secretKeySize, + char **issuer, char **subject); /* Values for "on" */ -#define SSL_SECURITY_STATUS_NOOPT -1 -#define SSL_SECURITY_STATUS_OFF 0 -#define SSL_SECURITY_STATUS_ON_HIGH 1 -#define SSL_SECURITY_STATUS_ON_LOW 2 -#define SSL_SECURITY_STATUS_FORTEZZA 3 /* NO LONGER SUPPORTED */ +#define SSL_SECURITY_STATUS_NOOPT -1 +#define SSL_SECURITY_STATUS_OFF 0 +#define SSL_SECURITY_STATUS_ON_HIGH 1 +#define SSL_SECURITY_STATUS_ON_LOW 2 +#define SSL_SECURITY_STATUS_FORTEZZA 3 /* NO LONGER SUPPORTED */ /* ** Return the certificate for our SSL peer. If the client calls this ** it will always return the server's certificate. If the server calls ** this, it may return NULL if client authentication is not enabled or ** if the client had no certificate when asked. -** "fd" the socket "file" descriptor +** "fd" the socket "file" descriptor */ SSL_IMPORT CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd); @@ -538,7 +625,7 @@ SSL_IMPORT CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd); ** did not present certificates, return NULL with the ** SSL_ERROR_NO_CERTIFICATE error. On failure, return NULL with an error ** code other than SSL_ERROR_NO_CERTIFICATE. -** "fd" the socket "file" descriptor +** "fd" the socket "file" descriptor */ SSL_IMPORT CERTCertList *SSL_PeerCertificateChain(PRFileDesc *fd); @@ -558,17 +645,50 @@ SSL_IMPORT CERTCertList *SSL_PeerCertificateChain(PRFileDesc *fd); * authenticate certificate hook, SSL_AuthCertificate, does not implement * any OCSP stapling funtionality, but this may change in future versions. */ -SSL_IMPORT const SECItemArray * SSL_PeerStapledOCSPResponses(PRFileDesc *fd); +SSL_IMPORT const SECItemArray *SSL_PeerStapledOCSPResponses(PRFileDesc *fd); + +/* SSL_PeerSignedCertTimestamps returns the signed_certificate_timestamp + * extension data provided by the TLS server. The return value is a pointer + * to an internal SECItem that contains the returned response (as a serialized + * SignedCertificateTimestampList, see RFC 6962). The returned pointer is only + * valid until the callback function that calls SSL_PeerSignedCertTimestamps + * (e.g. the authenticate certificate hook, or the handshake callback) returns. + * + * If no Signed Certificate Timestamps were given by the server then the result + * will be empty. If there was an error, then the result will be NULL. + * + * You must set the SSL_ENABLE_SIGNED_CERT_TIMESTAMPS option to indicate support + * for Signed Certificate Timestamps to a server. + * + * libssl does not do any parsing or validation of the response itself. + */ +SSL_IMPORT const SECItem *SSL_PeerSignedCertTimestamps(PRFileDesc *fd); /* SSL_SetStapledOCSPResponses stores an array of one or multiple OCSP responses * in the fd's data, which may be sent as part of a server side cert_status * handshake message. Parameter |responses| is for the server certificate of * the key exchange type |kea|. * The function will duplicate the responses array. + * + * Deprecated: see SSL_ConfigSecureServer for details. */ SSL_IMPORT SECStatus SSL_SetStapledOCSPResponses(PRFileDesc *fd, const SECItemArray *responses, - SSLKEAType kea); + SSLKEAType kea); + +/* + * SSL_SetSignedCertTimestamps stores serialized signed_certificate_timestamp + * extension data in the fd. The signed_certificate_timestamp data is sent + * during the handshake (if requested by the client). Parameter |scts| + * is for the server certificate of the key exchange type |kea|. + * The function will duplicate the provided data item. To clear previously + * set data for a given key exchange type |kea|, pass NULL to |scts|. + * + * Deprecated: see SSL_ConfigSecureServer for details. + */ +SSL_IMPORT SECStatus +SSL_SetSignedCertTimestamps(PRFileDesc *fd, const SECItem *scts, + SSLKEAType kea); /* ** Authenticate certificate hook. Called when a certificate comes in @@ -601,41 +721,40 @@ SSL_SetStapledOCSPResponses(PRFileDesc *fd, const SECItemArray *responses, ** Consequently, the current version of libssl does not ever send the ** bad_certificate_status_response alert. This may change in future releases. */ -typedef SECStatus (PR_CALLBACK *SSLAuthCertificate)(void *arg, PRFileDesc *fd, - PRBool checkSig, - PRBool isServer); +typedef SECStatus(PR_CALLBACK *SSLAuthCertificate)(void *arg, PRFileDesc *fd, + PRBool checkSig, + PRBool isServer); -SSL_IMPORT SECStatus SSL_AuthCertificateHook(PRFileDesc *fd, - SSLAuthCertificate f, - void *arg); +SSL_IMPORT SECStatus SSL_AuthCertificateHook(PRFileDesc *fd, + SSLAuthCertificate f, + void *arg); /* An implementation of the certificate authentication hook */ -SSL_IMPORT SECStatus SSL_AuthCertificate(void *arg, PRFileDesc *fd, - PRBool checkSig, PRBool isServer); +SSL_IMPORT SECStatus SSL_AuthCertificate(void *arg, PRFileDesc *fd, + PRBool checkSig, PRBool isServer); /* * Prototype for SSL callback to get client auth data from the application. - * arg - application passed argument - * caNames - pointer to distinguished names of CAs that the server likes - * pRetCert - pointer to pointer to cert, for return of cert - * pRetKey - pointer to key pointer, for return of key + * arg - application passed argument + * caNames - pointer to distinguished names of CAs that the server likes + * pRetCert - pointer to pointer to cert, for return of cert + * pRetKey - pointer to key pointer, for return of key */ -typedef SECStatus (PR_CALLBACK *SSLGetClientAuthData)(void *arg, - PRFileDesc *fd, - CERTDistNames *caNames, - CERTCertificate **pRetCert,/*return */ - SECKEYPrivateKey **pRetKey);/* return */ +typedef SECStatus(PR_CALLBACK *SSLGetClientAuthData)(void *arg, + PRFileDesc *fd, + CERTDistNames *caNames, + CERTCertificate **pRetCert, /*return */ + SECKEYPrivateKey **pRetKey); /* return */ /* * Set the client side callback for SSL to retrieve user's private key * and certificate. - * fd - the file descriptor for the connection in question - * f - the application's callback that delivers the key and cert - * a - application specific data + * fd - the file descriptor for the connection in question + * f - the application's callback that delivers the key and cert + * a - application specific data */ -SSL_IMPORT SECStatus SSL_GetClientAuthDataHook(PRFileDesc *fd, - SSLGetClientAuthData f, void *a); - +SSL_IMPORT SECStatus SSL_GetClientAuthDataHook(PRFileDesc *fd, + SSLGetClientAuthData f, void *a); /* ** SNI extension processing callback function. @@ -663,10 +782,10 @@ SSL_IMPORT SECStatus SSL_GetClientAuthDataHook(PRFileDesc *fd, ** send an "unrecognized_name" alert if SNI extension name list contains more ** then one name of a type. */ -typedef PRInt32 (PR_CALLBACK *SSLSNISocketConfig)(PRFileDesc *fd, - const SECItem *srvNameArr, - PRUint32 srvNameArrSize, - void *arg); +typedef PRInt32(PR_CALLBACK *SSLSNISocketConfig)(PRFileDesc *fd, + const SECItem *srvNameArr, + PRUint32 srvNameArrSize, + void *arg); /* ** SSLSNISocketConfig should return an index within 0 and srvNameArrSize-1 @@ -675,13 +794,13 @@ typedef PRInt32 (PR_CALLBACK *SSLSNISocketConfig)(PRFileDesc *fd, ** tells libSSL to use the default cert and key. The other tells libSSL ** to send the "unrecognized_name" alert. These values are: **/ -#define SSL_SNI_CURRENT_CONFIG_IS_USED -1 -#define SSL_SNI_SEND_ALERT -2 +#define SSL_SNI_CURRENT_CONFIG_IS_USED -1 +#define SSL_SNI_SEND_ALERT -2 /* ** Set application implemented SNISocketConfig callback. */ -SSL_IMPORT SECStatus SSL_SNISocketConfigHook(PRFileDesc *fd, +SSL_IMPORT SECStatus SSL_SNISocketConfigHook(PRFileDesc *fd, SSLSNISocketConfig f, void *arg); @@ -694,8 +813,8 @@ SSL_IMPORT PRFileDesc *SSL_ReconfigFD(PRFileDesc *model, PRFileDesc *fd); /* * Set the client side argument for SSL to retrieve PKCS #11 pin. - * fd - the file descriptor for the connection in question - * a - pkcs11 application specific data + * fd - the file descriptor for the connection in question + * a - pkcs11 application specific data */ SSL_IMPORT SECStatus SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a); @@ -714,22 +833,80 @@ SSL_IMPORT SECStatus SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a); ** about the asynchronous behavior that occurs when the bad cert hook returns ** SECWouldBlock. */ -typedef SECStatus (PR_CALLBACK *SSLBadCertHandler)(void *arg, PRFileDesc *fd); -SSL_IMPORT SECStatus SSL_BadCertHook(PRFileDesc *fd, SSLBadCertHandler f, - void *arg); +typedef SECStatus(PR_CALLBACK *SSLBadCertHandler)(void *arg, PRFileDesc *fd); +SSL_IMPORT SECStatus SSL_BadCertHook(PRFileDesc *fd, SSLBadCertHandler f, + void *arg); /* ** Configure SSL socket for running a secure server. Needs the ** certificate for the server and the servers private key. The arguments ** are copied. +** +** This method should be used in preference to SSL_ConfigSecureServer, +** SSL_ConfigSecureServerWithCertChain, SSL_SetStapledOCSPResponses, and +** SSL_SetSignedCertTimestamps. +** +** The authentication method is determined from the certificate and private key +** based on how libssl authenticates peers. Primarily, this uses the value of +** the SSLAuthType enum and is derived from the type of public key in the +** certificate. For example, different RSA certificates might be saved for +** signing (ssl_auth_rsa_sign) and key encipherment +** (ssl_auth_rsa_decrypt). Unique to RSA, the same certificate can be used for +** both usages. Additional information about the authentication method is also +** used: EC keys with different curves are separately stored. +** +** Only one certificate is stored for each authentication method. +** +** The optional |data| argument contains additional information about the +** certificate: +** +** - |authType| (with a value other than ssl_auth_null) limits the +** authentication method; this is primarily useful in limiting the use of an +** RSA certificate to one particular key usage (either signing or key +** encipherment) when its key usages indicate support for both. +** +** - |certChain| provides an explicit certificate chain, rather than relying on +** NSS functions for finding a certificate chain. +** +** - |stapledOCSPResponses| provides a response for OCSP stapling. +** +** - |signedCertTimestamps| provides a value for the +** signed_certificate_timestamp extension used in certificate transparency. +** +** The |data_len| argument provides the length of the data. This should be set +** to |sizeof(data)|. +** +** This function allows an application to provide certificates with narrow key +** usages attached to them. For instance, RSA keys can be provided that are +** limited to signing or decryption only. Multiple EC certificates with keys on +** different named curves can be provided. +** +** Unlike SSL_ConfigSecureServer(WithCertChain), this function does not accept +** NULL for the |cert| and |key| arguments. It will replace certificates that +** have the same type, but it cannot be used to remove certificates that have +** already been configured. +*/ +SSL_IMPORT SECStatus SSL_ConfigServerCert( + PRFileDesc *fd, CERTCertificate *cert, SECKEYPrivateKey *key, + const SSLExtraServerCertData *data, unsigned int data_len); + +/* +** Deprecated variant of SSL_ConfigServerCert. +** +** This uses values from the SSLKEAType to identify the type of |key| that the +** |cert| contains. This is incorrect, since key exchange and authentication +** are separated in some cipher suites (in particular, ECDHE_RSA_* suites). +** +** Providing a |kea| parameter of ssl_kea_ecdh (or kt_ecdh) is interpreted as +** providing both ECDH and ECDSA certificates. */ SSL_IMPORT SECStatus SSL_ConfigSecureServer( - PRFileDesc *fd, CERTCertificate *cert, - SECKEYPrivateKey *key, SSLKEAType kea); + PRFileDesc *fd, CERTCertificate *cert, + SECKEYPrivateKey *key, SSLKEAType kea); /* -** Allows SSL socket configuration with caller-supplied certificate chain. -** If certChainOpt is NULL, tries to find one. +** Deprecated variant of SSL_ConfigSecureServerCert. The |data| argument to +** SSL_ConfigSecureServerCert can be used to pass a certificate chain. */ SSL_IMPORT SECStatus SSL_ConfigSecureServerWithCertChain(PRFileDesc *fd, CERTCertificate *cert, @@ -739,63 +916,63 @@ SSL_ConfigSecureServerWithCertChain(PRFileDesc *fd, CERTCertificate *cert, /* ** Configure a secure server's session-id cache. Define the maximum number ** of entries in the cache, the longevity of the entires, and the directory -** where the cache files will be placed. These values can be zero, and +** where the cache files will be placed. These values can be zero, and ** if so, the implementation will choose defaults. -** This version of the function is for use in applications that have only one +** This version of the function is for use in applications that have only one ** process that uses the cache (even if that process has multiple threads). */ -SSL_IMPORT SECStatus SSL_ConfigServerSessionIDCache(int maxCacheEntries, - PRUint32 timeout, - PRUint32 ssl3_timeout, - const char * directory); +SSL_IMPORT SECStatus SSL_ConfigServerSessionIDCache(int maxCacheEntries, + PRUint32 timeout, + PRUint32 ssl3_timeout, + const char *directory); /* Configure a secure server's session-id cache. Depends on value of * enableMPCache, configures malti-proc or single proc cache. */ SSL_IMPORT SECStatus SSL_ConfigServerSessionIDCacheWithOpt( - PRUint32 timeout, - PRUint32 ssl3_timeout, - const char * directory, - int maxCacheEntries, - int maxCertCacheEntries, - int maxSrvNameCacheEntries, - PRBool enableMPCache); + PRUint32 timeout, + PRUint32 ssl3_timeout, + const char *directory, + int maxCacheEntries, + int maxCertCacheEntries, + int maxSrvNameCacheEntries, + PRBool enableMPCache); /* ** Like SSL_ConfigServerSessionIDCache, with one important difference. -** If the application will run multiple processes (as opposed to, or in +** If the application will run multiple processes (as opposed to, or in ** addition to multiple threads), then it must call this function, instead ** of calling SSL_ConfigServerSessionIDCache(). ** This has nothing to do with the number of processORs, only processEs. ** This function sets up a Server Session ID (SID) cache that is safe for ** access by multiple processes on the same system. */ -SSL_IMPORT SECStatus SSL_ConfigMPServerSIDCache(int maxCacheEntries, - PRUint32 timeout, - PRUint32 ssl3_timeout, - const char * directory); - -/* Get and set the configured maximum number of mutexes used for the -** server's store of SSL sessions. This value is used by the server -** session ID cache initialization functions shown above. Note that on -** some platforms, these mutexes are actually implemented with POSIX +SSL_IMPORT SECStatus SSL_ConfigMPServerSIDCache(int maxCacheEntries, + PRUint32 timeout, + PRUint32 ssl3_timeout, + const char *directory); + +/* Get and set the configured maximum number of mutexes used for the +** server's store of SSL sessions. This value is used by the server +** session ID cache initialization functions shown above. Note that on +** some platforms, these mutexes are actually implemented with POSIX ** semaphores, or with unnamed pipes. The default value varies by platform. -** An attempt to set a too-low maximum will return an error and the +** An attempt to set a too-low maximum will return an error and the ** configured value will not be changed. */ -SSL_IMPORT PRUint32 SSL_GetMaxServerCacheLocks(void); +SSL_IMPORT PRUint32 SSL_GetMaxServerCacheLocks(void); SSL_IMPORT SECStatus SSL_SetMaxServerCacheLocks(PRUint32 maxLocks); /* environment variable set by SSL_ConfigMPServerSIDCache, and queried by * SSL_InheritMPServerSIDCache when envString is NULL. */ -#define SSL_ENV_VAR_NAME "SSL_INHERITANCE" +#define SSL_ENV_VAR_NAME "SSL_INHERITANCE" -/* called in child to inherit SID Cache variables. +/* called in child to inherit SID Cache variables. * If envString is NULL, this function will use the value of the environment - * variable "SSL_INHERITANCE", otherwise the string value passed in will be + * variable "SSL_INHERITANCE", otherwise the string value passed in will be * used. */ -SSL_IMPORT SECStatus SSL_InheritMPServerSIDCache(const char * envString); +SSL_IMPORT SECStatus SSL_InheritMPServerSIDCache(const char *envString); /* ** Set the callback that gets called when a TLS handshake is complete. The @@ -807,10 +984,10 @@ SSL_IMPORT SECStatus SSL_InheritMPServerSIDCache(const char * envString); ** before the handshake callback is called. If we did not false start then the ** callback will get called before any application data is sent. */ -typedef void (PR_CALLBACK *SSLHandshakeCallback)(PRFileDesc *fd, - void *client_data); -SSL_IMPORT SECStatus SSL_HandshakeCallback(PRFileDesc *fd, - SSLHandshakeCallback cb, void *client_data); +typedef void(PR_CALLBACK *SSLHandshakeCallback)(PRFileDesc *fd, + void *client_data); +SSL_IMPORT SECStatus SSL_HandshakeCallback(PRFileDesc *fd, + SSLHandshakeCallback cb, void *client_data); /* Applications that wish to enable TLS false start must set this callback ** function. NSS will invoke the functon to determine if a particular @@ -823,7 +1000,7 @@ SSL_IMPORT SECStatus SSL_HandshakeCallback(PRFileDesc *fd, ** If no false start callback is registered then false start will never be ** done, even if the SSL_ENABLE_FALSE_START option is enabled. **/ -typedef SECStatus (PR_CALLBACK *SSLCanFalseStartCallback)( +typedef SECStatus(PR_CALLBACK *SSLCanFalseStartCallback)( PRFileDesc *fd, void *arg, PRBool *canFalseStart); SSL_IMPORT SECStatus SSL_SetCanFalseStartCallback( @@ -839,10 +1016,10 @@ SSL_IMPORT SECStatus SSL_RecommendedCanFalseStart(PRFileDesc *fd, /* ** For the server, request a new handshake. For the client, begin a new -** handshake. If flushCache is non-zero, the SSL3 cache entry will be +** handshake. If flushCache is non-zero, the SSL3 cache entry will be ** flushed first, ensuring that a full SSL handshake will be done. -** If flushCache is zero, and an SSL connection is established, it will -** do the much faster session restart handshake. This will change the +** If flushCache is zero, and an SSL connection is established, it will +** do the much faster session restart handshake. This will change the ** session keys without doing another private key operation. */ SSL_IMPORT SECStatus SSL_ReHandshake(PRFileDesc *fd, PRBool flushCache); @@ -854,12 +1031,11 @@ SSL_IMPORT SECStatus SSL_ReHandshakeWithTimeout(PRFileDesc *fd, PRBool flushCache, PRIntervalTime timeout); - -#ifdef SSL_DEPRECATED_FUNCTION +#ifdef SSL_DEPRECATED_FUNCTION /* deprecated! ** For the server, request a new handshake. For the client, begin a new -** handshake. Flushes SSL3 session cache entry first, ensuring that a -** full handshake will be done. +** handshake. Flushes SSL3 session cache entry first, ensuring that a +** full handshake will be done. ** This call is equivalent to SSL_ReHandshake(fd, PR_TRUE) */ SSL_IMPORT SECStatus SSL_RedoHandshake(PRFileDesc *fd); @@ -909,11 +1085,11 @@ SSL_IMPORT SECStatus SSL_ShutdownServerSessionIDCache(void); SSL_IMPORT SECStatus SSL_SetSockPeerID(PRFileDesc *fd, const char *peerID); /* -** Reveal the security information for the peer. +** Reveal the security information for the peer. */ -SSL_IMPORT CERTCertificate * SSL_RevealCert(PRFileDesc * socket); -SSL_IMPORT void * SSL_RevealPinArg(PRFileDesc * socket); -SSL_IMPORT char * SSL_RevealURL(PRFileDesc * socket); +SSL_IMPORT CERTCertificate *SSL_RevealCert(PRFileDesc *socket); +SSL_IMPORT void *SSL_RevealPinArg(PRFileDesc *socket); +SSL_IMPORT char *SSL_RevealURL(PRFileDesc *socket); /* This callback may be passed to the SSL library via a call to * SSL_GetClientAuthDataHook() for each SSL client socket. @@ -921,14 +1097,14 @@ SSL_IMPORT char * SSL_RevealURL(PRFileDesc * socket); * (if any) to use to respond to a request for client authentication. * If arg is non-NULL, it is a pointer to a NULL-terminated string containing * the nickname of the cert/key pair to use. - * If arg is NULL, this function will search the cert and key databases for + * If arg is NULL, this function will search the cert and key databases for * a suitable match and send it if one is found. */ SSL_IMPORT SECStatus -NSS_GetClientAuthData(void * arg, - PRFileDesc * socket, - struct CERTDistNamesStr * caNames, - struct CERTCertificateStr ** pRetCert, +NSS_GetClientAuthData(void *arg, + PRFileDesc *socket, + struct CERTDistNamesStr *caNames, + struct CERTCertificateStr **pRetCert, struct SECKEYPrivateKeyStr **pRetKey); /* @@ -942,8 +1118,8 @@ NSS_GetClientAuthData(void * arg, ** Otherwise returns SECFailure. */ SSL_IMPORT SECStatus SSL_SetSRTPCiphers(PRFileDesc *fd, - const PRUint16 *ciphers, - unsigned int numCiphers); + const PRUint16 *ciphers, + unsigned int numCiphers); /* ** Get the selected DTLS-SRTP cipher suite (if any). @@ -951,21 +1127,22 @@ SSL_IMPORT SECStatus SSL_SetSRTPCiphers(PRFileDesc *fd, ** Returns SECFailure if not negotiated. */ SSL_IMPORT SECStatus SSL_GetSRTPCipher(PRFileDesc *fd, - PRUint16 *cipher); + PRUint16 *cipher); /* * Look to see if any of the signers in the cert chain for "cert" are found - * in the list of caNames. + * in the list of caNames. * Returns SECSuccess if so, SECFailure if not. * Used by NSS_GetClientAuthData. May be used by other callback functions. */ -SSL_IMPORT SECStatus NSS_CmpCertChainWCANames(CERTCertificate *cert, - CERTDistNames *caNames); +SSL_IMPORT SECStatus NSS_CmpCertChainWCANames(CERTCertificate *cert, + CERTDistNames *caNames); -/* +/* Deprecated. This reports a misleading value for certificates that might + * be used for signing rather than key exchange. * Returns key exchange type of the keys in an SSL server certificate. */ -SSL_IMPORT SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert); +SSL_IMPORT SSLKEAType NSS_FindCertKEAType(CERTCertificate *cert); /* Set cipher policies to a predefined Domestic (U.S.A.) policy. * This essentially allows all supported ciphers. @@ -979,16 +1156,18 @@ SSL_IMPORT SECStatus NSS_SetDomesticPolicy(void); SSL_IMPORT SECStatus NSS_SetExportPolicy(void); /* Set cipher policies to a predefined Policy that is exportable from the USA - * according to present U.S. policies as we understand them, and that the + * according to present U.S. policies as we understand them, and that the * nation of France will permit to be imported into their country. * It is the same as NSS_SetDomesticPolicy now. */ SSL_IMPORT SECStatus NSS_SetFrancePolicy(void); -SSL_IMPORT SSL3Statistics * SSL_GetStatistics(void); +SSL_IMPORT SSL3Statistics *SSL_GetStatistics(void); /* Report more information than SSL_SecurityStatus. - * Caller supplies the info struct. This function fills it in. + * Caller supplies the info struct. This function fills it in. Caller should + * pass sizeof(SSLChannelInfo) as the |len| argument. + * * The information here will be zeroed prior to details being confirmed. The * details are confirmed either when a Finished message is received, or - for a * client - when the second flight of messages have been sent. This function @@ -998,6 +1177,9 @@ SSL_IMPORT SSL3Statistics * SSL_GetStatistics(void); SSL_IMPORT SECStatus SSL_GetChannelInfo(PRFileDesc *fd, SSLChannelInfo *info, PRUintn len); /* Get preliminary information about a channel. + * Caller supplies the info struct. This function fills it in. Caller should + * pass sizeof(SSLPreliminaryChannelInfo) as the |len| argument. + * * This function can be called prior to handshake details being confirmed (see * SSL_GetChannelInfo above for what that means). Thus, information provided by * this function is available to SSLAuthCertificate, SSLGetClientAuthData, @@ -1009,8 +1191,12 @@ SSL_IMPORT SECStatus SSL_GetPreliminaryChannelInfo(PRFileDesc *fd, SSLPreliminaryChannelInfo *info, PRUintn len); -SSL_IMPORT SECStatus SSL_GetCipherSuiteInfo(PRUint16 cipherSuite, - SSLCipherSuiteInfo *info, PRUintn len); +/* Get information about cipher suite with id of |cipherSuite|. + * Caller supplies the info struct. This function fills it in. Caller should + * pass sizeof(SSLCipherSuiteInfo) as the |len| argument. + */ +SSL_IMPORT SECStatus SSL_GetCipherSuiteInfo(PRUint16 cipherSuite, + SSLCipherSuiteInfo *info, PRUintn len); /* Returnes negotiated through SNI host info. */ SSL_IMPORT SECItem *SSL_GetNegotiatedHostInfo(PRFileDesc *fd); @@ -1030,48 +1216,38 @@ SSL_IMPORT SECStatus SSL_ExportKeyingMaterial(PRFileDesc *fd, unsigned char *out, unsigned int outLen); +/* Early exporters are used if 0-RTT is enabled. This is TLS 1.3 only. Note + * that in TLS 1.3, an empty context is equivalent to an absent context. */ +SSL_IMPORT SECStatus SSL_ExportEarlyKeyingMaterial(PRFileDesc *fd, + const char *label, + unsigned int labelLen, + const unsigned char *context, + unsigned int contextLen, + unsigned char *out, + unsigned int outLen); + /* ** Return a new reference to the certificate that was most recently sent ** to the peer on this SSL/TLS connection, or NULL if none has been sent. */ -SSL_IMPORT CERTCertificate * SSL_LocalCertificate(PRFileDesc *fd); - -/* Test an SSL configuration to see if SSL_BYPASS_PKCS11 can be turned on. -** Check the key exchange algorithm for each cipher in the list to see if -** a master secret key can be extracted after being derived with the mechanism -** required by the protocolmask argument. If the KEA will use keys from the -** specified cert make sure the extract operation is attempted from the slot -** where the private key resides. -** If MS can be extracted for all ciphers, (*pcanbypass) is set to TRUE and -** SECSuccess is returned. In all other cases but one (*pcanbypass) is -** set to FALSE and SECFailure is returned. -** In that last case Derive() has been called successfully but the MS is null, -** CanBypass sets (*pcanbypass) to FALSE and returns SECSuccess indicating the -** arguments were all valid but the slot cannot be bypassed. -** -** Note: A TRUE return code from CanBypass means "Your configuration will perform -** NO WORSE with the bypass enabled than without"; it does NOT mean that every -** cipher suite listed will work properly with the selected protocols. -** -** Caveat: If export cipher suites are included in the argument list Canbypass -** will return FALSE. -**/ +SSL_IMPORT CERTCertificate *SSL_LocalCertificate(PRFileDesc *fd); -/* protocol mask bits */ -#define SSL_CBP_SSL3 0x0001 /* test SSL v3 mechanisms */ -#define SSL_CBP_TLS1_0 0x0002 /* test TLS v1.0 mechanisms */ +#define SSL_CBP_SSL3 0x0001 /* (deprecated) */ +#define SSL_CBP_TLS1_0 0x0002 /* (deprecated) */ +/* DEPRECATED: The PKCS#11 bypass has been removed. +** This function will now always return false. */ SSL_IMPORT SECStatus SSL_CanBypass(CERTCertificate *cert, SECKEYPrivateKey *privKey, - PRUint32 protocolmask, - PRUint16 *ciphers, int nciphers, + PRUint32 protocolmask, + PRUint16 *ciphers, int nciphers, PRBool *pcanbypass, void *pwArg); /* ** Did the handshake with the peer negotiate the given extension? ** Output parameter valid only if function returns SECSuccess */ -SSL_IMPORT SECStatus SSL_HandshakeNegotiatedExtension(PRFileDesc * socket, +SSL_IMPORT SECStatus SSL_HandshakeNegotiatedExtension(PRFileDesc *socket, SSLExtensionType extId, PRBool *yes); @@ -1161,7 +1337,7 @@ extern const char *NSSSSL_GetVersion(void); * connection. */ SSL_IMPORT SECStatus SSL_AuthCertificateComplete(PRFileDesc *fd, - PRErrorCode error); + PRErrorCode error); SEC_END_PROTOS #endif /* __ssl_h_ */ |