tls13ech.h (5982B)
1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* 3 * This file is PRIVATE to SSL. 4 * 5 * This Source Code Form is subject to the terms of the Mozilla Public 6 * License, v. 2.0. If a copy of the MPL was not distributed with this 7 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 8 9 #ifndef __tls13ech_h_ 10 #define __tls13ech_h_ 11 12 #include "pk11hpke.h" 13 14 /* draft-09, supporting shared-mode and split-mode as a backend server only. 15 * Notes on the implementation status: 16 * - Padding (https://tools.ietf.org/html/draft-ietf-tls-esni-08#section-6.2), 17 * is not implemented (see bug 1677181). 18 * - When multiple ECHConfigs are provided by the server, the first compatible 19 * config is selected by the client. Ciphersuite choices are limited and only 20 * the AEAD may vary (AES-128-GCM or ChaCha20Poly1305). 21 * - Some of the buffering (construction/compression/decompression) could likely 22 * be optimized, but the spec is still evolving so that work is deferred. 23 */ 24 #define TLS13_ECH_VERSION 0xfe0d 25 #define TLS13_ECH_SIGNAL_LEN 8 26 #define TLS13_ECH_AEAD_TAG_LEN 16 27 28 static const char kHpkeInfoEch[] = "tls ech"; 29 static const char hHkdfInfoEchConfigID[] = "tls ech config id"; 30 static const char kHkdfInfoEchConfirm[] = "ech accept confirmation"; 31 static const char kHkdfInfoEchHrrConfirm[] = "hrr ech accept confirmation"; 32 33 typedef enum { 34 ech_xtn_type_outer = 0, 35 ech_xtn_type_inner = 1, 36 } EchXtnType; 37 38 struct sslEchConfigContentsStr { 39 PRUint8 configId; 40 HpkeKemId kemId; 41 SECItem publicKey; /* NULL on server. Use the keypair in sslEchConfig instead. */ 42 HpkeKdfId kdfId; 43 HpkeAeadId aeadId; 44 SECItem suites; /* One or more HpkeCipherSuites. The selected s 45 * suite is placed in kdfId and aeadId. */ 46 PRUint8 maxNameLen; 47 char *publicName; 48 /* No supported extensions. */ 49 }; 50 51 /* ECH Information needed by a server to process a second CH after a 52 * HelloRetryRequest is sent. This data is stored in the cookie. 53 */ 54 struct sslEchCookieDataStr { 55 PRBool previouslyOffered; 56 PRUint8 configId; 57 HpkeKdfId kdfId; 58 HpkeAeadId aeadId; 59 HpkeContext *hpkeCtx; 60 PRUint8 signal[TLS13_ECH_SIGNAL_LEN]; 61 }; 62 63 struct sslEchConfigStr { 64 PRCList link; 65 SECItem raw; 66 PRUint16 version; 67 sslEchConfigContents contents; 68 }; 69 70 struct sslEchXtnStateStr { 71 SECItem innerCh; /* Server: ClientECH.payload */ 72 SECItem senderPubKey; /* Server: ClientECH.enc */ 73 PRUint8 configId; /* Server: ClientECH.config_id */ 74 HpkeKdfId kdfId; /* Server: ClientECH.cipher_suite.kdf */ 75 HpkeAeadId aeadId; /* Server: ClientECH.cipher_suite.aead */ 76 SECItem retryConfigs; /* Client: ServerECH.retry_configs*/ 77 PRBool retryConfigsValid; /* Client: Extraction of retry_configss is allowed. 78 * This is set once the handshake completes (having 79 * verified to the ECHConfig public name). */ 80 PRUint8 *hrrConfirmation; /* Client/Server: HRR Confirmation Location */ 81 PRBool receivedInnerXtn; /* Server: Handled ECH Xtn with Inner Enum */ 82 PRUint8 *payloadStart; /* Server: Start of ECH Payload*/ 83 }; 84 85 SEC_BEGIN_PROTOS 86 87 SECStatus SSLExp_EncodeEchConfigId(PRUint8 configId, const char *publicName, unsigned int maxNameLen, 88 HpkeKemId kemId, const SECKEYPublicKey *pubKey, 89 const HpkeSymmetricSuite *hpkeSuites, unsigned int hpkeSuiteCount, 90 PRUint8 *out, unsigned int *outlen, unsigned int maxlen); 91 SECStatus SSLExp_GetEchRetryConfigs(PRFileDesc *fd, SECItem *retryConfigs); 92 SECStatus SSLExp_SetClientEchConfigs(PRFileDesc *fd, const PRUint8 *echConfigs, 93 unsigned int echConfigsLen); 94 SECStatus SSLExp_SetServerEchConfigs(PRFileDesc *fd, 95 const SECKEYPublicKey *pubKey, const SECKEYPrivateKey *privKey, 96 const PRUint8 *echConfigs, unsigned int numEchConfigs); 97 SECStatus SSLExp_RemoveEchConfigs(PRFileDesc *fd); 98 99 SEC_END_PROTOS 100 101 SECStatus tls13_ClientSetupEch(sslSocket *ss, sslClientHelloType type); 102 SECStatus tls13_ConstructClientHelloWithEch(sslSocket *ss, const sslSessionID *sid, 103 PRBool freshSid, sslBuffer *chOuterBuf, 104 sslBuffer *chInnerXtnsBuf); 105 SECStatus tls13_CopyEchConfigs(PRCList *oconfigs, PRCList *configs); 106 SECStatus tls13_DecodeEchConfigs(const SECItem *data, PRCList *configs); 107 void tls13_DestroyEchConfigs(PRCList *list); 108 void tls13_DestroyEchXtnState(sslEchXtnState *state); 109 SECStatus tls13_GetMatchingEchConfig(const sslSocket *ss, HpkeKdfId kdf, HpkeAeadId aead, 110 const SECItem *configId, sslEchConfig **cfg); 111 void tls13_EchKeyLog(sslSocket *ss); 112 SECStatus tls13_MaybeHandleEch(sslSocket *ss, const PRUint8 *msg, PRUint32 msgLen, SECItem *sidBytes, 113 SECItem *comps, SECItem *cookieBytes, SECItem *suites, SECItem **echInner); 114 SECStatus tls13_MaybeHandleEchSignal(sslSocket *ss, const PRUint8 *savedMsg, PRUint32 savedLength, PRBool isHrr); 115 SECStatus tls13_MaybeAcceptEch(sslSocket *ss, const SECItem *sidBytes, const PRUint8 *chOuter, 116 unsigned int chOuterLen, SECItem **chInner); 117 SECStatus tls13_MaybeGreaseEch(sslSocket *ss, const sslBuffer *preamble, sslBuffer *buf); 118 SECStatus tls13_WriteServerEchSignal(sslSocket *ss, PRUint8 *sh, unsigned int shLen); 119 SECStatus tls13_WriteServerEchHrrSignal(sslSocket *ss, PRUint8 *sh, unsigned int shLen); 120 SECStatus tls13_DeriveEchSecret(const sslSocket *ss, PK11SymKey **output); 121 SECStatus tls13_ComputeEchSignal(sslSocket *ss, PRBool isHrr, const PRUint8 *sh, unsigned int shLen, PRUint8 *out); 122 123 PRBool tls13_IsIp(const PRUint8 *str, unsigned int len); 124 PRBool tls13_IsLDH(const PRUint8 *str, unsigned int len); 125 126 #endif