summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/ssl/sslexp.h
diff options
context:
space:
mode:
authorwolfbeast <mcwerewolf@gmail.com>2018-04-25 21:33:33 +0200
committerwolfbeast <mcwerewolf@gmail.com>2018-04-25 21:33:33 +0200
commitfba28f19754f62b5227650143d5441fc86d4c7d7 (patch)
tree26629d73f83543ff92a060fd7b310bb748b13173 /security/nss/lib/ssl/sslexp.h
parentb4154e043bfc0d2f301d88304efc896989d650bf (diff)
downloadUXP-fba28f19754f62b5227650143d5441fc86d4c7d7.tar
UXP-fba28f19754f62b5227650143d5441fc86d4c7d7.tar.gz
UXP-fba28f19754f62b5227650143d5441fc86d4c7d7.tar.lz
UXP-fba28f19754f62b5227650143d5441fc86d4c7d7.tar.xz
UXP-fba28f19754f62b5227650143d5441fc86d4c7d7.zip
Revert "Update NSS to 3.35-RTM"
This reverts commit f1a0f0a56fdd0fc39f255174ce08c06b91c66c94.
Diffstat (limited to 'security/nss/lib/ssl/sslexp.h')
-rw-r--r--security/nss/lib/ssl/sslexp.h358
1 files changed, 0 insertions, 358 deletions
diff --git a/security/nss/lib/ssl/sslexp.h b/security/nss/lib/ssl/sslexp.h
deleted file mode 100644
index 569add861..000000000
--- a/security/nss/lib/ssl/sslexp.h
+++ /dev/null
@@ -1,358 +0,0 @@
-/*
- * This file contains prototypes for experimental SSL functions.
- *
- * This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-#ifndef __sslexp_h_
-#define __sslexp_h_
-
-#include "ssl.h"
-#include "sslerr.h"
-
-SEC_BEGIN_PROTOS
-
-/* The functions in this header file are not guaranteed to remain available in
- * future NSS versions. Code that uses these functions needs to safeguard
- * against the function not being available. */
-
-#define SSL_EXPERIMENTAL_API(name, arglist, args) \
- (SSL_GetExperimentalAPI(name) \
- ? ((SECStatus(*) arglist)SSL_GetExperimentalAPI(name))args \
- : SECFailure)
-#define SSL_DEPRECATED_EXPERIMENTAL_API \
- (PR_SetError(SSL_ERROR_UNSUPPORTED_EXPERIMENTAL_API, 0), SECFailure)
-
-/*
- * SSL_GetExtensionSupport() returns whether NSS supports a particular TLS
- * extension.
- *
- * - ssl_ext_none indicates that NSS does not support the extension and
- * extension hooks can be installed.
- *
- * - ssl_ext_native indicates that NSS supports the extension natively, but
- * allows an application to override that support and install its own
- * extension hooks.
- *
- * - ssl_ext_native_only indicates that NSS supports the extension natively
- * and does not permit custom extension hooks to be installed. These
- * extensions are critical to the functioning of NSS.
- */
-typedef enum {
- ssl_ext_none,
- ssl_ext_native,
- ssl_ext_native_only
-} SSLExtensionSupport;
-
-#define SSL_GetExtensionSupport(extension, support) \
- SSL_EXPERIMENTAL_API("SSL_GetExtensionSupport", \
- (PRUint16 _extension, \
- SSLExtensionSupport * _support), \
- (extension, support))
-
-/*
- * Custom extension hooks.
- *
- * The SSL_InstallExtensionHooks() registers two callback functions for use
- * with the identified extension type.
- *
- * Installing extension hooks disables the checks in TLS 1.3 that ensure that
- * extensions are only added to the correct messages. The application is
- * responsible for ensuring that extensions are only sent with the right message
- * or messages.
- *
- * Installing an extension handler does not disable checks for whether an
- * extension can be used in a message that is a response to an extension in
- * another message. Extensions in ServerHello, EncryptedExtensions and the
- * server Certificate messages are rejected unless the client sends an extension
- * in the ClientHello. Similarly, a client Certificate message cannot contain
- * extensions that don't appear in a CertificateRequest (in TLS 1.3).
- *
- * Setting both |writer| and |handler| to NULL removes any existing hooks for
- * that extension.
- *
- * == SSLExtensionWriter
- *
- * An SSLExtensionWriter function is responsible for constructing the contents
- * of an extension. This function is called during the construction of all
- * handshake messages where an extension might be included.
- *
- * - The |fd| argument is the socket file descriptor.
- *
- * - The |message| argument is the TLS handshake message type. The writer will
- * be called for every handshake message that NSS sends. Most extensions
- * should only be sent in a subset of messages. NSS doesn’t check that
- * extension writers don’t violate protocol rules regarding which message an
- * extension can be sent in.
- *
- * - The |data| argument is a pointer to a buffer that should be written to with
- * any data for the extension.
- *
- * - The |len| argument is an outparam indicating how many bytes were written to
- * |data|. The value referenced by |len| is initialized to zero, so an
- * extension that is empty does not need to write to this value.
- *
- * - The |maxLen| indicates the maximum number of bytes that can be written to
- * |data|.
- *
- * - The |arg| argument is the value of the writerArg that was passed during
- * installation.
- *
- * An SSLExtensionWriter function returns PR_TRUE if an extension should be
- * written, and PR_FALSE otherwise.
- *
- * If there is an error, return PR_FALSE; if the error is truly fatal, the
- * application can mark the connection as failed. However, recursively calling
- * functions that alter the file descriptor in the callback - such as PR_Close()
- * - should be avoided.
- *
- * Note: The ClientHello message can be sent twice in TLS 1.3. An
- * SSLExtensionWriter will be called twice with the same arguments in that case;
- * NSS does not distinguish between a first and second ClientHello. It is up to
- * the application to track this if it needs to act differently each time. In
- * most cases the correct behaviour is to provide an identical extension on each
- * invocation.
- *
- * == SSLExtensionHandler
- *
- * An SSLExtensionHandler function consumes a handshake message. This function
- * is called when an extension is present.
- *
- * - The |fd| argument is the socket file descriptor.
- *
- * - The |message| argument is the TLS handshake message type. This can be used
- * to validate that the extension was included in the correct handshake
- * message.
- *
- * - The |data| argument points to the contents of the extension.
- *
- * - The |len| argument contains the length of the extension.
- *
- * - The |alert| argument is an outparam that allows an application to choose
- * which alert is sent in the case of a fatal error.
- *
- * - The |arg| argument is the value of the handlerArg that was passed during
- * installation.
- *
- * An SSLExtensionHandler function returns SECSuccess when the extension is
- * process successfully. It can return SECFailure to cause the handshake to
- * fail. If the value of alert is written to, NSS will generate a fatal alert
- * using the provided alert code. The value of |alert| is otherwise not used.
- */
-typedef PRBool(PR_CALLBACK *SSLExtensionWriter)(
- PRFileDesc *fd, SSLHandshakeType message,
- PRUint8 *data, unsigned int *len, unsigned int maxLen, void *arg);
-
-typedef SECStatus(PR_CALLBACK *SSLExtensionHandler)(
- PRFileDesc *fd, SSLHandshakeType message,
- const PRUint8 *data, unsigned int len,
- SSLAlertDescription *alert, void *arg);
-
-#define SSL_InstallExtensionHooks(fd, extension, writer, writerArg, \
- handler, handlerArg) \
- SSL_EXPERIMENTAL_API("SSL_InstallExtensionHooks", \
- (PRFileDesc * _fd, PRUint16 _extension, \
- SSLExtensionWriter _writer, void *_writerArg, \
- SSLExtensionHandler _handler, void *_handlerArg), \
- (fd, extension, writer, writerArg, \
- handler, handlerArg))
-
-/*
- * Setup the anti-replay buffer for supporting 0-RTT in TLS 1.3 on servers.
- *
- * To use 0-RTT on a server, you must call this function. Failing to call this
- * function will result in all 0-RTT being rejected. Connections will complete,
- * but early data will be rejected.
- *
- * NSS uses a Bloom filter to track the ClientHello messages that it receives
- * (specifically, it uses the PSK binder). This function initializes a pair of
- * Bloom filters. The two filters are alternated over time, with new
- * ClientHello messages recorded in the current filter and, if they are not
- * already present, being checked against the previous filter. If the
- * ClientHello is found, then early data is rejected, but the handshake is
- * allowed to proceed.
- *
- * The false-positive probability of Bloom filters means that some valid
- * handshakes will be marked as potential replays. Early data will be rejected
- * for a false positive. To minimize this and to allow a trade-off of space
- * against accuracy, the size of the Bloom filter can be set by this function.
- *
- * The first tuning parameter to consider is |window|, which determines the
- * window over which ClientHello messages will be tracked. This also causes
- * early data to be rejected if a ClientHello contains a ticket age parameter
- * that is outside of this window (see Section 4.2.10.4 of
- * draft-ietf-tls-tls13-20 for details). Set |window| to account for any
- * potential sources of clock error. |window| is the entire width of the
- * window, which is symmetrical. Therefore to allow 5 seconds of clock error in
- * both directions, set the value to 10 seconds (i.e., 10 * PR_USEC_PER_SEC).
- *
- * After calling this function, early data will be rejected until |window|
- * elapses. This prevents replay across crashes and restarts. Only call this
- * function once to avoid inadvertently disabling 0-RTT (use PR_CallOnce() to
- * avoid this problem).
- *
- * The primary tuning parameter is |bits| which determines the amount of memory
- * allocated to each Bloom filter. NSS will allocate two Bloom filters, each
- * |2^(bits - 3)| octets in size. The value of |bits| is primarily driven by
- * the number of connections that are expected in any time window. Note that
- * this needs to account for there being two filters both of which have
- * (presumably) independent false positive rates. The following formulae can be
- * used to find a value of |bits| and |k| given a chosen false positive
- * probability |p| and the number of requests expected in a given window |n|:
- *
- * bits = log2(n) + log2(-ln(1 - sqrt(1 - p))) + 1.0575327458897952
- * k = -log2(p)
- *
- * ... where log2 and ln are base 2 and e logarithms respectively. For a target
- * false positive rate of 1% and 1000 handshake attempts, this produces bits=14
- * and k=7. This results in two Bloom filters that are 2kB each in size. Note
- * that rounding |k| and |bits| up causes the false positive probability for
- * these values to be a much lower 0.123%.
- *
- * IMPORTANT: This anti-replay scheme has several weaknesses. See the TLS 1.3
- * specification for the details of the generic problems with this technique.
- *
- * In addition to the generic anti-replay weaknesses, the state that the server
- * maintains is in local memory only. Servers that operate in a cluster, even
- * those that use shared memory for tickets, will not share anti-replay state.
- * Early data can be replayed at least once with every server instance that will
- * accept tickets that are encrypted with the same key.
- */
-#define SSL_SetupAntiReplay(window, k, bits) \
- SSL_EXPERIMENTAL_API("SSL_SetupAntiReplay", \
- (PRTime _window, unsigned int _k, unsigned int _bits), \
- (window, k, bits))
-
-/*
- * This function allows a server application to generate a session ticket that
- * will embed the provided token.
- *
- * This function will cause a NewSessionTicket message to be sent by a server.
- * This happens even if SSL_ENABLE_SESSION_TICKETS is disabled. This allows a
- * server to suppress the usually automatic generation of a session ticket at
- * the completion of the handshake - which do not include any token - and to
- * control when session tickets are transmitted.
- *
- * This function will fail unless the socket has an active TLS 1.3 session.
- * Earlier versions of TLS do not support the spontaneous sending of the
- * NewSessionTicket message.
- */
-#define SSL_SendSessionTicket(fd, appToken, appTokenLen) \
- SSL_EXPERIMENTAL_API("SSL_SendSessionTicket", \
- (PRFileDesc * _fd, const PRUint8 *_appToken, \
- unsigned int _appTokenLen), \
- (fd, appToken, appTokenLen))
-
-/*
- * A stateless retry handler gives an application some control over NSS handling
- * of ClientHello messages.
- *
- * SSL_HelloRetryRequestCallback() installs a callback that allows an
- * application to control how NSS sends HelloRetryRequest messages. This
- * handler is only used on servers and will only be called if the server selects
- * TLS 1.3. Support for older TLS versions could be added in other releases.
- *
- * The SSLHelloRetryRequestCallback is invoked during the processing of a
- * TLS 1.3 ClientHello message. It takes the following arguments:
- *
- * - |firstHello| indicates if the NSS believes that this is an initial
- * ClientHello. An initial ClientHello will never include a cookie extension,
- * though it may contain a session ticket.
- *
- * - |clientToken| includes a token previously provided by the application. If
- * |clientTokenLen| is 0, then |clientToken| may be NULL.
- *
- * - If |firstHello| is PR_FALSE, the value that was provided in the
- * |retryToken| outparam of previous invocations of this callback will be
- * present here.
- *
- * - If |firstHello| is PR_TRUE, and the handshake is resuming a session, then
- * this will contain any value that was passed in the |token| parameter of
- * SSL_SendNewSessionTicket() method (see below). If this is not resuming a
- * session, then the token will be empty (and this value could be NULL).
- *
- * - |clientTokenLen| is the length of |clientToken|.
- *
- * - |retryToken| is an item that callback can write to. This provides NSS with
- * a token. This token is encrypted and integrity protected and embedded in
- * the cookie extension of a HelloRetryRequest. The value of this field is
- * only used if the handler returns ssl_stateless_retry_check. NSS allocates
- * space for this value.
- *
- * - |retryTokenLen| is an outparam for the length of the token. If this value
- * is not set, or set to 0, an empty token will be sent.
- *
- * - |retryTokenMax| is the size of the space allocated for retryToken. An
- * application cannot write more than this many bytes to retryToken.
- *
- * - |arg| is the same value that was passed to
- * SSL_InstallStatelessRetryHandler().
- *
- * The handler can validate any the value of |clientToken|, query the socket
- * status (using SSL_GetPreliminaryChannelInfo() for example) and decide how to
- * proceed:
- *
- * - Returning ssl_hello_retry_fail causes the handshake to fail. This might be
- * used if the token is invalid or the application wishes to abort the
- * handshake.
- *
- * - Returning ssl_hello_retry_accept causes the handshake to proceed.
- *
- * - Returning ssl_hello_retry_request causes NSS to send a HelloRetryRequest
- * message and request a second ClientHello. NSS generates a cookie extension
- * and embeds the value of |retryToken|. The value of |retryToken| value may
- * be left empty if the application does not require any additional context to
- * validate a second ClientHello attempt. This return code cannot be used to
- * reject a second ClientHello (i.e., when firstHello is PR_FALSE); NSS will
- * abort the handshake if this value is returned from a second call.
- *
- * An application that chooses to perform a stateless retry can discard the
- * server socket. All necessary state to continue the TLS handshake will be
- * included in the cookie extension. This makes it possible to use a new socket
- * to handle the remainder of the handshake. The existing socket can be safely
- * discarded.
- *
- * If the same socket is retained, the information in the cookie will be checked
- * for consistency against the existing state of the socket. Any discrepancy
- * will result in the connection being closed.
- *
- * Tokens should be kept as small as possible. NSS sets a limit on the size of
- * tokens, which it passes in |retryTokenMax|. Depending on circumstances,
- * observing a smaller limit might be desirable or even necessary. For
- * instance, having HelloRetryRequest and ClientHello fit in a single packet has
- * significant performance benefits.
- */
-typedef enum {
- ssl_hello_retry_fail,
- ssl_hello_retry_accept,
- ssl_hello_retry_request
-} SSLHelloRetryRequestAction;
-
-typedef SSLHelloRetryRequestAction(PR_CALLBACK *SSLHelloRetryRequestCallback)(
- PRBool firstHello, const PRUint8 *clientToken, unsigned int clientTokenLen,
- PRUint8 *retryToken, unsigned int *retryTokenLen, unsigned int retryTokMax,
- void *arg);
-
-#define SSL_HelloRetryRequestCallback(fd, cb, arg) \
- SSL_EXPERIMENTAL_API("SSL_HelloRetryRequestCallback", \
- (PRFileDesc * _fd, \
- SSLHelloRetryRequestCallback _cb, void *_arg), \
- (fd, cb, arg))
-
-/* Update traffic keys (TLS 1.3 only).
- *
- * The |requestUpdate| flag determines whether to request an update from the
- * remote peer.
- */
-#define SSL_KeyUpdate(fd, requestUpdate) \
- SSL_EXPERIMENTAL_API("SSL_KeyUpdate", \
- (PRFileDesc * _fd, PRBool _requestUpdate), \
- (fd, requestUpdate))
-
-#define SSL_UseAltServerHelloType(fd, enable) \
- SSL_DEPRECATED_EXPERIMENTAL_API
-
-SEC_END_PROTOS
-
-#endif /* __sslexp_h_ */