index.rst (183685B)
1 .. _mozilla_projects_nss_ssl_functions_sslfnc: 2 3 sslfnc 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/MDN/Guidelines>`__. If you are inclined to 13 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:: SSL Functions 18 :name: SSL_Functions 19 20 -------------- 21 22 .. _chapter_4_ssl_functions: 23 24 `Chapter 4 SSL Functions <#chapter_4_ssl_functions>`__ 25 ------------------------------------------------------ 26 27 .. container:: 28 29 This chapter describes the core SSL functions. 30 31 - `SSL Initialization Functions <#ssl_initialization_functions>`__ 32 - `SSL Export Policy Functions <#ssl_export_policy_functions>`__ 33 - `SSL Configuration Functions <#ssl_configuration_functions>`__ 34 - `SSL Communication Functions <#ssl_communication_functions>`__ 35 - `SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__ 36 - `SSL Handshake Functions <#ssl_handshake_functions>`__ 37 - `NSS Shutdown Function <#nss_shutdown_function>`__ 38 - `Deprecated Functions <#deprecated_functions>`__ 39 40 .. _ssl_initialization_functions: 41 42 `SSL Initialization Functions <#ssl_initialization_functions>`__ 43 ---------------------------------------------------------------- 44 45 .. container:: 46 47 This section describes the initialization functions that are specific to SSL. For a complete list 48 of NSS initialization functions, see `Initialization <sslintro.html#1027662>`__. 49 50 Note that at least one of the functions listed in `SSL Export Policy Functions <#1098841>`__ must 51 also be called during NSS initialization. 52 53 | ```NSS_Init`` <#1067601>`__ 54 | ```NSS_InitReadWrite`` <#1237143>`__ 55 | ```NSS_NoDB_Init`` <#1234224>`__ 56 | ```SSL_OptionSetDefault`` <#1068466>`__ 57 | ```SSL_OptionGetDefault`` <#1204897>`__ 58 | ```SSL_CipherPrefSetDefault`` <#1084747>`__ 59 | ```SSL_CipherPrefGetDefault`` <#1208119>`__ 60 | ```SSL_ClearSessionCache`` <#1138601>`__ 61 | ```SSL_ConfigServerSessionIDCache`` <#1143851>`__ 62 | ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ 63 | ```SSL_InheritMPServerSIDCache`` <#1162055>`__ 64 65 .. rubric:: NSS_Init 66 :name: nss_init 67 68 Sets up configuration files and performs other tasks required to run Network Security Services. 69 Database files are opened read-only. 70 71 .. rubric:: Syntax 72 :name: syntax 73 74 .. code:: 75 76 #include "nss.h" 77 78 .. code:: 79 80 SECStatus NSS_Init(char *configdir); 81 82 .. rubric:: Parameter 83 :name: parameter 84 85 This function has the following parameter: 86 87 +---------------+---------------------------------------------------------------------------------+ 88 | ``configdir`` | A pointer to a string containing the pathname of the directory where the | 89 | | certificate, key, and security module databases reside. | 90 +---------------+---------------------------------------------------------------------------------+ 91 92 .. rubric:: Returns 93 :name: returns 94 95 The function returns one of these value\ ``s``: 96 97 - If successful, ``SECSuccess``. 98 - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. 99 100 .. rubric:: Description 101 :name: description 102 103 ``NSS_Init`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db`` files 104 (where\ *N* is a numeric digit) in the specified directory. ``NSS_Init`` is\ *not* idempotent, so 105 call it only once. 106 107 ``NSS_Init`` opens the database files read-only. If you are performing operations that require 108 write permission, for example S/MIME operations such as adding a certificate, use 109 ```NSS_InitReadWrite`` <#1237143>`__ instead. 110 111 Before calling ``NSS_Init``, your program must call ``PR_Init``. 112 113 The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. 114 Therefore, an application cannot use NSS to perform any cryptographic operations until after it 115 enables appropriate cipher suites by calling one of the `SSL Export Policy 116 Functions <#1098841>`__: 117 118 - ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and 119 ```NSS_SetFrancePolicy`` <#1105952>`__ configure the cipher suites for domestic, 120 international, and French versions of software products with encryption features. 121 - ```SSL_CipherPolicySet`` <#1104647>`__ sets policy flags for individual cipher suites, one at 122 a time. This may be helpful if you have an export license that permits more or fewer 123 capabilities than those allowed by the other export policy functions. 124 125 .. rubric:: NSS_InitReadWrite 126 :name: nss_initreadwrite 127 128 Sets up configuration files and performs other tasks required to run Network Security Services. 129 Unlike ```NSS_Init`` <#1067601>`__, ``NSS_InitReadWrite`` provides both read and write access to 130 database files. 131 132 .. rubric:: Syntax 133 :name: syntax_2 134 135 .. code:: 136 137 #include "nss.h" 138 139 .. code:: 140 141 SECStatus NSS_InitReadWrite(char *configdir); 142 143 .. rubric:: Parameter 144 :name: parameter_2 145 146 This function has the following parameter: 147 148 +---------------+---------------------------------------------------------------------------------+ 149 | ``configdir`` | A pointer to a string containing the pathname of the directory where the | 150 | | certificate, key, and security module databases reside. | 151 +---------------+---------------------------------------------------------------------------------+ 152 153 .. rubric:: Returns 154 :name: returns_2 155 156 The function returns one of these value\ ``s``: 157 158 - If successful, ``SECSuccess``. 159 - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. 160 161 .. rubric:: Description 162 :name: description_2 163 164 ``NSS_InitReadWrite`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db`` 165 files (where\ *N* is a numeric digit) with both read and write permission in the specified 166 directory. ``NSS_InitReadWrite`` is\ *not* idempotent, so call it only once. 167 168 Use ``NSS_InitReadWrite`` rather than ```NSS_Init`` <#1067601>`__ if you are performing 169 operations that require write permission, such as some S/MIME operations. 170 171 Before calling ``NSS_InitReadWrite``, your program must call ``PR_Init``. 172 173 The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. 174 Therefore, an application cannot use NSS to perform any cryptographic operations until after it 175 enables appropriate cipher suites by calling one of the `SSL Export Policy 176 Functions <#1098841>`__. 177 178 .. rubric:: NSS_NoDB_Init 179 :name: nss_nodb_init 180 181 Performs tasks required to run Network Security Services without setting up configuration files. 182 **Important:** This NSS function is not intended for use with SSL, which requires that the 183 certificate and key database files be opened. 184 185 .. rubric:: Syntax 186 :name: syntax_3 187 188 .. code:: 189 190 #include "nss.h" 191 192 .. code:: 193 194 SECStatus NSS_NoDB_Init(char *reserved); 195 196 .. rubric:: Parameter 197 :name: parameter_3 198 199 This function has the following parameter: 200 201 ============ ==================== 202 ``reserved`` Should be ``NULL``.. 203 ============ ==================== 204 205 .. rubric:: Returns 206 :name: returns_3 207 208 The function returns one of these value\ ``s``: 209 210 - If successful, ``SECSuccess``. 211 - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. 212 213 .. rubric:: Description 214 :name: description_3 215 216 ``NSS_NoDB_Init`` opens only the temporary database and the internal PKCS #112 module. Unlike 217 ``NSS_Init``, ``NSS_NoDB_Init`` allows applications that do not have access to storage for 218 databases to run raw crypto, hashing, and certificate functions. 219 220 ``NSS_NoDB_Init`` is\ *not* idempotent, so call it only once. 221 222 Before calling ``NSS_NoDB_Init``, your program must call ``PR_Init``. 223 224 The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. 225 Therefore, an application cannot use NSS to perform any cryptographic operations until after it 226 enables appropriate cipher suites by calling one of the `SSL Export Policy 227 Functions <#1098841>`__. 228 229 .. rubric:: SSL_OptionSetDefault 230 :name: ssl_optionsetdefault 231 232 Changes the default value of a specified SSL option for all subsequently opened sockets as long 233 as the current application program is running. 234 235 ``SSL_OptionSetDefault`` replaces the deprecated function ```SSL_EnableDefault`` <#1206365>`__. 236 237 .. rubric:: Syntax 238 :name: syntax_4 239 240 .. code:: 241 242 #include "ssl.h" 243 244 .. code:: 245 246 SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on); 247 248 .. rubric:: Parameters 249 :name: parameters 250 251 This function has the following parameters: 252 253 +-------------------------------------------------+-------------------------------------------------+ 254 | ``option`` | One of the following values (except as noted, | 255 | | the factory setting is "off"): | 256 | | | 257 | | - ``SSL_SECURITY`` enables use of security | 258 | | protocol. Factory setting is on. WARNING: If | 259 | | you turn this option off, the session will | 260 | | not be an SSL session and will not have | 261 | | certificate-based authentication, tamper | 262 | | detection, or encryption. | 263 | | - ``SSL_REQUEST_CERTIFICATE`` is a server | 264 | | option that requests a client to | 265 | | authenticate itself. | 266 | | - ``SSL_REQUIRE_CERTIFICATE`` is a server | 267 | | option that requires a client to | 268 | | authenticate itself (only if | 269 | | ``SSL_REQUEST_CERTIFICATE`` is also on). If | 270 | | client does not provide certificate, the | 271 | | connection terminates. Default state is a | 272 | | third state similar to on, that provides | 273 | | backward compatibility with older Netscape | 274 | | server products. | 275 | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the | 276 | | behavior of ``PR_Accept``,. If this option | 277 | | is off, the ``PR_Accept`` configures the SSL | 278 | | socket to handshake as a server. If it is | 279 | | on, then ``PR_Accept`` configures the SSL | 280 | | socket to handshake as a client, even though | 281 | | it accepted the connection as a TCP server. | 282 | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the | 283 | | behavior of ``PR_Connect``. If this option | 284 | | is off, then ``PR_Connect`` configures the | 285 | | SSL socket to handshake as a client. If it | 286 | | is on, then ``PR_Connect`` configures the | 287 | | SSL socket to handshake as a server, even | 288 | | though it connected as a TCP client. | 289 | | - ``SSL_ENABLE_FDX`` tells the SSL library | 290 | | whether the application will have two | 291 | | threads, one reading and one writing, or | 292 | | just one thread doing reads and writes | 293 | | alternately. The factory setting for this | 294 | | option (which is the default, unless the | 295 | | application changes the default) is off | 296 | | (``PR_FALSE``), which means that the | 297 | | application will not do simultaneous reads | 298 | | and writes. An application that wishes to do | 299 | | sumultaneous reads and writes should set | 300 | | this to ``PR_TRUE``. | 301 | | | 302 | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only | 303 | | affects the behavior of non-blocking SSL | 304 | | sockets. See the description below for more | 305 | | information on this option. | 306 +-------------------------------------------------+-------------------------------------------------+ 307 | | - ``SSL_ENABLE_SSL3`` enables the application | 308 | | to communicate with SSL v3. Factory setting | 309 | | is on. If you turn this option off, an | 310 | | attempt to establish a connection with a | 311 | | peer that only understands SSL v3 will fail. | 312 | | - ``SSL_ENABLE_SSL2`` enables the application | 313 | | to communicate with SSL v2. Factory setting | 314 | | is on. If you turn this option off, an | 315 | | attempt to establish a connection with a | 316 | | peer that only understands SSL v2 will fail. | 317 | | - ``SSL_ENABLE_TLS`` is a peer of the | 318 | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` | 319 | | options. The IETF standard Transport Layer | 320 | | Security (TLS) protocol, RFC 2246, is a | 321 | | modified version of SSL3. It uses the SSL | 322 | | version number 3.1, appearing to be a | 323 | | "minor" revision of SSL 3.0. NSS 2.8 | 324 | | supports TLS in addition to SSL2 and SSL3. | 325 | | You can think of it as | 326 | | "``SSL_ENABLE_SSL3.1``". See the description | 327 | | below for more information about this | 328 | | option. | 329 | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL | 330 | | library whether or not to send SSL3 client | 331 | | hello messages in SSL2-compatible format. If | 332 | | set to ``PR_TRUE``, it will; otherwise, it | 333 | | will not. Factory setting is on | 334 | | (``PR_TRUE``). See the description below for | 335 | | more information on this option. | 336 | | - ``SSL_NO_CACHE`` disallows use of the | 337 | | session cache. Factory setting is off. If | 338 | | you turn this option on, this socket will be | 339 | | unable to resume a session begun by another | 340 | | socket. When this socket's session is | 341 | | finished, no other socket will be able to | 342 | | resume the session begun by this socket. | 343 | | - ``SSL_ROLLBACK_DETECTION`` disables | 344 | | detection of a rollback attack. Factory | 345 | | setting is on. You must turn this option off | 346 | | to interoperate with TLS clients ( such as | 347 | | certain versions of Microsoft Internet | 348 | | Explorer) that do not conform to the TLS | 349 | | specification regarding rollback attacks. | 350 | | Important: turning this option off means | 351 | | that your code will not comply with the TLS | 352 | | 3.1 and SSL 3.0 specifications regarding | 353 | | rollback attack and will therefore be | 354 | | vulnerable to this form of attack. | 355 +-------------------------------------------------+-------------------------------------------------+ 356 | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns | 357 | | option off. | 358 +-------------------------------------------------+-------------------------------------------------+ 359 360 .. rubric:: Returns 361 :name: returns_4 362 363 The function returns one of these values: 364 365 - If successful, ``SECSuccess``. 366 - If unsuccessful, ``SECFailure``. Use 367 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 368 to obtain the error code. 369 370 .. rubric:: Description 371 :name: description_4 372 373 This function changes the default values for all subsequently opened sockets as long as the 374 current application program is running. This function must be called once for each default value 375 you want to change from the factory setting. To change a value in a socket that is already open, 376 use ```SSL_OptionSet`` <#1086543>`__. 377 378 Keep the following in mind when deciding on the operating parameters you want to use with a 379 particular socket: 380 381 Enabling the ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no 382 certificate and this option is enabled, the client's connection terminates with an error. The 383 user is likely to think something is wrong with either the client or the server, and is unlikely 384 to realize that the problem is the lack of a certificate. It is better to allow the SSL handshake 385 to complete and then have your application return an error message to the client that informs the 386 user of the need for a certificate. 387 388 - As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a 389 socket into SSL after the TCP connection on that socket has already been established, it must 390 call ``SSL_ResetHandshake`` to determine whether the socket is for a client or server. At 391 first glance this may seem unnecessary, since ``SSL_Enable`` can set 392 ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control 393 the behavior of 394 ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ 395 and 396 ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ 397 only; if you don't call one of those functions after importing a non-SSL socket with 398 ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to 399 know whether the application is functioning as a client or server. For a complete discussion 400 of the use of ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` with 401 ``SSL_EnableDefault`` and ``SSL_Enable``, see `SSL_OptionSet <#1086543>`__. 402 - The SSL protocol is defined to be able to handle simultaneous two-way communication between 403 applications at each end of an SSL connection. Two-way simultaneous communication is also 404 known as "Full Duplex", abbreviated FDX. However, most application protocols that use SSL are 405 not two-way simultaneous, but two-way alternate, also known as "Half Dupled"; that is, each 406 end takes turns sending, and each end is either sending, or receiving, but not both at the 407 same time. 408 409 For an application to do full duplex, it would typically have two threads sharing the socket; one 410 doing all the reading and the other doing all the writing. 411 412 The ``SSL_ENABLE_FDX`` option tells the SSL library whether the application will have two 413 threads, one reading and one writing, or just one thread doing reads and writes alternately. 414 415 - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello 416 messages in SSL2-compatible format. If an SSL3 client hello message is sent to a server that 417 only understands SSL2 and not SSL3, then the server will interpret the SSL3 client hello as a 418 very large message, and the connection will usually seem to "hang" while the SSL2 server 419 expects more data that will never arrive. For this reason, the SSL3 spec allows SSL3 client 420 hellos to be sent in SSL2 format, and it recommends that SSL3 servers all accept SSL3 client 421 hellos in SSL2 format. When an SSL2-only server receives an SSL3 client hello in SSL2 format, 422 it can (and probably will) negotiate the protocol version correctly, not causing a "hang". 423 424 Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in 425 SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does 426 not understand SSL2-compatible client hello messages. 427 428 Note that calling ``SSL_Enable`` to set ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly 429 also sets the ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that SSL socket. Calling 430 ``SSL_EnableDefault`` to change the application default setting for ``SSL_V2_COMPATIBLE_HELLO`` 431 to ``PR_FALSE`` implicitly also sets the default value for ``SSL_ENABLE_SSL2`` option to 432 ``PR_FALSE`` for that application. 433 434 - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set 435 to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 will negotiate the higest 436 protocol version with the peer application from among the set of protocols that are commonly 437 enabled in both applications. 438 439 Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled, 440 all SSL3/TLS ciphersuites that are enabled are enabled for both SSL3 and TLS. 441 442 .. rubric:: SSL_OptionGetDefault 443 :name: ssl_optiongetdefault 444 445 Gets the value of a specified SSL default option. 446 447 ``SSL_OptionGetDefault`` is the complementary function for 448 ```SSL_OptionSetDefault`` <#1068466>`__. 449 450 .. rubric:: Syntax 451 :name: syntax_5 452 453 .. code:: 454 455 #include "ssl.h" 456 457 .. code:: 458 459 SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on) 460 461 .. rubric:: Parameters 462 :name: parameters_2 463 464 This function has the parameters listed below. 465 466 +------------+------------------------------------------------------------------------------------+ 467 | ``option`` | The value of the option whose default setting you wish to get. For information | 468 | | about the options available and the possible values to pass in this parameter, see | 469 | | the description of the ``option`` parameter under | 470 | | ```SSL_OptionSetDefault`` <#1068466>`__. | 471 +------------+------------------------------------------------------------------------------------+ 472 | ``on`` | A pointer to the value of the option specified in the option parameter. | 473 | | ``PR_TRUE`` indicates that the option is on; ``PR_FALSE`` indicates that the | 474 | | option is off. | 475 +------------+------------------------------------------------------------------------------------+ 476 477 .. rubric:: Returns 478 :name: returns_5 479 480 The function returns one of these value\ ``s``: 481 482 - If successful, ``SECSuccess``. 483 - If unsuccessful, ``SECFailure``. Use 484 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 485 to obtain error code. 486 487 .. rubric:: Description 488 :name: description_5 489 490 ``SSL_CipherPrefGetDefault`` gets the application default preference for the specified SSL2, 491 SSL3, or TLS cipher A cipher suite is used only if the policy allows it and the preference for it 492 is set to ``PR_TRUE``. 493 494 .. rubric:: SSL_CipherPrefSetDefault 495 :name: ssl_cipherprefsetdefault 496 497 Enables or disables SSL2 or SSL3 cipher suites (subject to which cipher suites are permitted or 498 disallowed by previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__). 499 This function must be called once for each cipher you want to enable or disable by default. 500 501 .. rubric:: Syntax 502 :name: syntax_6 503 504 .. code:: 505 506 #include "ssl.h" 507 508 .. code:: 509 510 SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool enabled); 511 512 .. rubric:: Parameters 513 :name: parameters_3 514 515 This function has the following parameters: 516 517 +-------------------------------------------------+-------------------------------------------------+ 518 | ``cipher`` | One of the following values for SSL2 (factory | 519 | | settings for all are enabled): | 520 | | | 521 | | ``SSL_EN_RC4_128_WITH_ | 522 | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | 523 | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | 524 | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | 525 | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | 526 | | | 527 | | Or one of the following values for SSL3/TLS | 528 | | (unless indicated otherwise, factory settings | 529 | | for all are enabled): | 530 | | | 531 | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not | 532 | | enabled by default; client side only) | 533 | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not | 534 | | enabled by default; client side only) | 535 | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled | 536 | | by default) | 537 | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | 538 | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled | 539 | | by default; client side only) | 540 | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not | 541 | | enabled by default; client side only) | 542 | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not | 543 | | enabled by default; client side only) | 544 | | ``SSL_RSA_WITH_RC4_128_MD5`` | 545 | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by | 546 | | default) | 547 | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled | 548 | | by default) | 549 | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not | 550 | | enabled by default; client side only) | 551 | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not | 552 | | enabled by default; client side only) | 553 | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | 554 | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | 555 | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | 556 | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled | 557 | | by default; client side only) | 558 | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled | 559 | | by default; client side only) | 560 | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | 561 | | ``SSL_RSA_WITH_DES_CBC_SHA`` | 562 | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | 563 | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | 564 | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | 565 | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | 566 | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | 567 | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by | 568 | | default) | 569 | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by | 570 | | default) | 571 +-------------------------------------------------+-------------------------------------------------+ 572 | ``enabled`` | If nonzero, the specified cipher is enabled. If | 573 | | zero, the cipher is disabled. | 574 +-------------------------------------------------+-------------------------------------------------+ 575 576 .. rubric:: Returns 577 :name: returns_6 578 579 The function returns one of these values: 580 581 - If successful, ``SECSuccess``. 582 - If unsuccessful, ``SECFailure``. Use 583 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 584 to obtain the error code. 585 586 .. rubric:: Description 587 :name: description_6 588 589 The CipherPrefSetDefault function enables or disables individual cipher suites globally. You 590 typically call this in response to changes in user-controlled settings. You must call this 591 function once for each cipher you want to enable or disable. To enable or disable cipher suites 592 for an individual socket, use ```SSL_CipherPrefSet`` <#1214758>`__. 593 594 The set of available SSL cipher suites may grow from release to release of NSS. Applications will 595 find it desirable to determine, at run time, what SSL2 cipher kinds and SSL3 cipher suites are 596 actually implememted in a particular release. Applications may disable any cipher suites that 597 they don't know about (for example, that they cannot present to the user via a GUI). To that end, 598 NSS provides a table that can be examined at run time. All aspects of this table are declared in 599 ``ssl.h``. 600 601 ``SSL_ImplementedCiphers[]`` is an external array of unsigned 16-bit integers whose values are 602 either SSL2 cipher kinds or SSL3 cipher suites. The values are the same as the values used to 603 enable or disable a cipher suite via calls to ```SSL_CipherPrefSetDefault`` <#1084747>`__, and 604 are defined in ``sslproto.h``. The number of values in the table is contained in an external 605 16-bit integer named ``SSL_NumImplementedCiphers``. The macro ``SSL_IS_SSL2_CIPHER`` can be used 606 to determine whether a particular value is an SSL2 or an SSL3 cipher. 607 608 **WARNING**: Using the external array ``SSL_ImplementedCiphers[]`` directly is deprecated. It 609 causes dynamic linking issues at run-time after an update of NSS because the actual size of the 610 array changes between releases. The recommended way of accessing the array is through the 611 ``SSL_GetImplementedCiphers()`` and ``SSL_GetNumImplementedCiphers()`` accessors. 612 613 By default, all SSL2 and 12 SSL3/TLS cipher suites are enabled. However, this does not 614 necessarily mean that they are all permitted. The ``SSL_CipherPrefSetDefault`` function cannot 615 override cipher suite policy settings that are not permitted; see `SSL Export Policy 616 Functions <#1098841>`__ for details. Your application must call one of the export policy 617 functions before it can perform any cryptographic operations. 618 619 The ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` and ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` cipher 620 suites are defined in RFC 2246. They work with both SSL3 and TLS. They use symmetric ciphers with 621 an effective key size of 56 bits. The so-called 56-bit export browsers and servers use these 622 cipher suites. 623 624 The cipher suite numbers for the ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` and 625 ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` cipher suites have been changed so that they are no longer 626 "experimental" values. If an application attempts to set or set the policy or preference for one 627 of the old FIPS cipher suite numbers, the library recognizes the old number and sets or gets the 628 value for the new cipher suite number instead. 629 630 In this release, the three ``SSL_FORTEZZA_`` cipher suites cannot be enabled unless there is a 631 PKCS #11 module available with a FORTEZZA-enabled token. The ``SSL_FORTEZZA_`` cipher suites will 632 be removed in NSS 3.11. 633 634 .. rubric:: SSL_CipherPrefGetDefault 635 :name: ssl_cipherprefgetdefault 636 637 Gets the current default preference setting for a specified SSL2 or SSL3 cipher suite. 638 639 .. rubric:: Syntax 640 :name: syntax_7 641 642 .. code:: 643 644 #include "ssl.h" 645 646 .. code:: 647 648 SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool *enabled); 649 650 .. rubric:: Parameters 651 :name: parameters_4 652 653 This function has the parameters listed below. 654 655 +---------+---------------------------------------------------------------------------------------+ 656 | cipher | The cipher suite whose default preference setting you want to get. For a list of the | 657 | | cipher suites you can specify, see ```SSL_CipherPrefSetDefault`` <#1084747>`__. | 658 +---------+---------------------------------------------------------------------------------------+ 659 | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` | 660 | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is | 661 | | disabled. | 662 +---------+---------------------------------------------------------------------------------------+ 663 664 .. rubric:: Returns 665 :name: returns_7 666 667 The function returns one of these value\ ``s``: 668 669 - If successful, ``SECSuccess``. 670 - If unsuccessful, ``SECFailure``. Use 671 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 672 to obtain error code. 673 674 .. rubric:: Description 675 :name: description_7 676 677 ``SSL_CipherPrefGetDefault`` performs the complementary function to ``SSL_CipherPrefSetDefault``. 678 It returns the application process' current default preference value for the specified cipher 679 suite. If the application has not previously set the default preference, 680 ``SSL_CipherPrefGetDefault`` returns the factory setting. 681 682 .. rubric:: SSL_ClearSessionCache 683 :name: ssl_clearsessioncache 684 685 Empties the SSL client session ID cache. 686 687 .. rubric:: Syntax 688 :name: syntax_8 689 690 .. code:: 691 692 #include "ssl.h" 693 694 .. code:: 695 696 void SSL_ClearSessionCache(void); 697 698 .. rubric:: Description 699 :name: description_8 700 701 You must call ``SSL_ClearSessionCache`` after you use one of the `SSL Export Policy 702 Functions <#1098841>`__ to change cipher suite policy settings or use 703 ```SSL_CipherPrefSetDefault`` <#1084747>`__ to enable or disable any cipher suite. Otherwise, the 704 old settings remain in the session cache and will be used instead of the new settings. 705 706 This function clears only the client cache. The client cache is not configurable. It is located 707 in RAM (not on disk), and has the following characteristics: 708 709 - maximum number of entries: unlimited 710 - SSL 2.0 timeout value: 100 seconds 711 - SSL 3.0 timeout value: 24 hours 712 713 .. 714 715 **NOTE:** If an SSL client application does not call ``SSL_ClearSessionCache`` before 716 shutdown, ```NSS_Shutdown`` <#1061858>`__ fails with the error code ``SEC_ERROR_BUSY``. 717 718 .. rubric:: SSL_ConfigServerSessionIDCache 719 :name: ssl_configserversessionidcache 720 721 Sets up parameters for and opens the server session cache for a single-process application. 722 723 .. rubric:: Syntax 724 :name: syntax_9 725 726 .. code:: 727 728 #include "ssl.h" 729 730 .. code:: 731 732 SECStatus SSL_ConfigServerSessionIDCache( 733 int maxCacheEntries, 734 PRUint32 timeout, 735 PRUint32 ssl3_timeout, 736 const char *directory); 737 738 .. rubric:: Parameters 739 :name: parameters_5 740 741 This function has the parameters listed below. 742 743 +---------------------+---------------------------------------------------------------------------+ 744 | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is | 745 | | passed, the server default value of 10,000 is used. | 746 +---------------------+---------------------------------------------------------------------------+ 747 | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is | 748 | | 5 seconds and the maximum is 24 hours. Values outside this range are | 749 | | replaced by the server default value of 100 seconds. | 750 +---------------------+---------------------------------------------------------------------------+ 751 | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is | 752 | | 5 seconds and the maximum is 24 hours. Values outside this range are | 753 | | replaced by the server default value of 24 hours. | 754 +---------------------+---------------------------------------------------------------------------+ 755 | ``directory`` | A pointer to a string specifying the pathname of the directory that will | 756 | | contain the session cache. If a ``NULL`` value is passed, the server | 757 | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). | 758 +---------------------+---------------------------------------------------------------------------+ 759 760 .. rubric:: Returns 761 :name: returns_8 762 763 The function returns one of these value\ ``s``: 764 765 - If successful, ``SECSuccess``. 766 - If unsuccessful, ``SECFailure``. Use 767 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 768 to obtain error code. 769 770 .. rubric:: Description 771 :name: description_9 772 773 If you are writing an application that will use SSL sockets that handshake as a server, you must 774 call ``SSL_ConfigServerSessionIDCache`` to configure additional session caches for *server* 775 sessions. If your server application uses multiple processes (instead of or in addition to 776 multiple threads), use ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ instead. You must use one of 777 these functions to create a server cache. This function creates two caches: the\ *server session 778 ID cache* (also called the server session cache, or server cache), and the\ *client-auth 779 certificate cache* (also called the client cert cache, or client auth cache). Both caches are 780 used only for sessions where the program handshakes as a server. The client-auth certificate 781 cache is used to remember the certificates previously presented by clients for client certificate 782 authentication. 783 784 Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the 785 server default value to be used in the server cache. The values that you pass affect only the 786 server cache, not the client cache. 787 788 .. _initializing_multi-processing_with_a_shared_ssl_server_cache: 789 790 `Initializing Multi-Processing with a Shared SSL Server Cache <#initializing_multi-processing_with_a_shared_ssl_server_cache>`__ 791 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 792 793 .. container:: 794 795 To start a multi-processing application, the initial parent process calls 796 ```SSL_ConfigMPServerSIDCache`` <#1142625>`__, and then creates child processes, by one of these 797 methods: 798 799 - Call ``fork`` and then ``exec`` (Unix) 800 - Call ``CreateProcess`` (Win32) 801 - Call ``PR_CreateProcess`` (both Unix and Win32) 802 803 It is essential that the parent allow the child to inherit the file descriptors. WIN32's 804 ``CreateProcess`` takes an argument that tells it whether or not to permit files to be inherited; 805 this argument must be ``TRUE``. 806 807 When a new child that has been created by either ``CreateProcess`` or ``exec`` begins, it may 808 have inherited file descriptors (FDs), but not the parent's memory. Therefore, to find out what 809 FDs it has inherited, it must be told about them. To that end, the function 810 ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ sets an environment variable named 811 ``SSL_INHERITANCE``. The value of the variable is a printable ASCII string, containing all the 812 information needed to set up and use the inherited FDs. 813 814 There are two ways to transfer the content of ``SSL_INHERITANCE`` from parent to child: 815 816 - The child inherits the parent's environment, which must include the ``SSL_INHERITANCE`` 817 variable. For the child to inherit the parent's environment you must set a specific argument 818 to ``CreateProcess`` or ``PR_CreateProcess``. 819 - The parent transmits the content of ``SSL_INHERITANCE`` to the child by some other means, such 820 as on the command line, or in another file or pipe. 821 822 In either case, the child must call ```SSL_InheritMPServerSIDCache`` <#1162055>`__ to complete 823 the inheritance of the shared cache FDs/handles. 824 825 .. rubric:: SSL_ConfigMPServerSIDCache 826 :name: ssl_configmpserversidcache 827 828 Sets up parameters for and opens the server session cache for a multi-process application. 829 830 .. rubric:: Syntax 831 :name: syntax_10 832 833 .. code:: 834 835 #include "ssl.h" 836 837 .. code:: 838 839 SECStatus SSL_ConfigMPServerSIDCache( 840 int maxCacheEntries, 841 PRUint32 timeout, 842 PRUint32 ssl3_timeout, 843 const char *directory); 844 845 .. rubric:: Parameters 846 :name: parameters_6 847 848 This function has the parameters listed below. 849 850 +---------------------+---------------------------------------------------------------------------+ 851 | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is | 852 | | passed, the server default value of 10,000 is used. | 853 +---------------------+---------------------------------------------------------------------------+ 854 | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is | 855 | | 5 seconds and the maximum is 24 hours. Values outside this range are | 856 | | replaced by the server default value of 100 seconds. | 857 +---------------------+---------------------------------------------------------------------------+ 858 | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is | 859 | | 5 seconds and the maximum is 24 hours. Values outside this range are | 860 | | replaced by the server default value of 24 hours. | 861 +---------------------+---------------------------------------------------------------------------+ 862 | ``directory`` | A pointer to a string specifying the pathname of the directory that will | 863 | | contain the session cache. If a ``NULL`` value is passed, the server | 864 | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). | 865 +---------------------+---------------------------------------------------------------------------+ 866 867 .. rubric:: Returns 868 :name: returns_9 869 870 The function returns one of these value\ ``s``: 871 872 - If successful, ``SECSuccess``. 873 - If unsuccessful, ``SECFailure``. Use 874 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 875 to obtain error code. 876 877 .. rubric:: Description 878 :name: description_10 879 880 This function is identical to ```SSL_ConfigServerSessionIDCache`` <#1143851>`__, except that it 881 is for use with applications that use multiple processes. You must use one or the other of these 882 functions to create a server cache, not both. 883 884 If your application will use multiple processes (instead of, or in addition to, multiple 885 threads), and all of the processes appear to be on the same server (same IP address and port 886 number), then those processes must share a common SSL session cache. The common parent of all the 887 processes must call this function to create the cache before creating the other processes. 888 889 An application uses multiple processes\ *only* if it uses the Unix function ``fork``, or the 890 Win32 function ``CreateProcess``. This is not the same as using multiple threads or multiple 891 processors. Note that an SSL server that uses Fortezza hardware devices is limited to a single 892 process. It can use multiple threads, and thereby make use of multiple processors, but this must 893 all be done from a single process. 894 895 This function creates two caches: the\ *server session ID cache* (also called the server session 896 cache, or server cache), and the\ *client-auth certificate cache* (also called the client cert 897 cache, or client auth cache). Both caches are used only for sessions where the program handshakes 898 as a server. The client-auth certificate cache is used to remember the certificates previously 899 presented by clients for client certificate authentication. 900 901 Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the 902 server default value to be used in the server cache. The values that you pass affect only the 903 server cache, not the client cache. Before the cache can be used in the child process, the child 904 process must complete its initialization using ```SSL_InheritMPServerSIDCache`` <#1162055>`__. 905 906 .. rubric:: SSL_InheritMPServerSIDCache 907 :name: ssl_inheritmpserversidcache 908 909 Ensures the inheritance of file descriptors to a child process. 910 911 .. rubric:: Syntax 912 :name: syntax_11 913 914 .. code:: 915 916 #include "ssl.h" 917 918 .. code:: 919 920 SECStatus SSL_InheritMPServerSIDCache (const char *envString); 921 922 .. rubric:: Parameters 923 :name: parameters_7 924 925 This function has the following parameter: 926 927 +-------------------------------------------------+-------------------------------------------------+ 928 | ``envString`` | A pointer to the location of the inheritance | 929 | | information. The value depends on how you are | 930 | | passing the information. | 931 | | | 932 | | If a ``NULL`` value is passed, the function | 933 | | looks for the ``SSL_INHERITANCE`` variable that | 934 | | has been inherited as part of the child's | 935 | | environment. | 936 +-------------------------------------------------+-------------------------------------------------+ 937 938 .. rubric:: Returns 939 :name: returns_10 940 941 The function returns one of these values: 942 943 - If successful, ``SECSuccess``. 944 - If unsuccessful, ``SECFailure``. Use 945 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 946 to obtain the error code. 947 948 .. rubric:: Description 949 :name: description_11 950 951 This function completes the inheritance of file descriptors from a parent to a child process. 952 After the child process is created, it must call this function to complete its initialization. 953 954 The value of the ``envString`` argument depends on which of the two possible inheritance schemes 955 you have used. (See `Initializing Multi-Processing with a Shared SSL Server Cache <#1154189>`__.) 956 957 - If the ``SSL_INHERITANCE`` variable has been inherited as part of the child's environment, the 958 child must pass a ``NULL`` pointer as the ``envString`` argument. This causes the function to 959 look in the environment for the variable. 960 - If the parent has transmitted the value of the ``SSL_INHERITANCE`` variable to the child by 961 some other means, the child must pass a pointer to that string as the ``envString`` argument 962 to complete the inheritance. 963 964 When this function returns ``SECSuccess``, the server cache is ready to be used by the SSL code. 965 966 .. _ssl_export_policy_functions: 967 968 `SSL Export Policy Functions <#ssl_export_policy_functions>`__ 969 -------------------------------------------------------------- 970 971 .. container:: 972 973 The SSL export policy functions determine which cipher suites are\ *permitted* for use in an SSL 974 session. They do not determine which cipher suites are actually\ *enabled*--that is, turned on 975 and ready to use. To enable or disable a permitted cipher suite, use 976 ```SSL_CipherPrefSetDefault`` <#1084747>`__; but bear in mind that 977 ```SSL_CipherPrefSetDefault`` <#1084747>`__ can't enable any cipher suite that is not explicitly 978 permitted as a result of a call to one of the export policy functions. 979 980 By default, none of the cipher suites supported by SSL are permitted. The functions 981 ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and 982 ```NSS_SetFrancePolicy`` <#1105952>`__ permit the use of approved cipher suites for domestic, 983 international, and French versions, respectively, of software products with encryption features. 984 The policy settings permitted by these functions conform with current U.S. export regulations as 985 understood by Netscape (for products with and without "retail status" as defined by the `latest 986 U.S. Export Regulations <http://w3.access.gpo.gov/bxa/ear/ear_data.html>`__) and French import 987 regulations. 988 989 Under some circumstances, you may be required to abide by the terms of an export license that 990 permits more or fewer capabilities than those allowed by these three functions. In such cases, 991 use ```SSL_CipherPolicySet`` <#1104647>`__ to explicitly enable those cipher suites you may 992 legally export. 993 994 For descriptions of cipher suites supported by SSL, see `Introduction to 995 SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__. 996 997 Applications must call one of the export policy functions before attempting to perform any 998 cryptographic operations: 999 1000 | ```NSS_SetDomesticPolicy`` <#1228530>`__ 1001 | ```NSS_SetExportPolicy`` <#1100285>`__ 1002 | ```NSS_SetFrancePolicy`` <#1105952>`__ 1003 | ```SSL_CipherPolicySet`` <#1104647>`__ 1004 1005 The following function is also described in this section: 1006 1007 ```SSL_CipherPolicyGet`` <#1210463>`__ 1008 1009 .. rubric:: NSS_SetDomesticPolicy 1010 :name: nss_setdomesticpolicy 1011 1012 Configures cipher suites to conform with current U.S. export regulations related to domestic 1013 software products with encryption features. 1014 1015 .. rubric:: Syntax 1016 :name: syntax_12 1017 1018 .. code:: 1019 1020 #include "ssl.h" 1021 1022 .. code:: 1023 1024 extern SECStatus NSS_SetDomesticPolicy(void); 1025 1026 .. rubric:: Returns 1027 :name: returns_11 1028 1029 The function returns one of these values: 1030 1031 - If successful, ``SECSuccess``. 1032 - If unsuccessful, returns ``SECFailure``. Use 1033 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1034 to obtain the error code. 1035 1036 .. rubric:: Description 1037 :name: description_12 1038 1039 ``NSS_SetDomesticPolicy`` configures all the cipher suites listed under 1040 ```SSL_CipherPolicySet`` <#1104647>`__ for software that is\ *not* intended for export, and is 1041 thus not required to conform with U.S. export regulations related to domestic software products 1042 with encryption features. After calling this function, all cipher suites listed are permitted 1043 (but not necessarily enabled; see `SSL Export Policy Functions <#1098841>`__) for the calling 1044 application. 1045 1046 When an SSL connection is established, SSL permits the use of the strongest cipher suites that 1047 are both permitted and enabled for the software on both ends of the connection. For example, if a 1048 client that has called ``NSS_SetDomesticPolicy`` establishes an SSL connection with a server for 1049 which some cipher suites are either not permitted or not enabled (such as an international 1050 version of Netscape server software), SSL uses the strongest cipher suites supported by the 1051 server that are also supported by the client. 1052 1053 Under some circumstances, you may be required to abide by the terms of an export license that 1054 permits more or fewer capabilities than those allowed by ``NSS_SetDomesticPolicy``. In that case, 1055 first call ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or 1056 ```NSS_SetFrancePolicy`` <#1105952>`__, then call ```SSL_CipherPolicySet`` <#1104647>`__ 1057 repeatedly to explicitly allow or disallow cipher suites until only those that you may legally 1058 export are permitted. 1059 1060 .. rubric:: Important 1061 :name: important 1062 1063 If you call ``NSS_SetDomesticPolicy`` sometime after initialization to change cipher suite policy 1064 settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the 1065 session cache and will be used instead of the new settings. 1066 1067 .. rubric:: NSS_SetExportPolicy 1068 :name: nss_setexportpolicy 1069 1070 Configures the SSL cipher suites to conform with current U.S. export regulations related to 1071 international software products with encryption features. 1072 1073 .. rubric:: Syntax 1074 :name: syntax_13 1075 1076 .. code:: 1077 1078 #include "ssl.h" 1079 1080 .. code:: 1081 1082 extern SECStatus NSS_SetExportPolicy(void); 1083 1084 .. rubric:: Returns 1085 :name: returns_12 1086 1087 The function returns one of these values: 1088 1089 - If successful, ``SECSuccess``. 1090 - If unsuccessful, returns ``SECFailure``. Use 1091 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1092 to obtain the error code. 1093 1094 .. rubric:: Description 1095 :name: description_13 1096 1097 ``NSS_SetExportPolicy`` configures all the cipher suites listed under 1098 ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations related to 1099 international software products with encryption features (as Netscape understands them). Calling 1100 this function permits use of cipher suites listed below (but doesn't necessarily enable them; see 1101 `SSL Export Policy Functions <#1098841>`__). Policy for these suites is set to ``SSL_ALLOWED`` 1102 unless otherwise indicated. ``SSL_RESTRICTED`` means the suite can be used by clients only when 1103 they are communicating with domestic server software or with international server software that 1104 presents a Global ID certificate. For more details on policy settings, see 1105 ```SSL_CipherPolicySet`` <#1104647>`__. 1106 1107 For SSL 2.0: 1108 1109 - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5`` 1110 - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5`` 1111 1112 For SSL 3.0: 1113 1114 - ``SSL_RSA_WITH_NULL_MD5`` 1115 - ``SSL_RSA_WITH_RC4_128_MD5 (SSL_RESTRICTED)`` 1116 - ``SSL_RSA_WITH_3DES_EDE_CBC_SHA (SSL_RESTRICTED)`` 1117 - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` 1118 - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` 1119 1120 Under some circumstances, you may be required to abide by the terms of an export license that 1121 permits more or fewer capabilities than those allowed by ``NSS_SetExportPolicy``. In that case, 1122 you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__, 1123 ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call 1124 ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites 1125 until only those that you may legally export are permitted. 1126 1127 .. rubric:: Important 1128 :name: important_2 1129 1130 If you call ``NSS_SetExportPolicy`` sometime after initialization to change cipher suite policy 1131 settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the 1132 session cache and will be used instead of the new settings. 1133 1134 .. rubric:: NSS_SetFrancePolicy 1135 :name: nss_setfrancepolicy 1136 1137 Configures the SSL cipher suites to conform with French import regulations related to software 1138 products with encryption features. 1139 1140 .. rubric:: Syntax 1141 :name: syntax_14 1142 1143 .. code:: 1144 1145 #include "ssl.h" 1146 1147 .. code:: 1148 1149 SECStatus NSS_SetFrancePolicy(void); 1150 1151 .. rubric:: Returns 1152 :name: returns_13 1153 1154 The function returns one of these values: 1155 1156 - If successful, ``SECSuccess``. 1157 - If unsuccessful, returns ``SECFailure``. Use 1158 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1159 to obtain the error code. 1160 1161 .. rubric:: Description 1162 :name: description_14 1163 1164 ``NSS_SetFrancePolicy`` configures all the cipher suites listed under 1165 ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations and French 1166 import regulations (as Netscape understands them) related to software products with encryption 1167 features. Calling this function permits use of cipher suites listed below (but doesn't 1168 necessarily enable them; see `SSL Export Policy Functions <#1098841>`__). Policy for these suites 1169 is set to ``SSL_ALLOWED``. For more details on policy settings, see 1170 ```SSL_CipherPolicySet`` <#1104647>`__. 1171 1172 For SSL 2.0: 1173 1174 - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5`` 1175 - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5`` 1176 1177 For SSL 3.0: 1178 1179 - ``SSL_RSA_WITH_NULL_MD5`` 1180 - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` 1181 - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` 1182 1183 Under some circumstances, you may be required to abide by the terms of an export license that 1184 permits more or fewer capabilities than those allowed by ``NSS_SetFrancePolicy``. In that case, 1185 you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__, 1186 ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call 1187 ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites 1188 until only those that you may legally export are permitted. 1189 1190 .. rubric:: Important 1191 :name: important_3 1192 1193 If you call ``NSS_SetFrancePolicy`` sometime after initialization to change cipher suite policy 1194 settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the 1195 session cache and will be used instead of the new settings. 1196 1197 .. rubric:: SSL_CipherPolicySet 1198 :name: ssl_cipherpolicyset 1199 1200 Sets policy for the use of individual cipher suites. 1201 1202 ``SSL_CipherPolicySet`` replaces the deprecated function ```SSL_SetPolicy`` <#1207350>`__. 1203 1204 .. rubric:: Syntax 1205 :name: syntax_15 1206 1207 .. code:: 1208 1209 #include "ssl.h" 1210 #include "proto.h" 1211 1212 .. code:: 1213 1214 SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy); 1215 1216 .. rubric:: Parameters 1217 :name: parameters_8 1218 1219 This function has the following parameters: 1220 1221 +-------------------------------------------------+-------------------------------------------------+ 1222 | ``cipher`` | A value from one of the following lists. | 1223 | | | 1224 | | Values for SSL2 (all are disallowed by | 1225 | | default): | 1226 | | | 1227 | | ``SSL_EN_RC4_128_WITH_ | 1228 | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | 1229 | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | 1230 | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | 1231 | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | 1232 | | | 1233 | | Values for SSL3/TLS (all are disallowed by | 1234 | | default): | 1235 | | | 1236 | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (client | 1237 | | side only) | 1238 | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (client | 1239 | | side only) | 1240 | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` | 1241 | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | 1242 | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (client side | 1243 | | only) | 1244 | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (client | 1245 | | side only) | 1246 | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (client | 1247 | | side only) | 1248 | | ``SSL_RSA_WITH_RC4_128_MD5`` | 1249 | | ``SSL_RSA_WITH_RC4_128_SHA`` | 1250 | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` | 1251 | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (client | 1252 | | side only) | 1253 | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (client | 1254 | | side only) | 1255 | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | 1256 | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | 1257 | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | 1258 | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (client side | 1259 | | only) | 1260 | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (client side | 1261 | | only) | 1262 | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | 1263 | | ``SSL_RSA_WITH_DES_CBC_SHA`` | 1264 | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | 1265 | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | 1266 | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | 1267 | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | 1268 | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | 1269 | | ``SSL_RSA_WITH_NULL_SHA`` | 1270 | | ``SSL_RSA_WITH_NULL_MD5`` | 1271 +-------------------------------------------------+-------------------------------------------------+ 1272 | ``policy`` | One of the following values: | 1273 | | | 1274 | | - ``SSL_ALLOWED``. Cipher is always allowed by | 1275 | | U.S. government policy. | 1276 | | - ``SSL_RESTRICTED``. Cipher is allowed by | 1277 | | U.S. government policy for servers with | 1278 | | Global ID certificates. | 1279 | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | 1280 | | by U.S. government policy. | 1281 +-------------------------------------------------+-------------------------------------------------+ 1282 1283 .. rubric:: Returns 1284 :name: returns_14 1285 1286 The function returns one of these values: 1287 1288 - If successful, ``SECSuccess``. 1289 - If unsuccessful, ``SECFailure``. Use 1290 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1291 to obtain the error code. 1292 1293 .. rubric:: Description 1294 :name: description_15 1295 1296 ``SSL_CipherPolicySet`` tells the SSL library that the specified cipher suite is allowed by the 1297 application's export license, or is not allowed by the application's export license, or is 1298 allowed to be used only with a Step-Up certificate. It overrides the factory default policy for 1299 that cipher suite. The default policy for all cipher suites is ``SSL_NOT_ALLOWED``, meaning that 1300 the application's export license does not approve the use of this cipher suite. A U.S. "domestic" 1301 version of a product typically sets all cipher suites to ``SSL_ALLOWED``. This setting is used to 1302 separate export and domestic versions of a product, and is not intended to express user cipher 1303 preferences. This setting affects all SSL sockets in the application process that are opened 1304 after a call to ``SSL_CipherPolicySet``. 1305 1306 Under some circumstances, you may be required to abide by the terms of an export license that 1307 permits more or fewer capabilities than those allowed by 1308 ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or 1309 ```NSS_SetFrancePolicy`` <#1105952>`__. In that case, first call 1310 ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or 1311 ```NSS_SetFrancePolicy`` <#1105952>`__, then call ``SSL_CipherPolicySet`` repeatedly to 1312 explicitly allow or disallow cipher suites until only those that you may legally export are 1313 permitted. 1314 1315 In a domestic US product, all the cipher suites are (presently) allowed. In an export client 1316 product, some cipher suites are always allowed (such as those with 40-bit keys), some are never 1317 allowed (such as triple-DES), and some are allowed (such as RC4_128) for use with approved 1318 servers, typically servers owned by banks with special Global ID certificates. (For details, see 1319 ```NSS_SetExportPolicy`` <#1100285>`__ and ```NSS_SetFrancePolicy`` <#1105952>`__.) When an SSL 1320 connection is established, SSL uses only cipher suites that have previously been explicitly 1321 permitted by a call to one of the SSL export policy functions. 1322 1323 Note that the value ``SSL_RESTRICTED`` (passed in the ``policy`` parameter) is currently used 1324 only by SSL clients, which can use it to set policy for connections with servers that have SSL 1325 step-up certificates. 1326 1327 .. rubric:: Important 1328 :name: important_4 1329 1330 If you call ``SSL_CipherPolicySet`` sometime after initialization to change cipher suite policy 1331 settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the 1332 session cache and will be used instead of the new settings. 1333 1334 .. rubric:: See Also 1335 :name: see_also 1336 1337 Permitting a cipher suite is not necessarily the same as enabling it. For details, see `SSL 1338 Export Policy Functions <#1098841>`__. 1339 1340 For descriptions of cipher suites supported by SSL, see `Introduction to 1341 SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__. 1342 1343 .. rubric:: SSL_CipherPolicyGet 1344 :name: ssl_cipherpolicyget 1345 1346 Gets the current policy setting for a specified cipher suite. 1347 1348 ``SSL_CipherPolicyGet`` is the complementary function for ```SSL_CipherPolicySet`` <#1104647>`__. 1349 1350 .. rubric:: Syntax 1351 :name: syntax_16 1352 1353 .. code:: 1354 1355 #include "ssl.h" 1356 #include "proto.h" 1357 1358 .. code:: 1359 1360 SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy); 1361 1362 .. rubric:: Parameters 1363 :name: parameters_9 1364 1365 This function has the following parameters: 1366 1367 +-------------------------------------------------+-------------------------------------------------+ 1368 | ``cipher`` | A value identifying a cipher suite. For a list | 1369 | | of possible values, see | 1370 | | ```SSL_CipherPolicySet`` <#1104647>`__. | 1371 +-------------------------------------------------+-------------------------------------------------+ 1372 | policy | A pointer to one of the following values: | 1373 | | | 1374 | | - ``SSL_ALLOWED``. Cipher is always allowed by | 1375 | | U.S. government policy. | 1376 | | - ``SSL_RESTRICTED``. Cipher is allowed by | 1377 | | U.S. government policy for servers with | 1378 | | Global ID certificates. | 1379 | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | 1380 | | by U.S. government policy. | 1381 +-------------------------------------------------+-------------------------------------------------+ 1382 1383 .. rubric:: Description 1384 :name: description_16 1385 1386 See the description above for ```SSL_CipherPolicySet`` <#1104647>`__. 1387 1388 .. _ssl_configuration_functions: 1389 1390 `SSL Configuration Functions <#ssl_configuration_functions>`__ 1391 -------------------------------------------------------------- 1392 1393 .. container:: 1394 1395 SSL configuration involves several NSPR functions in addition to the SSL functions listed here. 1396 For a complete list of configuration functions, see `Configuration <sslintro.html#1027742>`__. 1397 1398 | `SSL Configuration <#1090577>`__ 1399 | `Callback Configuration <#1089578>`__ 1400 1401 .. _ssl_configuration: 1402 1403 `SSL Configuration <#ssl_configuration>`__ 1404 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1405 1406 .. container:: 1407 1408 | ```SSL_ImportFD`` <#1085950>`__ 1409 | ```SSL_OptionSet`` <#1086543>`__ 1410 | ```SSL_OptionGet`` <#1194921>`__ 1411 | ```SSL_CipherPrefSet`` <#1214758>`__ 1412 | ```SSL_CipherPrefGet`` <#1214800>`__ 1413 | ```SSL_ConfigSecureServer`` <#1217647>`__ 1414 | ```SSL_SetURL`` <#1087792>`__ 1415 | ```SSL_SetPKCS11PinArg`` <#1088040>`__ 1416 1417 .. rubric:: SSL_ImportFD 1418 :name: ssl_importfd 1419 1420 Imports an existing NSPR file descriptor into SSL and returns a new SSL socket. 1421 1422 .. rubric:: Syntax 1423 :name: syntax_17 1424 1425 .. code:: 1426 1427 #include "ssl.h" 1428 1429 .. code:: 1430 1431 PRFileDesc *SSL_ImportFD( 1432 PRFileDesc *model, 1433 PRFileDesc *fd); 1434 1435 .. rubric:: Parameters 1436 :name: parameters_10 1437 1438 This function has the following parameters: 1439 1440 ========= ======================================================== 1441 ``model`` A pointer to the model file descriptor. 1442 ``fd`` A pointer to the file descriptor for the new SSL socket. 1443 ========= ======================================================== 1444 1445 .. rubric:: Returns 1446 :name: returns_15 1447 1448 The function returns one of these values: 1449 1450 - If successful, a pointer to a new socket file descriptor. 1451 - If unsuccessful, ``NULL``. 1452 1453 .. rubric:: Description 1454 :name: description_17 1455 1456 Any SSL function that takes a pointer to a file descriptor (socket) as a parameter will have no 1457 effect (even though the SSL function may return ``SECSuccess``) if the socket is not an SSL 1458 socket. Sockets do not automatically become secure SSL sockets when they are created by the NSPR 1459 functions. You must pass an NSPR socket's file descriptor to ``SSL_ImportFD`` to make it an SSL 1460 socket before you call any other SSL function that takes the socket's file descriptor as a 1461 parameter 1462 1463 ``SSL_ImportFD`` imports an existing NSPR file descriptor into SSL and returns a new SSL socket 1464 file descriptor. If the ``model`` parameter is not ``NULL``, the configuration of the new file 1465 descriptor is copied from the model. If the ``model`` parameter is ``NULL``, then the default SSL 1466 configuration is used. 1467 1468 The new file descriptor returned by ``SSL_ImportFD`` is not necessarily equal to the original 1469 NSPR file descriptor. If, after calling ``SSL_ImportFD``, the file descriptors are not equal, you 1470 should perform all operations on the new ``PRFileDesc`` structure, never the old one. Even when 1471 it's time to close the file descriptor, always close the new ``PRFileDesc`` structure, never the 1472 old one. 1473 1474 .. rubric:: SSL_OptionSet 1475 :name: ssl_optionset 1476 1477 Sets a single configuration parameter of a specified socket. Call once for each parameter you 1478 want to change. 1479 1480 ``SSL_OptionSet`` replaces the deprecated function ```SSL_Enable`` <#1220189>`__. 1481 1482 .. rubric:: Syntax 1483 :name: syntax_18 1484 1485 .. code:: 1486 1487 #include "ssl.h" 1488 1489 .. code:: 1490 1491 SECStatus SSL_OptionSet( 1492 PRFileDesc *fd, 1493 PRInt32 option, 1494 PRBool on); 1495 1496 .. rubric:: Parameters 1497 :name: parameters_11 1498 1499 This function has the following parameters: 1500 1501 +-------------------------------------------------+-------------------------------------------------+ 1502 | ``fd`` | Pointer to the NSPR file descriptor for the SSL | 1503 | | socket. | 1504 +-------------------------------------------------+-------------------------------------------------+ 1505 | ``option`` | One of the following values (default values are | 1506 | | determined by the use of | 1507 | | ```SSL_OptionSetDefault`` <#1068466>`__): | 1508 | | | 1509 | | - ``SSL_SECURITY`` enables use of security | 1510 | | protocol. WARNING: If you turn this option | 1511 | | off, the session will not be an SSL session | 1512 | | and will not have certificate-based | 1513 | | authentication, tamper detection, or | 1514 | | encryption. | 1515 | | - ``SSL_REQUEST_CERTIFICATE`` is a server | 1516 | | option that requests a client to | 1517 | | authenticate itself. | 1518 | | - ``SSL_REQUIRE_CERTIFICATE`` is a server | 1519 | | option that requires a client to | 1520 | | authenticate itself (only if | 1521 | | ``SSL_REQUEST_CERTIFICATE`` is also on). If | 1522 | | client does not provide certificate, the | 1523 | | connection terminates. | 1524 | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the | 1525 | | behavior of ``PR_Accept``,. If this option | 1526 | | is off, the ``PR_Accept`` configures the SSL | 1527 | | socket to handshake as a server. If it is | 1528 | | on, then ``PR_Accept`` configures the SSL | 1529 | | socket to handshake as a client, even though | 1530 | | it accepted the connection as a TCP server. | 1531 | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the | 1532 | | behavior of ``PR_Connect``. If this option | 1533 | | is off, then ``PR_Connect`` configures the | 1534 | | SSL socket to handshake as a client. If it | 1535 | | is on, then ``PR_Connect`` configures the | 1536 | | SSL socket to handshake as a server, even | 1537 | | though it connected as a TCP client. | 1538 | | - ``SSL_ENABLE_FDX`` tells the SSL library | 1539 | | whether the application will have two | 1540 | | threads, one reading and one writing, or | 1541 | | just one thread doing reads and writes | 1542 | | alternately. The factory setting for this | 1543 | | option (which is the default, unless the | 1544 | | application changes the default) is off | 1545 | | (``PR_FALSE``), which means that the | 1546 | | application will not do simultaneous reads | 1547 | | and writes. An application that needs to do | 1548 | | simultaneous reads and writes should set | 1549 | | this to ``PR_TRUE``. | 1550 | | | 1551 | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only | 1552 | | affects the behavior of nonblocking SSL | 1553 | | sockets. See the description below for more | 1554 | | information on this option. | 1555 +-------------------------------------------------+-------------------------------------------------+ 1556 | | - ``SSL_ENABLE_SSL3`` enables the application | 1557 | | to communicate with SSL v3. If you turn this | 1558 | | option off, an attempt to establish a | 1559 | | connection with a peer that understands only | 1560 | | SSL v3 will fail. | 1561 | | - ``SSL_ENABLE_SSL2`` enables the application | 1562 | | to communicate with SSL v2. If you turn this | 1563 | | option off, an attempt to establish a | 1564 | | connection with a peer that understands only | 1565 | | SSL v2 will fail. | 1566 | | - ``SSL_ENABLE_TLS`` is a peer of the | 1567 | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` | 1568 | | options. The IETF standard Transport Layer | 1569 | | Security (TLS) protocol, RFC 2246, is a | 1570 | | modified version of SSL3. It uses the SSL | 1571 | | version number 3.1, appearing to be a | 1572 | | "minor" revision of SSL3.0. NSS 2.8 supports | 1573 | | TLS in addition to SSL2 and SSL3. You can | 1574 | | think of it as "``SSL_ENABLE_SSL3.1``." See | 1575 | | the description below for more information | 1576 | | about this option. | 1577 | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL | 1578 | | library whether or not to send SSL3 client | 1579 | | hello messages in SSL2-compatible format. If | 1580 | | set to ``PR_TRUE``, it will; otherwise, it | 1581 | | will not. See the description below for more | 1582 | | information on this option. | 1583 | | - ``SSL_NO_CACHE`` disallows use of the | 1584 | | session cache. Factory setting is off. If | 1585 | | you turn this option on, this socket will be | 1586 | | unable to resume a session begun by another | 1587 | | socket. When this socket's session is | 1588 | | finished, no other socket will be able to | 1589 | | resume the session begun by this socket. | 1590 | | - ``SSL_ROLLBACK_DETECTION`` disables | 1591 | | detection of a rollback attack. Factory | 1592 | | setting is on. You must turn this option off | 1593 | | to interoperate with TLS clients ( such as | 1594 | | certain versions of Microsoft Internet | 1595 | | Explorer) that do not conform to the TLS | 1596 | | specification regarding rollback attacks. | 1597 | | Important: turning this option off means | 1598 | | that your code will not comply with the TLS | 1599 | | 3.1 and SSL 3.0 specifications regarding | 1600 | | rollback attack and will therefore be | 1601 | | vulnerable to this form of attack. | 1602 +-------------------------------------------------+-------------------------------------------------+ 1603 | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns | 1604 | | option off. | 1605 +-------------------------------------------------+-------------------------------------------------+ 1606 1607 .. rubric:: Returns 1608 :name: returns_16 1609 1610 The function returns one of these values: 1611 1612 - If successful, ``SECSuccess``. 1613 - If unsuccessful, returns ``SECFailure``. Use 1614 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1615 to obtain the error code. 1616 1617 .. rubric:: Description 1618 :name: description_18 1619 1620 Keep the following in mind when deciding on the operating parameters you want to use with a 1621 particular socket: 1622 1623 - Turning on ``SSL_REQUIRE_CERTIFICATE`` will have no effect unless ``SSL_REQUEST_CERTIFICATE`` 1624 is also turned on. If you enable ``SSL_REQUEST_CERTIFICATE``, then you should explicitly 1625 enable or disable ``SSL_REQUIRE_CERTIFICATE`` rather than allowing it to default. Enabling the 1626 ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no certificate and 1627 this option is enabled, the client's connection terminates with an error. The user is likely 1628 to think something is wrong with either the client or the server, and is unlikely to realize 1629 that the problem is the lack of a certificate. It is better to allow the SSL handshake to 1630 complete and then return an error message to the client that informs the user of the need for 1631 a certificate. 1632 1633 Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in 1634 SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does 1635 not understand SSL2-compatible client hello messages. 1636 1637 ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello 1638 messages in SSL2-compatible format. Note that calling ``SSL_OptionSet`` to set 1639 ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the ``SSL_ENABLE_SSL2`` option 1640 to ``PR_FALSE`` for that SSL socket. Calling ``SSL_EnableDefault`` to change the application 1641 default setting for ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the default 1642 value for ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that application. 1643 1644 - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set 1645 to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 and later versions will 1646 negotiate the highest protocol version with the peer application from among the set of 1647 protocols that are commonly enabled in both applications. 1648 1649 Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled, 1650 all SSL3/TLS cipher suites that are enabled are enabled for both SSL3 and TLS. 1651 1652 As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a socket 1653 into SSL after the TCP connection on that socket has already been established, it must call 1654 `SSL_ResetHandshake <#1058001>`__ to indicate whether the socket is for a client or server. At 1655 first glance this may seem unnecessary, since ``SSL_OptionSet`` can set 1656 ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control the 1657 behavior of 1658 ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ 1659 and 1660 ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ 1661 only; if you don't call one of those functions after importing a non-SSL socket with 1662 ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to know 1663 whether the application is functioning as a client or server. 1664 1665 If a socket file descriptor is imported as an SSL socket before it is connected, it is implicitly 1666 configured to handshake as a client or handshake as a server when the connection is made. If the 1667 application calls ``PR_Connect`` (connecting as a TCP client), then the SSL socket is (by 1668 default) configured to handshake as an SSL client. If the application calls ``PR_Accept`` 1669 (connecting the socket as a TCP server) then the SSL socket is (by default) configured to 1670 handshake as an SSL server. ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` control 1671 this implicit configuration. 1672 1673 Both ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` are initially set to off--that 1674 is, the process default for both values is ``PR_FALSE`` when the process begins. The process 1675 default can be changed from the initial values by using ``SSL_EnableDefault``, and the value for 1676 a particular socket can be changed by using ``SSL_OptionSet``. 1677 1678 When you import a new SSL socket with ``SSL_ImportFD`` using a model file descriptor, the new SSL 1679 socket inherits its values for ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` from 1680 the model file descriptor. 1681 1682 When ``PR_Accept`` accepts a new connection from a listen file descriptor and creates a new file 1683 descriptor for the new connection, the listen file descriptor also acts as a model for the new 1684 file descriptor, and the new file descriptor inherits its values from the model. 1685 1686 ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` cannot both be turned on 1687 simultaneously. If you use ``SSL_OptionSet`` to turn one of these on when the other one is 1688 already turned on for a particular socket, the function returns with the error code set to 1689 ``SEC_ERROR_INVALID_ARGS``. Likewise, using ``SSL_EnableDefault`` to turn on the global default 1690 for one of these when the global default for the other one is already turned for a particular 1691 socket generates the same error. However, there is no good reason for these to be mutually 1692 exclusive. This restirction will be removed in future releases. 1693 1694 If a socket that is already connected gets imported into SSL after it has been connected (that 1695 is, after ``PR_Accept`` or ``PR_Connect`` has returned), then no implicit SSL handshake 1696 configuration as a client or server will have been done by ``PR_Connect`` or ``PR_Accept`` on 1697 that socket. In this case, a call to ``SSL_ResetHandshake`` is required to explicitly configure 1698 the socket to handshake as a client or as a server. If ``SSL_ResetHandshake`` is not called to 1699 explicitly configure the socket handshake, a crash is likely to occur when the first I/O 1700 operation is done on the socket after it is imported into SSL. 1701 1702 .. rubric:: SSL_OptionGet 1703 :name: ssl_optionget 1704 1705 ``SSL_OptionGet`` gets the value of a specified SSL option on a specified SSL socket. 1706 1707 .. rubric:: Syntax 1708 :name: syntax_19 1709 1710 .. code:: 1711 1712 #include "ssl.h" 1713 1714 .. code:: 1715 1716 SECStatus SSL_OptionGet( 1717 PRFileDesc *fd, 1718 PRInt32 option, 1719 PRBool *on); 1720 1721 .. rubric:: Parameters 1722 :name: parameters_12 1723 1724 This function has the following parameters: 1725 1726 +------------+------------------------------------------------------------------------------------+ 1727 | ``fd`` | Pointer to the file descriptor for the SSL socket. | 1728 +------------+------------------------------------------------------------------------------------+ 1729 | ``option`` | The value of the option whose default setting you wish to get. For information | 1730 | | about the options available and the possible values to pass in this parameter, see | 1731 | | the description of the ``option`` parameter under | 1732 | | ```SSL_OptionSet`` <#1086543>`__. | 1733 +------------+------------------------------------------------------------------------------------+ 1734 | ``on`` | ``PR_TRUE`` indicates the specified option is on; ``PR_FALSE`` indicates it is | 1735 | | off. | 1736 +------------+------------------------------------------------------------------------------------+ 1737 1738 .. rubric:: Returns 1739 :name: returns_17 1740 1741 The function returns one of these values: 1742 1743 - If successful, ``SECSuccess``. 1744 - If unsuccessful, returns ``SECFailure``. Use 1745 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1746 to obtain the error code. 1747 1748 .. rubric:: Description 1749 :name: description_19 1750 1751 See the description above for ```SSL_OptionSet`` <#1086543>`__. 1752 1753 .. rubric:: SSL_CipherPrefSet 1754 :name: ssl_cipherprefset 1755 1756 ``SSL_CipherPrefSet`` specifies the use of a specified cipher suite on a specified SSL socket. 1757 1758 .. rubric:: Syntax 1759 :name: syntax_20 1760 1761 .. code:: 1762 1763 #include "ssl.h" 1764 #include "proto.h" 1765 1766 .. code:: 1767 1768 SECStatus SSL_CipherPrefSet( 1769 PRFileDesc *fd, 1770 PRInt32 cipher, 1771 PRBool enabled); 1772 1773 .. rubric:: Parameters 1774 :name: parameters_13 1775 1776 This function has the following parameters: 1777 1778 +-------------------------------------------------+-------------------------------------------------+ 1779 | ``fd`` | Pointer to the file descriptor for the SSL | 1780 | | socket. | 1781 +-------------------------------------------------+-------------------------------------------------+ 1782 | ``cipher`` | One of the following values for SSL2 (all are | 1783 | | enabled by default): | 1784 | | | 1785 | | ``SSL_EN_RC4_128_WITH_ | 1786 | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | 1787 | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | 1788 | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | 1789 | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | 1790 | | | 1791 | | Or one of the following values for SSL3/TLS | 1792 | | (unless indicated otherwise, all are enabled by | 1793 | | default): | 1794 | | | 1795 | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not | 1796 | | enabled by default; client side only) | 1797 | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not | 1798 | | enabled by default; client side only) | 1799 | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled | 1800 | | by default) | 1801 | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | 1802 | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled | 1803 | | by default; client side only) | 1804 | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not | 1805 | | enabled by default; client side only) | 1806 | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not | 1807 | | enabled by default; client side only) | 1808 | | ``SSL_RSA_WITH_RC4_128_MD5`` | 1809 | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by | 1810 | | default) | 1811 | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled | 1812 | | by default) | 1813 | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not | 1814 | | enabled by default; client side only) | 1815 | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not | 1816 | | enabled by default; client side only) | 1817 | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | 1818 | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | 1819 | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | 1820 | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled | 1821 | | by default; client side only) | 1822 | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled | 1823 | | by default; client side only) | 1824 | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | 1825 | | ``SSL_RSA_WITH_DES_CBC_SHA`` | 1826 | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | 1827 | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | 1828 | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | 1829 | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | 1830 | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | 1831 | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by | 1832 | | default) | 1833 | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by | 1834 | | default) | 1835 +-------------------------------------------------+-------------------------------------------------+ 1836 | ``enabled`` | If nonzero, the specified cipher is enabled. If | 1837 | | zero, the cipher is disabled. | 1838 +-------------------------------------------------+-------------------------------------------------+ 1839 1840 .. rubric:: Description 1841 :name: description_20 1842 1843 ``SSL_CipherPrefSet`` is a new function in NSS 2.6 and later. It allows the application to set 1844 the user preferences for cipher suites on an individual socket, overriding the default value for 1845 the preference (which can be set with ```SSL_CipherPrefSetDefault`` <#1084747>`__). If an 1846 application needs to set the cipher preferences on an individual socket, it should do so before 1847 initiating an SSL handshake, not during an SSL handshake. 1848 1849 For more information on the use of the TLS and FIPS cipher suites, see 1850 ```SSL_CipherPrefSetDefault`` <#1084747>`__. 1851 1852 .. rubric:: SSL_CipherPrefGet 1853 :name: ssl_cipherprefget 1854 1855 Gets the current preference setting for a specified SSL2 or SSL3 cipher suite. 1856 1857 .. rubric:: Syntax 1858 :name: syntax_21 1859 1860 .. code:: 1861 1862 #include "ssl.h" 1863 #include "proto.h" 1864 1865 .. code:: 1866 1867 SECStatus SSL_CipherPrefGet( 1868 PRFileDesc *fd, 1869 PRInt32 cipher, 1870 PRBool *enabled); 1871 1872 .. rubric:: Parameters 1873 :name: parameters_14 1874 1875 This function has the parameters listed below. 1876 1877 +---------+---------------------------------------------------------------------------------------+ 1878 | ``fd`` | Pointer to the file descriptor for the SSL socket. | 1879 +---------+---------------------------------------------------------------------------------------+ 1880 | cipher | The cipher suite whose default preference setting you want to get. For a list of the | 1881 | | cipher suites you can specify, see ```SSL_CipherPrefSet`` <#1214758>`__. | 1882 +---------+---------------------------------------------------------------------------------------+ 1883 | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` | 1884 | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is | 1885 | | disabled. | 1886 +---------+---------------------------------------------------------------------------------------+ 1887 1888 .. rubric:: Description 1889 :name: description_21 1890 1891 ``SSL_CipherPrefGet`` performs the complementary function to ``SSL_CipherPrefSet``. It returns 1892 the current preference setting for the SSL cipher suite for the socket. If the application has 1893 not previously set the cipher preference for this cipher on this socket, the value will be either 1894 the process default value or the value inherited from a listen socket or a model socket. 1895 1896 .. rubric:: SSL_ConfigSecureServer 1897 :name: ssl_configsecureserver 1898 1899 Configures a listen socket with the information needed to handshake as an SSL server. 1900 ``SSL_ConfigSecureServer`` requires the certificate for the server and the server's private key. 1901 The arguments are copied. 1902 1903 .. rubric:: Syntax 1904 :name: syntax_22 1905 1906 .. code:: 1907 1908 #include "ssl.h" 1909 1910 .. code:: 1911 1912 SECStatus SSL_ConfigSecureServer( 1913 PRFileDesc *fd, 1914 CERTCertificate *cert, 1915 SECKEYPrivateKey *key, 1916 SSLKEAType keaType); 1917 1918 .. rubric:: Parameters 1919 :name: parameters_15 1920 1921 This function has the following parameters: 1922 1923 +-------------------------------------------------+-------------------------------------------------+ 1924 | ``fd`` | A pointer to the file descriptor for the SSL | 1925 | | listen socket. | 1926 +-------------------------------------------------+-------------------------------------------------+ 1927 | ``cert`` | A pointer to the server's certificate | 1928 | | structure. | 1929 +-------------------------------------------------+-------------------------------------------------+ 1930 | ``key`` | A pointer to the server's private key | 1931 | | structure. | 1932 +-------------------------------------------------+-------------------------------------------------+ 1933 | ``keaType`` | Key exchange type for use with specified | 1934 | | certificate and key. These values are currently | 1935 | | valid: | 1936 | | | 1937 | | - ``kt_rsa`` | 1938 | | - ``kt_dh`` | 1939 | | - ``kt_fortezza`` | 1940 +-------------------------------------------------+-------------------------------------------------+ 1941 1942 .. rubric:: Returns 1943 :name: returns_18 1944 1945 The function returns one of these values: 1946 1947 - If successful, ``SECSuccess``. 1948 - If unsuccessful, ``SECFailure``. Use 1949 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 1950 to obtain the error code. 1951 1952 .. rubric:: Description 1953 :name: description_22 1954 1955 Before SSL can handshake as a server on a socket, it must be configured to do so with a call to 1956 SSL_ConfigSecureServer (among other things). This function configures a listen socket. Child 1957 sockets created by 1958 ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ 1959 inherit the configuration. 1960 1961 Servers can be configured with more than one certificate for a given port, and different 1962 certificates can support different key-exchange algorithms. To find out what key-exchange 1963 algorithm a particular certificate supports, pass the certificate structure to 1964 ```NSS_FindCertKEAType`` <sslcrt.html#1056950>`__. You can then pass the ``SSLKEAType`` value 1965 returned by ``NSS_FindCertKEAType`` in the ``keaType`` parameter of ``SSL_ConfigSecureServer``. 1966 The server uses the specified key-exchange algorithm with the specified certificate and key. 1967 1968 When the ``keaType`` is ``kt_rsa``, this function generates a step-down key that is supplied as 1969 part of the handshake if needed. (A step-down key is needed when the server's public key is 1970 stronger than is allowed for export ciphers.) In this case, if the server is expected to continue 1971 running for a long time, you should call this function periodically (once a day, for example) to 1972 generate a new step-down key. 1973 1974 SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of 1975 certificate and key structures. The application should destroy its copies when it has no further 1976 use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and 1977 ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. 1978 1979 .. rubric:: SSL_SetURL 1980 :name: ssl_seturl 1981 1982 Sets the domain name of the intended server in the client's SSL socket. 1983 1984 .. rubric:: Syntax 1985 :name: syntax_23 1986 1987 .. code:: 1988 1989 #include "ssl.h" 1990 1991 .. code:: 1992 1993 int SSL_SetURL( 1994 PRFileDesc *fd, 1995 char *url); 1996 1997 .. rubric:: Parameters 1998 :name: parameters_16 1999 2000 This function has the following parameters: 2001 2002 ======= ================================================================== 2003 ``fd`` A pointer to a file descriptor. 2004 ``url`` A pointer to a string specifying the desired server's domain name. 2005 ======= ================================================================== 2006 2007 .. rubric:: Returns 2008 :name: returns_19 2009 2010 The function returns one of the following values: 2011 2012 - If successful, zero. 2013 - If unsuccessful, ``-1``. Use 2014 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2015 to obtain the error code. 2016 2017 .. rubric:: Description 2018 :name: description_23 2019 2020 The client application's certificate authentication callback function needs to compare the domain 2021 name in the server's certificate against the domain name of the server the client was attempting 2022 to contact. This step is vital because it is the client's\ *only* protection against a 2023 man-in-the-middle attack. 2024 2025 The client application uses ``SSL_SetURL`` to set the domain name of the desired server before 2026 performing the first SSL handshake. The client application's certificate authentication callback 2027 function gets this string by calling ```SSL_RevealURL`` <#1081175>`__. 2028 2029 .. rubric:: SSL_SetPKCS11PinArg 2030 :name: ssl_setpkcs11pinarg 2031 2032 Sets the argument passed to the password callback function specified by a call to 2033 ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__. 2034 2035 .. rubric:: Syntax 2036 :name: syntax_24 2037 2038 .. code:: 2039 2040 #include "ssl.h" 2041 2042 .. code:: 2043 2044 int SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a); 2045 2046 .. rubric:: Parameters 2047 :name: parameters_17 2048 2049 This function has the following parameters: 2050 2051 +--------+----------------------------------------------------------------------------------------+ 2052 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2053 +--------+----------------------------------------------------------------------------------------+ 2054 | ``a`` | A pointer supplied by the application that can be used to pass state information. This | 2055 | | value is passed as the third argument of the application's password function. The | 2056 | | meaning is determined solely by the application. | 2057 +--------+----------------------------------------------------------------------------------------+ 2058 2059 .. rubric:: Returns 2060 :name: returns_20 2061 2062 The function returns one of the following values: 2063 2064 - If successful, zero. 2065 - If unsuccessful, ``-1``. Use 2066 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2067 to obtain the error code. 2068 2069 .. rubric:: Description 2070 :name: description_24 2071 2072 During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 2073 token (either a smart card or soft token) to access protected information, such as a private key. 2074 Such information is protected with a password that can be retrieved by calling an 2075 application-supplied callback function. The callback function is specified in a call to 2076 ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ that takes place during NSS initialization. 2077 2078 Several functions in the NSS libraries use the password callback function to obtain the password 2079 before performing operations that involve the protected information. When NSS libraries call the 2080 password callback function, the value they pass in as the third parameter is the value of the 2081 ``a`` argument to ``PK11_SetPKCS11PinArg``. The third parameter to the password callback function 2082 is application-defined and can be used for any purpose. For example, Communicator uses the 2083 parameter to pass information about which window is associated with the modal dialog box 2084 requesting the password from the user. 2085 2086 You can obtain the PIN argument by calling ```SSL_RevealPinArg`` <#1123385>`__. 2087 2088 .. _callback_configuration: 2089 2090 `Callback Configuration <#callback_configuration>`__ 2091 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2092 2093 .. container:: 2094 2095 At the beginning of an SSL application, it is often necessary to set up callback functions for 2096 the SSL API to use when it needs to call the application. These functions are used to request 2097 authentication information from the application or to inform the application when a handshake is 2098 completed. 2099 2100 | ```SSL_AuthCertificateHook`` <#1088805>`__ 2101 | ```SSL_AuthCertificate`` <#1088888>`__ 2102 | ```SSL_BadCertHook`` <#1088928>`__ 2103 | ```SSL_GetClientAuthDataHook`` <#1126622>`__ 2104 | ```NSS_GetClientAuthData`` <#1106762>`__ 2105 | ```SSL_HandshakeCallback`` <#1112702>`__ 2106 2107 Setting up the callback functions described in this section may be optional for some 2108 applications. However, all applications must use 2109 ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ to set up the password callback function during 2110 NSS initialization. 2111 2112 For examples of the callback functions listed here, see `Chapter 2, "Getting Started With 2113 SSL." <gtstd.html#1005439>`__ 2114 2115 .. rubric:: SSL_AuthCertificateHook 2116 :name: ssl_authcertificatehook 2117 2118 Specifies a certificate authentication callback function called to authenticate an incoming 2119 certificate. 2120 2121 .. rubric:: Syntax 2122 :name: syntax_25 2123 2124 .. code:: 2125 2126 #include "ssl.h" 2127 2128 .. code:: 2129 2130 SECStatus SSL_AuthCertificateHook( 2131 PRFileDesc *fd, 2132 SSLAuthCertificate f, 2133 void *arg); 2134 2135 .. rubric:: Parameters 2136 :name: parameters_18 2137 2138 This function has the following parameters: 2139 2140 +---------+---------------------------------------------------------------------------------------+ 2141 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2142 +---------+---------------------------------------------------------------------------------------+ 2143 | ``f`` | A pointer to the callback function. If ``NULL``, the default callback function, | 2144 | | ```SSL_AuthCertificate`` <#1088888>`__, will be used. | 2145 +---------+---------------------------------------------------------------------------------------+ 2146 | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | 2147 | | be ``NULL``. | 2148 +---------+---------------------------------------------------------------------------------------+ 2149 2150 .. rubric:: Returns 2151 :name: returns_21 2152 2153 The function returns one of the following values: 2154 2155 - If successful, ``SECSuccess``. 2156 - If unsuccessful, ``SECFailure``. Use 2157 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2158 to obtain the error code. 2159 2160 .. rubric:: Description 2161 :name: description_25 2162 2163 The callback function set up by ``SSL_AuthCertificateHook`` is called to authenticate an incoming 2164 certificate. If the ``checksig`` parameter is set to ``PR_TRUE``, the callback function also 2165 verifies the digital signature. 2166 2167 **NOTE:** If you do not call\ ``SSL_AuthCertificateHook`` to supply a certificate 2168 authentication callback function, SSL uses the default callback function, 2169 ```SSL_AuthCertificate`` <#1088888>`__. 2170 2171 The callback function has the following prototype: 2172 2173 .. code:: 2174 2175 typedef SECStatus (*SSLAuthCertificate) ( 2176 void *arg, 2177 PRFileDesc *fd, 2178 PRBool checksig, 2179 PRBool isServer); 2180 2181 This callback function has the following parameters: 2182 2183 +--------------+----------------------------------------------------------------------------------+ 2184 | ``arg`` | A pointer supplied by the application (in the call to | 2185 | | ``SSL_AuthCertificateHook``) that can be used to pass state information. Can be | 2186 | | ``NULL``. | 2187 +--------------+----------------------------------------------------------------------------------+ 2188 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2189 +--------------+----------------------------------------------------------------------------------+ 2190 | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to | 2191 | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is | 2192 | | normally ``PR_TRUE``.) | 2193 +--------------+----------------------------------------------------------------------------------+ 2194 | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a | 2195 | | server does, treating the remote end as a client. ``PR_FALSE`` means the | 2196 | | callback function should evaluate the certificate as a client does, treating the | 2197 | | remote end as a server. | 2198 +--------------+----------------------------------------------------------------------------------+ 2199 2200 The callback function returns one of these values: 2201 2202 - If authentication is successful, ``SECSuccess``. 2203 - If authentication is not successful, ``SECFailure``. If the callback returns ``SECFailure``, 2204 the callback should indicate the reason for the failure (if possible) by calling 2205 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2206 with the appropriate error code. 2207 2208 The callback function obtains the certificate to be authenticated by calling 2209 ```SSL_PeerCertificate`` <#1096168>`__. 2210 2211 If ``isServer`` is false, the callback should also check that the domain name in the remote 2212 server's certificate matches the desired domain name specified in a previous call to 2213 ```SSL_SetURL`` <#1087792>`__. To obtain that domain name, the callback calls 2214 ```SSL_RevealURL`` <#1081175>`__. 2215 2216 The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11 2217 module. Some of the PK11 functions require a PIN argument (see 2218 ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value that was set with 2219 ```SSL_SetPKCS11PinArg`` <#1088040>`__, the callback calls ```SSL_RevealPinArg`` <#1123385>`__. 2220 2221 If the callback returns ``SECFailure``, the SSL connection is terminated immediately unless the 2222 application has supplied a bad-certificate callback function by having previously called 2223 ```SSL_BadCertHook`` <#1088928>`__. A bad-certificate callback function gives the application the 2224 opportunity to choose to accept the certificate as authentic and authorized even though it failed 2225 the check performed by the certificate authentication callback function. 2226 2227 .. rubric:: See Also 2228 :name: see_also_2 2229 2230 For examples of certificate authentication callback functions, see the sample code referenced 2231 from `Chapter 2, "Getting Started With SSL." <gtstd.html#1005439>`__ 2232 2233 .. rubric:: SSL_AuthCertificate 2234 :name: ssl_authcertificate 2235 2236 Default callback function used to authenticate certificates received from the remote end of an 2237 SSL connection if the application has not previously called 2238 ```SSL_AuthCertificateHook`` <#1088805>`__ to specify its own certificate authentication callback 2239 function. 2240 2241 .. rubric:: Syntax 2242 :name: syntax_26 2243 2244 .. code:: 2245 2246 #include "ssl.h" 2247 2248 .. code:: 2249 2250 SECStatus SSL_AuthCertificate( 2251 void *arg, 2252 PRFileDesc *fd, 2253 PRBool checksig, 2254 PRBool isServer); 2255 2256 .. rubric:: Parameters 2257 :name: parameters_19 2258 2259 This function has the following parameters: 2260 2261 +--------------+----------------------------------------------------------------------------------+ 2262 | ``arg`` | A pointer to the handle of the certificate database to be used in validating the | 2263 | | certificate's signature. (This use of the ``arg`` parameter is required for | 2264 | | ``SSL_AuthCertificate``, but not for all implementations of a certificate | 2265 | | authentication callback function.) | 2266 +--------------+----------------------------------------------------------------------------------+ 2267 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2268 +--------------+----------------------------------------------------------------------------------+ 2269 | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to | 2270 | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is | 2271 | | normally ``PR_TRUE``.) | 2272 +--------------+----------------------------------------------------------------------------------+ 2273 | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a | 2274 | | server does, treating the remote end is a client. ``PR_FALSE`` means the | 2275 | | callback function should evaluate the certificate as a client does, treating the | 2276 | | remote end as a server. | 2277 +--------------+----------------------------------------------------------------------------------+ 2278 2279 .. rubric:: Returns 2280 :name: returns_22 2281 2282 The function returns one of these values: 2283 2284 - If authentication is successful, ``SECSuccess``. 2285 - If authentication is not successful, ``SECFailure``. 2286 2287 .. rubric:: Description 2288 :name: description_26 2289 2290 SSL calls ``SSL_AuthCertificate`` by default (if no other callback function is provided) to 2291 authenticate an incoming certificate. If the ``checksig`` parameter is set to ``PR_TRUE`` (which 2292 is normally the case), the function also verifies the digital signature and the certificate 2293 chain. 2294 2295 If the socket is a client socket, ``SSL_AuthCertificate`` tests the domain name in the SSL socket 2296 against the domain name in the server certificate's subject DN: 2297 2298 - If the domain name in the SSL socket doesn't match the domain name in the server certificate's 2299 subject DN, the function fails. 2300 - If the SSL socket has not had a domain name set (that is, if ```SSL_SetURL`` <#1087792>`__ has 2301 not been called) or its domain name is set to an empty string, the function fails. 2302 2303 SSL_BadCertHook 2304 2305 Sets up a callback function to deal with a situation where the 2306 ```SSL_AuthCertificate`` <#1088888>`__ callback function has failed. This callback function 2307 allows the application to override the decision made by the certificate authorization callback 2308 and authorize the certificate for use in the SSL connection. 2309 2310 .. rubric:: Syntax 2311 :name: syntax_27 2312 2313 .. code:: 2314 2315 #include "ssl.h" 2316 2317 .. code:: 2318 2319 SECStatus SSL_BadCertHook( 2320 PRFileDesc *fd, 2321 SSLBadCertHandler f, 2322 void *arg); 2323 2324 .. rubric:: Parameters 2325 :name: parameters_20 2326 2327 This function has the following parameters: 2328 2329 +---------+---------------------------------------------------------------------------------------+ 2330 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2331 +---------+---------------------------------------------------------------------------------------+ 2332 | ``f`` | A pointer to the application's callback function. | 2333 +---------+---------------------------------------------------------------------------------------+ 2334 | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | 2335 | | be ``NULL``. | 2336 +---------+---------------------------------------------------------------------------------------+ 2337 2338 .. rubric:: Returns 2339 :name: returns_23 2340 2341 The function returns one of these value\ ``s``: 2342 2343 - If successful, ``SECSuccess``. 2344 - If unsuccessful, ``SECFailure``. Use 2345 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2346 to obtain the error code. 2347 2348 .. rubric:: Description 2349 :name: description_27 2350 2351 The bad-certificate callback function gives the program an opportunity to do something (for 2352 example, log the attempt or authorize the certificate) when certificate authentication is not 2353 successful. If such a callback function is not provided by the application, the SSL connection 2354 simply fails when certificate authentication is not successful. 2355 2356 The callback function set up by ``SSL_BadCertHook`` has the following prototype: 2357 2358 .. code:: 2359 2360 typedef SECStatus (*SSLBadCertHandler)( 2361 void *arg, 2362 PRFileDesc *fd); 2363 2364 This callback function has the following parameters: 2365 2366 ======= =================================================================== 2367 ``arg`` The ``arg`` parameter passed to ```SSL_BadCertHook`` <#1088928>`__. 2368 ``fd`` A pointer to the file descriptor for the SSL socket. 2369 ======= =================================================================== 2370 2371 The callback function returns one of these values: 2372 2373 - ``SECSuccess``: The callback has chosen to authorize the certificate for use in this SSL 2374 connection, despite the fact that it failed the examination by the certificate authentication 2375 callback. 2376 - ``SECFailure``: The certificate is not authorized for this SSL connection. The SSL connection 2377 will be terminated immediately. 2378 2379 To obtain the certificate that was rejected by the certificate authentication callback, the 2380 bad-certificate callback function calls ```SSL_PeerCertificate`` <#1096168>`__. Since it is 2381 called immediately after the certificate authentication callback returns, the bad-certificate 2382 callback function can obtain the error code set by the certificate authentication callback by 2383 calling 2384 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2385 immediately, as the first operation it performs. Note: once the bad-certificate callback function 2386 returns, the peer certificate is destroyed, and SSL_PeerCertificate will fail. 2387 2388 The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11 2389 module. Some of the PK11 functions require a PIN argument (see 2390 ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value previously passed, the 2391 callback calls ```SSL_RevealPinArg`` <#1123385>`__ 2392 2393 .. rubric:: See Also 2394 :name: see_also_3 2395 2396 SSL_GetClientAuthDataHook 2397 2398 Defines a callback function for SSL to use in a client application when a server asks for client 2399 authentication information. This callback function is required if your client application is 2400 going to support client authentication. 2401 2402 .. rubric:: Syntax 2403 :name: syntax_28 2404 2405 .. code:: 2406 2407 #include "ssl.h" 2408 2409 .. code:: 2410 2411 SECStatus SSL_GetClientAuthDataHook( 2412 PRFileDesc *fd, 2413 SSLGetClientAuthData f, 2414 void *a); 2415 2416 .. rubric:: Parameters 2417 :name: parameters_21 2418 2419 This function has the following parameters: 2420 2421 +---------+---------------------------------------------------------------------------------------+ 2422 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2423 +---------+---------------------------------------------------------------------------------------+ 2424 | ``f`` | A pointer to the application's callback function that delivers the key and | 2425 | | certificate. | 2426 +---------+---------------------------------------------------------------------------------------+ 2427 | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | 2428 | | be ``NULL``. | 2429 +---------+---------------------------------------------------------------------------------------+ 2430 2431 .. rubric:: Returns 2432 :name: returns_24 2433 2434 The function returns one of these values: 2435 2436 - If successful, ``SECSuccess``. 2437 - If unsuccessful, ``SECFailure``. Use 2438 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2439 to obtain the error code. 2440 2441 .. rubric:: Description 2442 :name: description_28 2443 2444 The callback function set with ``SSL_GetClientAuthDataHook`` is used to get information from a 2445 client application when authentication is requested by the server. The callback function 2446 retrieves the client's private key and certificate. 2447 2448 SSL provides an implementation of this callback function; see 2449 ```NSS_GetClientAuthData`` <#1106762>`__ for details. Unlike 2450 ```SSL_AuthCertificate`` <#1088888>`__, ```NSS_GetClientAuthData`` <#1106762>`__ is not a default 2451 callback function. You must set it explicitly with ``SSL_GetClientAuthDataHook`` if you want to 2452 use it. 2453 2454 The callback function has the following prototype: 2455 2456 .. code:: 2457 2458 typedef SECStatus (*SSLGetClientAuthData)( 2459 void *arg, 2460 PRFileDesc *fd, 2461 CertDistNames *caNames, 2462 CERTCertificate **pRetCert, 2463 SECKEYPrivateKey **pRetKey); 2464 2465 This callback function has the following parameters: 2466 2467 ============ ================================================================================= 2468 ``arg`` The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``. 2469 ``fd`` A pointer to the file descriptor for the SSL socket. 2470 ``caNames`` A pointer to distinguished names of CAs that the server accepts. 2471 ``pRetCert`` A pointer to a pointer to a certificate structure, for returning the certificate. 2472 ``pRetKey`` A pointer to a pointer to a key structure, for returning the private key. 2473 ============ ================================================================================= 2474 2475 The callback function returns one of these values: 2476 2477 - If data returned is valid, ``SECSuccess``. 2478 - If the function cannot obtain a certificate, ``SECFailure``. 2479 2480 .. rubric:: NSS_GetClientAuthData 2481 :name: nss_getclientauthdata 2482 2483 Callback function that a client application can use to get the client's private key and 2484 certificate when authentication is requested by a remote server. 2485 2486 .. rubric:: Syntax 2487 :name: syntax_29 2488 2489 .. code:: 2490 2491 #include "ssl.h" 2492 2493 .. code:: 2494 2495 SECStatus NSS_GetClientAuthData( 2496 void * arg, 2497 PRFileDesc *socket, 2498 struct CERTDistNamesStr *caNames, 2499 struct CERTCertificateStr **pRetCert, 2500 struct SECKEYPrivateKeyStr **pRetKey); 2501 2502 .. rubric:: Parameters 2503 :name: parameters_22 2504 2505 This function has the following parameters: 2506 2507 +--------------+----------------------------------------------------------------------------------+ 2508 | ``arg`` | The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``, which should be a | 2509 | | pointer to a ``NULL``-terminated string containing the nickname of the | 2510 | | certificate and key pair to use. If ``arg`` is ``NULL``, | 2511 | | ``NSS_GetClientAuthData`` searches the certificate and key databases for a | 2512 | | suitable match and uses the certificate and key pair it finds, if any. | 2513 +--------------+----------------------------------------------------------------------------------+ 2514 | ``socket`` | A pointer to the file descriptor for the SSL socket. | 2515 +--------------+----------------------------------------------------------------------------------+ 2516 | ``caNames`` | A pointer to distinguished names of CAs that the server accepts. | 2517 +--------------+----------------------------------------------------------------------------------+ 2518 | ``pRetCert`` | A pointer to a pointer to a certificate structure, for returning the | 2519 | | certificate. | 2520 +--------------+----------------------------------------------------------------------------------+ 2521 | ``pRetKey`` | A pointer to a pointer to a key structure, for returning the private key. | 2522 +--------------+----------------------------------------------------------------------------------+ 2523 2524 .. rubric:: Returns 2525 :name: returns_25 2526 2527 The function returns one of these values: 2528 2529 - If successful, ``SECSuccess``. 2530 - If unsuccessful, ``SECFailure``. Use 2531 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2532 to obtain the error code. 2533 2534 .. rubric:: Description 2535 :name: description_29 2536 2537 Unlike ```SSL_AuthCertificate`` <#1088888>`__, ``NSS_GetClientAuthData`` is not a default 2538 callback function. You must set it explicitly with ```SSL_GetClientAuthDataHook`` <#1126622>`__ 2539 for each SSL client socket. 2540 2541 Once ``NSS_GetClientAuthData`` has been set for a client socket, SSL invokes it whenever SSL 2542 needs to know what certificate and private key (if any) to use to respond to a request for client 2543 authentication. 2544 2545 .. rubric:: SSL_HandshakeCallback 2546 :name: ssl_handshakecallback 2547 2548 Sets up a callback function used by SSL to inform either a client application or a server 2549 application when the handshake is completed. 2550 2551 .. rubric:: Syntax 2552 :name: syntax_30 2553 2554 .. code:: 2555 2556 #include "ssl.h" 2557 2558 .. code:: 2559 2560 SECStatus SSL_HandshakeCallback( 2561 PRFileDesc *fd, 2562 SSLHandshakeCallback cb, 2563 void *client_data); 2564 2565 .. rubric:: Parameters 2566 :name: parameters_23 2567 2568 This function has the following parameters: 2569 2570 +-----------------+-------------------------------------------------------------------------------+ 2571 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2572 +-----------------+-------------------------------------------------------------------------------+ 2573 | ``cb`` | A pointer to the application's callback function. | 2574 +-----------------+-------------------------------------------------------------------------------+ 2575 | ``client_data`` | A pointer to the value of the ``client_data`` argument that was passed to | 2576 | | ``SSL_HandshakeCallback``. | 2577 +-----------------+-------------------------------------------------------------------------------+ 2578 2579 .. rubric:: Returns 2580 :name: returns_26 2581 2582 The function returns one of these values: 2583 2584 - If successful, ``SECSuccess``. 2585 - If unsuccessful, ``SECFailure``. Use 2586 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2587 to obtain the error code. 2588 2589 .. rubric:: Description 2590 :name: description_30 2591 2592 The callback function set by ``SSL_HandshakeCallback`` has the following prototype: 2593 2594 .. code:: 2595 2596 typedef void (*SSLHandshakeCallback)( 2597 PRFileDesc *fd, 2598 void *client_data); 2599 2600 This callback function has the following parameters: 2601 2602 +-----------------+-------------------------------------------------------------------------------+ 2603 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2604 +-----------------+-------------------------------------------------------------------------------+ 2605 | ``client_data`` | A pointer supplied by the application that can be used to pass state | 2606 | | information. Can be ``NULL``. | 2607 +-----------------+-------------------------------------------------------------------------------+ 2608 2609 .. rubric:: See Also 2610 :name: see_also_4 2611 2612 .. _ssl_communication_functions: 2613 2614 `SSL Communication Functions <#ssl_communication_functions>`__ 2615 -------------------------------------------------------------- 2616 2617 .. container:: 2618 2619 Most communication functions are described in the `NSPR 2620 Reference <../../../../../nspr/reference/html/index.html>`__. For a complete list of 2621 communication functions used by SSL-enabled applications, see 2622 `Communication <sslintro.html#1027816>`__. 2623 2624 | ```SSL_InvalidateSession`` <#1089420>`__ 2625 | ```SSL_DataPending`` <#1092785>`__ 2626 | ```SSL_SecurityStatus`` <#1092805>`__ 2627 | ```SSL_GetSessionID`` <#1092869>`__ 2628 | ```SSL_SetSockPeerID`` <#1124562>`__ 2629 2630 .. rubric:: SSL_InvalidateSession 2631 :name: ssl_invalidatesession 2632 2633 Removes the current session on a particular SSL socket from the session cache. 2634 2635 .. rubric:: Syntax 2636 :name: syntax_31 2637 2638 .. code:: 2639 2640 #include "ssl.h" 2641 2642 .. code:: 2643 2644 int SSL_InvalidateSession(PRFileDesc *fd); 2645 2646 .. rubric:: Parameter 2647 :name: parameter_4 2648 2649 This function has the following parameter: 2650 2651 ====== ==================================================== 2652 ``fd`` A pointer to the file descriptor for the SSL socket. 2653 ====== ==================================================== 2654 2655 .. rubric:: Returns 2656 :name: returns_27 2657 2658 The function returns one of these values: 2659 2660 - If successful, zero. 2661 - If unsuccessful, -1. Use 2662 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2663 to obtain the error code. 2664 2665 .. rubric:: Description 2666 :name: description_31 2667 2668 After you call ``SSL_InvalidateSession``, the existing connection using the session can continue, 2669 but no new connections can resume this SSL session. 2670 2671 .. rubric:: SSL_DataPending 2672 :name: ssl_datapending 2673 2674 Returns the number of bytes waiting in internal SSL buffers to be read by the local application 2675 from the SSL socket. 2676 2677 .. rubric:: Syntax 2678 :name: syntax_32 2679 2680 .. code:: 2681 2682 #include "ssl.h" 2683 2684 .. code:: 2685 2686 int SSL_DataPending(PRFileDesc *fd); 2687 2688 .. rubric:: Parameter 2689 :name: parameter_5 2690 2691 This function has the following parameter: 2692 2693 ====== ========================================================== 2694 ``fd`` A pointer to a file descriptor for a connected SSL socket. 2695 ====== ========================================================== 2696 2697 .. rubric:: Returns 2698 :name: returns_28 2699 2700 The function returns an integer: 2701 2702 - If successful, the function returns the number of bytes waiting in internal SSL buffers for 2703 the specified socket. 2704 - If ``SSL_SECURITY`` has not been enabled with a call to 2705 ```SSL_OptionSetDefault`` <#1068466>`__ or ```SSL_OptionSet`` <#1086543>`__, the function 2706 returns zero. 2707 2708 .. rubric:: Description 2709 :name: description_32 2710 2711 The ``SSL_DataPending`` function determines whether there is any received and decrypted 2712 application data remaining in the SSL socket's receive buffers after a prior read operation. This 2713 function does not reveal any information about data that has been received but has not yet been 2714 decrypted. Hence, if this function returns zero, that does not necessarily mean that a subsequent 2715 call to 2716 ```PR_Read`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Read>`__ 2717 would block. 2718 2719 .. rubric:: SSL_SecurityStatus 2720 :name: ssl_securitystatus 2721 2722 Gets information about the security parameters of the current connection. 2723 2724 .. rubric:: Syntax 2725 :name: syntax_33 2726 2727 .. code:: 2728 2729 #include "ssl.h" 2730 2731 .. code:: 2732 2733 SECStatus SSL_SecurityStatus( 2734 PRFileDesc *fd, 2735 int *on, 2736 char **cipher, 2737 int *keysize, 2738 int *secretKeySize, 2739 char **issuer, 2740 char **subject); 2741 2742 .. rubric:: Parameters 2743 :name: parameters_24 2744 2745 This function has the following parameters: 2746 2747 +-------------------------------------------------+-------------------------------------------------+ 2748 | ``fd`` | The file descriptor for the SSL socket. | 2749 +-------------------------------------------------+-------------------------------------------------+ 2750 | ``on`` | A pointer to an integer. On output, the integer | 2751 | | will be one of these values: | 2752 | | | 2753 | | - ``SSL_SECURITY_STATUS_ OFF (= 0)`` | 2754 | | - ``SSL_SECURITY_STATUS_ ON_HIGH (= 1)`` | 2755 | | - ``SSL_SECURITY_STATUS_ON_LOW (= 2)`` | 2756 +-------------------------------------------------+-------------------------------------------------+ 2757 | ``cipher`` | A pointer to a string pointer. On output, the | 2758 | | string pointer references a newly allocated | 2759 | | string specifying the name of the cipher. For | 2760 | | SSL v2, the string is one of the following: | 2761 | | | 2762 | | ``RC4`` | 2763 | | ``RC4-Export`` | 2764 | | | 2765 | | ``RC2-CBC`` | 2766 | | | 2767 | | ``RC2-CBC-Export`` | 2768 | | | 2769 | | ``DES-CBC`` | 2770 | | | 2771 | | ``DES-EDE3-CBC`` | 2772 | | | 2773 | | For SSL v3, the string is one of the following: | 2774 | | | 2775 | | ``RC4`` | 2776 | | ``RC4-40`` | 2777 | | | 2778 | | ``RC2-CBC`` | 2779 | | | 2780 | | ``RC2-CBC-40`` | 2781 | | | 2782 | | ``DES-CBC`` | 2783 | | | 2784 | | ``3DES-EDE-CBC`` | 2785 | | | 2786 | | ``DES-CBC-40`` | 2787 | | | 2788 | | ``FORTEZZA`` | 2789 +-------------------------------------------------+-------------------------------------------------+ 2790 | ``keySize`` | A pointer to an integer. On output, the integer | 2791 | | is the session key size used, in bits. | 2792 +-------------------------------------------------+-------------------------------------------------+ 2793 | ``secretKeySize`` | A pointer to an integer. On output, the integer | 2794 | | indicates the size, in bits, of the secret | 2795 | | portion of the session key used (also known as | 2796 | | the "effective key size"). The secret key size | 2797 | | is never greater than the session key size. | 2798 +-------------------------------------------------+-------------------------------------------------+ 2799 | ``issuer`` | A pointer to a string pointer. On output, the | 2800 | | string pointer references a newly allocated | 2801 | | string specifying the DN of the issuer of the | 2802 | | certificate at the other end of the connection, | 2803 | | in RFC1485 format. If no certificate is | 2804 | | supplied, the string is "``no certificate``." | 2805 +-------------------------------------------------+-------------------------------------------------+ 2806 | ``subject`` | A pointer to a string pointer specifying the | 2807 | | distinguished name of the certificate at the | 2808 | | other end of the connection, in RFC1485 format. | 2809 | | If no certificate is supplied, the string is | 2810 | | "``no certificate``." | 2811 +-------------------------------------------------+-------------------------------------------------+ 2812 2813 .. rubric:: Returns 2814 :name: returns_29 2815 2816 The function returns one of these values: 2817 2818 - If successful, ``SECSuccess``. 2819 - If unsuccessful, ``SECFailure``. Use 2820 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2821 to obtain the error code. 2822 2823 .. rubric:: Description 2824 :name: description_33 2825 2826 The ``SSL_SecurityStatus`` function fills in values only if you supply pointers to values of the 2827 appropriate type. Pointers passed can be ``NULL``, in which case the function does not supply 2828 values. When you are finished with them, you should free all the returned values using 2829 ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__. 2830 2831 .. rubric:: SSL_GetSessionID 2832 :name: ssl_getsessionid 2833 2834 Returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL session ID 2835 associated with a file descriptor. 2836 2837 .. rubric:: Syntax 2838 :name: syntax_34 2839 2840 .. code:: 2841 2842 #include "ssl.h" 2843 2844 .. code:: 2845 2846 SECItem *SSL_GetSessionID(PRFileDesc *fd); 2847 2848 .. rubric:: Parameter 2849 :name: parameter_6 2850 2851 This function has the following parameter: 2852 2853 ====== ==================================================== 2854 ``fd`` A pointer to the file descriptor for the SSL socket. 2855 ====== ==================================================== 2856 2857 .. rubric:: Returns 2858 :name: returns_30 2859 2860 The function returns one of these values: 2861 2862 If unsuccessful, ``NULL``. 2863 2864 .. rubric:: Description 2865 :name: description_34 2866 2867 This function returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL 2868 session ID associated with the file descriptor ``fd``. When the application is finished with the 2869 ``SECItem`` structure returned by this function, it should free the structure by calling 2870 ``SECITEM_FreeItem(item, PR_TRUE)``. 2871 2872 .. rubric:: SSL_SetSockPeerID 2873 :name: ssl_setsockpeerid 2874 2875 Associates a peer ID with a socket to facilitate looking up the SSL session when it is tunneling 2876 through a proxy. 2877 2878 .. rubric:: Syntax 2879 :name: syntax_35 2880 2881 .. code:: 2882 2883 #include "ssl.h" 2884 2885 .. code:: 2886 2887 int SSL_SetSockPeerID(PRFileDesc *fd, char *peerID); 2888 2889 .. rubric:: Parameters 2890 :name: parameters_25 2891 2892 This function has the following parameters: 2893 2894 +------------+------------------------------------------------------------------------------------+ 2895 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 2896 +------------+------------------------------------------------------------------------------------+ 2897 | ``peerID`` | An ID number assigned by the application to keep track of the SSL session | 2898 | | associated with the peer. | 2899 +------------+------------------------------------------------------------------------------------+ 2900 2901 .. rubric:: Returns 2902 :name: returns_31 2903 2904 The function returns one of these values: 2905 2906 - If successful, zero. 2907 - If unsuccessful, -1. Use 2908 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 2909 to obtain the error code. 2910 2911 .. rubric:: Description 2912 :name: description_35 2913 2914 SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of 2915 repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a 2916 session cache, which retains information about each connection for some predetermined length of 2917 time. For example, a client session cache includes the hostname and port number of each server 2918 the client connects with, plus additional information such as the master secret generated during 2919 the SSL handshake. 2920 2921 For a direct connection with a server, the hostname and port number are sufficient for the client 2922 to identify the server as one for which it has an entry in its session cache. However, the 2923 situation is more complicated if the client is on an intranet and is connecting to a server on 2924 the Internet through a proxy. In this case, the client first connects to the proxy, and the 2925 client and proxy exchange messages specified by the proxy protocol that allow the proxy, in turn, 2926 to connect to the requested server on behalf of the client. This arrangement is known as SSL 2927 tunneling. 2928 2929 Client session cache entries for SSL connections that tunnel through a particular proxy all have 2930 the same hostname and port number--that is, the hostname and port number of the proxy. To 2931 determine whether a particular server with which the client is attempting to connect has an entry 2932 in the session cache, the session cache needs some additional information that identifies that 2933 server. This additional identifying information is known as a peer ID. The peer ID is associated 2934 with a socket, and must be set before the SSL handshake occurs--that is, before the SSL handshake 2935 is initiated by a call to a function such as ``PR_Read`` or 2936 ```SSL_ForceHandshake`` <#1133431>`__. To set the peer ID, you use ``SSL_SetSockPeerID``. 2937 2938 In summary, SSL uses three pieces of information to identify a server's entry in the client 2939 session cache: the hostname, port number, and peer ID. In the case of a client that is tunneling 2940 through a proxy, the hostname and port number identify the proxy, and the peer ID identifies the 2941 desired server. Netscape recommends that the client set the peer ID to a string that consists of 2942 the server's hostname and port number, like this: "``www.hostname.com:387``". This convention 2943 guarantees that each server has a unique entry in the client session cache. 2944 2945 .. rubric:: See Also 2946 :name: see_also_5 2947 2948 For information about configuring the session cache for a server, see 2949 ```SSL_ConfigServerSessionIDCache`` <#1143851>`__. 2950 2951 .. _ssl_functions_used_by_callbacks: 2952 2953 `SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__ 2954 ---------------------------------------------------------------------- 2955 2956 .. container:: 2957 2958 | ```SSL_PeerCertificate`` <#1096168>`__ 2959 | ```SSL_RevealURL`` <#1081175>`__ 2960 | ```SSL_RevealPinArg`` <#1123385>`__ 2961 2962 .. rubric:: SSL_PeerCertificate 2963 :name: ssl_peercertificate 2964 2965 Returns a pointer to the certificate structure for the certificate received from the remote end 2966 of the SSL connection. 2967 2968 .. rubric:: Syntax 2969 :name: syntax_36 2970 2971 .. code:: 2972 2973 #include "ssl.h" 2974 2975 .. code:: 2976 2977 CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd); 2978 2979 .. rubric:: Parameter 2980 :name: parameter_7 2981 2982 This function has the following parameter: 2983 2984 ====== ==================================================== 2985 ``fd`` A pointer to the file descriptor for the SSL socket. 2986 ====== ==================================================== 2987 2988 .. rubric:: Returns 2989 :name: returns_32 2990 2991 The function returns one of these values: 2992 2993 - If successful, a pointer to a certificate structure. 2994 - If unsuccessful, ``NULL``. 2995 2996 .. rubric:: Description 2997 :name: description_36 2998 2999 The ``SSL_PeerCertificate`` function is used by certificate authentication and bad-certificate 3000 callback functions to obtain the certificate under scrutiny. If the client calls 3001 ``SSL_PeerCertificate``, it always returns the server's certificate. If the server calls 3002 ``SSL_PeerCertificate``, it may return ``NULL`` if client authentication is not enabled or if the 3003 client had no certificate when asked. 3004 3005 SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of 3006 certificate and key structures. The application should destroy its copies when it has no further 3007 use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and 3008 ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. 3009 3010 .. rubric:: SSL_RevealURL 3011 :name: ssl_revealurl 3012 3013 Returns a pointer to a newly allocated string containing the domain name of the desired server. 3014 3015 .. rubric:: Syntax 3016 :name: syntax_37 3017 3018 .. code:: 3019 3020 #include "ssl.h" 3021 3022 .. code:: 3023 3024 char *SSL_RevealURL(PRFileDesc *fd); 3025 3026 .. rubric:: Parameter 3027 :name: parameter_8 3028 3029 This function has the following parameter: 3030 3031 ====== ==================================================== 3032 ``fd`` A pointer to the file descriptor for the SSL socket. 3033 ====== ==================================================== 3034 3035 .. rubric:: Returns 3036 :name: returns_33 3037 3038 The function returns one of the following values: 3039 3040 - If successful, returns a pointer to a newly allocated string containing the domain name of the 3041 desired server. 3042 - If unsuccessful, ``NULL``. 3043 3044 .. rubric:: Description 3045 :name: description_37 3046 3047 The ``SSL_RevealURL`` function is used by certificate authentication callback function to obtain 3048 the domain name of the desired SSL server for the purpose of comparing it with the domain name in 3049 the certificate presented by the server actually contacted. When the callback function is 3050 finished with the string returned, the string should be freed with a call to 3051 ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__. 3052 3053 .. rubric:: SSL_RevealPinArg 3054 :name: ssl_revealpinarg 3055 3056 Returns the ``PKCS11PinArg`` value associated with the socket. 3057 3058 .. rubric:: Syntax 3059 :name: syntax_38 3060 3061 .. code:: 3062 3063 #include "ssl.h" 3064 3065 .. code:: 3066 3067 void *SSL_RevealPinArg(PRFileDesc *fd); 3068 3069 .. rubric:: Parameter 3070 :name: parameter_9 3071 3072 This function has the following parameter: 3073 3074 ====== ==================================================== 3075 ``fd`` A pointer to the file descriptor for the SSL socket. 3076 ====== ==================================================== 3077 3078 .. rubric:: Returns 3079 :name: returns_34 3080 3081 The function returns one of the following values: 3082 3083 - If successful, the ``PKCS11PinArg`` value associated with the socket. 3084 - If unsuccessful, ``NULL``. 3085 3086 .. rubric:: Description 3087 :name: description_38 3088 3089 The ``SSL_RevealPinArg`` function is used by callback functions to obtain the PIN argument that 3090 NSS passes to certain functions. The PIN argument points to memory allocated by the application. 3091 The application is responsible for managing the memory referred to by this pointer. For more 3092 information about this argument, see ```SSL_SetPKCS11PinArg`` <#1088040>`__. 3093 3094 .. _ssl_handshake_functions: 3095 3096 `SSL Handshake Functions <#ssl_handshake_functions>`__ 3097 ------------------------------------------------------ 3098 3099 .. container:: 3100 3101 | ```SSL_ForceHandshake`` <#1133431>`__ 3102 | ```SSL_ReHandshake`` <#1232052>`__ 3103 | ```SSL_ResetHandshake`` <#1058001>`__ 3104 3105 .. rubric:: SSL_ForceHandshake 3106 :name: ssl_forcehandshake 3107 3108 Drives a handshake for a specified SSL socket to completion on a socket that has already been 3109 prepared to do a handshake or is in the middle of doing a handshake. 3110 3111 .. rubric:: Syntax 3112 :name: syntax_39 3113 3114 .. code:: 3115 3116 #include "ssl.h" 3117 3118 .. code:: 3119 3120 SECStatus SSL_ForceHandshake(PRFileDesc *fd); 3121 3122 .. rubric:: Parameters 3123 :name: parameters_26 3124 3125 This function has the following parameter: 3126 3127 ====== ================================================== 3128 ``fd`` Pointer to the file descriptor for the SSL socket. 3129 ====== ================================================== 3130 3131 .. rubric:: Returns 3132 :name: returns_35 3133 3134 The function returns one of these values: 3135 3136 - If successful, ``SECSuccess``. 3137 - If unsuccessful, ``SECFailure``. Use 3138 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3139 to obtain the error code. 3140 3141 .. rubric:: Description 3142 :name: description_39 3143 3144 When you are forcing the initial handshake on a blocking socket, this function returns when the 3145 handshake is complete. For subsequent handshakes, the function can return either because the 3146 handshake is complete, or because application data has been received on the connection that must 3147 be processed (that is, the application must read it) before the handshake can continue. 3148 3149 You can use ``SSL_ForceHandshake`` when a handshake is desired but neither end has anything to 3150 say immediately. This occurs, for example, when an HTTPS server has received a request and 3151 determines that before it can answer the request, it needs to request an authentication 3152 certificate from the client. At the HTTP protocol level, nothing more is being said (that is, no 3153 HTTP request or response is being sent), so the server uses ``SSL_ForceHandshake`` to make the 3154 handshake occur. 3155 3156 ``SSL_ForceHandshake`` does not prepare a socket to do a handshake by itself. The following 3157 functions prepare a socket (previously imported into SSL and configured as necessary) to do a 3158 handshake: 3159 3160 - ``PR_Connect`` 3161 - ``PR_Accept`` 3162 - ```SSL_ReHandshake`` <#1232052>`__ (after the first handshake is finished) 3163 - ```SSL_ResetHandshake`` <#1058001>`__ (for sockets that were connected or accepted prior to 3164 being imported) 3165 3166 A call to ``SSL_ForceHandshake`` will almost always be preceded by one of those functions. 3167 3168 In versions prior to NSS 1.2, you cannot force a subsequent handshake. If you use this function 3169 after the initial handshake, it returns immediately without forcing a handshake. 3170 3171 .. rubric:: SSL_ReHandshake 3172 :name: ssl_rehandshake 3173 3174 Causes SSL to begin a new SSL 3.0 handshake on a connection that has already completed one 3175 handshake. 3176 3177 ``SSL_ReHandshake`` replaces the deprecated function ```SSL_RedoHandshake`` <#1231825>`__. 3178 3179 .. rubric:: Syntax 3180 :name: syntax_40 3181 3182 .. code:: 3183 3184 #include "ssl.h" 3185 3186 .. code:: 3187 3188 SECStatus SSL_RedoHandshake(PRFileDesc *fd, PRBool flushCache); 3189 3190 .. rubric:: Parameter 3191 :name: parameter_10 3192 3193 This function has the following parameters: 3194 3195 +-------------------------------------------------+-------------------------------------------------+ 3196 | ``fd`` | A pointer to the file descriptor for the SSL | 3197 | | socket. | 3198 +-------------------------------------------------+-------------------------------------------------+ 3199 | ``flushCache`` | If ``flushCache`` is non-zero, the SSL3 cache | 3200 | | entry will be flushed first, ensuring that a | 3201 | | full SSL handshake from scratch will occur. | 3202 | | | 3203 | | If ``flushCache`` is zero, and an SSL | 3204 | | connection is established, it will do the much | 3205 | | faster session restart handshake. This will | 3206 | | regenerate the symmetric session keys without | 3207 | | doing another private key operation. | 3208 +-------------------------------------------------+-------------------------------------------------+ 3209 3210 .. rubric:: Returns 3211 :name: returns_36 3212 3213 The function returns one of these values: 3214 3215 - If successful, ``SECSuccess``. 3216 - If unsuccessful, ``SECFailure``. Use 3217 ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error 3218 code. 3219 3220 .. rubric:: Description 3221 :name: description_40 3222 3223 If ``flushCache`` is non-zero, the ``SSL_ReHandshake`` function invalidates the current SSL 3224 session associated with the specified ``fd`` from the session cache and starts another full SSL 3225 3.0 handshake. It is for use with SSL 3.0 only. You can call this function to redo the handshake 3226 if you have changed one of the socket's configuration parameters (for example, if you are going 3227 to request client authentication). 3228 3229 Setting ``flushCache`` to zero can be useful, for example, if you are using export ciphers and 3230 want to keep changing the symmetric keys to foil potential attackers. 3231 3232 ``SSL_ReHandshake`` only initiates the new handshake by sending the first message of that 3233 handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake`` 3234 or do another I/O operation (read or write) on the socket. A call to ``SSL_ReHandshake`` is 3235 typically followed by a call to ``SSL_ForceHandshake``. 3236 3237 .. rubric:: SSL_ResetHandshake 3238 :name: ssl_resethandshake 3239 3240 Resets the handshake state for a specified socket. 3241 3242 .. rubric:: Syntax 3243 :name: syntax_41 3244 3245 .. code:: 3246 3247 #include "ssl.h" 3248 3249 .. code:: 3250 3251 SECStatus SSL_ResetHandshake( 3252 PRFileDesc *fd, 3253 PRBool asServer); 3254 3255 .. rubric:: Parameters 3256 :name: parameters_27 3257 3258 This function has the following parameters: 3259 3260 +--------------+----------------------------------------------------------------------------------+ 3261 | ``fd`` | A pointer to the file descriptor for the SSL socket. | 3262 +--------------+----------------------------------------------------------------------------------+ 3263 | ``asServer`` | A Boolean value. ``PR_TRUE`` means the socket will attempt to handshake as a | 3264 | | server the next time it tries, and ``PR_FALSE`` means the socket will attempt to | 3265 | | handshake as a client the next time it tries. | 3266 +--------------+----------------------------------------------------------------------------------+ 3267 3268 .. rubric:: Returns 3269 :name: returns_37 3270 3271 The function returns one of these values: 3272 3273 - If successful, ``SECSuccess``. 3274 - If unsuccessful, ``SECFailure``. Use 3275 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3276 to obtain the error code. 3277 3278 .. rubric:: Description 3279 :name: description_41 3280 3281 Calling ``SSL_ResetHandshake`` causes the SSL handshake protocol to start from the beginning on 3282 the next I/O operation. That is, the handshake starts with no cipher suite already in use, just 3283 as it does on the first handshake on a new socket. 3284 3285 When an application imports a socket into SSL after the TCP connection on that socket has already 3286 been established, it must call ``SSL_ResetHandshake`` to determine whether SSL should behave like 3287 an SSL client or an SSL server. Note that this step would not be necessary if the socket weren't 3288 already connected. For an SSL socket that is configured before it is connected, SSL figures this 3289 out when the application calls 3290 ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ 3291 or 3292 ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__. 3293 If the socket is already connected before SSL gets involved, you must provide this extra hint. 3294 3295 .. _nss_shutdown_function: 3296 3297 `NSS Shutdown Function <#nss_shutdown_function>`__ 3298 -------------------------------------------------- 3299 3300 .. container:: 3301 3302 .. rubric:: NSS_Shutdown 3303 :name: nss_shutdown 3304 3305 Closes the key and certificate databases that were opened by ```NSS_Init`` <#1067601>`__. 3306 3307 .. rubric:: Syntax 3308 :name: syntax_42 3309 3310 .. code:: 3311 3312 #include "nss.h" 3313 3314 .. code:: 3315 3316 SECStatus NSS_Shutdown(void); 3317 3318 .. rubric:: Description 3319 :name: description_42 3320 3321 Note that if any reference to an NSS object is leaked (for example, if an SSL client application 3322 doesn't call ```SSL_ClearSessionCache`` <#1138601>`__ first), ``NSS_Shutdown`` fails with the 3323 error code ``SEC_ERROR_BUSY``. 3324 3325 .. _deprecated_functions: 3326 3327 `Deprecated Functions <#deprecated_functions>`__ 3328 ------------------------------------------------ 3329 3330 .. container:: 3331 3332 The following functions have been replaced with newer versions but are still supported: 3333 3334 | ```SSL_EnableDefault`` <#1206365>`__ 3335 | ```SSL_Enable`` <#1220189>`__ 3336 | ```SSL_EnableCipher`` <#1207298>`__ 3337 | ```SSL_SetPolicy`` <#1207350>`__ 3338 3339 .. rubric:: SSL_EnableDefault 3340 :name: ssl_enabledefault 3341 3342 Changes a default value for all subsequently opened sockets as long as the current application 3343 program is running. 3344 3345 ``SSL_EnableDefault`` has been replaced by ```SSL_OptionSetDefault`` <#1068466>`__ and works the 3346 same way. 3347 3348 .. rubric:: Syntax 3349 :name: syntax_43 3350 3351 .. code:: 3352 3353 #include "ssl.h" 3354 3355 .. code:: 3356 3357 SECStatus SSL_EnableDefault(int which, PRBool on); 3358 3359 .. rubric:: Parameters 3360 :name: parameters_28 3361 3362 This function has the following parameters: 3363 3364 +-----------+-------------------------------------------------------------------------------------+ 3365 | ``which`` | For information about the values that can be passed in the ``which`` parameter, see | 3366 | | ```SSL_OptionSetDefault`` <#1068466>`__. | 3367 +-----------+-------------------------------------------------------------------------------------+ 3368 | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. | 3369 +-----------+-------------------------------------------------------------------------------------+ 3370 3371 .. rubric:: Returns 3372 :name: returns_38 3373 3374 The function returns one of these values: 3375 3376 - If successful, ``SECSuccess``. 3377 - If unsuccessful, ``SECFailure``. Use 3378 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3379 to obtain the error code. 3380 3381 .. rubric:: Description 3382 :name: description_43 3383 3384 For detailed information about using ``SSL_Enable``, see the description of 3385 ```SSL_OptionSetDefault`` <#1068466>`__. 3386 3387 .. rubric:: SSL_Enable 3388 :name: ssl_enable 3389 3390 Sets a single configuration parameter of a specified socket. Call once for each parameter you 3391 want to change. 3392 3393 ``SSL_Enable`` has been replaced by ```SSL_OptionSet`` <#1086543>`__ and works the same way. 3394 3395 .. rubric:: Syntax 3396 :name: syntax_44 3397 3398 .. code:: 3399 3400 #include "ssl.h" 3401 3402 .. code:: 3403 3404 SECStatus SSL_Enable( 3405 PRFileDesc *fd, 3406 int which, 3407 PRBool on); 3408 3409 .. rubric:: Parameters 3410 :name: parameters_29 3411 3412 This function has the following parameters: 3413 3414 +-----------+-------------------------------------------------------------------------------------+ 3415 | ``fd`` | Pointer to the file descriptor for the SSL socket. | 3416 +-----------+-------------------------------------------------------------------------------------+ 3417 | ``which`` | For information about the values that can be passed in the ``which`` parameter, see | 3418 | | the description of the ``option`` parameter under ```SSL_OptionSet`` <#1086543>`__. | 3419 +-----------+-------------------------------------------------------------------------------------+ 3420 | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. | 3421 +-----------+-------------------------------------------------------------------------------------+ 3422 3423 .. rubric:: Returns 3424 :name: returns_39 3425 3426 The function returns one of these values: 3427 3428 - If successful, ``SECSuccess``. 3429 - If unsuccessful, returns ``SECFailure``. Use 3430 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3431 to obtain the error code. 3432 3433 .. rubric:: Description 3434 :name: description_44 3435 3436 For detailed information about using ``SSL_Enable``, see the description of 3437 ```SSL_OptionSet`` <#1086543>`__. 3438 3439 .. rubric:: SSL_EnableCipher 3440 :name: ssl_enablecipher 3441 3442 Enables or disables cipher suites (subject to which cipher suites are permitted or disallowed by 3443 previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__). This function 3444 must be called once for each cipher you want to enable or disable. 3445 3446 ``SSL_EnableCipher`` has been replaced by ```SSL_CipherPrefSetDefault`` <#1084747>`__ and works 3447 the same way. 3448 3449 .. rubric:: Syntax 3450 :name: syntax_45 3451 3452 .. code:: 3453 3454 #include "ssl.h" 3455 #include "sslproto.h" 3456 3457 .. code:: 3458 3459 SECStatus SSL_EnableCipher(long which, PRBool enabled); 3460 3461 .. rubric:: Parameters 3462 :name: parameters_30 3463 3464 This function has the following parameters: 3465 3466 +-------------+-----------------------------------------------------------------------------------+ 3467 | ``which`` | The cipher suite whose default preference setting you want to set. For a list of | 3468 | | the cipher suites you can specify, see | 3469 | | ```SSL_CipherPrefSetDefault`` <#1084747>`__. | 3470 +-------------+-----------------------------------------------------------------------------------+ 3471 | ``enabled`` | If nonzero, the specified cipher is enabled. If zero, the cipher is disabled. | 3472 +-------------+-----------------------------------------------------------------------------------+ 3473 3474 .. rubric:: Returns 3475 :name: returns_40 3476 3477 The function returns one of these values: 3478 3479 - If successful, ``SECSuccess``. 3480 - If unsuccessful, ``SECFailure``. Use 3481 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3482 to obtain the error code. 3483 3484 .. rubric:: Description 3485 :name: description_45 3486 3487 For detailed information about using ``SSL_EnableCipher``, see the description of 3488 ```SSL_CipherPrefSetDefault`` <#1084747>`__. 3489 3490 .. rubric:: SSL_SetPolicy 3491 :name: ssl_setpolicy 3492 3493 Sets policy for the use of individual cipher suites. 3494 3495 ``SSL_SetPolicy`` has been replaced by ```SSL_CipherPolicySet`` <#1104647>`__ and works the same 3496 way. 3497 3498 .. rubric:: Syntax 3499 :name: syntax_46 3500 3501 .. code:: 3502 3503 #include <ssl.h> 3504 #include <sslproto.h> 3505 3506 .. code:: 3507 3508 SECStatus SSL_SetPolicy(long which, int policy); 3509 3510 .. rubric:: Parameters 3511 :name: parameters_31 3512 3513 This function has the following parameters: 3514 3515 +-------------------------------------------------+-------------------------------------------------+ 3516 | ``which`` | The cipher suite for which you want to set | 3517 | | policy. For a list of possible values, see | 3518 | | ```SSL_CipherPolicySet`` <#1104647>`__. | 3519 +-------------------------------------------------+-------------------------------------------------+ 3520 | ``policy`` | One of the following values: | 3521 | | | 3522 | | - ``SSL_ALLOWED``. Cipher is always allowed by | 3523 | | U.S. government policy. | 3524 | | - ``SSL_RESTRICTED``. Cipher is allowed by | 3525 | | U.S. government policy for servers with | 3526 | | Global ID certificates. | 3527 | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | 3528 | | by U.S. government policy. | 3529 +-------------------------------------------------+-------------------------------------------------+ 3530 3531 .. rubric:: Returns 3532 :name: returns_41 3533 3534 The function returns one of these values: 3535 3536 - If successful, ``SECSuccess``. 3537 - If unsuccessful, ``SECFailure``. Use 3538 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3539 to obtain the error code. 3540 3541 .. rubric:: Description 3542 :name: description_46 3543 3544 For detailed information about using ``SSL_SetPolicy``, see the description of 3545 ```SSL_CipherPolicySet`` <#1104647>`__. 3546 3547 .. rubric:: SSL_RedoHandshake 3548 :name: ssl_redohandshake 3549 3550 Causes SSL to begin a full, new SSL 3.0 handshake from scratch on a connection that has already 3551 completed one handshake. 3552 3553 .. rubric:: Syntax 3554 :name: syntax_47 3555 3556 .. code:: 3557 3558 #include "ssl.h" 3559 3560 .. code:: 3561 3562 int SSL_RedoHandshake(PRFileDesc *fd); 3563 3564 .. rubric:: Parameter 3565 :name: parameter_11 3566 3567 This function has the following parameter: 3568 3569 ====== ==================================================== 3570 ``fd`` A pointer to the file descriptor for the SSL socket. 3571 ====== ==================================================== 3572 3573 .. rubric:: Returns 3574 :name: returns_42 3575 3576 The function returns one of these values: 3577 3578 - If successful, zero. 3579 - If unsuccessful, -1. Use 3580 ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ 3581 to obtain the error code. 3582 3583 .. rubric:: Description 3584 :name: description_47 3585 3586 The ``SSL_RedoHandshake`` function invalidates the current SSL session associated with the ``fd`` 3587 parameter from the session cache and starts another full SSL 3.0 handshake. It is for use with 3588 SSL 3.0 only. You can call this function to redo the handshake if you have changed one of the 3589 socket's configuration parameters (for example, if you are going to request client 3590 authentication). 3591 3592 ``SSL_RedoHandshake`` only initiates the new handshake by sending the first message of that 3593 handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake`` 3594 or do another I/O operation (read or write) on the socket. A call to ``SSL_RedoHandshake`` is 3595 typically followed by a call to ``SSL_ForceHandshake``.