1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/ssl/ssl.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1051 @@
1.4 +/*
1.5 + * This file contains prototypes for the public SSL functions.
1.6 + *
1.7 + * This Source Code Form is subject to the terms of the Mozilla Public
1.8 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.9 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.10 +
1.11 +#ifndef __ssl_h_
1.12 +#define __ssl_h_
1.13 +
1.14 +#include "prtypes.h"
1.15 +#include "prerror.h"
1.16 +#include "prio.h"
1.17 +#include "seccomon.h"
1.18 +#include "cert.h"
1.19 +#include "keyt.h"
1.20 +
1.21 +#include "sslt.h" /* public ssl data types */
1.22 +
1.23 +#if defined(_WIN32) && !defined(IN_LIBSSL) && !defined(NSS_USE_STATIC_LIBS)
1.24 +#define SSL_IMPORT extern __declspec(dllimport)
1.25 +#else
1.26 +#define SSL_IMPORT extern
1.27 +#endif
1.28 +
1.29 +SEC_BEGIN_PROTOS
1.30 +
1.31 +/* constant table enumerating all implemented SSL 2 and 3 cipher suites. */
1.32 +SSL_IMPORT const PRUint16 SSL_ImplementedCiphers[];
1.33 +
1.34 +/* the same as the above, but is a function */
1.35 +SSL_IMPORT const PRUint16 *SSL_GetImplementedCiphers(void);
1.36 +
1.37 +/* number of entries in the above table. */
1.38 +SSL_IMPORT const PRUint16 SSL_NumImplementedCiphers;
1.39 +
1.40 +/* the same as the above, but is a function */
1.41 +SSL_IMPORT PRUint16 SSL_GetNumImplementedCiphers(void);
1.42 +
1.43 +/* Macro to tell which ciphers in table are SSL2 vs SSL3/TLS. */
1.44 +#define SSL_IS_SSL2_CIPHER(which) (((which) & 0xfff0) == 0xff00)
1.45 +
1.46 +/*
1.47 +** Imports fd into SSL, returning a new socket. Copies SSL configuration
1.48 +** from model.
1.49 +*/
1.50 +SSL_IMPORT PRFileDesc *SSL_ImportFD(PRFileDesc *model, PRFileDesc *fd);
1.51 +
1.52 +/*
1.53 +** Imports fd into DTLS, returning a new socket. Copies DTLS configuration
1.54 +** from model.
1.55 +*/
1.56 +SSL_IMPORT PRFileDesc *DTLS_ImportFD(PRFileDesc *model, PRFileDesc *fd);
1.57 +
1.58 +/*
1.59 +** Enable/disable an ssl mode
1.60 +**
1.61 +** SSL_SECURITY:
1.62 +** enable/disable use of SSL security protocol before connect
1.63 +**
1.64 +** SSL_SOCKS:
1.65 +** enable/disable use of socks before connect
1.66 +** (No longer supported).
1.67 +**
1.68 +** SSL_REQUEST_CERTIFICATE:
1.69 +** require a certificate during secure connect
1.70 +*/
1.71 +/* options */
1.72 +#define SSL_SECURITY 1 /* (on by default) */
1.73 +#define SSL_SOCKS 2 /* (off by default) */
1.74 +#define SSL_REQUEST_CERTIFICATE 3 /* (off by default) */
1.75 +#define SSL_HANDSHAKE_AS_CLIENT 5 /* force accept to hs as client */
1.76 + /* (off by default) */
1.77 +#define SSL_HANDSHAKE_AS_SERVER 6 /* force connect to hs as server */
1.78 + /* (off by default) */
1.79 +
1.80 +/* OBSOLETE: SSL v2 is obsolete and may be removed soon. */
1.81 +#define SSL_ENABLE_SSL2 7 /* enable ssl v2 (off by default) */
1.82 +
1.83 +/* OBSOLETE: See "SSL Version Range API" below for the replacement and a
1.84 +** description of the non-obvious semantics of using SSL_ENABLE_SSL3.
1.85 +*/
1.86 +#define SSL_ENABLE_SSL3 8 /* enable ssl v3 (on by default) */
1.87 +
1.88 +#define SSL_NO_CACHE 9 /* don't use the session cache */
1.89 + /* (off by default) */
1.90 +#define SSL_REQUIRE_CERTIFICATE 10 /* (SSL_REQUIRE_FIRST_HANDSHAKE */
1.91 + /* by default) */
1.92 +#define SSL_ENABLE_FDX 11 /* permit simultaneous read/write */
1.93 + /* (off by default) */
1.94 +
1.95 +/* OBSOLETE: SSL v2 compatible hellos are not accepted by some TLS servers
1.96 +** and cannot negotiate extensions. SSL v2 is obsolete. This option may be
1.97 +** removed soon.
1.98 +*/
1.99 +#define SSL_V2_COMPATIBLE_HELLO 12 /* send v3 client hello in v2 fmt */
1.100 + /* (off by default) */
1.101 +
1.102 +/* OBSOLETE: See "SSL Version Range API" below for the replacement and a
1.103 +** description of the non-obvious semantics of using SSL_ENABLE_TLS.
1.104 +*/
1.105 +#define SSL_ENABLE_TLS 13 /* enable TLS (on by default) */
1.106 +
1.107 +#define SSL_ROLLBACK_DETECTION 14 /* for compatibility, default: on */
1.108 +#define SSL_NO_STEP_DOWN 15 /* Disable export cipher suites */
1.109 + /* if step-down keys are needed. */
1.110 + /* default: off, generate */
1.111 + /* step-down keys if needed. */
1.112 +#define SSL_BYPASS_PKCS11 16 /* use PKCS#11 for pub key only */
1.113 +#define SSL_NO_LOCKS 17 /* Don't use locks for protection */
1.114 +#define SSL_ENABLE_SESSION_TICKETS 18 /* Enable TLS SessionTicket */
1.115 + /* extension (off by default) */
1.116 +#define SSL_ENABLE_DEFLATE 19 /* Enable TLS compression with */
1.117 + /* DEFLATE (off by default) */
1.118 +#define SSL_ENABLE_RENEGOTIATION 20 /* Values below (default: never) */
1.119 +#define SSL_REQUIRE_SAFE_NEGOTIATION 21 /* Peer must send Signaling */
1.120 + /* Cipher Suite Value (SCSV) or */
1.121 + /* Renegotiation Info (RI) */
1.122 + /* extension in ALL handshakes. */
1.123 + /* default: off */
1.124 +#define SSL_ENABLE_FALSE_START 22 /* Enable SSL false start (off by */
1.125 + /* default, applies only to */
1.126 + /* clients). False start is a */
1.127 +/* mode where an SSL client will start sending application data before
1.128 + * verifying the server's Finished message. This means that we could end up
1.129 + * sending data to an imposter. However, the data will be encrypted and
1.130 + * only the true server can derive the session key. Thus, so long as the
1.131 + * cipher isn't broken this is safe. The advantage of false start is that
1.132 + * it saves a round trip for client-speaks-first protocols when performing a
1.133 + * full handshake.
1.134 + *
1.135 + * In addition to enabling this option, the application must register a
1.136 + * callback using the SSL_SetCanFalseStartCallback function.
1.137 + */
1.138 +
1.139 +/* For SSL 3.0 and TLS 1.0, by default we prevent chosen plaintext attacks
1.140 + * on SSL CBC mode cipher suites (see RFC 4346 Section F.3) by splitting
1.141 + * non-empty application_data records into two records; the first record has
1.142 + * only the first byte of plaintext, and the second has the rest.
1.143 + *
1.144 + * This only prevents the attack in the sending direction; the connection may
1.145 + * still be vulnerable to such attacks if the peer does not implement a similar
1.146 + * countermeasure.
1.147 + *
1.148 + * This protection mechanism is on by default; the default can be overridden by
1.149 + * setting NSS_SSL_CBC_RANDOM_IV=0 in the environment prior to execution,
1.150 + * and/or by the application setting the option SSL_CBC_RANDOM_IV to PR_FALSE.
1.151 + *
1.152 + * The per-record IV in TLS 1.1 and later adds one block of overhead per
1.153 + * record, whereas this hack will add at least two blocks of overhead per
1.154 + * record, so TLS 1.1+ will always be more efficient.
1.155 + *
1.156 + * Other implementations (e.g. some versions of OpenSSL, in some
1.157 + * configurations) prevent the same attack by prepending an empty
1.158 + * application_data record to every application_data record they send; we do
1.159 + * not do that because some implementations cannot handle empty
1.160 + * application_data records. Also, we only split application_data records and
1.161 + * not other types of records, because some implementations will not accept
1.162 + * fragmented records of some other types (e.g. some versions of NSS do not
1.163 + * accept fragmented alerts).
1.164 + */
1.165 +#define SSL_CBC_RANDOM_IV 23
1.166 +#define SSL_ENABLE_OCSP_STAPLING 24 /* Request OCSP stapling (client) */
1.167 +
1.168 +/* SSL_ENABLE_NPN controls whether the NPN extension is enabled for the initial
1.169 + * handshake when application layer protocol negotiation is used.
1.170 + * SSL_SetNextProtoCallback or SSL_SetNextProtoNego must be used to control the
1.171 + * application layer protocol negotiation; otherwise, the NPN extension will
1.172 + * not be negotiated. SSL_ENABLE_NPN is currently enabled by default but this
1.173 + * may change in future versions.
1.174 + */
1.175 +#define SSL_ENABLE_NPN 25
1.176 +
1.177 +/* SSL_ENABLE_ALPN controls whether the ALPN extension is enabled for the
1.178 + * initial handshake when application layer protocol negotiation is used.
1.179 + * SSL_SetNextProtoNego (not SSL_SetNextProtoCallback) must be used to control
1.180 + * the application layer protocol negotiation; otherwise, the ALPN extension
1.181 + * will not be negotiated. ALPN is not negotiated for renegotiation handshakes,
1.182 + * even though the ALPN specification defines a way to use ALPN during
1.183 + * renegotiations. SSL_ENABLE_ALPN is currently disabled by default, but this
1.184 + * may change in future versions.
1.185 + */
1.186 +#define SSL_ENABLE_ALPN 26
1.187 +
1.188 +#define SSL_ENABLE_FALLBACK_SCSV 28 /* Send fallback SCSV in
1.189 + * handshakes. */
1.190 +
1.191 +#ifdef SSL_DEPRECATED_FUNCTION
1.192 +/* Old deprecated function names */
1.193 +SSL_IMPORT SECStatus SSL_Enable(PRFileDesc *fd, int option, PRBool on);
1.194 +SSL_IMPORT SECStatus SSL_EnableDefault(int option, PRBool on);
1.195 +#endif
1.196 +
1.197 +/* New function names */
1.198 +SSL_IMPORT SECStatus SSL_OptionSet(PRFileDesc *fd, PRInt32 option, PRBool on);
1.199 +SSL_IMPORT SECStatus SSL_OptionGet(PRFileDesc *fd, PRInt32 option, PRBool *on);
1.200 +SSL_IMPORT SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on);
1.201 +SSL_IMPORT SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on);
1.202 +SSL_IMPORT SECStatus SSL_CertDBHandleSet(PRFileDesc *fd, CERTCertDBHandle *dbHandle);
1.203 +
1.204 +/* SSLNextProtoCallback is called during the handshake for the client, when a
1.205 + * Next Protocol Negotiation (NPN) extension has been received from the server.
1.206 + * |protos| and |protosLen| define a buffer which contains the server's
1.207 + * advertisement. This data is guaranteed to be well formed per the NPN spec.
1.208 + * |protoOut| is a buffer provided by the caller, of length 255 (the maximum
1.209 + * allowed by the protocol). On successful return, the protocol to be announced
1.210 + * to the server will be in |protoOut| and its length in |*protoOutLen|.
1.211 + *
1.212 + * The callback must return SECFailure or SECSuccess (not SECWouldBlock).
1.213 + */
1.214 +typedef SECStatus (PR_CALLBACK *SSLNextProtoCallback)(
1.215 + void *arg,
1.216 + PRFileDesc *fd,
1.217 + const unsigned char* protos,
1.218 + unsigned int protosLen,
1.219 + unsigned char* protoOut,
1.220 + unsigned int* protoOutLen,
1.221 + unsigned int protoMaxOut);
1.222 +
1.223 +/* SSL_SetNextProtoCallback sets a callback function to handle Next Protocol
1.224 + * Negotiation. It causes a client to advertise NPN. */
1.225 +SSL_IMPORT SECStatus SSL_SetNextProtoCallback(PRFileDesc *fd,
1.226 + SSLNextProtoCallback callback,
1.227 + void *arg);
1.228 +
1.229 +/* SSL_SetNextProtoNego can be used as an alternative to
1.230 + * SSL_SetNextProtoCallback. It also causes a client to advertise NPN and
1.231 + * installs a default callback function which selects the first supported
1.232 + * protocol in server-preference order. If no matching protocol is found it
1.233 + * selects the first supported protocol.
1.234 + *
1.235 + * Using this function also allows the client to transparently support ALPN.
1.236 + * The same set of protocols will be advertised via ALPN and, if the server
1.237 + * uses ALPN to select a protocol, SSL_GetNextProto will return
1.238 + * SSL_NEXT_PROTO_SELECTED as the state.
1.239 + *
1.240 + * Since NPN uses the first protocol as the fallback protocol, when sending an
1.241 + * ALPN extension, the first protocol is moved to the end of the list. This
1.242 + * indicates that the fallback protocol is the least preferred. The other
1.243 + * protocols should be in preference order.
1.244 + *
1.245 + * The supported protocols are specified in |data| in wire-format (8-bit
1.246 + * length-prefixed). For example: "\010http/1.1\006spdy/2". */
1.247 +SSL_IMPORT SECStatus SSL_SetNextProtoNego(PRFileDesc *fd,
1.248 + const unsigned char *data,
1.249 + unsigned int length);
1.250 +
1.251 +typedef enum SSLNextProtoState {
1.252 + SSL_NEXT_PROTO_NO_SUPPORT = 0, /* No peer support */
1.253 + SSL_NEXT_PROTO_NEGOTIATED = 1, /* Mutual agreement */
1.254 + SSL_NEXT_PROTO_NO_OVERLAP = 2, /* No protocol overlap found */
1.255 + SSL_NEXT_PROTO_SELECTED = 3 /* Server selected proto (ALPN) */
1.256 +} SSLNextProtoState;
1.257 +
1.258 +/* SSL_GetNextProto can be used in the HandshakeCallback or any time after
1.259 + * a handshake to retrieve the result of the Next Protocol negotiation.
1.260 + *
1.261 + * The length of the negotiated protocol, if any, is written into *bufLen.
1.262 + * If the negotiated protocol is longer than bufLenMax, then SECFailure is
1.263 + * returned. Otherwise, the negotiated protocol, if any, is written into buf,
1.264 + * and SECSuccess is returned. */
1.265 +SSL_IMPORT SECStatus SSL_GetNextProto(PRFileDesc *fd,
1.266 + SSLNextProtoState *state,
1.267 + unsigned char *buf,
1.268 + unsigned int *bufLen,
1.269 + unsigned int bufLenMax);
1.270 +
1.271 +/*
1.272 +** Control ciphers that SSL uses. If on is non-zero then the named cipher
1.273 +** is enabled, otherwise it is disabled.
1.274 +** The "cipher" values are defined in sslproto.h (the SSL_EN_* values).
1.275 +** EnableCipher records user preferences.
1.276 +** SetPolicy sets the policy according to the policy module.
1.277 +*/
1.278 +#ifdef SSL_DEPRECATED_FUNCTION
1.279 +/* Old deprecated function names */
1.280 +SSL_IMPORT SECStatus SSL_EnableCipher(long which, PRBool enabled);
1.281 +SSL_IMPORT SECStatus SSL_SetPolicy(long which, int policy);
1.282 +#endif
1.283 +
1.284 +/* New function names */
1.285 +SSL_IMPORT SECStatus SSL_CipherPrefSet(PRFileDesc *fd, PRInt32 cipher, PRBool enabled);
1.286 +SSL_IMPORT SECStatus SSL_CipherPrefGet(PRFileDesc *fd, PRInt32 cipher, PRBool *enabled);
1.287 +SSL_IMPORT SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool enabled);
1.288 +SSL_IMPORT SECStatus SSL_CipherPrefGetDefault(PRInt32 cipher, PRBool *enabled);
1.289 +SSL_IMPORT SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy);
1.290 +SSL_IMPORT SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy);
1.291 +
1.292 +/* SSL Version Range API
1.293 +**
1.294 +** This API should be used to control SSL 3.0 & TLS support instead of the
1.295 +** older SSL_Option* API; however, the SSL_Option* API MUST still be used to
1.296 +** control SSL 2.0 support. In this version of libssl, SSL 3.0 and TLS 1.0 are
1.297 +** enabled by default. Future versions of libssl may change which versions of
1.298 +** the protocol are enabled by default.
1.299 +**
1.300 +** The SSLProtocolVariant enum indicates whether the protocol is of type
1.301 +** stream or datagram. This must be provided to the functions that do not
1.302 +** take an fd. Functions which take an fd will get the variant from the fd,
1.303 +** which is typed.
1.304 +**
1.305 +** Using the new version range API in conjunction with the older
1.306 +** SSL_OptionSet-based API for controlling the enabled protocol versions may
1.307 +** cause unexpected results. Going forward, we guarantee only the following:
1.308 +**
1.309 +** SSL_OptionGet(SSL_ENABLE_TLS) will return PR_TRUE if *ANY* versions of TLS
1.310 +** are enabled.
1.311 +**
1.312 +** SSL_OptionSet(SSL_ENABLE_TLS, PR_FALSE) will disable *ALL* versions of TLS,
1.313 +** including TLS 1.0 and later.
1.314 +**
1.315 +** The above two properties provide compatibility for applications that use
1.316 +** SSL_OptionSet to implement the insecure fallback from TLS 1.x to SSL 3.0.
1.317 +**
1.318 +** SSL_OptionSet(SSL_ENABLE_TLS, PR_TRUE) will enable TLS 1.0, and may also
1.319 +** enable some later versions of TLS, if it is necessary to do so in order to
1.320 +** keep the set of enabled versions contiguous. For example, if TLS 1.2 is
1.321 +** enabled, then after SSL_OptionSet(SSL_ENABLE_TLS, PR_TRUE), TLS 1.0,
1.322 +** TLS 1.1, and TLS 1.2 will be enabled, and the call will have no effect on
1.323 +** whether SSL 3.0 is enabled. If no later versions of TLS are enabled at the
1.324 +** time SSL_OptionSet(SSL_ENABLE_TLS, PR_TRUE) is called, then no later
1.325 +** versions of TLS will be enabled by the call.
1.326 +**
1.327 +** SSL_OptionSet(SSL_ENABLE_SSL3, PR_FALSE) will disable SSL 3.0, and will not
1.328 +** change the set of TLS versions that are enabled.
1.329 +**
1.330 +** SSL_OptionSet(SSL_ENABLE_SSL3, PR_TRUE) will enable SSL 3.0, and may also
1.331 +** enable some versions of TLS if TLS 1.1 or later is enabled at the time of
1.332 +** the call, the same way SSL_OptionSet(SSL_ENABLE_TLS, PR_TRUE) works, in
1.333 +** order to keep the set of enabled versions contiguous.
1.334 +*/
1.335 +
1.336 +/* Returns, in |*vrange|, the range of SSL3/TLS versions supported for the
1.337 +** given protocol variant by the version of libssl linked-to at runtime.
1.338 +*/
1.339 +SSL_IMPORT SECStatus SSL_VersionRangeGetSupported(
1.340 + SSLProtocolVariant protocolVariant, SSLVersionRange *vrange);
1.341 +
1.342 +/* Returns, in |*vrange|, the range of SSL3/TLS versions enabled by default
1.343 +** for the given protocol variant.
1.344 +*/
1.345 +SSL_IMPORT SECStatus SSL_VersionRangeGetDefault(
1.346 + SSLProtocolVariant protocolVariant, SSLVersionRange *vrange);
1.347 +
1.348 +/* Sets the range of enabled-by-default SSL3/TLS versions for the given
1.349 +** protocol variant to |*vrange|.
1.350 +*/
1.351 +SSL_IMPORT SECStatus SSL_VersionRangeSetDefault(
1.352 + SSLProtocolVariant protocolVariant, const SSLVersionRange *vrange);
1.353 +
1.354 +/* Returns, in |*vrange|, the range of enabled SSL3/TLS versions for |fd|. */
1.355 +SSL_IMPORT SECStatus SSL_VersionRangeGet(PRFileDesc *fd,
1.356 + SSLVersionRange *vrange);
1.357 +
1.358 +/* Sets the range of enabled SSL3/TLS versions for |fd| to |*vrange|. */
1.359 +SSL_IMPORT SECStatus SSL_VersionRangeSet(PRFileDesc *fd,
1.360 + const SSLVersionRange *vrange);
1.361 +
1.362 +
1.363 +/* Values for "policy" argument to SSL_CipherPolicySet */
1.364 +/* Values returned by SSL_CipherPolicyGet. */
1.365 +#define SSL_NOT_ALLOWED 0 /* or invalid or unimplemented */
1.366 +#define SSL_ALLOWED 1
1.367 +#define SSL_RESTRICTED 2 /* only with "Step-Up" certs. */
1.368 +
1.369 +/* Values for "on" with SSL_REQUIRE_CERTIFICATE. */
1.370 +#define SSL_REQUIRE_NEVER ((PRBool)0)
1.371 +#define SSL_REQUIRE_ALWAYS ((PRBool)1)
1.372 +#define SSL_REQUIRE_FIRST_HANDSHAKE ((PRBool)2)
1.373 +#define SSL_REQUIRE_NO_ERROR ((PRBool)3)
1.374 +
1.375 +/* Values for "on" with SSL_ENABLE_RENEGOTIATION */
1.376 +/* Never renegotiate at all. */
1.377 +#define SSL_RENEGOTIATE_NEVER ((PRBool)0)
1.378 +/* Renegotiate without restriction, whether or not the peer's client hello */
1.379 +/* bears the renegotiation info extension. Vulnerable, as in the past. */
1.380 +#define SSL_RENEGOTIATE_UNRESTRICTED ((PRBool)1)
1.381 +/* Only renegotiate if the peer's hello bears the TLS renegotiation_info */
1.382 +/* extension. This is safe renegotiation. */
1.383 +#define SSL_RENEGOTIATE_REQUIRES_XTN ((PRBool)2)
1.384 +/* Disallow unsafe renegotiation in server sockets only, but allow clients */
1.385 +/* to continue to renegotiate with vulnerable servers. */
1.386 +/* This value should only be used during the transition period when few */
1.387 +/* servers have been upgraded. */
1.388 +#define SSL_RENEGOTIATE_TRANSITIONAL ((PRBool)3)
1.389 +
1.390 +/*
1.391 +** Reset the handshake state for fd. This will make the complete SSL
1.392 +** handshake protocol execute from the ground up on the next i/o
1.393 +** operation.
1.394 +*/
1.395 +SSL_IMPORT SECStatus SSL_ResetHandshake(PRFileDesc *fd, PRBool asServer);
1.396 +
1.397 +/*
1.398 +** Force the handshake for fd to complete immediately. This blocks until
1.399 +** the complete SSL handshake protocol is finished.
1.400 +*/
1.401 +SSL_IMPORT SECStatus SSL_ForceHandshake(PRFileDesc *fd);
1.402 +
1.403 +/*
1.404 +** Same as above, but with an I/O timeout.
1.405 + */
1.406 +SSL_IMPORT SECStatus SSL_ForceHandshakeWithTimeout(PRFileDesc *fd,
1.407 + PRIntervalTime timeout);
1.408 +
1.409 +/*
1.410 +** Query security status of socket. *on is set to one if security is
1.411 +** enabled. *keySize will contain the stream key size used. *issuer will
1.412 +** contain the RFC1485 verison of the name of the issuer of the
1.413 +** certificate at the other end of the connection. For a client, this is
1.414 +** the issuer of the server's certificate; for a server, this is the
1.415 +** issuer of the client's certificate (if any). Subject is the subject of
1.416 +** the other end's certificate. The pointers can be zero if the desired
1.417 +** data is not needed. All strings returned by this function are owned
1.418 +** by the caller, and need to be freed with PORT_Free.
1.419 +*/
1.420 +SSL_IMPORT SECStatus SSL_SecurityStatus(PRFileDesc *fd, int *on, char **cipher,
1.421 + int *keySize, int *secretKeySize,
1.422 + char **issuer, char **subject);
1.423 +
1.424 +/* Values for "on" */
1.425 +#define SSL_SECURITY_STATUS_NOOPT -1
1.426 +#define SSL_SECURITY_STATUS_OFF 0
1.427 +#define SSL_SECURITY_STATUS_ON_HIGH 1
1.428 +#define SSL_SECURITY_STATUS_ON_LOW 2
1.429 +#define SSL_SECURITY_STATUS_FORTEZZA 3 /* NO LONGER SUPPORTED */
1.430 +
1.431 +/*
1.432 +** Return the certificate for our SSL peer. If the client calls this
1.433 +** it will always return the server's certificate. If the server calls
1.434 +** this, it may return NULL if client authentication is not enabled or
1.435 +** if the client had no certificate when asked.
1.436 +** "fd" the socket "file" descriptor
1.437 +*/
1.438 +SSL_IMPORT CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd);
1.439 +
1.440 +/*
1.441 +** Return the certificates presented by the SSL peer. If the SSL peer
1.442 +** did not present certificates, return NULL with the
1.443 +** SSL_ERROR_NO_CERTIFICATE error. On failure, return NULL with an error
1.444 +** code other than SSL_ERROR_NO_CERTIFICATE.
1.445 +** "fd" the socket "file" descriptor
1.446 +*/
1.447 +SSL_IMPORT CERTCertList *SSL_PeerCertificateChain(PRFileDesc *fd);
1.448 +
1.449 +/* SSL_PeerStapledOCSPResponses returns the OCSP responses that were provided
1.450 + * by the TLS server. The return value is a pointer to an internal SECItemArray
1.451 + * that contains the returned OCSP responses; it is only valid until the
1.452 + * callback function that calls SSL_PeerStapledOCSPResponses returns.
1.453 + *
1.454 + * If no OCSP responses were given by the server then the result will be empty.
1.455 + * If there was an error, then the result will be NULL.
1.456 + *
1.457 + * You must set the SSL_ENABLE_OCSP_STAPLING option to enable OCSP stapling.
1.458 + * to be provided by a server.
1.459 + *
1.460 + * libssl does not do any validation of the OCSP response itself; the
1.461 + * authenticate certificate hook is responsible for doing so. The default
1.462 + * authenticate certificate hook, SSL_AuthCertificate, does not implement
1.463 + * any OCSP stapling funtionality, but this may change in future versions.
1.464 + */
1.465 +SSL_IMPORT const SECItemArray * SSL_PeerStapledOCSPResponses(PRFileDesc *fd);
1.466 +
1.467 +/* SSL_SetStapledOCSPResponses stores an array of one or multiple OCSP responses
1.468 + * in the fd's data, which may be sent as part of a server side cert_status
1.469 + * handshake message. Parameter |responses| is for the server certificate of
1.470 + * the key exchange type |kea|.
1.471 + * The function will duplicate the responses array.
1.472 + */
1.473 +SSL_IMPORT SECStatus
1.474 +SSL_SetStapledOCSPResponses(PRFileDesc *fd, const SECItemArray *responses,
1.475 + SSLKEAType kea);
1.476 +
1.477 +/*
1.478 +** Authenticate certificate hook. Called when a certificate comes in
1.479 +** (because of SSL_REQUIRE_CERTIFICATE in SSL_Enable) to authenticate the
1.480 +** certificate.
1.481 +**
1.482 +** The authenticate certificate hook must return SECSuccess to indicate the
1.483 +** certificate is valid, SECFailure to indicate the certificate is invalid,
1.484 +** or SECWouldBlock if the application will authenticate the certificate
1.485 +** asynchronously. SECWouldBlock is only supported for non-blocking sockets.
1.486 +**
1.487 +** If the authenticate certificate hook returns SECFailure, then the bad cert
1.488 +** hook will be called. The bad cert handler is NEVER called if the
1.489 +** authenticate certificate hook returns SECWouldBlock. If the application
1.490 +** needs to handle and/or override a bad cert, it should do so before it
1.491 +** calls SSL_AuthCertificateComplete (modifying the error it passes to
1.492 +** SSL_AuthCertificateComplete as needed).
1.493 +**
1.494 +** See the documentation for SSL_AuthCertificateComplete for more information
1.495 +** about the asynchronous behavior that occurs when the authenticate
1.496 +** certificate hook returns SECWouldBlock.
1.497 +**
1.498 +** RFC 6066 says that clients should send the bad_certificate_status_response
1.499 +** alert when they encounter an error processing the stapled OCSP response.
1.500 +** libssl does not provide a way for the authenticate certificate hook to
1.501 +** indicate that an OCSP error (SEC_ERROR_OCSP_*) that it returns is an error
1.502 +** in the stapled OCSP response or an error in some other OCSP response.
1.503 +** Further, NSS does not provide a convenient way to control or determine
1.504 +** which OCSP response(s) were used to validate a certificate chain.
1.505 +** Consequently, the current version of libssl does not ever send the
1.506 +** bad_certificate_status_response alert. This may change in future releases.
1.507 +*/
1.508 +typedef SECStatus (PR_CALLBACK *SSLAuthCertificate)(void *arg, PRFileDesc *fd,
1.509 + PRBool checkSig,
1.510 + PRBool isServer);
1.511 +
1.512 +SSL_IMPORT SECStatus SSL_AuthCertificateHook(PRFileDesc *fd,
1.513 + SSLAuthCertificate f,
1.514 + void *arg);
1.515 +
1.516 +/* An implementation of the certificate authentication hook */
1.517 +SSL_IMPORT SECStatus SSL_AuthCertificate(void *arg, PRFileDesc *fd,
1.518 + PRBool checkSig, PRBool isServer);
1.519 +
1.520 +/*
1.521 + * Prototype for SSL callback to get client auth data from the application.
1.522 + * arg - application passed argument
1.523 + * caNames - pointer to distinguished names of CAs that the server likes
1.524 + * pRetCert - pointer to pointer to cert, for return of cert
1.525 + * pRetKey - pointer to key pointer, for return of key
1.526 + */
1.527 +typedef SECStatus (PR_CALLBACK *SSLGetClientAuthData)(void *arg,
1.528 + PRFileDesc *fd,
1.529 + CERTDistNames *caNames,
1.530 + CERTCertificate **pRetCert,/*return */
1.531 + SECKEYPrivateKey **pRetKey);/* return */
1.532 +
1.533 +/*
1.534 + * Set the client side callback for SSL to retrieve user's private key
1.535 + * and certificate.
1.536 + * fd - the file descriptor for the connection in question
1.537 + * f - the application's callback that delivers the key and cert
1.538 + * a - application specific data
1.539 + */
1.540 +SSL_IMPORT SECStatus SSL_GetClientAuthDataHook(PRFileDesc *fd,
1.541 + SSLGetClientAuthData f, void *a);
1.542 +
1.543 +
1.544 +/*
1.545 +** SNI extension processing callback function.
1.546 +** It is called when SSL socket receives SNI extension in ClientHello message.
1.547 +** Upon this callback invocation, application is responsible to reconfigure the
1.548 +** socket with the data for a particular server name.
1.549 +** There are three potential outcomes of this function invocation:
1.550 +** * application does not recognize the name or the type and wants the
1.551 +** "unrecognized_name" alert be sent to the client. In this case the callback
1.552 +** function must return SSL_SNI_SEND_ALERT status.
1.553 +** * application does not recognize the name, but wants to continue with
1.554 +** the handshake using the current socket configuration. In this case,
1.555 +** no socket reconfiguration is needed and the function should return
1.556 +** SSL_SNI_CURRENT_CONFIG_IS_USED.
1.557 +** * application recognizes the name and reconfigures the socket with
1.558 +** appropriate certs, key, etc. There are many ways to reconfigure. NSS
1.559 +** provides SSL_ReconfigFD function that can be used to update the socket
1.560 +** data from model socket. To continue with the rest of the handshake, the
1.561 +** implementation function should return an index of a name it has chosen.
1.562 +** LibSSL will ignore any SNI extension received in a ClientHello message
1.563 +** if application does not register a SSLSNISocketConfig callback.
1.564 +** Each type field of SECItem indicates the name type.
1.565 +** NOTE: currently RFC3546 defines only one name type: sni_host_name.
1.566 +** Client is allowed to send only one name per known type. LibSSL will
1.567 +** send an "unrecognized_name" alert if SNI extension name list contains more
1.568 +** then one name of a type.
1.569 +*/
1.570 +typedef PRInt32 (PR_CALLBACK *SSLSNISocketConfig)(PRFileDesc *fd,
1.571 + const SECItem *srvNameArr,
1.572 + PRUint32 srvNameArrSize,
1.573 + void *arg);
1.574 +
1.575 +/*
1.576 +** SSLSNISocketConfig should return an index within 0 and srvNameArrSize-1
1.577 +** when it has reconfigured the socket fd to use certs and keys, etc
1.578 +** for a specific name. There are two other allowed return values. One
1.579 +** tells libSSL to use the default cert and key. The other tells libSSL
1.580 +** to send the "unrecognized_name" alert. These values are:
1.581 +**/
1.582 +#define SSL_SNI_CURRENT_CONFIG_IS_USED -1
1.583 +#define SSL_SNI_SEND_ALERT -2
1.584 +
1.585 +/*
1.586 +** Set application implemented SNISocketConfig callback.
1.587 +*/
1.588 +SSL_IMPORT SECStatus SSL_SNISocketConfigHook(PRFileDesc *fd,
1.589 + SSLSNISocketConfig f,
1.590 + void *arg);
1.591 +
1.592 +/*
1.593 +** Reconfigure fd SSL socket with model socket parameters. Sets
1.594 +** server certs and keys, list of trust anchor, socket options
1.595 +** and all SSL socket call backs and parameters.
1.596 +*/
1.597 +SSL_IMPORT PRFileDesc *SSL_ReconfigFD(PRFileDesc *model, PRFileDesc *fd);
1.598 +
1.599 +/*
1.600 + * Set the client side argument for SSL to retrieve PKCS #11 pin.
1.601 + * fd - the file descriptor for the connection in question
1.602 + * a - pkcs11 application specific data
1.603 + */
1.604 +SSL_IMPORT SECStatus SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a);
1.605 +
1.606 +/*
1.607 +** This is a callback for dealing with server certs that are not authenticated
1.608 +** by the client. The client app can decide that it actually likes the
1.609 +** cert by some external means and restart the connection.
1.610 +**
1.611 +** The bad cert hook must return SECSuccess to override the result of the
1.612 +** authenticate certificate hook, SECFailure if the certificate should still be
1.613 +** considered invalid, or SECWouldBlock if the application will authenticate
1.614 +** the certificate asynchronously. SECWouldBlock is only supported for
1.615 +** non-blocking sockets.
1.616 +**
1.617 +** See the documentation for SSL_AuthCertificateComplete for more information
1.618 +** about the asynchronous behavior that occurs when the bad cert hook returns
1.619 +** SECWouldBlock.
1.620 +*/
1.621 +typedef SECStatus (PR_CALLBACK *SSLBadCertHandler)(void *arg, PRFileDesc *fd);
1.622 +SSL_IMPORT SECStatus SSL_BadCertHook(PRFileDesc *fd, SSLBadCertHandler f,
1.623 + void *arg);
1.624 +
1.625 +/*
1.626 +** Configure SSL socket for running a secure server. Needs the
1.627 +** certificate for the server and the servers private key. The arguments
1.628 +** are copied.
1.629 +*/
1.630 +SSL_IMPORT SECStatus SSL_ConfigSecureServer(
1.631 + PRFileDesc *fd, CERTCertificate *cert,
1.632 + SECKEYPrivateKey *key, SSLKEAType kea);
1.633 +
1.634 +/*
1.635 +** Allows SSL socket configuration with caller-supplied certificate chain.
1.636 +** If certChainOpt is NULL, tries to find one.
1.637 +*/
1.638 +SSL_IMPORT SECStatus
1.639 +SSL_ConfigSecureServerWithCertChain(PRFileDesc *fd, CERTCertificate *cert,
1.640 + const CERTCertificateList *certChainOpt,
1.641 + SECKEYPrivateKey *key, SSLKEAType kea);
1.642 +
1.643 +/*
1.644 +** Configure a secure server's session-id cache. Define the maximum number
1.645 +** of entries in the cache, the longevity of the entires, and the directory
1.646 +** where the cache files will be placed. These values can be zero, and
1.647 +** if so, the implementation will choose defaults.
1.648 +** This version of the function is for use in applications that have only one
1.649 +** process that uses the cache (even if that process has multiple threads).
1.650 +*/
1.651 +SSL_IMPORT SECStatus SSL_ConfigServerSessionIDCache(int maxCacheEntries,
1.652 + PRUint32 timeout,
1.653 + PRUint32 ssl3_timeout,
1.654 + const char * directory);
1.655 +
1.656 +/* Configure a secure server's session-id cache. Depends on value of
1.657 + * enableMPCache, configures malti-proc or single proc cache. */
1.658 +SSL_IMPORT SECStatus SSL_ConfigServerSessionIDCacheWithOpt(
1.659 + PRUint32 timeout,
1.660 + PRUint32 ssl3_timeout,
1.661 + const char * directory,
1.662 + int maxCacheEntries,
1.663 + int maxCertCacheEntries,
1.664 + int maxSrvNameCacheEntries,
1.665 + PRBool enableMPCache);
1.666 +
1.667 +/*
1.668 +** Like SSL_ConfigServerSessionIDCache, with one important difference.
1.669 +** If the application will run multiple processes (as opposed to, or in
1.670 +** addition to multiple threads), then it must call this function, instead
1.671 +** of calling SSL_ConfigServerSessionIDCache().
1.672 +** This has nothing to do with the number of processORs, only processEs.
1.673 +** This function sets up a Server Session ID (SID) cache that is safe for
1.674 +** access by multiple processes on the same system.
1.675 +*/
1.676 +SSL_IMPORT SECStatus SSL_ConfigMPServerSIDCache(int maxCacheEntries,
1.677 + PRUint32 timeout,
1.678 + PRUint32 ssl3_timeout,
1.679 + const char * directory);
1.680 +
1.681 +/* Get and set the configured maximum number of mutexes used for the
1.682 +** server's store of SSL sessions. This value is used by the server
1.683 +** session ID cache initialization functions shown above. Note that on
1.684 +** some platforms, these mutexes are actually implemented with POSIX
1.685 +** semaphores, or with unnamed pipes. The default value varies by platform.
1.686 +** An attempt to set a too-low maximum will return an error and the
1.687 +** configured value will not be changed.
1.688 +*/
1.689 +SSL_IMPORT PRUint32 SSL_GetMaxServerCacheLocks(void);
1.690 +SSL_IMPORT SECStatus SSL_SetMaxServerCacheLocks(PRUint32 maxLocks);
1.691 +
1.692 +/* environment variable set by SSL_ConfigMPServerSIDCache, and queried by
1.693 + * SSL_InheritMPServerSIDCache when envString is NULL.
1.694 + */
1.695 +#define SSL_ENV_VAR_NAME "SSL_INHERITANCE"
1.696 +
1.697 +/* called in child to inherit SID Cache variables.
1.698 + * If envString is NULL, this function will use the value of the environment
1.699 + * variable "SSL_INHERITANCE", otherwise the string value passed in will be
1.700 + * used.
1.701 + */
1.702 +SSL_IMPORT SECStatus SSL_InheritMPServerSIDCache(const char * envString);
1.703 +
1.704 +/*
1.705 +** Set the callback that gets called when a TLS handshake is complete. The
1.706 +** handshake callback is called after verifying the peer's Finished message and
1.707 +** before processing incoming application data.
1.708 +**
1.709 +** For the initial handshake: If the handshake false started (see
1.710 +** SSL_ENABLE_FALSE_START), then application data may already have been sent
1.711 +** before the handshake callback is called. If we did not false start then the
1.712 +** callback will get called before any application data is sent.
1.713 +*/
1.714 +typedef void (PR_CALLBACK *SSLHandshakeCallback)(PRFileDesc *fd,
1.715 + void *client_data);
1.716 +SSL_IMPORT SECStatus SSL_HandshakeCallback(PRFileDesc *fd,
1.717 + SSLHandshakeCallback cb, void *client_data);
1.718 +
1.719 +/* Applications that wish to enable TLS false start must set this callback
1.720 +** function. NSS will invoke the functon to determine if a particular
1.721 +** connection should use false start or not. SECSuccess indicates that the
1.722 +** callback completed successfully, and if so *canFalseStart indicates if false
1.723 +** start can be used. If the callback does not return SECSuccess then the
1.724 +** handshake will be canceled. NSS's recommended criteria can be evaluated by
1.725 +** calling SSL_RecommendedCanFalseStart.
1.726 +**
1.727 +** If no false start callback is registered then false start will never be
1.728 +** done, even if the SSL_ENABLE_FALSE_START option is enabled.
1.729 +**/
1.730 +typedef SECStatus (PR_CALLBACK *SSLCanFalseStartCallback)(
1.731 + PRFileDesc *fd, void *arg, PRBool *canFalseStart);
1.732 +
1.733 +SSL_IMPORT SECStatus SSL_SetCanFalseStartCallback(
1.734 + PRFileDesc *fd, SSLCanFalseStartCallback callback, void *arg);
1.735 +
1.736 +/* This function sets *canFalseStart according to the recommended criteria for
1.737 +** false start. These criteria may change from release to release and may depend
1.738 +** on which handshake features have been negotiated and/or properties of the
1.739 +** certifciates/keys used on the connection.
1.740 +*/
1.741 +SSL_IMPORT SECStatus SSL_RecommendedCanFalseStart(PRFileDesc *fd,
1.742 + PRBool *canFalseStart);
1.743 +
1.744 +/*
1.745 +** For the server, request a new handshake. For the client, begin a new
1.746 +** handshake. If flushCache is non-zero, the SSL3 cache entry will be
1.747 +** flushed first, ensuring that a full SSL handshake will be done.
1.748 +** If flushCache is zero, and an SSL connection is established, it will
1.749 +** do the much faster session restart handshake. This will change the
1.750 +** session keys without doing another private key operation.
1.751 +*/
1.752 +SSL_IMPORT SECStatus SSL_ReHandshake(PRFileDesc *fd, PRBool flushCache);
1.753 +
1.754 +/*
1.755 +** Same as above, but with an I/O timeout.
1.756 + */
1.757 +SSL_IMPORT SECStatus SSL_ReHandshakeWithTimeout(PRFileDesc *fd,
1.758 + PRBool flushCache,
1.759 + PRIntervalTime timeout);
1.760 +
1.761 +
1.762 +#ifdef SSL_DEPRECATED_FUNCTION
1.763 +/* deprecated!
1.764 +** For the server, request a new handshake. For the client, begin a new
1.765 +** handshake. Flushes SSL3 session cache entry first, ensuring that a
1.766 +** full handshake will be done.
1.767 +** This call is equivalent to SSL_ReHandshake(fd, PR_TRUE)
1.768 +*/
1.769 +SSL_IMPORT SECStatus SSL_RedoHandshake(PRFileDesc *fd);
1.770 +#endif
1.771 +
1.772 +/*
1.773 + * Allow the application to pass a URL or hostname into the SSL library.
1.774 + */
1.775 +SSL_IMPORT SECStatus SSL_SetURL(PRFileDesc *fd, const char *url);
1.776 +
1.777 +/*
1.778 + * Allow an application to define a set of trust anchors for peer
1.779 + * cert validation.
1.780 + */
1.781 +SSL_IMPORT SECStatus SSL_SetTrustAnchors(PRFileDesc *fd, CERTCertList *list);
1.782 +
1.783 +/*
1.784 +** Return the number of bytes that SSL has waiting in internal buffers.
1.785 +** Return 0 if security is not enabled.
1.786 +*/
1.787 +SSL_IMPORT int SSL_DataPending(PRFileDesc *fd);
1.788 +
1.789 +/*
1.790 +** Invalidate the SSL session associated with fd.
1.791 +*/
1.792 +SSL_IMPORT SECStatus SSL_InvalidateSession(PRFileDesc *fd);
1.793 +
1.794 +/*
1.795 +** Return a SECItem containing the SSL session ID associated with the fd.
1.796 +*/
1.797 +SSL_IMPORT SECItem *SSL_GetSessionID(PRFileDesc *fd);
1.798 +
1.799 +/*
1.800 +** Clear out the client's SSL session cache, not the server's session cache.
1.801 +*/
1.802 +SSL_IMPORT void SSL_ClearSessionCache(void);
1.803 +
1.804 +/*
1.805 +** Close the server's SSL session cache.
1.806 +*/
1.807 +SSL_IMPORT SECStatus SSL_ShutdownServerSessionIDCache(void);
1.808 +
1.809 +/*
1.810 +** Set peer information so we can correctly look up SSL session later.
1.811 +** You only have to do this if you're tunneling through a proxy.
1.812 +*/
1.813 +SSL_IMPORT SECStatus SSL_SetSockPeerID(PRFileDesc *fd, const char *peerID);
1.814 +
1.815 +/*
1.816 +** Reveal the security information for the peer.
1.817 +*/
1.818 +SSL_IMPORT CERTCertificate * SSL_RevealCert(PRFileDesc * socket);
1.819 +SSL_IMPORT void * SSL_RevealPinArg(PRFileDesc * socket);
1.820 +SSL_IMPORT char * SSL_RevealURL(PRFileDesc * socket);
1.821 +
1.822 +/* This callback may be passed to the SSL library via a call to
1.823 + * SSL_GetClientAuthDataHook() for each SSL client socket.
1.824 + * It will be invoked when SSL needs to know what certificate and private key
1.825 + * (if any) to use to respond to a request for client authentication.
1.826 + * If arg is non-NULL, it is a pointer to a NULL-terminated string containing
1.827 + * the nickname of the cert/key pair to use.
1.828 + * If arg is NULL, this function will search the cert and key databases for
1.829 + * a suitable match and send it if one is found.
1.830 + */
1.831 +SSL_IMPORT SECStatus
1.832 +NSS_GetClientAuthData(void * arg,
1.833 + PRFileDesc * socket,
1.834 + struct CERTDistNamesStr * caNames,
1.835 + struct CERTCertificateStr ** pRetCert,
1.836 + struct SECKEYPrivateKeyStr **pRetKey);
1.837 +
1.838 +/*
1.839 +** Configure DTLS-SRTP (RFC 5764) cipher suite preferences.
1.840 +** Input is a list of ciphers in descending preference order and a length
1.841 +** of the list. As a side effect, this causes the use_srtp extension to be
1.842 +** negotiated.
1.843 +**
1.844 +** Invalid or unimplemented cipher suites in |ciphers| are ignored. If at
1.845 +** least one cipher suite in |ciphers| is implemented, returns SECSuccess.
1.846 +** Otherwise returns SECFailure.
1.847 +*/
1.848 +SSL_IMPORT SECStatus SSL_SetSRTPCiphers(PRFileDesc *fd,
1.849 + const PRUint16 *ciphers,
1.850 + unsigned int numCiphers);
1.851 +
1.852 +/*
1.853 +** Get the selected DTLS-SRTP cipher suite (if any).
1.854 +** To be called after the handshake completes.
1.855 +** Returns SECFailure if not negotiated.
1.856 +*/
1.857 +SSL_IMPORT SECStatus SSL_GetSRTPCipher(PRFileDesc *fd,
1.858 + PRUint16 *cipher);
1.859 +
1.860 +/*
1.861 + * Look to see if any of the signers in the cert chain for "cert" are found
1.862 + * in the list of caNames.
1.863 + * Returns SECSuccess if so, SECFailure if not.
1.864 + * Used by NSS_GetClientAuthData. May be used by other callback functions.
1.865 + */
1.866 +SSL_IMPORT SECStatus NSS_CmpCertChainWCANames(CERTCertificate *cert,
1.867 + CERTDistNames *caNames);
1.868 +
1.869 +/*
1.870 + * Returns key exchange type of the keys in an SSL server certificate.
1.871 + */
1.872 +SSL_IMPORT SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
1.873 +
1.874 +/* Set cipher policies to a predefined Domestic (U.S.A.) policy.
1.875 + * This essentially allows all supported ciphers.
1.876 + */
1.877 +SSL_IMPORT SECStatus NSS_SetDomesticPolicy(void);
1.878 +
1.879 +/* Set cipher policies to a predefined Policy that is exportable from the USA
1.880 + * according to present U.S. policies as we understand them.
1.881 + * It is the same as NSS_SetDomesticPolicy now.
1.882 + */
1.883 +SSL_IMPORT SECStatus NSS_SetExportPolicy(void);
1.884 +
1.885 +/* Set cipher policies to a predefined Policy that is exportable from the USA
1.886 + * according to present U.S. policies as we understand them, and that the
1.887 + * nation of France will permit to be imported into their country.
1.888 + * It is the same as NSS_SetDomesticPolicy now.
1.889 + */
1.890 +SSL_IMPORT SECStatus NSS_SetFrancePolicy(void);
1.891 +
1.892 +SSL_IMPORT SSL3Statistics * SSL_GetStatistics(void);
1.893 +
1.894 +/* Report more information than SSL_SecurityStatus.
1.895 +** Caller supplies the info struct. Function fills it in.
1.896 +*/
1.897 +SSL_IMPORT SECStatus SSL_GetChannelInfo(PRFileDesc *fd, SSLChannelInfo *info,
1.898 + PRUintn len);
1.899 +SSL_IMPORT SECStatus SSL_GetCipherSuiteInfo(PRUint16 cipherSuite,
1.900 + SSLCipherSuiteInfo *info, PRUintn len);
1.901 +
1.902 +/* Returnes negotiated through SNI host info. */
1.903 +SSL_IMPORT SECItem *SSL_GetNegotiatedHostInfo(PRFileDesc *fd);
1.904 +
1.905 +/* Export keying material according to RFC 5705.
1.906 +** fd must correspond to a TLS 1.0 or higher socket and out must
1.907 +** already be allocated. If hasContext is false, it uses the no-context
1.908 +** construction from the RFC and ignores the context and contextLen
1.909 +** arguments.
1.910 +*/
1.911 +SSL_IMPORT SECStatus SSL_ExportKeyingMaterial(PRFileDesc *fd,
1.912 + const char *label,
1.913 + unsigned int labelLen,
1.914 + PRBool hasContext,
1.915 + const unsigned char *context,
1.916 + unsigned int contextLen,
1.917 + unsigned char *out,
1.918 + unsigned int outLen);
1.919 +
1.920 +/*
1.921 +** Return a new reference to the certificate that was most recently sent
1.922 +** to the peer on this SSL/TLS connection, or NULL if none has been sent.
1.923 +*/
1.924 +SSL_IMPORT CERTCertificate * SSL_LocalCertificate(PRFileDesc *fd);
1.925 +
1.926 +/* Test an SSL configuration to see if SSL_BYPASS_PKCS11 can be turned on.
1.927 +** Check the key exchange algorithm for each cipher in the list to see if
1.928 +** a master secret key can be extracted after being derived with the mechanism
1.929 +** required by the protocolmask argument. If the KEA will use keys from the
1.930 +** specified cert make sure the extract operation is attempted from the slot
1.931 +** where the private key resides.
1.932 +** If MS can be extracted for all ciphers, (*pcanbypass) is set to TRUE and
1.933 +** SECSuccess is returned. In all other cases but one (*pcanbypass) is
1.934 +** set to FALSE and SECFailure is returned.
1.935 +** In that last case Derive() has been called successfully but the MS is null,
1.936 +** CanBypass sets (*pcanbypass) to FALSE and returns SECSuccess indicating the
1.937 +** arguments were all valid but the slot cannot be bypassed.
1.938 +**
1.939 +** Note: A TRUE return code from CanBypass means "Your configuration will perform
1.940 +** NO WORSE with the bypass enabled than without"; it does NOT mean that every
1.941 +** cipher suite listed will work properly with the selected protocols.
1.942 +**
1.943 +** Caveat: If export cipher suites are included in the argument list Canbypass
1.944 +** will return FALSE.
1.945 +**/
1.946 +
1.947 +/* protocol mask bits */
1.948 +#define SSL_CBP_SSL3 0x0001 /* test SSL v3 mechanisms */
1.949 +#define SSL_CBP_TLS1_0 0x0002 /* test TLS v1.0 mechanisms */
1.950 +
1.951 +SSL_IMPORT SECStatus SSL_CanBypass(CERTCertificate *cert,
1.952 + SECKEYPrivateKey *privKey,
1.953 + PRUint32 protocolmask,
1.954 + PRUint16 *ciphers, int nciphers,
1.955 + PRBool *pcanbypass, void *pwArg);
1.956 +
1.957 +/*
1.958 +** Did the handshake with the peer negotiate the given extension?
1.959 +** Output parameter valid only if function returns SECSuccess
1.960 +*/
1.961 +SSL_IMPORT SECStatus SSL_HandshakeNegotiatedExtension(PRFileDesc * socket,
1.962 + SSLExtensionType extId,
1.963 + PRBool *yes);
1.964 +
1.965 +/*
1.966 +** How long should we wait before retransmitting the next flight of
1.967 +** the DTLS handshake? Returns SECFailure if not DTLS or not in a
1.968 +** handshake.
1.969 +*/
1.970 +SSL_IMPORT SECStatus DTLS_GetHandshakeTimeout(PRFileDesc *socket,
1.971 + PRIntervalTime *timeout);
1.972 +
1.973 +/*
1.974 + * Return a boolean that indicates whether the underlying library
1.975 + * will perform as the caller expects.
1.976 + *
1.977 + * The only argument is a string, which should be the version
1.978 + * identifier of the NSS library. That string will be compared
1.979 + * against a string that represents the actual build version of
1.980 + * the SSL library.
1.981 + */
1.982 +extern PRBool NSSSSL_VersionCheck(const char *importedVersion);
1.983 +
1.984 +/*
1.985 + * Returns a const string of the SSL library version.
1.986 + */
1.987 +extern const char *NSSSSL_GetVersion(void);
1.988 +
1.989 +/* Restart an SSL connection that was paused to do asynchronous certificate
1.990 + * chain validation (when the auth certificate hook or bad cert handler
1.991 + * returned SECWouldBlock).
1.992 + *
1.993 + * This function only works for non-blocking sockets; Do not use it for
1.994 + * blocking sockets. Currently, this function works only for the client role of
1.995 + * a connection; it does not work for the server role.
1.996 + *
1.997 + * The application must call SSL_AuthCertificateComplete with 0 as the value of
1.998 + * the error parameter after it has successfully validated the peer's
1.999 + * certificate, in order to continue the SSL handshake.
1.1000 + *
1.1001 + * The application may call SSL_AuthCertificateComplete with a non-zero value
1.1002 + * for error (e.g. SEC_ERROR_REVOKED_CERTIFICATE) when certificate validation
1.1003 + * fails, before it closes the connection. If the application does so, an
1.1004 + * alert corresponding to the error (e.g. certificate_revoked) will be sent to
1.1005 + * the peer. See the source code of the internal function
1.1006 + * ssl3_SendAlertForCertError for the current mapping of error to alert. This
1.1007 + * mapping may change in future versions of libssl.
1.1008 + *
1.1009 + * This function will not complete the entire handshake. The application must
1.1010 + * call SSL_ForceHandshake, PR_Recv, PR_Send, etc. after calling this function
1.1011 + * to force the handshake to complete.
1.1012 + *
1.1013 + * On the first handshake of a connection, libssl will wait for the peer's
1.1014 + * certificate to be authenticated before calling the handshake callback,
1.1015 + * sending a client certificate, sending any application data, or returning
1.1016 + * any application data to the application. On subsequent (renegotiation)
1.1017 + * handshakes, libssl will block the handshake unconditionally while the
1.1018 + * certificate is being validated.
1.1019 + *
1.1020 + * libssl may send and receive handshake messages while waiting for the
1.1021 + * application to call SSL_AuthCertificateComplete, and it may call other
1.1022 + * callbacks (e.g, the client auth data hook) before
1.1023 + * SSL_AuthCertificateComplete has been called.
1.1024 + *
1.1025 + * An application that uses this asynchronous mechanism will usually have lower
1.1026 + * handshake latency if it has to do public key operations on the certificate
1.1027 + * chain and/or CRL/OCSP/cert fetching during the authentication, especially if
1.1028 + * it does so in parallel on another thread. However, if the application can
1.1029 + * authenticate the peer's certificate quickly then it may be more efficient
1.1030 + * to use the synchronous mechanism (i.e. returning SECFailure/SECSuccess
1.1031 + * instead of SECWouldBlock from the authenticate certificate hook).
1.1032 + *
1.1033 + * Be careful about converting an application from synchronous cert validation
1.1034 + * to asynchronous certificate validation. A naive conversion is likely to
1.1035 + * result in deadlocks; e.g. the application will wait in PR_Poll for network
1.1036 + * I/O on the connection while all network I/O on the connection is blocked
1.1037 + * waiting for this function to be called.
1.1038 + *
1.1039 + * Returns SECFailure on failure, SECSuccess on success. Never returns
1.1040 + * SECWouldBlock. Note that SSL_AuthCertificateComplete will (usually) return
1.1041 + * SECSuccess; do not interpret the return value of SSL_AuthCertificateComplete
1.1042 + * as an indicator of whether it is OK to continue using the connection. For
1.1043 + * example, SSL_AuthCertificateComplete(fd, SEC_ERROR_REVOKED_CERTIFICATE) will
1.1044 + * return SECSuccess (normally), but that does not mean that the application
1.1045 + * should continue using the connection. If the application passes a non-zero
1.1046 + * value for second argument (error), or if SSL_AuthCertificateComplete returns
1.1047 + * anything other than SECSuccess, then the application should close the
1.1048 + * connection.
1.1049 + */
1.1050 +SSL_IMPORT SECStatus SSL_AuthCertificateComplete(PRFileDesc *fd,
1.1051 + PRErrorCode error);
1.1052 +SEC_END_PROTOS
1.1053 +
1.1054 +#endif /* __ssl_h_ */
