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   * 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)]
80interface 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)]
142interface 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)]
170interface 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};
184