nsITLSServerSocket.idl (5745B)
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, builtinclass, 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 };