security/manager/ssl/nsITLSSocketControl.idl

   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 };