nsITLSSocketControl.idl (6916B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #include "nsISupports.idl" 8 9 interface nsIInterfaceRequestor; 10 interface nsITlsHandshakeCallbackListener; 11 interface nsITransportSecurityInfo; 12 interface nsIX509Cert; 13 14 %{C++ 15 #include "nsStringFwd.h" 16 #include "nsTArrayForwardDeclare.h" 17 %} 18 [ref] native nsCStringTArrayRef(nsTArray<nsCString>); 19 20 // An interface describing an object that controls and holds information about 21 // a TLS handshake. 22 // NB: The implementations of this interface may only be used on the socket 23 // thread (except for asyncGetSecurityInfo); 24 [scriptable, builtinclass, uuid(418265c8-654e-4fbb-ba62-4eed27de1f03)] 25 interface nsITLSSocketControl : nsISupports { 26 [noscript] void proxyStartSSL(); 27 [noscript] void StartTLS(); 28 29 /** 30 * Calls StartTLS on the socket thread, and resolves with the nsresult 31 * return value of that call. 32 */ 33 [implicit_jscontext,must_use] 34 Promise asyncStartTLS(); 35 36 /* NPN (Next Protocol Negotiation) is a mechanism for 37 negotiating the protocol to be spoken inside the SSL 38 tunnel during the SSL handshake. The NPNList is the list 39 of offered client side protocols. setNPNList() needs to 40 be called before any data is read or written (including the 41 handshake to be setup correctly. The server determines the 42 priority when multiple matches occur, but if there is no overlap 43 the first protocol in the list is used. */ 44 45 [noscript] void setNPNList(in nsCStringTArrayRef aNPNList); 46 47 /* For 0RTT we need to know the alpn protocol selected for the last tls 48 * session. This function will return a value if applicable or an error 49 * NS_ERROR_NOT_AVAILABLE. 50 */ 51 ACString getAlpnEarlySelection(); 52 53 /* If 0RTT handshake was applied and some data has been sent, as soon as 54 * the handshake finishes this attribute will be set to appropriate value. 55 */ 56 readonly attribute boolean earlyDataAccepted; 57 58 /* When 0RTT is performed, PR_Write will not drive the handshake forward. 59 * It must be forced by calling this function. 60 */ 61 void driveHandshake(); 62 63 /* Determine if a potential SSL connection to hostname:port with 64 * a desired NPN negotiated protocol of npnProtocol can use the socket 65 * associated with this object instead of making a new one. And if so, combine 66 * them. 67 */ 68 boolean joinConnection( 69 in ACString npnProtocol, /* e.g. "h2" */ 70 in ACString hostname, 71 in long port); 72 73 /* just like JoinConnection() except do not mark a successful test as joined. 74 */ 75 boolean testJoinConnection( 76 in ACString npnProtocol, /* e.g. "h2" */ 77 in ACString hostname, 78 in long port); 79 80 /* Determine if existing connection should be trusted to convey information about 81 * a hostname. 82 */ 83 boolean isAcceptableForHost(in ACString hostname); 84 85 /* The Key Exchange Algorithm is used when determining whether or 86 not HTTP/2 can be used. 87 88 After a handshake is complete it can be read from KEAUsed. 89 The values correspond to the SSLKEAType enum in NSS or the 90 KEY_EXCHANGE_UNKNOWN constant defined below. 91 92 KEAKeyBits is the size/security-level used for the KEA. 93 */ 94 95 [infallible] readonly attribute short KEAUsed; 96 [infallible] readonly attribute unsigned long KEAKeyBits; 97 98 const short KEY_EXCHANGE_UNKNOWN = -1; 99 100 /* 101 * The original flags from the socket provider. 102 */ 103 readonly attribute uint32_t providerFlags; 104 105 /* These values are defined by TLS. */ 106 const short SSL_VERSION_3 = 0x0300; 107 const short TLS_VERSION_1 = 0x0301; 108 const short TLS_VERSION_1_1 = 0x0302; 109 const short TLS_VERSION_1_2 = 0x0303; 110 const short TLS_VERSION_1_3 = 0x0304; 111 const short SSL_VERSION_UNKNOWN = -1; 112 113 [infallible] readonly attribute short SSLVersionUsed; 114 [infallible] readonly attribute short SSLVersionOffered; 115 116 /* These values match the NSS defined values in sslt.h */ 117 const short SSL_MAC_UNKNOWN = -1; 118 const short SSL_MAC_NULL = 0; 119 const short SSL_MAC_MD5 = 1; 120 const short SSL_MAC_SHA = 2; 121 const short SSL_HMAC_MD5 = 3; 122 const short SSL_HMAC_SHA = 4; 123 const short SSL_HMAC_SHA256 = 5; 124 const short SSL_MAC_AEAD = 6; 125 126 [infallible] readonly attribute short MACAlgorithmUsed; 127 128 /** 129 * If set to true before the server requests a client cert 130 * no cert will be sent. 131 */ 132 [notxpcom, nostdcall] attribute boolean denyClientCert; 133 134 /** 135 * True iff a client cert has been sent to the server - i.e. this 136 * socket has been client-cert authenticated. 137 */ 138 [infallible] readonly attribute boolean clientCertSent; 139 140 /* 141 * failedVerification is true if any enforced certificate checks have failed. 142 * Connections that have not yet tried to verify, or are using acceptable 143 * exceptions will all return false. 144 */ 145 [infallible] readonly attribute boolean failedVerification; 146 147 /* 148 * esniTxt is a string that consists of the concatenated _esni. TXT records. 149 * This is a base64 encoded ESNIKeys structure. 150 */ 151 attribute ACString esniTxt; 152 153 /* 154 * echConfig is defined for conveying the ECH configuration. 155 * This is encoded in base64. 156 */ 157 attribute ACString echConfig; 158 159 /** 160 * The echConfig that should be used to retry for the connection setup. 161 */ 162 readonly attribute ACString retryEchConfig; 163 164 /** 165 * Disable early data. 166 */ 167 [noscript] void disableEarlyData(); 168 169 [noscript] void setHandshakeCallbackListener(in nsITlsHandshakeCallbackListener callback); 170 171 /** 172 * The id used to uniquely identify the connection to the peer. 173 */ 174 readonly attribute ACString peerId; 175 176 /** 177 * The securityInfo of the TLS handshake. 178 */ 179 readonly attribute nsITransportSecurityInfo securityInfo; 180 181 /** 182 * Asynchronously obtain the securityInfo of the TLS handshake. Resolves 183 * with an nsITransportSecurityInfo. This should probably only be used in 184 * tests, where JS running on the main thread cannot access any of the 185 * other fields of nsITLSSocketControl. 186 */ 187 [implicit_jscontext, must_use] 188 Promise asyncGetSecurityInfo(); 189 190 /** 191 * Claim a speculative connection. 192 */ 193 void claim(); 194 195 /** 196 * The top-level outer content window ID (called "browserId" in networking 197 * code) associated with this connection, if any (otherwise, 0). Useful for 198 * associating this connection with a browser tab in order to show UI (e.g. 199 * the client authentication certificate selection dialog). 200 */ 201 attribute uint64_t browserId; 202 };