index.rst (15133B)
1 .. _mozilla_projects_nss_ssl_functions_sslintro: 2 3 sslintro 4 ======== 5 6 .. container:: 7 8 .. note:: 9 10 - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that 11 we are migrating into the format described in the `MDN Style 12 Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are 13 inclined to help with this migration, your help would be very much appreciated. 14 15 - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` 16 17 .. rubric:: Overview of an SSL Application 18 :name: Overview_of_an_SSL_Application 19 20 -------------- 21 22 .. _chapter_1_overview_of_an_ssl_application: 23 24 `Chapter 1 25 <#chapter_1_overview_of_an_ssl_application>`__ Overview of an SSL Application 26 ------------------------------------------------------------------------------ 27 28 .. container:: 29 30 SSL and related APIs allow compliant applications to configure sockets for authenticated, 31 tamper-proof, and encrypted communications. This chapter introduces some of the basic SSL 32 functions. `Chapter 2, "Getting Started With SSL" <gtstd.html#1005439>`__ illustrates their use 33 in sample client and server applications. 34 35 An SSL application typically includes five parts: 36 37 | `Initialization <#1027662>`__ 38 | `Configuration <#1027742>`__ 39 | `Communication <#1027816>`__ 40 | `Functions Used by Callbacks <#1027820>`__ 41 | `Cleanup <#1030535>`__ 42 43 Although the details differ somewhat for client and server applications, the concepts and many of 44 the functions are the same for both. 45 46 **WARNING:** Some of the SSL header files provided as part of NSS 2.0 include both public APIs 47 documented in the NSS 2.0 documentation set and private APIs intended for internal use by the 48 NSS implementation of SSL. You should use only the SSL APIs (and related certificate, key, and 49 PKCS #11 APIs) that are described in this document, the SSL Reference. Other APIs that may be 50 exposed in the header files are not supported for application use. 51 52 .. _initialization_2: 53 54 ` <#initialization_2>`__ Initialization 55 --------------------------------------- 56 57 .. container:: 58 59 Initialization includes setting up configuration files, setting global defaults, and setting up 60 callback functions. Functions used in the initialization part of an application can include the 61 following: 62 63 - ``PR_Init``. Initializes NSPR. Must be called before any other NSS functions. 64 - ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__. Sets the global callback function to 65 obtain passwords for PKCS #11 modules. Required. 66 - ``NSS_Init``. Sets up configuration files and performs other tasks required to run Network 67 Security Services. ``NSS_Init`` is *not* idempotent, so call it only once. Required. 68 - ``SSL_OptionSetDefault``. Changes default values for all subsequently opened sockets as long 69 as the application is running (compare with 70 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` which only configures the socket that 71 is currently open). This function must be called once for each default value that needs to be 72 changed. Optional. 73 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530`, 74 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285`, 75 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952`, or 76 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647`. These functions tell the library 77 which cipher suites are permitted by policy (for example, to comply with export restrictions). 78 Cipher suites disabled by policy cannot be enabled by user preference. One of these functions 79 must be called before any cryptographic operations can be performed with NSS. 80 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747`. Enables all ciphers chosen by user 81 preference. Optional. 82 83 .. _initializing_caches: 84 85 `Initializing Caches <#initializing_caches>`__ 86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 88 .. container:: 89 90 SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of 91 repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a 92 session cache, which retains information about each connection, such as the master secret 93 generated during the SSL handshake, for a predetermined length of time. If SSL can locate the 94 information about a previous connection in the local session cache, it can reestablish the 95 connection much more quickly than it can without the connection information. 96 97 By default, SSL allocates one session cache. This default cache is called the *client session ID 98 cache*, (also known as the client session cache, or simply the client cache). The client cache is 99 used for all sessions where the program handshakes as an SSL client. It is not configurable. You 100 can initialize the client cache with the function 101 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`. 102 103 If an application will use SSL sockets that handshake as a server, you must specifically create 104 and configure a server cache, using either 105 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` or 106 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. The server cache is used for all 107 sessions where the program handshakes as an SSL server. 108 109 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`. Clears all sessions from the client 110 session cache. Optional. 111 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`. Sets up parameters for a server 112 session cache for a single-process application. Required for single-process server 113 applications. 114 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. Sets up parameters for a server 115 cache for a multi-process application. Required for multi-process server applications. You can 116 use either this function or :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`, not 117 both. 118 119 .. _configuration_2: 120 121 ` <#configuration_2>`__ Configuration 122 ------------------------------------- 123 124 .. container:: 125 126 The configuration portion of an SSL-enabled application typically begins by opening a new socket 127 and then importing the new socket into the SSL environment: 128 129 - ``PR_NewTCPSocket``. Opens a new socket. A legal NSPR socket is required to be passed to 130 ``SSL_ImportFD``, whether it is created with this function or by another method. 131 - ``SSL_ImportFD``. Makes an NSPR socket into an SSL socket. Required. Brings an ordinary NSPR 132 socket into the SSL library, returning a new NSPR socket that can be used to make SSL calls. 133 You can pass this function a *model* file descriptor to create the new SSL socket with the 134 same configuration state as the model. 135 136 It is also possible for an application to import a socket into SSL after the TCP connection on 137 that socket has already been established. In this case, initial configuration takes place in the 138 same way: pass the existing NSPR file descriptor to ``SSL_ImportFD`` and perform any additional 139 configuration that has not already been determined by the model file descriptor. 140 141 Configuration functions control the configuration of an individual socket. 142 143 - ``PR_GetSocketOption``. Retrieves the socket options currently set for a specified socket. 144 Optional. 145 - ``PR_SetSocketOption``. Sets the socket options for a specified socket., including making it 146 blocking or nonblocking. Optional. 147 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543`. Sets a single configuration 148 parameter of a specified socket. This function must be called once for each parameter whose 149 settings you want to change from those established with ``SSL_OptionSetDefault``. Optional. 150 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647`. For servers only. Configures the 151 socket with the information needed to handshake as an SSL server. Required for servers. 152 - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792`. For clients only. Records the 153 target server URL for comparison with the URL specified by the server certificate. Required 154 for clients. 155 156 Callbacks and helper functions allow you to specify such things as how authentication is 157 accomplished and what happens if it fails. 158 159 - ``SSL_SetPKCS11PinArg``. Sets the argument passed to the PKCS #11 password callback function. 160 Required. 161 - ``SSL_AuthCertificateHook``. Specifies a callback function used to authenticate an incoming 162 certificate (optional for servers, necessary for clients to avoid "man-in-the-middle" 163 attacks). Optional. If not specified, SSL uses the default callback function, 164 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888`. 165 - ``SSL_BadCertHook``. Specifies a callback function to deal with a situation where 166 authentication has failed. Optional. 167 - ``SSL_GetClientAuthDataHook``. Specifies a callback function for SSL to use when the server 168 asks for client authentication information. This callback is required if you want to do client 169 authentication. You can set the callback function to a standard one that is provided, 170 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762`. 171 - ``SSL_HandshakeCallback``. Specifies a callback function that will be used by SSL to inform 172 either a client application or a server application when the SSL handshake is completed. 173 Optional. 174 175 .. _communication_2: 176 177 ` <#communication_2>`__ Communication 178 ------------------------------------- 179 180 .. container:: 181 182 At this point the application has set up the socket to communicate using SSL. For simple 183 encrypted and authenticated communications, no further calls to SSL functions are required. A 184 variety of additional SSL functions are available, however. These can be used, for example, when 185 interrupting and restarting socket communications, when the application needs to change socket 186 parameters, or when an application imports a socket into SSL after the TCP connection on that 187 socket has already been established. 188 189 Communication between SSL sockets always begins with the SSL handshake. The handshake occurs 190 automatically the first time communication is requested with a socket read/write or send/receive 191 call. It is also possible to force the handshake explicitly with 192 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` or repeat it explicitly with 193 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052`. 194 195 Once the SSL sockets have been configured, authentication and encryption happen automatically 196 whenever you use the communication functions from the NSPR library. 197 198 A server application typically uses these functions to establish a connection: 199 200 ``PR_Bind PR_Listen PR_Accept PR_GetSockName`` 201 202 A client application typically uses these functions to establish a connection: 203 204 | ``PR_GetHostByName`` 205 | ``PR_EnumerateHostEnt`` 206 | ``PR_Connect`` 207 | ``PR_GetConnectStatus`` 208 209 When an application imports a socket into SSL after the TCP connection on that socket has already 210 been established, it must call :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` to 211 determine whether SSL should behave like an SSL client or an SSL server. Note that this step 212 would not be necessary if the socket weren't already connected. For an SSL socket that is 213 configured before it is connected, SSL figures this out when the application calls ``PR_Connect`` 214 or ``PR_Accept``. If the socket is already connected before SSL gets involved, you must provide 215 this extra hint. 216 217 Functions that can be used by both clients and servers during communication include the 218 following: 219 220 | ``PR_Send`` or ``PR_Write`` 221 | ``PR_Read`` or ``PR_Recv`` 222 | ``PR_GetError`` 223 | ``PR_GetPeerName`` 224 | ``PR_Sleep`` 225 | ``PR_Malloc`` 226 | ``PR_Free`` 227 | ``PR_Poll`` 228 | ``PR_Now`` 229 | ``PR_IntervalToMilliseconds`` 230 | ``PR_MillisecondsToInterval`` 231 | ``PR_Shutdown`` 232 | ``PR_Close`` 233 | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420` 234 235 After establishing a connection, an application first calls ``PR_Send``, ``PR_Recv``, 236 ``PR_Read``, ``PR_Write``, or ``SSL_ForceHandshake`` to initiate the handshake. The application's 237 protocol (for example, HTTP) determines which end has responsibility to talk first. The end that 238 has to talk first should call ``PR_Send`` or ``PR_Write``, and the other end should call 239 ``PR_Read`` or ``PR_Recv``. 240 241 Use :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` when the socket has been prepared 242 for a handshake but neither end has anything to say immediately. This occurs, for example, when 243 an HTTPS server has received a request and determines that before it can answer the request, it 244 needs to request an authentication certificate from the client. At the HTTP protocol level, 245 nothing more is being said (that is, no HTTP request or response is being sent), so the server 246 first uses :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` to begin a new handshake and 247 then call ``SSL_ForceHandshake`` to drive the handshake to completion. 248 249 .. _functions_used_by_callbacks: 250 251 `Functions Used by Callbacks <#functions_used_by_callbacks>`__ 252 -------------------------------------------------------------- 253 254 .. container:: 255 256 An SSL application typically provides one or more callback functions that are called by the SSL 257 or PKCS #11 library code under certain circumstances. Numerous functions provided by the NSS 258 libraries are useful for such application callback functions, including these: 259 260 | ```CERT_CheckCertValidTimes`` <sslcrt.html#1056662>`__ 261 | ```CERT_GetDefaultCertDB`` <sslcrt.html#1052308>`__ 262 | ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ 263 | ```CERT_DupCertificate`` <sslcrt.html#1058344>`__ 264 | ```CERT_FindCertByName`` <sslcrt.html#1050345>`__ 265 | ```CERT_FreeNicknames`` <sslcrt.html#1050349>`__ 266 | ```CERT_GetCertNicknames`` <sslcrt.html#1050346>`__ 267 | ```CERT_VerifyCertName`` <sslcrt.html#1050342>`__ 268 | ```CERT_VerifyCertNow`` <sslcrt.html#1058011>`__ 269 | ```PK11_FindCertFromNickname`` <pkfnc.html#1035673>`__ 270 | ```PK11_FindKeyByAnyCert`` <pkfnc.html#1026891>`__ 271 | ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ 272 | ``PL_strcpy`` 273 | ``PL_strdup`` 274 | ``PL_strfree`` 275 | ``PL_strlen`` 276 | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168` 277 | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` 278 | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` 279 280 .. _cleanup_2: 281 282 ` <#cleanup_2>`__ Cleanup 283 ------------------------- 284 285 .. container:: 286 287 This portion of an SSL-enabled application consists primarily of closing the socket and freeing 288 memory. After these tasks have been performed, call 289 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061858` to close the certificate and key 290 databases opened by :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`, and ``PR_Cleanup`` 291 to coordinate a graceful shutdown of NSPR.