1 /* 2 * This file contains prototypes for experimental SSL functions. 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 7 8 #ifndef __sslexp_h_ 9 #define __sslexp_h_ 10 11 #include "ssl.h" 12 #include "sslerr.h" 13 #include "pk11hpke.h" 14 15 SEC_BEGIN_PROTOS 16 17 /* The functions in this header file are not guaranteed to remain available in 18 * future NSS versions. Code that uses these functions needs to safeguard 19 * against the function not being available. */ 20 21 #define SSL_EXPERIMENTAL_API(name, arglist, args) \ 22 (SSL_GetExperimentalAPI(name) \ 23 ? ((SECStatus(*) arglist)SSL_GetExperimentalAPI(name))args \ 24 : SECFailure) 25 #define SSL_DEPRECATED_EXPERIMENTAL_API \ 26 (PR_SetError(SSL_ERROR_UNSUPPORTED_EXPERIMENTAL_API, 0), SECFailure) 27 28 /* 29 * SSL_GetExtensionSupport() returns whether NSS supports a particular TLS 30 * extension. 31 * 32 * - ssl_ext_none indicates that NSS does not support the extension and 33 * extension hooks can be installed. 34 * 35 * - ssl_ext_native indicates that NSS supports the extension natively, but 36 * allows an application to override that support and install its own 37 * extension hooks. 38 * 39 * - ssl_ext_native_only indicates that NSS supports the extension natively 40 * and does not permit custom extension hooks to be installed. These 41 * extensions are critical to the functioning of NSS. 42 */ 43 typedef enum { 44 ssl_ext_none, 45 ssl_ext_native, 46 ssl_ext_native_only 47 } SSLExtensionSupport; 48 49 #define SSL_GetExtensionSupport(extension, support) \ 50 SSL_EXPERIMENTAL_API("SSL_GetExtensionSupport", \ 51 (PRUint16 _extension, \ 52 SSLExtensionSupport * _support), \ 53 (extension, support)) 54 55 /* 56 * Custom extension hooks. 57 * 58 * The SSL_InstallExtensionHooks() registers two callback functions for use 59 * with the identified extension type. 60 * 61 * Installing extension hooks disables the checks in TLS 1.3 that ensure that 62 * extensions are only added to the correct messages. The application is 63 * responsible for ensuring that extensions are only sent with the right message 64 * or messages. 65 * 66 * Installing an extension handler does not disable checks for whether an 67 * extension can be used in a message that is a response to an extension in 68 * another message. Extensions in ServerHello, EncryptedExtensions and the 69 * server Certificate messages are rejected unless the client sends an extension 70 * in the ClientHello. Similarly, a client Certificate message cannot contain 71 * extensions that don't appear in a CertificateRequest (in TLS 1.3). 72 * 73 * Setting both |writer| and |handler| to NULL removes any existing hooks for 74 * that extension. 75 * 76 * == SSLExtensionWriter 77 * 78 * An SSLExtensionWriter function is responsible for constructing the contents 79 * of an extension. This function is called during the construction of all 80 * handshake messages where an extension might be included. 81 * 82 * - The |fd| argument is the socket file descriptor. 83 * 84 * - The |message| argument is the TLS handshake message type. The writer will 85 * be called for every handshake message that NSS sends. Most extensions 86 * should only be sent in a subset of messages. NSS doesn’t check that 87 * extension writers don’t violate protocol rules regarding which message an 88 * extension can be sent in. 89 * 90 * - The |data| argument is a pointer to a buffer that should be written to with 91 * any data for the extension. 92 * 93 * - The |len| argument is an outparam indicating how many bytes were written to 94 * |data|. The value referenced by |len| is initialized to zero, so an 95 * extension that is empty does not need to write to this value. 96 * 97 * - The |maxLen| indicates the maximum number of bytes that can be written to 98 * |data|. 99 * 100 * - The |arg| argument is the value of the writerArg that was passed during 101 * installation. 102 * 103 * An SSLExtensionWriter function returns PR_TRUE if an extension should be 104 * written, and PR_FALSE otherwise. 105 * 106 * If there is an error, return PR_FALSE; if the error is truly fatal, the 107 * application can mark the connection as failed. However, recursively calling 108 * functions that alter the file descriptor in the callback - such as PR_Close() 109 * - should be avoided. 110 * 111 * Note: The ClientHello message can be sent twice in TLS 1.3. An 112 * SSLExtensionWriter will be called twice with the same arguments in that case; 113 * NSS does not distinguish between a first and second ClientHello. It is up to 114 * the application to track this if it needs to act differently each time. In 115 * most cases the correct behaviour is to provide an identical extension on each 116 * invocation. 117 * 118 * == SSLExtensionHandler 119 * 120 * An SSLExtensionHandler function consumes a handshake message. This function 121 * is called when an extension is present. 122 * 123 * - The |fd| argument is the socket file descriptor. 124 * 125 * - The |message| argument is the TLS handshake message type. This can be used 126 * to validate that the extension was included in the correct handshake 127 * message. 128 * 129 * - The |data| argument points to the contents of the extension. 130 * 131 * - The |len| argument contains the length of the extension. 132 * 133 * - The |alert| argument is an outparam that allows an application to choose 134 * which alert is sent in the case of a fatal error. 135 * 136 * - The |arg| argument is the value of the handlerArg that was passed during 137 * installation. 138 * 139 * An SSLExtensionHandler function returns SECSuccess when the extension is 140 * process successfully. It can return SECFailure to cause the handshake to 141 * fail. If the value of alert is written to, NSS will generate a fatal alert 142 * using the provided alert code. The value of |alert| is otherwise not used. 143 */ 144 typedef PRBool(PR_CALLBACK *SSLExtensionWriter)( 145 PRFileDesc *fd, SSLHandshakeType message, 146 PRUint8 *data, unsigned int *len, unsigned int maxLen, void *arg); 147 148 typedef SECStatus(PR_CALLBACK *SSLExtensionHandler)( 149 PRFileDesc *fd, SSLHandshakeType message, 150 const PRUint8 *data, unsigned int len, 151 SSLAlertDescription *alert, void *arg); 152 153 #define SSL_InstallExtensionHooks(fd, extension, writer, writerArg, \ 154 handler, handlerArg) \ 155 SSL_EXPERIMENTAL_API("SSL_InstallExtensionHooks", \ 156 (PRFileDesc * _fd, PRUint16 _extension, \ 157 SSLExtensionWriter _writer, void *_writerArg, \ 158 SSLExtensionHandler _handler, void *_handlerArg), \ 159 (fd, extension, writer, writerArg, \ 160 handler, handlerArg)) 161 162 /* 163 * Create an anti-replay context for supporting 0-RTT in TLS 1.3 on servers. 164 * 165 * To use 0-RTT on a server, you must create an anti-replay context using 166 * SSL_CreateAntiReplayContext and set that on the socket with 167 * SSL_SetAntiReplayContext. Failing to set a context on the server will result 168 * in all 0-RTT being rejected. Connections will complete, but early data will 169 * be rejected. 170 * 171 * Anti-replay contexts are reference counted and are released with 172 * SSL_ReleaseAntiReplayContext. 173 * 174 * NSS uses a Bloom filter to track the ClientHello messages that it receives 175 * (specifically, it uses the PSK binder). This function initializes a pair of 176 * Bloom filters. The two filters are alternated over time, with new 177 * ClientHello messages recorded in the current filter and, if they are not 178 * already present, being checked against the previous filter. If the 179 * ClientHello is found, then early data is rejected, but the handshake is 180 * allowed to proceed. 181 * 182 * The false-positive probability of Bloom filters means that some valid 183 * handshakes will be marked as potential replays. Early data will be rejected 184 * for a false positive. To minimize this and to allow a trade-off of space 185 * against accuracy, the size of the Bloom filter can be set by this function. 186 * 187 * The first tuning parameter to consider is |window|, which determines the 188 * window over which ClientHello messages will be tracked. This also causes 189 * early data to be rejected if a ClientHello contains a ticket age parameter 190 * that is outside of this window (see Section 8.3 of RFC 8446 for details). 191 * Set |window| to account for any potential sources of clock error. |window| 192 * is the entire width of the window, which is symmetrical. Therefore to allow 193 * 5 seconds of clock error in both directions, set the value to 10 seconds 194 * (i.e., 10 * PR_USEC_PER_SEC). 195 * 196 * After calling this function, early data will be rejected until |window| 197 * elapses. This prevents replay across crashes and restarts. Only call this 198 * function once to avoid inadvertently disabling 0-RTT (use PR_CallOnce() to 199 * avoid this problem). 200 * 201 * The primary tuning parameter is |bits| which determines the amount of memory 202 * allocated to each Bloom filter. NSS will allocate two Bloom filters, each 203 * |2^(bits - 3)| octets in size. The value of |bits| is primarily driven by 204 * the number of connections that are expected in any time window. Note that 205 * this needs to account for there being two filters both of which have 206 * (presumably) independent false positive rates. The following formulae can be 207 * used to find a value of |bits| and |k| given a chosen false positive 208 * probability |p| and the number of requests expected in a given window |n|: 209 * 210 * bits = log2(n) + log2(-ln(1 - sqrt(1 - p))) + 1.0575327458897952 211 * k = -log2(p) 212 * 213 * ... where log2 and ln are base 2 and e logarithms respectively. For a target 214 * false positive rate of 1% and 1000 handshake attempts, this produces bits=14 215 * and k=7. This results in two Bloom filters that are 2kB each in size. Note 216 * that rounding |k| and |bits| up causes the false positive probability for 217 * these values to be a much lower 0.123%. 218 * 219 * IMPORTANT: This anti-replay scheme has several weaknesses. See the TLS 1.3 220 * specification for the details of the generic problems with this technique. 221 * 222 * In addition to the generic anti-replay weaknesses, the state that the server 223 * maintains is in local memory only. Servers that operate in a cluster, even 224 * those that use shared memory for tickets, will not share anti-replay state. 225 * Early data can be replayed at least once with every server instance that will 226 * accept tickets that are encrypted with the same key. 227 */ 228 typedef struct SSLAntiReplayContextStr SSLAntiReplayContext; 229 #define SSL_CreateAntiReplayContext(now, window, k, bits, ctx) \ 230 SSL_EXPERIMENTAL_API("SSL_CreateAntiReplayContext", \ 231 (PRTime _now, PRTime _window, \ 232 unsigned int _k, unsigned int _bits, \ 233 SSLAntiReplayContext **_ctx), \ 234 (now, window, k, bits, ctx)) 235 236 #define SSL_SetAntiReplayContext(fd, ctx) \ 237 SSL_EXPERIMENTAL_API("SSL_SetAntiReplayContext", \ 238 (PRFileDesc * _fd, SSLAntiReplayContext * _ctx), \ 239 (fd, ctx)) 240 241 #define SSL_ReleaseAntiReplayContext(ctx) \ 242 SSL_EXPERIMENTAL_API("SSL_ReleaseAntiReplayContext", \ 243 (SSLAntiReplayContext * _ctx), \ 244 (ctx)) 245 246 /* 247 * This function allows a server application to generate a session ticket that 248 * will embed the provided token. 249 * 250 * This function will cause a NewSessionTicket message to be sent by a server. 251 * This happens even if SSL_ENABLE_SESSION_TICKETS is disabled. This allows a 252 * server to suppress the usually automatic generation of a session ticket at 253 * the completion of the handshake - which do not include any token - and to 254 * control when session tickets are transmitted. 255 * 256 * This function will fail unless the socket has an active TLS 1.3 session. 257 * Earlier versions of TLS do not support the spontaneous sending of the 258 * NewSessionTicket message. It will also fail when external PSK 259 * authentication has been negotiated. 260 */ 261 #define SSL_SendSessionTicket(fd, appToken, appTokenLen) \ 262 SSL_EXPERIMENTAL_API("SSL_SendSessionTicket", \ 263 (PRFileDesc * _fd, const PRUint8 *_appToken, \ 264 unsigned int _appTokenLen), \ 265 (fd, appToken, appTokenLen)) 266 267 /* 268 * A stateless retry handler gives an application some control over NSS handling 269 * of ClientHello messages. 270 * 271 * SSL_HelloRetryRequestCallback() installs a callback that allows an 272 * application to control how NSS sends HelloRetryRequest messages. This 273 * handler is only used on servers and will only be called if the server selects 274 * TLS 1.3. Support for older TLS versions could be added in other releases. 275 * 276 * The SSLHelloRetryRequestCallback is invoked during the processing of a 277 * TLS 1.3 ClientHello message. It takes the following arguments: 278 * 279 * - |firstHello| indicates if the NSS believes that this is an initial 280 * ClientHello. An initial ClientHello will never include a cookie extension, 281 * though it may contain a session ticket. 282 * 283 * - |clientToken| includes a token previously provided by the application. If 284 * |clientTokenLen| is 0, then |clientToken| may be NULL. 285 * 286 * - If |firstHello| is PR_FALSE, the value that was provided in the 287 * |retryToken| outparam of previous invocations of this callback will be 288 * present here. 289 * 290 * - If |firstHello| is PR_TRUE, and the handshake is resuming a session, then 291 * this will contain any value that was passed in the |token| parameter of 292 * SSL_SendNewSessionTicket() method (see below). If this is not resuming a 293 * session, then the token will be empty (and this value could be NULL). 294 * 295 * - |clientTokenLen| is the length of |clientToken|. 296 * 297 * - |retryToken| is an item that callback can write to. This provides NSS with 298 * a token. This token is encrypted and integrity protected and embedded in 299 * the cookie extension of a HelloRetryRequest. The value of this field is 300 * only used if the handler returns ssl_stateless_retry_check. NSS allocates 301 * space for this value. 302 * 303 * - |retryTokenLen| is an outparam for the length of the token. If this value 304 * is not set, or set to 0, an empty token will be sent. 305 * 306 * - |retryTokenMax| is the size of the space allocated for retryToken. An 307 * application cannot write more than this many bytes to retryToken. 308 * 309 * - |arg| is the same value that was passed to 310 * SSL_InstallStatelessRetryHandler(). 311 * 312 * The handler can validate any the value of |clientToken|, query the socket 313 * status (using SSL_GetPreliminaryChannelInfo() for example) and decide how to 314 * proceed: 315 * 316 * - Returning ssl_hello_retry_fail causes the handshake to fail. This might be 317 * used if the token is invalid or the application wishes to abort the 318 * handshake. 319 * 320 * - Returning ssl_hello_retry_accept causes the handshake to proceed. 321 * 322 * - Returning ssl_hello_retry_request causes NSS to send a HelloRetryRequest 323 * message and request a second ClientHello. NSS generates a cookie extension 324 * and embeds the value of |retryToken|. The value of |retryToken| value may 325 * be left empty if the application does not require any additional context to 326 * validate a second ClientHello attempt. This return code cannot be used to 327 * reject a second ClientHello (i.e., when firstHello is PR_FALSE); NSS will 328 * abort the handshake if this value is returned from a second call. 329 * 330 * - Returning ssl_hello_retry_reject_0rtt causes NSS to proceed normally, but 331 * to reject 0-RTT. Use this if there is something in the token that 332 * indicates that 0-RTT might be unsafe. 333 * 334 * An application that chooses to perform a stateless retry can discard the 335 * server socket. All necessary state to continue the TLS handshake will be 336 * included in the cookie extension. This makes it possible to use a new socket 337 * to handle the remainder of the handshake. The existing socket can be safely 338 * discarded. 339 * 340 * If the same socket is retained, the information in the cookie will be checked 341 * for consistency against the existing state of the socket. Any discrepancy 342 * will result in the connection being closed. 343 * 344 * Tokens should be kept as small as possible. NSS sets a limit on the size of 345 * tokens, which it passes in |retryTokenMax|. Depending on circumstances, 346 * observing a smaller limit might be desirable or even necessary. For 347 * instance, having HelloRetryRequest and ClientHello fit in a single packet has 348 * significant performance benefits. 349 */ 350 typedef enum { 351 ssl_hello_retry_fail, 352 ssl_hello_retry_accept, 353 ssl_hello_retry_request, 354 ssl_hello_retry_reject_0rtt 355 } SSLHelloRetryRequestAction; 356 357 typedef SSLHelloRetryRequestAction(PR_CALLBACK *SSLHelloRetryRequestCallback)( 358 PRBool firstHello, const PRUint8 *clientToken, unsigned int clientTokenLen, 359 PRUint8 *retryToken, unsigned int *retryTokenLen, unsigned int retryTokMax, 360 void *arg); 361 362 #define SSL_HelloRetryRequestCallback(fd, cb, arg) \ 363 SSL_EXPERIMENTAL_API("SSL_HelloRetryRequestCallback", \ 364 (PRFileDesc * _fd, \ 365 SSLHelloRetryRequestCallback _cb, void *_arg), \ 366 (fd, cb, arg)) 367 368 /* Update traffic keys (TLS 1.3 only). 369 * 370 * The |requestUpdate| flag determines whether to request an update from the 371 * remote peer. 372 */ 373 #define SSL_KeyUpdate(fd, requestUpdate) \ 374 SSL_EXPERIMENTAL_API("SSL_KeyUpdate", \ 375 (PRFileDesc * _fd, PRBool _requestUpdate), \ 376 (fd, requestUpdate)) 377 378 /* This function allows a server application to trigger 379 * re-authentication (TLS 1.3 only) after handshake. 380 * 381 * This function will cause a CertificateRequest message to be sent by 382 * a server. This can be called once at a time, and is not allowed 383 * until an answer is received. 384 * 385 * This function is not allowed for use with DTLS or when external 386 * PSK authentication has been negotiated. SECFailure is returned 387 * in both cases. 388 * 389 * The AuthCertificateCallback is called when the answer is received. 390 * If the answer is accepted by the server, the value returned by 391 * SSL_PeerCertificate() is replaced. If you need to remember all the 392 * certificates, you will need to call SSL_PeerCertificate() and save 393 * what you get before calling this. 394 * 395 * If the AuthCertificateCallback returns SECFailure, the connection 396 * is aborted. 397 */ 398 #define SSL_SendCertificateRequest(fd) \ 399 SSL_EXPERIMENTAL_API("SSL_SendCertificateRequest", \ 400 (PRFileDesc * _fd), \ 401 (fd)) 402 403 /* 404 * Session cache API. 405 */ 406 407 /* 408 * Information that can be retrieved about a resumption token. 409 * See SSL_GetResumptionTokenInfo for details about how to use this API. 410 * Note that peerCert points to a certificate in the NSS database and must be 411 * copied by the application if it should be used after NSS shutdown or after 412 * calling SSL_DestroyResumptionTokenInfo. 413 */ 414 typedef struct SSLResumptionTokenInfoStr { 415 PRUint16 length; 416 CERTCertificate *peerCert; 417 PRUint8 *alpnSelection; 418 PRUint32 alpnSelectionLen; 419 PRUint32 maxEarlyDataSize; 420 PRTime expirationTime; /* added in NSS 3.41 */ 421 } SSLResumptionTokenInfo; 422 423 /* 424 * Allows applications to retrieve information about a resumption token. 425 * This does not require a TLS session. 426 * 427 * - The |tokenData| argument is a pointer to the resumption token as byte array 428 * of length |tokenLen|. 429 * - The |token| argument is a pointer to a SSLResumptionTokenInfo struct of 430 * of |len|. The struct gets filled by this function. 431 * See SSL_DestroyResumptionTokenInfo for information about how to manage the 432 * |token| memory. 433 */ 434 #define SSL_GetResumptionTokenInfo(tokenData, tokenLen, token, len) \ 435 SSL_EXPERIMENTAL_API("SSL_GetResumptionTokenInfo", \ 436 (const PRUint8 *_tokenData, unsigned int _tokenLen, \ 437 SSLResumptionTokenInfo *_token, PRUintn _len), \ 438 (tokenData, tokenLen, token, len)) 439 440 /* 441 * SSL_GetResumptionTokenInfo allocates memory in order to populate |tokenInfo|. 442 * Any SSLResumptionTokenInfo struct filled with SSL_GetResumptionTokenInfo 443 * has to be freed with SSL_DestroyResumptionTokenInfo. 444 */ 445 #define SSL_DestroyResumptionTokenInfo(tokenInfo) \ 446 SSL_EXPERIMENTAL_API( \ 447 "SSL_DestroyResumptionTokenInfo", \ 448 (SSLResumptionTokenInfo * _tokenInfo), \ 449 (tokenInfo)) 450 451 /* 452 * This is the function signature for function pointers used as resumption 453 * token callback. The caller has to copy the memory at |resumptionToken| with 454 * length |len| before returning. 455 * 456 * - The |fd| argument is the socket file descriptor. 457 * - The |resumptionToken| is a pointer to the resumption token as byte array 458 * of length |len|. 459 * - The |ctx| is a void pointer to the context set by the application in 460 * SSL_SetResumptionTokenCallback. 461 */ 462 typedef SECStatus(PR_CALLBACK *SSLResumptionTokenCallback)( 463 PRFileDesc *fd, const PRUint8 *resumptionToken, unsigned int len, 464 void *ctx); 465 466 /* 467 * This allows setting a callback for external session caches to store 468 * resumption tokens. 469 * 470 * - The |fd| argument is the socket file descriptor. 471 * - The |cb| is a function pointer to an implementation of 472 * SSLResumptionTokenCallback. 473 * - The |ctx| is a pointer to some application specific context, which is 474 * returned when |cb| is called. 475 */ 476 #define SSL_SetResumptionTokenCallback(fd, cb, ctx) \ 477 SSL_EXPERIMENTAL_API( \ 478 "SSL_SetResumptionTokenCallback", \ 479 (PRFileDesc * _fd, SSLResumptionTokenCallback _cb, void *_ctx), \ 480 (fd, cb, ctx)) 481 482 /* 483 * This allows setting a resumption token for a session. 484 * The function returns SECSuccess iff the resumption token can be used, 485 * SECFailure in any other case. The caller should remove the |token| from its 486 * cache when the function returns SECFailure. 487 * 488 * - The |fd| argument is the socket file descriptor. 489 * - The |token| is a pointer to the resumption token as byte array 490 * of length |len|. 491 */ 492 #define SSL_SetResumptionToken(fd, token, len) \ 493 SSL_EXPERIMENTAL_API( \ 494 "SSL_SetResumptionToken", \ 495 (PRFileDesc * _fd, const PRUint8 *_token, const unsigned int _len), \ 496 (fd, token, len)) 497 498 /* TLS 1.3 allows a server to set a limit on the number of bytes of early data 499 * that can be received. This allows that limit to be set. This function has no 500 * effect on a client. */ 501 #define SSL_SetMaxEarlyDataSize(fd, size) \ 502 SSL_EXPERIMENTAL_API("SSL_SetMaxEarlyDataSize", \ 503 (PRFileDesc * _fd, PRUint32 _size), \ 504 (fd, size)) 505 506 /* If |enabled|, a GREASE ECH extension will be sent in every ClientHello, 507 * unless a valid and supported ECHConfig is configured to the socket 508 * (in which case real ECH takes precedence). If |!enabled|, it is not sent.*/ 509 #define SSL_EnableTls13GreaseEch(fd, enabled) \ 510 SSL_EXPERIMENTAL_API("SSL_EnableTls13GreaseEch", \ 511 (PRFileDesc * _fd, PRBool _enabled), (fd, enabled)) 512 513 /* If |enabled|, a server receiving a Client Hello containing the ech_is_inner 514 * (and not encrypted_client_hello) extension will respond with the ECH 515 * acceptance signal. This signals the client to continue with the inner 516 * transcript rather than outer. */ 517 #define SSL_EnableTls13BackendEch(fd, enabled) \ 518 SSL_EXPERIMENTAL_API("SSL_EnableTls13BackendEch", \ 519 (PRFileDesc * _fd, PRBool _enabled), (fd, enabled)) 520 521 /* Called by the client after an initial ECH connection fails with 522 * SSL_ERROR_ECH_RETRY_WITH_ECH. Returns compatible ECHConfigs, which 523 * are configured via SetClientEchConfigs for an ECH retry attempt. 524 * These configs MUST NOT be used for more than the single retry 525 * attempt. Subsequent connections MUST use advertised ECHConfigs. */ 526 #define SSL_GetEchRetryConfigs(fd, out) \ 527 SSL_EXPERIMENTAL_API("SSL_GetEchRetryConfigs", \ 528 (PRFileDesc * _fd, \ 529 SECItem * _out), \ 530 (fd, out)) 531 532 /* Called to remove all ECHConfigs from a socket (fd). */ 533 #define SSL_RemoveEchConfigs(fd) \ 534 SSL_EXPERIMENTAL_API("SSL_RemoveEchConfigs", \ 535 (PRFileDesc * _fd), \ 536 (fd)) 537 538 /* Set the ECHConfig and key pair on a socket (server side) 539 * 540 * fd -- the socket 541 * pubKey -- the server's SECKEYPublicKey for HPKE/ECH. 542 * privateKey -- the server's SECKEYPrivateKey for HPKE/ECH. 543 * record/recordLen -- the encoded DNS record (not base64) 544 */ 545 #define SSL_SetServerEchConfigs(fd, pubKey, \ 546 privKey, record, recordLen) \ 547 SSL_EXPERIMENTAL_API("SSL_SetServerEchConfigs", \ 548 (PRFileDesc * _fd, \ 549 const SECKEYPublicKey *_pubKey, \ 550 const SECKEYPrivateKey *_privKey, \ 551 const PRUint8 *_record, unsigned int _recordLen), \ 552 (fd, pubKey, privKey, \ 553 record, recordLen)) 554 555 /* Set ECHConfig(s) on a client. The first supported ECHConfig will be used. 556 * 557 * fd -- the socket 558 * echConfigs/echConfigsLen -- the ECHConfigs structure (not base64) 559 */ 560 #define SSL_SetClientEchConfigs(fd, echConfigs, echConfigsLen) \ 561 SSL_EXPERIMENTAL_API("SSL_SetClientEchConfigs", \ 562 (PRFileDesc * _fd, \ 563 const PRUint8 *_echConfigs, \ 564 unsigned int _echConfigsLen), \ 565 (fd, echConfigs, echConfigsLen)) 566 567 /* 568 * Generate an encoded ECHConfig structure (presumably server side). 569 * 570 * configId -- an identifier for the configuration. 571 * publicName -- the public_name value to be placed in SNI. 572 * maxNameLen -- the maximum length of protected names 573 * kemId -- the HKPE KEM ID value 574 * pubKey -- the public key for the key pair 575 * hpkeSuites -- the HPKE cipher suites that can be used 576 * hpkeSuitesCount -- the number of suites in hpkeSuites 577 * out/outlen/maxlen -- where to output the data 578 */ 579 typedef struct HpkeSymmetricSuiteStr { 580 HpkeKdfId kdfId; 581 HpkeAeadId aeadId; 582 } HpkeSymmetricSuite; 583 #define SSL_EncodeEchConfigId(configId, publicName, maxNameLen, \ 584 kemId, pubKey, hpkeSuites, hpkeSuiteCount, \ 585 out, outlen, maxlen) \ 586 SSL_EXPERIMENTAL_API("SSL_EncodeEchConfigId", \ 587 (PRUint8 _configId, const char *_publicName, \ 588 unsigned int _maxNameLen, HpkeKemId _kemId, \ 589 const SECKEYPublicKey *_pubKey, \ 590 const HpkeSymmetricSuite *_hpkeSuites, \ 591 unsigned int _hpkeSuiteCount, \ 592 PRUint8 *_out, unsigned int *_outlen, \ 593 unsigned int _maxlen), \ 594 (configId, publicName, maxNameLen, \ 595 kemId, pubKey, hpkeSuites, hpkeSuiteCount, \ 596 out, outlen, maxlen)) 597 598 /* SSL_SetSecretCallback installs a callback that TLS calls when it installs new 599 * traffic secrets. 600 * 601 * SSLSecretCallback is called with the current epoch and the corresponding 602 * secret; this matches the epoch used in DTLS 1.3, even if the socket is 603 * operating in stream mode: 604 * 605 * - client_early_traffic_secret corresponds to epoch 1 606 * - {client|server}_handshake_traffic_secret is epoch 2 607 * - {client|server}_application_traffic_secret_{N} is epoch 3+N 608 * 609 * The callback is invoked separately for read secrets (client secrets on the 610 * server; server secrets on the client), and write secrets. 611 * 612 * This callback is only called if (D)TLS 1.3 is negotiated. 613 */ 614 typedef void(PR_CALLBACK *SSLSecretCallback)( 615 PRFileDesc *fd, PRUint16 epoch, SSLSecretDirection dir, PK11SymKey *secret, 616 void *arg); 617 618 #define SSL_SecretCallback(fd, cb, arg) \ 619 SSL_EXPERIMENTAL_API("SSL_SecretCallback", \ 620 (PRFileDesc * _fd, SSLSecretCallback _cb, void *_arg), \ 621 (fd, cb, arg)) 622 623 /* SSL_RecordLayerWriteCallback() is used to replace the TLS record layer. This 624 * function installs a callback that TLS calls when it would otherwise encrypt 625 * and write a record to the underlying NSPR IO layer. The application is 626 * responsible for ensuring that these records are encrypted and written. 627 * 628 * Calling this API also disables reads from the underlying NSPR layer. The 629 * application is expected to push data when it is available using 630 * SSL_RecordLayerData(). 631 * 632 * When data would be written, the provided SSLRecordWriteCallback with the 633 * epoch, TLS content type, and the data. The data provided to the callback is 634 * not split into record-sized writes. If the callback returns SECFailure, the 635 * write will be considered to have failed; in particular, PR_WOULD_BLOCK_ERROR 636 * is not handled specially. 637 * 638 * If TLS 1.3 is in use, the epoch indicates the expected level of protection 639 * that the record would receive, this matches that used in DTLS 1.3: 640 * 641 * - epoch 0 corresponds to no record protection 642 * - epoch 1 corresponds to 0-RTT 643 * - epoch 2 corresponds to TLS handshake 644 * - epoch 3 and higher are application data 645 * 646 * Prior versions of TLS use epoch 1 and higher for application data. 647 * 648 * This API is not supported for DTLS. 649 */ 650 typedef SECStatus(PR_CALLBACK *SSLRecordWriteCallback)( 651 PRFileDesc *fd, PRUint16 epoch, SSLContentType contentType, 652 const PRUint8 *data, unsigned int len, void *arg); 653 654 #define SSL_RecordLayerWriteCallback(fd, writeCb, arg) \ 655 SSL_EXPERIMENTAL_API("SSL_RecordLayerWriteCallback", \ 656 (PRFileDesc * _fd, SSLRecordWriteCallback _wCb, \ 657 void *_arg), \ 658 (fd, writeCb, arg)) 659 660 /* SSL_RecordLayerData() is used to provide new data to TLS. The application 661 * indicates the epoch (see the description of SSL_RecordLayerWriteCallback()), 662 * content type, and the data that was received. The application is responsible 663 * for removing any encryption or other protection before passing data to this 664 * function. 665 * 666 * This returns SECSuccess if the data was successfully processed. If this 667 * function is used to drive the handshake and the caller needs to know when the 668 * handshake is complete, a call to SSL_ForceHandshake will return SECSuccess 669 * when the handshake is complete. 670 * 671 * This API is not supported for DTLS sockets. 672 */ 673 #define SSL_RecordLayerData(fd, epoch, ct, data, len) \ 674 SSL_EXPERIMENTAL_API("SSL_RecordLayerData", \ 675 (PRFileDesc * _fd, PRUint16 _epoch, \ 676 SSLContentType _contentType, \ 677 const PRUint8 *_data, unsigned int _len), \ 678 (fd, epoch, ct, data, len)) 679 680 /* 681 * SSL_GetCurrentEpoch() returns the read and write epochs that the socket is 682 * currently using. NULL values for readEpoch or writeEpoch are ignored. 683 * 684 * See SSL_RecordLayerWriteCallback() for details on epochs. 685 */ 686 #define SSL_GetCurrentEpoch(fd, readEpoch, writeEpoch) \ 687 SSL_EXPERIMENTAL_API("SSL_GetCurrentEpoch", \ 688 (PRFileDesc * _fd, PRUint16 * _readEpoch, \ 689 PRUint16 * _writeEpoch), \ 690 (fd, readEpoch, writeEpoch)) 691 692 /* 693 * The following AEAD functions expose an AEAD primitive that uses a ciphersuite 694 * to set parameters. The ciphersuite determines the Hash function used by 695 * HKDF, the AEAD function, and the size of key and IV. This is only supported 696 * for TLS 1.3. 697 * 698 * The key and IV are generated using the TLS KDF with a custom label. That is 699 * HKDF-Expand-Label(secret, labelPrefix + " key" or " iv", "", L). 700 * 701 * The encrypt and decrypt functions use a nonce construction identical to that 702 * used in TLS. The lower bits of the IV are XORed with the 64-bit counter to 703 * produce the nonce. Otherwise, this is an AEAD interface similar to that 704 * described in RFC 5116. 705 * 706 * Note: SSL_MakeAead internally calls SSL_MakeVariantAead with a variant of 707 * "stream", behaving as noted above. If "datagram" variant is passed instead, 708 * the Label prefix used in HKDF-Expand is "dtls13" instead of "tls13 ". See 709 * 7.1 of RFC 8446 and draft-ietf-tls-dtls13-34. */ 710 typedef struct SSLAeadContextStr SSLAeadContext; 711 712 #define SSL_MakeAead(version, cipherSuite, secret, \ 713 labelPrefix, labelPrefixLen, ctx) \ 714 SSL_EXPERIMENTAL_API("SSL_MakeAead", \ 715 (PRUint16 _version, PRUint16 _cipherSuite, \ 716 PK11SymKey * _secret, \ 717 const char *_labelPrefix, \ 718 unsigned int _labelPrefixLen, \ 719 SSLAeadContext **_ctx), \ 720 (version, cipherSuite, secret, \ 721 labelPrefix, labelPrefixLen, ctx)) 722 723 #define SSL_MakeVariantAead(version, cipherSuite, variant, secret, \ 724 labelPrefix, labelPrefixLen, ctx) \ 725 SSL_EXPERIMENTAL_API("SSL_MakeVariantAead", \ 726 (PRUint16 _version, PRUint16 _cipherSuite, \ 727 SSLProtocolVariant _variant, \ 728 PK11SymKey * _secret, \ 729 const char *_labelPrefix, \ 730 unsigned int _labelPrefixLen, \ 731 SSLAeadContext **_ctx), \ 732 (version, cipherSuite, variant, secret, \ 733 labelPrefix, labelPrefixLen, ctx)) 734 735 #define SSL_AeadEncrypt(ctx, counter, aad, aadLen, in, inLen, \ 736 output, outputLen, maxOutputLen) \ 737 SSL_EXPERIMENTAL_API("SSL_AeadEncrypt", \ 738 (const SSLAeadContext *_ctx, PRUint64 _counter, \ 739 const PRUint8 *_aad, unsigned int _aadLen, \ 740 const PRUint8 *_in, unsigned int _inLen, \ 741 PRUint8 *_out, unsigned int *_outLen, \ 742 unsigned int _maxOut), \ 743 (ctx, counter, aad, aadLen, in, inLen, \ 744 output, outputLen, maxOutputLen)) 745 746 #define SSL_AeadDecrypt(ctx, counter, aad, aadLen, in, inLen, \ 747 output, outputLen, maxOutputLen) \ 748 SSL_EXPERIMENTAL_API("SSL_AeadDecrypt", \ 749 (const SSLAeadContext *_ctx, PRUint64 _counter, \ 750 const PRUint8 *_aad, unsigned int _aadLen, \ 751 const PRUint8 *_in, unsigned int _inLen, \ 752 PRUint8 *_output, unsigned int *_outLen, \ 753 unsigned int _maxOut), \ 754 (ctx, counter, aad, aadLen, in, inLen, \ 755 output, outputLen, maxOutputLen)) 756 757 #define SSL_DestroyAead(ctx) \ 758 SSL_EXPERIMENTAL_API("SSL_DestroyAead", \ 759 (SSLAeadContext * _ctx), \ 760 (ctx)) 761 762 /* SSL_HkdfExtract and SSL_HkdfExpandLabel implement the functions from TLS, 763 * using the version and ciphersuite to set parameters. This allows callers to 764 * use these TLS functions as a KDF. This is only supported for TLS 1.3. 765 * 766 * SSL_HkdfExtract produces a key with a mechanism that is suitable for input to 767 * SSL_HkdfExpandLabel (and SSL_HkdfExpandLabelWithMech). */ 768 #define SSL_HkdfExtract(version, cipherSuite, salt, ikm, keyp) \ 769 SSL_EXPERIMENTAL_API("SSL_HkdfExtract", \ 770 (PRUint16 _version, PRUint16 _cipherSuite, \ 771 PK11SymKey * _salt, PK11SymKey * _ikm, \ 772 PK11SymKey * *_keyp), \ 773 (version, cipherSuite, salt, ikm, keyp)) 774 775 /* SSL_HkdfExpandLabel and SSL_HkdfVariantExpandLabel produce a key with a 776 * mechanism that is suitable for input to SSL_HkdfExpandLabel or SSL_MakeAead. 777 * 778 * Note: SSL_HkdfVariantExpandLabel internally calls SSL_HkdfExpandLabel with 779 * a default "stream" variant. If "datagram" variant is passed instead, the 780 * Label prefix used in HKDF-Expand is "dtls13" instead of "tls13 ". See 7.1 of 781 * RFC 8446 and draft-ietf-tls-dtls13-34. */ 782 #define SSL_HkdfExpandLabel(version, cipherSuite, prk, \ 783 hsHash, hsHashLen, label, labelLen, keyp) \ 784 SSL_EXPERIMENTAL_API("SSL_HkdfExpandLabel", \ 785 (PRUint16 _version, PRUint16 _cipherSuite, \ 786 PK11SymKey * _prk, \ 787 const PRUint8 *_hsHash, unsigned int _hsHashLen, \ 788 const char *_label, unsigned int _labelLen, \ 789 PK11SymKey **_keyp), \ 790 (version, cipherSuite, prk, \ 791 hsHash, hsHashLen, label, labelLen, keyp)) 792 793 #define SSL_HkdfVariantExpandLabel(version, cipherSuite, prk, \ 794 hsHash, hsHashLen, label, labelLen, variant, \ 795 keyp) \ 796 SSL_EXPERIMENTAL_API("SSL_HkdfVariantExpandLabel", \ 797 (PRUint16 _version, PRUint16 _cipherSuite, \ 798 PK11SymKey * _prk, \ 799 const PRUint8 *_hsHash, unsigned int _hsHashLen, \ 800 const char *_label, unsigned int _labelLen, \ 801 SSLProtocolVariant _variant, \ 802 PK11SymKey **_keyp), \ 803 (version, cipherSuite, prk, \ 804 hsHash, hsHashLen, label, labelLen, variant, \ 805 keyp)) 806 807 /* SSL_HkdfExpandLabelWithMech and SSL_HkdfVariantExpandLabelWithMech use the KDF 808 * from the selected TLS version and cipher suite, as with the other calls, but 809 * the provided mechanism and key size. This allows the key to be used more widely. 810 * 811 * Note: SSL_HkdfExpandLabelWithMech internally calls SSL_HkdfVariantExpandLabelWithMech 812 * with a default "stream" variant. If "datagram" variant is passed instead, the 813 * Label prefix used in HKDF-Expand is "dtls13" instead of "tls13 ". See 7.1 of 814 * RFC 8446 and draft-ietf-tls-dtls13-34. */ 815 #define SSL_HkdfExpandLabelWithMech(version, cipherSuite, prk, \ 816 hsHash, hsHashLen, label, labelLen, \ 817 mech, keySize, keyp) \ 818 SSL_EXPERIMENTAL_API("SSL_HkdfExpandLabelWithMech", \ 819 (PRUint16 _version, PRUint16 _cipherSuite, \ 820 PK11SymKey * _prk, \ 821 const PRUint8 *_hsHash, unsigned int _hsHashLen, \ 822 const char *_label, unsigned int _labelLen, \ 823 CK_MECHANISM_TYPE _mech, unsigned int _keySize, \ 824 PK11SymKey **_keyp), \ 825 (version, cipherSuite, prk, \ 826 hsHash, hsHashLen, label, labelLen, \ 827 mech, keySize, keyp)) 828 829 #define SSL_HkdfVariantExpandLabelWithMech(version, cipherSuite, prk, \ 830 hsHash, hsHashLen, label, labelLen, \ 831 mech, keySize, variant, keyp) \ 832 SSL_EXPERIMENTAL_API("SSL_HkdfVariantExpandLabelWithMech", \ 833 (PRUint16 _version, PRUint16 _cipherSuite, \ 834 PK11SymKey * _prk, \ 835 const PRUint8 *_hsHash, unsigned int _hsHashLen, \ 836 const char *_label, unsigned int _labelLen, \ 837 CK_MECHANISM_TYPE _mech, unsigned int _keySize, \ 838 SSLProtocolVariant _variant, \ 839 PK11SymKey **_keyp), \ 840 (version, cipherSuite, prk, \ 841 hsHash, hsHashLen, label, labelLen, \ 842 mech, keySize, variant, keyp)) 843 844 /* SSL_SetTimeFunc overrides the default time function (PR_Now()) and provides 845 * an alternative source of time for the socket. This is used in testing, and in 846 * applications that need better control over how the clock is accessed. Set the 847 * function to NULL to use PR_Now().*/ 848 typedef PRTime(PR_CALLBACK *SSLTimeFunc)(void *arg); 849 850 #define SSL_SetTimeFunc(fd, f, arg) \ 851 SSL_EXPERIMENTAL_API("SSL_SetTimeFunc", \ 852 (PRFileDesc * _fd, SSLTimeFunc _f, void *_arg), \ 853 (fd, f, arg)) 854 855 /* Create a delegated credential (DC) for the draft-ietf-tls-subcerts extension 856 * using the given certificate |cert| and its signing key |certPriv| and write 857 * the serialized DC to |out|. The 858 * parameters are: 859 * - the DC public key |dcPub|; 860 * - the DC signature scheme |dcCertVerifyAlg|, used to verify the handshake. 861 * - the DC time-to-live |dcValidFor|, the number of seconds from now for which 862 * the DC should be valid; and 863 * - the current time |now|. 864 * 865 * The signing algorithm used to verify the DC signature is deduced from 866 * |cert|. 867 * 868 * It's the caller's responsibility to ensure the input parameters are all 869 * valid. This procedure is meant primarily for testing; for this purpose it is 870 * useful to do no validation. 871 */ 872 #define SSL_DelegateCredential(cert, certPriv, dcPub, dcCertVerifyAlg, \ 873 dcValidFor, now, out) \ 874 SSL_EXPERIMENTAL_API("SSL_DelegateCredential", \ 875 (const CERTCertificate *_cert, \ 876 const SECKEYPrivateKey *_certPriv, \ 877 const SECKEYPublicKey *_dcPub, \ 878 SSLSignatureScheme _dcCertVerifyAlg, \ 879 PRUint32 _dcValidFor, \ 880 PRTime _now, \ 881 SECItem *_out), \ 882 (cert, certPriv, dcPub, dcCertVerifyAlg, dcValidFor, \ 883 now, out)) 884 885 /* New functions created to permit get/set the CipherSuites Order for the 886 * handshake (Client Hello). 887 * 888 * The *Get function puts the current set of active (enabled and policy set as 889 * PR_TRUE) cipher suites in the cipherOrder outparam. Cipher suites that 890 * aren't active aren't included. The paramenters are: 891 * - PRFileDesc *fd = FileDescriptor to get information. 892 * - PRUint16 *cipherOrder = The memory allocated for cipherOrder needs to be 893 * SSL_GetNumImplementedCiphers() * sizeof(PRUint16) or more. 894 * - PRUint16 numCiphers = The number of active ciphersuites listed in 895 * *cipherOrder is written here. 896 * 897 * The *Set function permits reorder the CipherSuites list for the Handshake 898 * (Client Hello). The default ordering defined in ssl3con.c is enough in 899 * almost all cases. But, if the client needs some hardening or performance 900 * adjusts related to CipherSuites, this can be done with this function. 901 * The caller has to be aware about the risk of call this function while a 902 * handshake are being processed in this fd/socket. For example, if you disable 903 * a cipher after the handshake and this cipher was choosen for that 904 * connection, something bad will happen. 905 * The parameters are: 906 * - PRFileDesc *fd = FileDescriptor to change. 907 * - const PRUint16 *cipherOrder = Must receive all ciphers to be ordered, in 908 * the desired order. They will be set in the begin of the list. Only 909 * suites listed by SSL_ImplementedCiphers() can be included. 910 * - PRUint16 numCiphers = Must receive the number of items in *cipherOrder. 911 * */ 912 #define SSL_CipherSuiteOrderGet(fd, cipherOrder, numCiphers) \ 913 SSL_EXPERIMENTAL_API("SSL_CipherSuiteOrderGet", \ 914 (PRFileDesc * _fd, PRUint16 * _cipherOrder, \ 915 unsigned int *_numCiphers), \ 916 (fd, cipherOrder, numCiphers)) 917 918 #define SSL_CipherSuiteOrderSet(fd, cipherOrder, numCiphers) \ 919 SSL_EXPERIMENTAL_API("SSL_CipherSuiteOrderSet", \ 920 (PRFileDesc * _fd, const PRUint16 *_cipherOrder, \ 921 PRUint16 _numCiphers), \ 922 (fd, cipherOrder, numCiphers)) 923 924 /* 925 * The following functions expose a masking primitive that uses ciphersuite and 926 * version information to set paramaters for the masking key and mask generation 927 * logic. This is only supported for TLS 1.3. 928 * 929 * The key and IV are generated using the TLS KDF with a custom label. That is 930 * HKDF-Expand-Label(secret, label, "", L), where |label| is an input to 931 * SSL_CreateMaskingContext. 932 * 933 * The mask generation logic in SSL_CreateMask is determined by the underlying 934 * symmetric cipher: 935 * - For AES-ECB, mask = AES-ECB(mask_key, sample). |len| must be <= 16 as 936 * the output is limited to a single block. 937 * - For CHACHA20, mask = ChaCha20(mask_key, sample[0..3], sample[4..15], {0}.len) 938 * That is, the low 4 bytes of |sample| used as the counter, the remaining 12 bytes 939 * the nonce. We encrypt |len| bytes of zeros, returning the raw key stream. 940 * 941 * The caller must pre-allocate at least |len| bytes for output. If the underlying 942 * cipher cannot produce the requested amount of data, SECFailure is returned. 943 */ 944 945 typedef struct SSLMaskingContextStr { 946 CK_MECHANISM_TYPE mech; 947 PRUint16 version; 948 PRUint16 cipherSuite; 949 PK11SymKey *secret; 950 } SSLMaskingContext; 951 952 #define SSL_CreateMaskingContext(version, cipherSuite, secret, \ 953 label, labelLen, ctx) \ 954 SSL_EXPERIMENTAL_API("SSL_CreateMaskingContext", \ 955 (PRUint16 _version, PRUint16 _cipherSuite, \ 956 PK11SymKey * _secret, \ 957 const char *_label, \ 958 unsigned int _labelLen, \ 959 SSLMaskingContext **_ctx), \ 960 (version, cipherSuite, secret, label, labelLen, ctx)) 961 962 #define SSL_CreateVariantMaskingContext(version, cipherSuite, variant, \ 963 secret, label, labelLen, ctx) \ 964 SSL_EXPERIMENTAL_API("SSL_CreateVariantMaskingContext", \ 965 (PRUint16 _version, PRUint16 _cipherSuite, \ 966 SSLProtocolVariant _variant, \ 967 PK11SymKey * _secret, \ 968 const char *_label, \ 969 unsigned int _labelLen, \ 970 SSLMaskingContext **_ctx), \ 971 (version, cipherSuite, variant, secret, \ 972 label, labelLen, ctx)) 973 974 #define SSL_DestroyMaskingContext(ctx) \ 975 SSL_EXPERIMENTAL_API("SSL_DestroyMaskingContext", \ 976 (SSLMaskingContext * _ctx), \ 977 (ctx)) 978 979 #define SSL_CreateMask(ctx, sample, sampleLen, mask, maskLen) \ 980 SSL_EXPERIMENTAL_API("SSL_CreateMask", \ 981 (SSLMaskingContext * _ctx, const PRUint8 *_sample, \ 982 unsigned int _sampleLen, PRUint8 *_mask, \ 983 unsigned int _maskLen), \ 984 (ctx, sample, sampleLen, mask, maskLen)) 985 986 #define SSL_SetDtls13VersionWorkaround(fd, enabled) \ 987 SSL_EXPERIMENTAL_API("SSL_SetDtls13VersionWorkaround", \ 988 (PRFileDesc * _fd, PRBool _enabled), (fd, enabled)) 989 990 /* SSL_AddExternalPsk() and SSL_AddExternalPsk0Rtt() can be used to 991 * set an external PSK on a socket. If successful, this PSK will 992 * be used in all subsequent connection attempts for this socket. 993 * This has no effect if the maximum TLS version is < 1.3. 994 * 995 * This API currently only accepts a single PSK, so multiple calls to 996 * either function will fail. An EPSK can be replaced by calling 997 * SSL_RemoveExternalPsk followed by SSL_AddExternalPsk. 998 * For both functions, the label is expected to be a unique identifier 999 * for the external PSK. Should en external PSK have the same label 1000 * as a configured resumption PSK identity, the external PSK will 1001 * take precedence. 1002 * 1003 * If you want to enable early data, you need to also provide a 1004 * cipher suite for 0-RTT and a limit for the early data using 1005 * SSL_AddExternalPsk0Rtt(). If you want to explicitly disallow 1006 * certificate authentication, use SSL_AuthCertificateHook to set 1007 * a callback that rejects all certificate chains. 1008 */ 1009 #define SSL_AddExternalPsk(fd, psk, identity, identityLen, hash) \ 1010 SSL_EXPERIMENTAL_API("SSL_AddExternalPsk", \ 1011 (PRFileDesc * _fd, PK11SymKey * _psk, \ 1012 const PRUint8 *_identity, unsigned int _identityLen, \ 1013 SSLHashType _hash), \ 1014 (fd, psk, identity, identityLen, hash)) 1015 1016 #define SSL_AddExternalPsk0Rtt(fd, psk, identity, identityLen, hash, \ 1017 zeroRttSuite, maxEarlyData) \ 1018 SSL_EXPERIMENTAL_API("SSL_AddExternalPsk0Rtt", \ 1019 (PRFileDesc * _fd, PK11SymKey * _psk, \ 1020 const PRUint8 *_identity, unsigned int _identityLen, \ 1021 SSLHashType _hash, PRUint16 _zeroRttSuite, \ 1022 PRUint32 _maxEarlyData), \ 1023 (fd, psk, identity, identityLen, hash, \ 1024 zeroRttSuite, maxEarlyData)) 1025 1026 /* SSLExp_RemoveExternalPsk() removes an external PSK from socket 1027 * configuration. Returns SECSuccess if the PSK was removed 1028 * successfully, and SECFailure otherwise. */ 1029 #define SSL_RemoveExternalPsk(fd, identity, identityLen) \ 1030 SSL_EXPERIMENTAL_API("SSL_RemoveExternalPsk", \ 1031 (PRFileDesc * _fd, const PRUint8 *_identity, \ 1032 unsigned int _identityLen), \ 1033 (fd, identity, identityLen)) 1034 1035 /* Deprecated experimental APIs */ 1036 #define SSL_UseAltServerHelloType(fd, enable) SSL_DEPRECATED_EXPERIMENTAL_API 1037 #define SSL_SetupAntiReplay(a, b, c) SSL_DEPRECATED_EXPERIMENTAL_API 1038 #define SSL_InitAntiReplay(a, b, c) SSL_DEPRECATED_EXPERIMENTAL_API 1039 #define SSL_EnableESNI(a, b, c, d) SSL_DEPRECATED_EXPERIMENTAL_API 1040 #define SSL_EncodeESNIKeys(a, b, c, d, e, f, g, h, i, j) SSL_DEPRECATED_EXPERIMENTAL_API 1041 #define SSL_SetESNIKeyPair(a, b, c, d) SSL_DEPRECATED_EXPERIMENTAL_API 1042 #define SSL_EncodeEchConfig(a, b, c, d, e, f, g, h, i) SSL_DEPRECATED_EXPERIMENTAL_API 1043 1044 SEC_END_PROTOS 1045 1046 #endif /* __sslexp_h_ */ 1047