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     void proxyStartSSL();
  27     void StartTLS();
  28
  29     /* NPN (Next Protocol Negotiation) is a mechanism for
  30        negotiating the protocol to be spoken inside the SSL
  31        tunnel during the SSL handshake. The NPNList is the list
  32        of offered client side protocols. setNPNList() needs to
  33        be called before any data is read or written (including the
  34        handshake to be setup correctly. The server determines the
  35        priority when multiple matches occur, but if there is no overlap
  36        the first protocol in the list is used. */
  37
  38     [noscript] void setNPNList(in nsCStringTArrayRef aNPNList);
  39
  40     /* For 0RTT we need to know the alpn protocol selected for the last tls
  41      * session. This function will return a value if applicable or an error
  42      * NS_ERROR_NOT_AVAILABLE.
  43      */
  44     ACString getAlpnEarlySelection();
  45
  46     /* If 0RTT handshake was applied and some data has been sent, as soon as
  47      * the handshake finishes this attribute will be set to appropriate value.
  48      */
  49     readonly attribute bool earlyDataAccepted;
  50
  51     /* When 0RTT is performed, PR_Write will not drive the handshake forward.
  52      * It must be forced by calling this function.
  53      */
  54     void driveHandshake();
  55
  56     /* Determine if a potential SSL connection to hostname:port with
  57      * a desired NPN negotiated protocol of npnProtocol can use the socket
  58      * associated with this object instead of making a new one. And if so, combine
  59      * them.
  60      */
  61     boolean joinConnection(
  62       in ACString npnProtocol, /* e.g. "h2" */
  63       in ACString hostname,
  64       in long port);
  65
  66     /* just like JoinConnection() except do not mark a successful test as joined.
  67      */
  68     boolean testJoinConnection(
  69       in ACString npnProtocol, /* e.g. "h2" */
  70       in ACString hostname,
  71       in long port);
  72
  73     /* Determine if existing connection should be trusted to convey information about
  74      * a hostname.
  75      */
  76     boolean isAcceptableForHost(in ACString hostname);
  77
  78     /* The Key Exchange Algorithm is used when determining whether or
  79        not HTTP/2 can be used.
  80
  81        After a handshake is complete it can be read from KEAUsed.
  82        The values correspond to the SSLKEAType enum in NSS or the
  83        KEY_EXCHANGE_UNKNOWN constant defined below.
  84
  85        KEAKeyBits is the size/security-level used for the KEA.
  86     */
  87
  88     [infallible] readonly attribute short KEAUsed;
  89     [infallible] readonly attribute unsigned long KEAKeyBits;
  90
  91     const short KEY_EXCHANGE_UNKNOWN = -1;
  92
  93     /*
  94      * The original flags from the socket provider.
  95      */
  96     readonly attribute uint32_t providerFlags;
  97
  98     /* These values are defined by TLS. */
  99     const short SSL_VERSION_3   = 0x0300;
 100     const short TLS_VERSION_1   = 0x0301;
 101     const short TLS_VERSION_1_1 = 0x0302;
 102     const short TLS_VERSION_1_2 = 0x0303;
 103     const short TLS_VERSION_1_3 = 0x0304;
 104     const short SSL_VERSION_UNKNOWN = -1;
 105
 106     [infallible] readonly attribute short SSLVersionUsed;
 107     [infallible] readonly attribute short SSLVersionOffered;
 108
 109     /* These values match the NSS defined values in sslt.h */
 110     const short SSL_MAC_UNKNOWN = -1;
 111     const short SSL_MAC_NULL    = 0;
 112     const short SSL_MAC_MD5     = 1;
 113     const short SSL_MAC_SHA     = 2;
 114     const short SSL_HMAC_MD5    = 3;
 115     const short SSL_HMAC_SHA    = 4;
 116     const short SSL_HMAC_SHA256 = 5;
 117     const short SSL_MAC_AEAD    = 6;
 118
 119     [infallible] readonly attribute short MACAlgorithmUsed;
 120
 121     /**
 122      * If set to true before the server requests a client cert
 123      * no cert will be sent.
 124      */
 125     [notxpcom, nostdcall] attribute boolean denyClientCert;
 126
 127     /**
 128      * True iff a client cert has been sent to the server - i.e. this
 129      * socket has been client-cert authenticated.
 130      */
 131     [infallible] readonly attribute boolean clientCertSent;
 132
 133     /*
 134      * failedVerification is true if any enforced certificate checks have failed.
 135      * Connections that have not yet tried to verify, or are using acceptable
 136      * exceptions will all return false.
 137      */
 138     [infallible] readonly attribute boolean failedVerification;
 139
 140     /*
 141      * esniTxt is a string that consists of the concatenated _esni. TXT records.
 142      * This is a base64 encoded ESNIKeys structure.
 143      */
 144     attribute ACString esniTxt;
 145
 146     /*
 147      * echConfig is defined for conveying the ECH configuration.
 148      * This is encoded in base64.
 149      */
 150     attribute ACString echConfig;
 151
 152     /**
 153      * The echConfig that should be used to retry for the connection setup.
 154      */
 155     readonly attribute ACString retryEchConfig;
 156
 157     /**
 158      * Disable early data.
 159      */
 160     [noscript] void disableEarlyData();
 161
 162     [noscript] void setHandshakeCallbackListener(in nsITlsHandshakeCallbackListener callback);
 163
 164     /**
 165      * The id used to uniquely identify the connection to the peer.
 166      */
 167     readonly attribute ACString peerId;
 168
 169     /**
 170      * The securityInfo of the TLS handshake.
 171      */
 172     readonly attribute nsITransportSecurityInfo securityInfo;
 173
 174     /**
 175      * Asynchronously obtain the securityInfo of the TLS handshake. Resolves
 176      * with an nsITransportSecurityInfo. This should probably only be used in
 177      * tests, where JS running on the main thread cannot access any of the
 178      * other fields of nsITLSSocketControl.
 179      */
 180     [implicit_jscontext, must_use]
 181     Promise asyncGetSecurityInfo();
 182
 183     /**
 184      * Claim a speculative connection.
 185      */
 186     void claim();
 187 };