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