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
7interface nsIX509Cert;
8interface nsITLSServerSecurityObserver;
9interface nsISocketTransport;
10
11[scriptable, uuid(cc2c30f9-cfaa-4b8a-bd44-c24881981b74)]
12interface 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   * setCipherSuites
57   *
58   * The server's cipher suites that is used by the TLS handshake.
59   * This is required to be set before calling |asyncListen|.
60   */
61  void setCipherSuites([array, size_is(aLength)] in unsigned short aCipherSuites,
62                       in unsigned long aLength);
63
64  /**
65   * setVersionRange
66   *
67   * The server's TLS versions that is used by the TLS handshake.
68   * This is required to be set before calling |asyncListen|.
69   *
70   * aMinVersion and aMaxVersion is a TLS version value from
71   * |nsITLSClientStatus| constants.
72   */
73  void setVersionRange(in unsigned short aMinVersion,
74                       in unsigned short aMaxVersion);
75};
76
77/**
78 * Security summary for a given TLS client connection being handled by a
79 * |nsITLSServerSocket| server.
80 *
81 * This is accessible through the security info object on the transport, which
82 * will be an instance of |nsITLSServerConnectionInfo| (see below).
83 *
84 * The values of these attributes are available once the |onHandshakeDone|
85 * method of the security observer has been called (see
86 * |nsITLSServerSecurityObserver| below).
87 */
88[scriptable, uuid(19668ea4-e5ad-4182-9698-7e890d48f327)]
89interface nsITLSClientStatus : nsISupports
90{
91  /**
92   * peerCert
93   *
94   * The client's certificate, if one was requested via |requestCertificate|
95   * above and supplied by the client.
96   */
97  readonly attribute nsIX509Cert peerCert;
98
99  /**
100   * Values for tlsVersionUsed, as defined by TLS
101   */
102  const short SSL_VERSION_3   = 0x0300;
103  const short TLS_VERSION_1   = 0x0301;
104  const short TLS_VERSION_1_1 = 0x0302;
105  const short TLS_VERSION_1_2 = 0x0303;
106  const short TLS_VERSION_1_3 = 0x0304;
107  const short TLS_VERSION_UNKNOWN = -1;
108
109  /**
110   * tlsVersionUsed
111   *
112   * The version of TLS used by the connection.  See values above.
113   */
114  readonly attribute short tlsVersionUsed;
115
116  /**
117   * cipherName
118   *
119   * Name of the cipher suite used, such as
120   * "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256".
121   * See security/nss/lib/ssl/sslinfo.c for the possible values.
122   */
123  readonly attribute ACString cipherName;
124
125  /**
126   * keyLength
127   *
128   * The "effective" key size of the symmetric key in bits.
129   */
130  readonly attribute unsigned long keyLength;
131
132  /**
133   * macLength
134   *
135   * The size of the MAC in bits.
136   */
137  readonly attribute unsigned long macLength;
138};
139
140/**
141 * Connection info for a given TLS client connection being handled by a
142 * |nsITLSServerSocket| server.  This object is thread-safe.
143 *
144 * This is exposed as the security info object on the transport, so it can be
145 * accessed via |transport.securityInfo|.
146 *
147 * This interface is available by the time the |onSocketAttached| is called,
148 * which is the first time the TLS server consumer is notified of a new client.
149 */
150[scriptable, uuid(8a93f5d5-eddd-4c62-a4bd-bfd297653184)]
151interface nsITLSServerConnectionInfo : nsISupports
152{
153  /**
154   * setSecurityObserver
155   *
156   * Set the security observer to be notified when the TLS handshake has
157   * completed.
158   */
159  void setSecurityObserver(in nsITLSServerSecurityObserver observer);
160
161  /**
162   * serverSocket
163   *
164   * The nsITLSServerSocket instance that accepted this client connection.
165   */
166  readonly attribute nsITLSServerSocket serverSocket;
167
168  /**
169   * status
170   *
171   * Security summary for this TLS client connection.  Note that the values of
172   * this interface are not available until the TLS handshake has completed.
173   * See |nsITLSClientStatus| above for more details.
174   */
175  readonly attribute nsITLSClientStatus status;
176};
177
178[scriptable, uuid(1f62e1ae-e546-4a38-8917-d428472ed736)]
179interface nsITLSServerSecurityObserver : nsISupports
180{
181  /**
182   * onHandsakeDone
183   *
184   * This method is called once the TLS handshake is completed.  This takes
185   * place after |onSocketAccepted| has been called, which typically opens the
186   * streams to keep things moving along. It's important to be aware that the
187   * handshake has not completed at the point that |onSocketAccepted| is called,
188   * so no security verification can be done until this method is called.
189   */
190  void onHandshakeDone(in nsITLSServerSocket aServer,
191                       in nsITLSClientStatus aStatus);
192};
193