netwerk/base/nsITLSServerSocket.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsIServerSocket.idl"
   6
   7 interface nsIX509Cert;
   8 interface nsITLSServerSecurityObserver;
   9 interface nsISocketTransport;
  10
  11 [scriptable, uuid(cc2c30f9-cfaa-4b8a-bd44-c24881981b74)]
  12 interface nsITLSServerSocket : nsIServerSocket
  13 {
  14   /**
  15    * serverCert
  16    *
  17    * The server's certificate that is presented to the client during the TLS
  18    * handshake.  This is required to be set before calling |asyncListen|.
  19    */
  20   attribute nsIX509Cert serverCert;
  21
  22   /**
  23    * setSessionTickets
  24    *
  25    * Whether the server should support session tickets.  Defaults to true.  This
  26    * should be set before calling |asyncListen| if you wish to change the
  27    * default.
  28    */
  29   void setSessionTickets(in boolean aSessionTickets);
  30
  31   /**
  32    * Values for setRequestClientCertificate
  33    */
  34   // Never request
  35   const unsigned long REQUEST_NEVER           = 0;
  36   // Request (but do not require) during the first handshake only
  37   const unsigned long REQUEST_FIRST_HANDSHAKE = 1;
  38   // Request (but do not require) during each handshake
  39   const unsigned long REQUEST_ALWAYS          = 2;
  40   // Require during the first handshake only
  41   const unsigned long REQUIRE_FIRST_HANDSHAKE = 3;
  42   // Require during each handshake
  43   const unsigned long REQUIRE_ALWAYS          = 4;
  44
  45   /**
  46    * setRequestClientCertificate
  47    *
  48    * Whether the server should request and/or require a client auth certificate
  49    * from the client.  Defaults to REQUEST_NEVER.  See the possible options
  50    * above.  This should be set before calling |asyncListen| if you wish to
  51    * change the default.
  52    */
  53   void setRequestClientCertificate(in unsigned long aRequestClientCert);
  54
  55   /**
  56    * setVersionRange
  57    *
  58    * The server's TLS versions that is used by the TLS handshake.
  59    * This is required to be set before calling |asyncListen|.
  60    *
  61    * aMinVersion and aMaxVersion is a TLS version value from
  62    * |nsITLSClientStatus| constants.
  63    */
  64   void setVersionRange(in unsigned short aMinVersion,
  65                        in unsigned short aMaxVersion);
  66 };
  67
  68 /**
  69  * Security summary for a given TLS client connection being handled by a
  70  * |nsITLSServerSocket| server.
  71  *
  72  * This is accessible through the security info object on the transport, which
  73  * will be an instance of |nsITLSServerConnectionInfo| (see below).
  74  *
  75  * The values of these attributes are available once the |onHandshakeDone|
  76  * method of the security observer has been called (see
  77  * |nsITLSServerSecurityObserver| below).
  78  */
  79 [scriptable, uuid(19668ea4-e5ad-4182-9698-7e890d48f327)]
  80 interface nsITLSClientStatus : nsISupports
  81 {
  82   /**
  83    * peerCert
  84    *
  85    * The client's certificate, if one was requested via |requestCertificate|
  86    * above and supplied by the client.
  87    */
  88   readonly attribute nsIX509Cert peerCert;
  89
  90   /**
  91    * Values for tlsVersionUsed, as defined by TLS
  92    */
  93   const short SSL_VERSION_3   = 0x0300;
  94   const short TLS_VERSION_1   = 0x0301;
  95   const short TLS_VERSION_1_1 = 0x0302;
  96   const short TLS_VERSION_1_2 = 0x0303;
  97   const short TLS_VERSION_1_3 = 0x0304;
  98   const short TLS_VERSION_UNKNOWN = -1;
  99
 100   /**
 101    * tlsVersionUsed
 102    *
 103    * The version of TLS used by the connection.  See values above.
 104    */
 105   readonly attribute short tlsVersionUsed;
 106
 107   /**
 108    * cipherName
 109    *
 110    * Name of the cipher suite used, such as
 111    * "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256".
 112    * See security/nss/lib/ssl/sslinfo.c for the possible values.
 113    */
 114   readonly attribute ACString cipherName;
 115
 116   /**
 117    * keyLength
 118    *
 119    * The "effective" key size of the symmetric key in bits.
 120    */
 121   readonly attribute unsigned long keyLength;
 122
 123   /**
 124    * macLength
 125    *
 126    * The size of the MAC in bits.
 127    */
 128   readonly attribute unsigned long macLength;
 129 };
 130
 131 /**
 132  * Connection info for a given TLS client connection being handled by a
 133  * |nsITLSServerSocket| server.  This object is thread-safe.
 134  *
 135  * This is exposed as the security info object on the transport, so it can be
 136  * accessed via |transport.securityInfo|.
 137  *
 138  * This interface is available by the time the |onSocketAttached| is called,
 139  * which is the first time the TLS server consumer is notified of a new client.
 140  */
 141 [scriptable, uuid(8a93f5d5-eddd-4c62-a4bd-bfd297653184)]
 142 interface nsITLSServerConnectionInfo : nsISupports
 143 {
 144   /**
 145    * setSecurityObserver
 146    *
 147    * Set the security observer to be notified when the TLS handshake has
 148    * completed.
 149    */
 150   void setSecurityObserver(in nsITLSServerSecurityObserver observer);
 151
 152   /**
 153    * serverSocket
 154    *
 155    * The nsITLSServerSocket instance that accepted this client connection.
 156    */
 157   readonly attribute nsITLSServerSocket serverSocket;
 158
 159   /**
 160    * status
 161    *
 162    * Security summary for this TLS client connection.  Note that the values of
 163    * this interface are not available until the TLS handshake has completed.
 164    * See |nsITLSClientStatus| above for more details.
 165    */
 166   readonly attribute nsITLSClientStatus status;
 167 };
 168
 169 [scriptable, uuid(1f62e1ae-e546-4a38-8917-d428472ed736)]
 170 interface nsITLSServerSecurityObserver : nsISupports
 171 {
 172   /**
 173    * onHandsakeDone
 174    *
 175    * This method is called once the TLS handshake is completed.  This takes
 176    * place after |onSocketAccepted| has been called, which typically opens the
 177    * streams to keep things moving along. It's important to be aware that the
 178    * handshake has not completed at the point that |onSocketAccepted| is called,
 179    * so no security verification can be done until this method is called.
 180    */
 181   void onHandshakeDone(in nsITLSServerSocket aServer,
 182                        in nsITLSClientStatus aStatus);
 183 };