summaryrefslogtreecommitdiffstats
path: root/security/nss/doc/rst/legacy/ssl_functions
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/doc/rst/legacy/ssl_functions')
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst264
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/index.rst83
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst269
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst439
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst632
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst1434
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst3595
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst291
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst107
-rw-r--r--security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst343
10 files changed, 7457 insertions, 0 deletions
diff --git a/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst b/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst
new file mode 100644
index 0000000000..520c9aa66c
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst
@@ -0,0 +1,264 @@
+.. _mozilla_projects_nss_ssl_functions_gtstd:
+
+gtstd
+=====
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: Getting Started With SSL
+ :name: Getting_Started_With_SSL
+
+ --------------
+
+.. _chapter_2_getting_started_with_ssl:
+
+`Chapter 2 <#chapter_2_getting_started_with_ssl>`__ Getting Started With SSL
+----------------------------------------------------------------------------
+
+.. container::
+
+ This chapter describes how to set up your environment, including certificate and key databases.
+
+ | `SSL, PKCS #11, and the Default Security Databases <#1011970>`__
+ | `Setting Up the Certificate and Key Databases <#1011987>`__
+ | `Building NSS Programs <#1013274>`__
+
+.. _ssl_pkcs_11_and_the_default_security_databases:
+
+`SSL, PKCS #11, and the Default Security Databases <#ssl_pkcs_11_and_the_default_security_databases>`__
+-------------------------------------------------------------------------------------------------------
+
+.. container::
+
+ The basic relationships among the NSS libraries are described in `Introduction to Network
+ Security Services <../../intro.html>`__. Before running the sample programs, it's important to
+ understand the relationships between the SSL interface, the PKCS #11 interface, PKCS #11 modules,
+ and the default Netscape security databases.
+
+ A **PKCS #11 module** (also called a **cryptographic module**) manages cryptographic services
+ such as encryption and decryption via the PKCS #11 interface. PKCS #11 modules can be thought of
+ as drivers for cryptographic devices that can be implemented in either hardware or software.
+ Netscape provides a built-in PKCS #11 module with NSS. Other kinds of PKCS #11 modules include
+ the Netscape FORTEZZA module, used by the government, and the Litronic PKCS #11 module for smart
+ card readers.
+
+ `Figure 2.1 <#1013181>`__ illustrates the relationships between NSPR, SSL, PKCS #11, and the
+ available cryptographic modules. SSL is built on top of NSPR, which handles sockets, threads, and
+ related low-level OS operations. On any given server or client, one or more PKCS #11 modules may
+ be available.
+
+ **Figure 2.1 Relationships among NSS libraries, cryptographic modules, slots, and tokens**
+
+ .. image:: /en-US/docs/Mozilla/Projects/NSS/SSL_functions/gtstd/pkcs.gif
+
+ As shown in the figure, SSL communicates with PKCS #11 modules through the PKCS #11 interface.
+ Any PKCS #11 module that supports PKCS #11 can be used with the NSS libraries. Netscape software
+ uses a file called ``secmod.db`` to keep track of the modules available.
+
+ A PKCS #11 module always has one or more **slots,** which may be implemented as physical hardware
+ slots in some form of physical reader (for example, for smart cards) or as conceptual slots in
+ software. Each slot for a PKCS #11 module can in turn contain a **token,** which is the hardware
+ or software device that actually provides cryptographic services and optionally stores
+ certificates and keys.
+
+ Netscape provides three built-in modules with NSS and with server and client products:
+
+ - The default Netscape Internal PKCS #11 Module comes with two built-in tokens:
+
+ - The Generic Crypto Services token performs all cryptographic operations, such as
+ encryption, decryption, and hashing.
+ - The Communicator Certificate DB token handles all communication with the certificate and
+ key database files (called ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db``, respectively,
+ where\ *X* is a version number) that store certificates and keys.
+
+ - The FORTEZZA module is intended for use with FORTEZZA hardware tokens.
+ - The FIPS 140-1 module is compliant with the FIPS 140-1 government standard for implementations
+ of cryptographic modules. Many products sold to the U.S. government must comply with one or
+ more of the FIPS standards. The FIPS 140-1 module includes a single, built-in FIPS 140-1
+ Certificate DB token (see `Figure 2.1 <#1013181>`__), which handles both cryptographic
+ operations and communication with the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files.
+
+ If you are creating a server application, you must use the Certificate Database Tool, which comes
+ with NSS, to create the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files and populate them
+ with the appropriate certificates and keys.
+
+ If you are creating a client application, you can use either the Certificate Database Tool or the
+ Communicator security interface to create the database files and populate them with the
+ appropriate certificates and keys. You can use Communicator to set up client certificate
+ databases by obtaining certificates from either a public CA or from a certificate server such as
+ Netscape Certificate Management System. The instructions that follow assume you are using the
+ Certificate Database Tool to set up both the server and client databases for testing purposes.
+
+ You can use the Security Module Database Tool, a command-line utility that comes with NSS, to
+ manage PKCS #11 module information within s\ ``ecmod.db`` files. The Security Module Database
+ Tool allows you to add and delete PKCS #11 modules, change passwords, set defaults, list module
+ contents, enable or disable slots, enable or disable FIPS-140-1 compliance, and assign default
+ providers for cryptographic operations.
+
+.. _setting_up_the_certificate_and_key_databases:
+
+`Setting Up the Certificate and Key Databases <#setting_up_the_certificate_and_key_databases>`__
+------------------------------------------------------------------------------------------------
+
+.. container::
+
+ Before you can run the sample programs (``server.c`` and ``client.c``) that come with NSS, you
+ must set up certificate, key, and security module databases for both the client and the server
+ and populate them with valid CA, client SSL, and server SSL certificates. The following sections
+ decribe how to the Certificate Database Tool to perform these tasks:
+
+ | `Setting Up the CA DB and Certificate <#1012301>`__
+ | `Setting Up the Server DB and Certificate <#1012351>`__
+ | `Setting Up the Client DB and Certificate <#1012067>`__
+ | `Verifying the Server and Client Certificates <#1012108>`__
+
+ **WARNING:** The instructions below illustrate the use of NSS command line tools to operate a
+ simple root Certificate Authority for test purposes only. The CA, SSL server and SSL client
+ certificates produced by these instructions work correctly for short term testing purposes.
+ Although it is possible to use NSS command line tools to operate a proper CA, these
+ instructions do not provide nearly enough understanding of the many considerations required to
+ competently operate a CA. The NSS teams **strongly** recommends that users should not attempt
+ to operate a CA for use in mission critical production business uses using NSS's command line
+ tools, nor with the simple command line test tools that come with any package of cryptographic
+ libraries. Many who have attempted it have eventually come to regret that decision. For
+ production deployment, the NSS team strongly recommends that you either:
+
+ - Use certificates from a competent third-party CA that is already known to your relying
+ party software (e.g. your SSL clients), or
+ - Use professional grade CA software, such as Red Hat's
+ `Dogtag <http://pki.fedoraproject.org/wiki/PKI_Main_Page>`__ `Certificate
+ System <http://www.redhat.com/certificate_system/>`__, to set up and operate your own CA
+ and issue your own certificates.
+
+ For complete information about the command-line options used in the examples that follow, see
+ `Using the Certificate Database Tool <../../tools/certutil.html>`__.
+
+.. _setting_up_the_ca_db_and_certificate:
+
+`Setting Up the CA DB and Certificate <#setting_up_the_ca_db_and_certificate>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ Set up the CA with its own separate set of databases.
+
+ #. Create a new certificate database in the ``CA_db`` directory.
+ ``>mkdir CA_db >certutil -N -d CA_db``
+ #. Create the self-signed Root CA certificate, specifying the subject name for the certificate.
+ ``>certutil -S -d CA_db -n "MyCo's Root CA" -s "CN=My CA,O=MyCo,ST=California,C=US" -t "CT,," -x -2 Enter Password or Pin for "Communicator Certificate DB":``
+ #. Extract the CA certificate from the CA's certificate database to a file.
+ ``>certutil -L -d CA_db -n "MyCo's Root CA" -a -o CA_db/rootca.crt Enter Password or Pin for "Communicator Certificate DB":``
+ #. Display the contents of the CA's certificate databases.
+ ``>certutil -L -d CA_db``
+
+ The trust flag settings ``"CTu,u,u"`` indicate that the certificate is a CA certificate that is
+ trusted to issue both client (``C``) and server (``T``) SSL certificates. The ``u`` flag
+ indicates that the private key for the CA certificate is present in this set of databases, so the
+ CA can issue SSL client and server certificates with these databases.
+
+.. _setting_up_the_server_db_and_certificate:
+
+`Setting Up the Server DB and Certificate <#setting_up_the_server_db_and_certificate>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ The sections that follow describe how to set up the Server DB and certificate:
+
+ #. Create a new certificate database in the ``server_db`` directory.
+ ``>mkdir server_db >certutil -N -d server_db``
+ #. Import the new CA certificate into the server's certificate database, and mark it trusted for
+ issuing certificates for SSL client and server authentication.
+ ``>certutil -A -d server_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt``
+ #. Create the server certificate request, specifying the subject name for the server certificate.
+ We make the common name (CN) be identical to the hostname of the server. Note that this step
+ generates the server's private key, so it must be done in the server's database directory.
+ ``>certutil -R -d server_db -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -a -o server_db/server.req Enter Password or Pin for "Communicator Certificate DB":``
+ #. This step simulates the CA signing and issuing a new server certificate based on the server's
+ certificate request. The new cert is signed with the CA's private key, so this operation uses
+ the CA's databases. This step leaves the server's new certificate in a file.
+ ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i server_db/server.req -o server_db/server.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":``
+ #. Import (Add) the new server certificate to the server's certificate database in the
+ ``server_db`` directory with the appropriate nickname. Notice that no trust is explicitly
+ needed for this certificate.
+ ``>certutil -A -d server_db -n myco.mcom.org -a -i server_db/server.crt -t ",,"``
+ #. Display the contents of the server's certificate databases.
+ ``>certutil -L -d server_db``
+
+ The trust flag settings ``"u,u,u"`` indicate that the server's databases contain the private key
+ for this certificate. This is necessary for the SSL server to be able to do its job.
+
+.. _setting_up_the_client_db_and_certificate:
+
+`Setting Up the Client DB and Certificate <#setting_up_the_client_db_and_certificate>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ Setting up the client certificate database involves three stages:
+
+ #. Create a new certificate database in the ``client_db`` directory.
+ ``>mkdir client_db >certutil -N -d client_db``
+ #. Import the new CA certificate into the client's certificate database, and mark it trusted for
+ issuing certificates for SSL client and server authentication.
+ ``>certutil -A -d client_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt``
+ #. Create the client certificate request, specifying the subject name for the certificate.
+ ``>certutil -R -d client_db -s "CN=Joe Client,O=MyCo,ST=California,C=US" -a -o client_db/client.req Enter Password or Pin for "Communicator Certificate DB":``
+ #. This step simulates the CA signing and issuing a new client certificate based on the client's
+ certificate request. The new cert is signed with the CA's private key, so this operation uses
+ the CA's databases. This step leaves the client's new certificate in a file.
+ ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i client_db/client.req -o client_db/client.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":``
+ #. Add the new client certificate to the client's certificate database in the ``client_db``
+ directory with the appropriate nickname. Notice that no trust is required for this
+ certificate.
+ ``>certutil -A -d client_db -n "Joe Client" -a -i client_db/client.crt -t ",,"``
+ #. Display the contents of the client's certificate databases.
+ ``>certutil -L -d client_db``
+
+ The trust flag settings ``"u,u,u"`` indicate that the client's databases contain the private key
+ for this certificate. This is necessary for the SSL client to be able to authenticate to the
+ server.
+
+.. _verifying_the_server_and_client_certificates:
+
+`Verifying the Server and Client Certificates <#verifying_the_server_and_client_certificates>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ When you have finished setting up the server and client certificate databases, verify that the
+ client and server certificates are valid, as follows:
+
+ ``>certutil -V -d server_db -u V -n myco.mcom.org certutil: certificate is valid``
+
+ ``>certutil -V -d client_db -u C -n "Joe Client" certutil: certificate is valid``
+
+.. _building_nss_programs:
+
+`Building NSS Programs <#building_nss_programs>`__
+--------------------------------------------------
+
+.. container::
+
+ On Unix, use the GNU utility ``gmake`` to run the makefile. On Windows NT, use the ``nmake``
+ utility that comes with Visual C++.
+
+ If you create your own makefiles, be sure to include the libraries in the same order that they
+ are listed in the sample makefiles. In addition, you must use the following compiler flags:
+
+ Solaris flags:
+
+ ``-c -O -KPIC -DSVR4 -DSYSV -D__svr4 -D__svr4__ -DSOLARIS -D_REENTRANT -DSOLARIS2_5 -D_SVID_GETTOD -DXP_UNIX -UDEBUG -DNDEBUG``
+
+ Windows NT flags:
+
+ ``-c -O2 -MD -W3 -nologo -D_X86_ -GT -DWINNT -DXP_PC -UDEBUG -U_DEBUG -DNDEBUG -DWIN32 -D_WINDOWS`` \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/index.rst b/security/nss/doc/rst/legacy/ssl_functions/index.rst
new file mode 100644
index 0000000000..ccbc7a84a4
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/index.rst
@@ -0,0 +1,83 @@
+.. _mozilla_projects_nss_ssl_functions:
+
+SSL functions
+=============
+
+.. container::
+
+ The public functions listed here are used to configure sockets for communication via the SSL and
+ TLS protocols. In addition to the functions listed here, applications that support SSL use some
+ of the Certificate functions, Crypto functions, and Utility functions described below on this
+ page.
+
+ Other sources of information:
+
+ - The :ref:`mozilla_projects_nss_reference` documents the functions most commonly used by
+ applications to support SSL.
+ - The :ref:`mozilla_projects_nss` home page links to additional SSL documentation.
+
+ If documentation is available for a function listed below, the function name is linked to either
+ its MDC wiki page or its entry in the
+ :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross
+ Reference <https://dxr.mozilla.org/>`__ (DXR) link for each function provides access to the
+ function definition, prototype definition, and source code references. The NSS version column
+ indicates which versions of NSS support the function.
+
+ ======================================================== =========== ================
+ Function name/documentation Source code NSS versions
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285` MXR 3.2 and later
+ ``NSS_SetFrancePolicy`` MXR 3.2 and later
+ ``NSSSSL_VersionCheck`` MXR 3.2.1 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088805` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928` MXR 3.2 and later
+ ``SSL_CertDBHandleSet`` MXR 3.2 and later
+ ``SSL_Canbypass`` MXR 3.11.7 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` MXR 3.2 and later
+ ``SSL_ForceHandshakeWithTimeout`` MXR 3.11.4 and later
+ ``SSL_GetChannelInfo`` MXR 3.4 and later
+ ``SSL_GetCipherSuiteInfo`` MXR 3.4 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622` MXR 3.2 and later
+ ``SSL_GetMaxServerCacheLocks`` MXR 3.4 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869` MXR 3.2 and later
+ ``SSL_GetStatistics`` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1085950` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420` MXR 3.2 and later
+ ``SSL_LocalCertificate`` MXR 3.4 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168` MXR 3.2 and later
+ ``SSL_PreencryptedFileToStream`` MXR 3.2 and later
+ ``SSL_PreencryptedStreamToFile`` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` MXR 3.2 and later
+ ``SSL_ReHandshakeWithTimeout`` MXR 3.11.4 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` MXR 3.2 and later
+ ``SSL_RestartHandshakeAfterCertReq`` MXR 3.2 and later
+ ``SSL_RestartHandshakeAfterServerCert`` MXR 3.2 and later
+ ``SSL_RevealCert`` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805` MXR 3.2 and later
+ ``SSL_SetMaxServerCacheLocks`` MXR 3.4 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562` MXR 3.2 and later
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` MXR 3.2 and later
+ ``SSL_ShutdownServerSessionIDCache`` MXR 3.7.4 and later
+ ======================================================== =========== ================ \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst b/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst
new file mode 100644
index 0000000000..c39e51557f
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst
@@ -0,0 +1,269 @@
+.. _mozilla_projects_nss_ssl_functions_old_ssl_reference:
+
+OLD SSL Reference
+=================
+
+.. container::
+
+ .. rubric:: OLD SSL Reference
+ :name: OLD_SSL_Reference
+
+ .. note::
+
+ - We are migrating this SSL Reference into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+.. _ssl_reference:
+
+`SSL Reference <#ssl_reference>`__
+----------------------------------
+
+.. container::
+
+ *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__\ *
+ Writer: Sean Cotter
+ Manager: Wan-Teh Chang*
+
+ .. rubric:: `Chapter 1 Overview of an SSL Application <sslintro.html#1028068>`__
+ :name: chapter_1_overview_of_an_ssl_application
+
+ SSL and related APIs allow compliant applications to configure sockets for authenticated,
+ tamper-proof, and encrypted communications. This chapter introduces some of the basic SSL
+ functions. Chapter 2, "Getting Started With SSL" illustrates their use in sample client and
+ server applications.
+
+ - `Initialization <sslintro.html#1027662>`__
+
+ - `Initializing Caches <sslintro.html#1039943>`__
+
+ - `Configuration <sslintro.html#1027742>`__ ` <sslintro.html#1027816>`__
+ - `Communication <sslintro.html#1027816>`__ ` <sslintro.html#1027820>`__
+ - `Functions Used by Callbacks <sslintro.html#1027820>`__ ` <sslintro.html#1030535>`__
+ - `Cleanup <sslintro.html#1030535>`__
+
+ .. rubric:: `Chapter 2 Getting Started With SSL <gtstd.html#1005439>`__
+ :name: chapter_2_getting_started_with_ssl
+
+ This chapter describes how to set up your environment, including certificate and key
+ databases, to run the NSS sample code. The sample code and makefiles are available via LXR in
+ the SSLSamples directory.
+
+ - `SSL, PKCS #11, and the Default Security Databases <gtstd.html#1011970>`__
+ ` <gtstd.html#1011987>`__
+ - `Setting Up the Certificate and Key Databases <gtstd.html#1011987>`__
+
+ - `Setting Up the CA DB and Certificate <gtstd.html#1012301>`__ ` <gtstd.html#1012351>`__
+ - `Setting Up the Server DB and Certificate <gtstd.html#1012351>`__ ` <gtstd.html#1012067>`__
+ - `Setting Up the Client DB and Certificate <gtstd.html#1012067>`__ ` <gtstd.html#1012108>`__
+ - `Verifying the Server and Client Certificates <gtstd.html#1012108>`__
+
+ - `Building NSS Programs <gtstd.html#1013274>`__
+
+ .. rubric:: `Chapter 3 Selected SSL Types and Structures <ssltyp.html#1029792>`__
+ :name: chapter_3_selected_ssl_types_and_structures
+
+ This chapter describes some of the most important types and structures used with the functions
+ described in the rest of this document, and how to manage the memory used for them. Additional
+ types are described with the functions that use them or in the header files.
+
+ - `Types and Structures <ssltyp.html#1030559>`__
+
+ - `CERTCertDBHandle <ssltyp.html#1028465>`__ ` <ssltyp.html#1027387>`__
+ - `CERTCertificate <ssltyp.html#1027387>`__ ` <ssltyp.html#1028593>`__
+ - `PK11SlotInfo <ssltyp.html#1028593>`__ ` <ssltyp.html#1026076>`__
+ - `SECItem <ssltyp.html#1026076>`__ ` <ssltyp.html#1026727>`__
+ - `SECKEYPrivateKey <ssltyp.html#1026727>`__ ` <ssltyp.html#1026722>`__
+ - `SECStatus <ssltyp.html#1026722>`__
+
+ - `Managing SECItem Memory <ssltyp.html#1029645>`__
+
+ - `SECItem_FreeItem <ssltyp.html#1030620>`__ ` <ssltyp.html#1030773>`__
+ - `SECItem_ZfreeItem <ssltyp.html#1030773>`__
+
+ .. rubric:: :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1047959`
+ :name: chapter_4_ssl_functions
+
+ This chapter describes the core SSL functions.
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1022864`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1237143`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1237143`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1234224`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1234224`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1154189`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1098841`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1163855`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1090577`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1085950`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089578`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088805`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1127321`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092785`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092785`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1127893`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061582`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1095840`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061858`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1198429`
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1206365`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1220189`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1220189`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207298`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207298`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207350`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207350`
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1231825`
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1231825`
+
+ .. rubric:: `Chapter 5 Certificate Functions <sslcrt.html#1047959>`__
+ :name: chapter_5_certificate_functions
+
+ This chapter describes the functions and related types used to work with a certificate
+ database such as the cert7.db database provided with Communicator.
+
+ - `Validating Certificates <sslcrt.html#1060423>`__
+
+ - `CERT_VerifyCertNow <sslcrt.html#1058011>`__ ` <sslcrt.html#1050342>`__
+ - `CERT_VerifyCertName <sslcrt.html#1050342>`__ ` <sslcrt.html#1056662>`__
+ - `CERT_CheckCertValidTimes <sslcrt.html#1056662>`__ ` <sslcrt.html#1056760>`__
+ - `NSS_CmpCertChainWCANames <sslcrt.html#1056760>`__
+
+ - `Manipulating Certificates <sslcrt.html#1056436>`__
+
+ - `CERT_DupCertificate <sslcrt.html#1058344>`__ ` <sslcrt.html#1050532>`__
+ - `CERT_DestroyCertificate <sslcrt.html#1050532>`__
+
+ - `Getting Certificate Information <sslcrt.html#1056475>`__
+
+ - `CERT_FindCertByName <sslcrt.html#1050345>`__ ` <sslcrt.html#1050346>`__
+ - `CERT_GetCertNicknames <sslcrt.html#1050346>`__ ` <sslcrt.html#1050349>`__
+ - `CERT_FreeNicknames <sslcrt.html#1050349>`__ ` <sslcrt.html#1052308>`__
+ - `CERT_GetDefaultCertDB <sslcrt.html#1052308>`__ ` <sslcrt.html#1056950>`__
+ - `NSS_FindCertKEAType <sslcrt.html#1056950>`__
+
+ - `Comparing SecItem Objects <sslcrt.html#1055384>`__
+
+ - `SECITEM_CompareItem <sslcrt.html#1057028>`__
+
+ .. rubric:: `Chapter 6 Key Functions <sslkey.html#1047959>`__
+ :name: chapter_6_key_functions
+
+ This chapter describes two functions used to manipulate private keys and key databases such as
+ the key3.db database provided with Communicator.
+
+ - `SECKEY_GetDefaultKeyDB <sslkey.html#1051479>`__ ` <sslkey.html#1051017>`__
+ - `SECKEY_DestroyPrivateKey <sslkey.html#1051017>`__
+
+ .. rubric:: `Chapter 7 PKCS #11 Functions <pkfnc.html#1027946>`__
+ :name: chapter_7_pkcs_11_functions
+
+ This chapter describes the core PKCS #11 functions that an application needs for communicating
+ with cryptographic modules. In particular, these functions are used for obtaining
+ certificates, keys, and passwords.
+
+ - `PK11_FindCertFromNickname <pkfnc.html#1035673>`__ ` <pkfnc.html#1026891>`__
+ - `PK11_FindKeyByAnyCert <pkfnc.html#1026891>`__ ` <pkfnc.html#1030779>`__
+ - `PK11_GetSlotName <pkfnc.html#1030779>`__ ` <pkfnc.html#1026964>`__
+ - `PK11_GetTokenName <pkfnc.html#1026964>`__ ` <pkfnc.html#1026762>`__
+ - `PK11_IsHW <pkfnc.html#1026762>`__ ` <pkfnc.html#1022948>`__
+ - `PK11_IsPresent <pkfnc.html#1022948>`__ ` <pkfnc.html#1022991>`__
+ - `PK11_IsReadOnly <pkfnc.html#1022991>`__ ` <pkfnc.html#1023128>`__
+ - `PK11_SetPasswordFunc <pkfnc.html#1023128>`__
+
+ .. rubric:: `Chapter 8 NSS and SSL Error Codes <sslerr.html#1013897>`__
+ :name: chapter_8_nss_and_ssl_error_codes
+
+ NSS error codes are retrieved using the NSPR function PR_GetError. In addition to the error
+ codes defined by NSPR, PR_GetError retrieves the error codes described in this chapter.
+
+ - `SSL Error Codes <sslerr.html#1040263>`__ ` <sslerr.html#1039257>`__
+ - `SEC Error Codes <sslerr.html#1039257>`__ \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst b/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst
new file mode 100644
index 0000000000..b71487dd7a
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst
@@ -0,0 +1,439 @@
+.. _mozilla_projects_nss_ssl_functions_pkfnc:
+
+pkfnc
+=====
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to
+ help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: PKCS #11 Functions
+ :name: PKCS_11_Functions
+
+ --------------
+
+.. _chapter_7_pkcs_11_functions:
+
+`Chapter 7
+PKCS #11 Functions <#chapter_7_pkcs_11_functions>`__
+----------------------------------------------------
+
+.. container::
+
+ This chapter describes the core PKCS #11 functions that an application needs for communicating
+ with cryptographic modules. In particular, these functions are used for obtaining certificates,
+ keys, and passwords.
+
+ | ```PK11_FindCertFromNickname`` <#1035673>`__
+ | ```PK11_FindKeyByAnyCert`` <#1026891>`__
+ | ```PK11_GetSlotName`` <#1030779>`__
+ | ```PK11_GetTokenName`` <#1026964>`__
+ | ```PK11_IsHW`` <#1026762>`__
+ | ```PK11_IsPresent`` <#1022948>`__
+ | ```PK11_IsReadOnly`` <#1022991>`__
+ | ```PK11_SetPasswordFunc`` <#1023128>`__
+
+ .. rubric:: PK11_FindCertFromNickname
+ :name: pk11_findcertfromnickname
+
+ Finds a certificate from its nickname.
+
+ .. rubric:: Syntax
+ :name: syntax
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <certt.h>
+
+ .. code::
+
+ CERTCertificate *PK11_FindCertFromNickname(
+ char *nickname,
+ void *wincx);
+
+ .. rubric:: Parameters
+ :name: parameters
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the nickname in the certificate |
+ | | database or to the nickname in the token. |
+ | nickname | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to application data for the password |
+ | | callback function. This pointer is set with |
+ | wincx | :ref:`moz |
+ | | illa_projects_nss_ssl_functions_sslfnc#1088040` |
+ | | during SSL configuration. To retrieve its |
+ | | current value, use |
+ | | :ref:`mozi |
+ | | lla_projects_nss_ssl_functions_sslfnc#1123385`. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns
+
+ The function returns one of these values:
+
+ - If successful, a pointer to a certificate structure.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description
+
+ A nickname is an alias for a certificate subject. There may be multiple certificates with the
+ same subject, and hence the same nickname. This function will return the newest certificate that
+ matches the subject, based on the NotBefore / NotAfter fields of the certificate. When you are
+ finished with the certificate structure returned by ``PK11_FindCertFromNickname``, you must free
+ it by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__.
+
+ The ``PK11_FindCertFromNickname`` function calls the password callback function set with
+ ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx``
+ parameter.
+
+ .. rubric:: PK11_FindKeyByAnyCert
+ :name: pk11_findkeybyanycert
+
+ Finds the private key associated with a specified certificate in any available slot.
+
+ .. rubric:: Syntax
+ :name: syntax_2
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <certt.h>
+ #include <keyt.h>
+
+ .. code::
+
+ SECKEYPrivateKey *PK11_FindKeyByAnyCert(
+ CERTCertificate *cert,
+ void *wincx);
+
+ .. rubric:: Parameters
+ :name: parameters_2
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a certificate structure in the |
+ | | certificate database. |
+ | cert | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to application data for the password |
+ | | callback function. This pointer is set with |
+ | wincx | :ref:`moz |
+ | | illa_projects_nss_ssl_functions_sslfnc#1088040` |
+ | | during SSL configuration. To retrieve its |
+ | | current value, use |
+ | | :ref:`mozi |
+ | | lla_projects_nss_ssl_functions_sslfnc#1123385`. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_2
+
+ The function returns one of these values:
+
+ - If successful, a pointer to a private key structure.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_2
+
+ When you are finished with the private key structure returned by ``PK11_FindKeyByAnyCert``, you
+ must free it by calling ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__.
+
+ The ``PK11_FindKeyByAnyCert`` function calls the password callback function set with
+ ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx``
+ parameter.
+
+ .. rubric:: PK11_GetSlotName
+ :name: pk11_getslotname
+
+ Gets the name of a slot.
+
+ .. rubric:: Syntax
+ :name: syntax_3
+
+ .. code::
+
+ #include <pk11func.h>
+
+ .. code::
+
+ char *PK11_GetSlotName(PK11SlotInfo *slot);
+
+ .. rubric:: Parameters
+ :name: parameters_3
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_3
+
+ The function returns one of these values:
+
+ - If successful, a pointer to the name of the slot (a string).
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_3
+
+ If the slot is freed, the string with the slot name may also be freed. If you want to preserve
+ it, copy the string before freeing the slot. Do not try to free the string yourself.
+
+ .. rubric:: PK11_GetTokenName
+ :name: pk11_gettokenname
+
+ Gets the name of the token.
+
+ .. rubric:: Syntax
+ :name: syntax_4
+
+ .. code::
+
+ #include <pk11func.h>
+
+ .. code::
+
+ char *PK11_GetTokenName(PK11SlotInfo *slot);
+
+ .. rubric:: Parameters
+ :name: parameters_4
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_4
+
+ The function returns one of these values:
+
+ - If successful, a pointer to the name of the token (a string).
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_4
+
+ If the slot is freed, the string with the token name may also be freed. If you want to preserve
+ it, copy the string before freeing the slot. Do not try to free the string yourself.
+
+ .. rubric:: PK11_IsHW
+ :name: pk11_ishw
+
+ Finds out whether a slot is implemented in hardware or software.
+
+ .. rubric:: Syntax
+ :name: syntax_5
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <prtypes.h>
+
+ .. code::
+
+ PRBool PK11_IsHW(PK11SlotInfo *slot);
+
+ .. rubric:: Parameters
+ :name: parameters_5
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_5
+
+ The function returns one of these values:
+
+ - If the slot is implemented in hardware, ``PR_TRUE``.
+ - If the slot is implemented in software, ``PR_FALSE``.
+
+ .. rubric:: PK11_IsPresent
+ :name: pk11_ispresent
+
+ Finds out whether the token for a slot is available.
+
+ .. rubric:: Syntax
+ :name: syntax_6
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <prtypes.h>
+
+ .. code::
+
+ PRBool PK11_IsPresent(PK11SlotInfo *slot);
+
+ .. rubric:: Parameters
+ :name: parameters_6
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_6
+
+ The function returns one of these values:
+
+ - If token is available, ``PR_TRUE``.
+ - If token is disabled or missing, ``PR_FALSE``.
+
+ .. rubric:: PK11_IsReadOnly
+ :name: pk11_isreadonly
+
+ Finds out whether a slot is read-only.
+
+ .. rubric:: Syntax
+ :name: syntax_7
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <prtypes.h>
+
+ .. code::
+
+ PRBool PK11_IsReadOnly(PK11SlotInfo *slot);
+
+ .. rubric:: Parameters
+ :name: parameters_7
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_7
+
+ The function returns one of these values:
+
+ - If slot is read-only, ``PR_TRUE``.
+ - Otherwise, ``PR_FALSE``.
+
+ .. rubric:: PK11_SetPasswordFunc
+ :name: pk11_setpasswordfunc
+
+ Defines a callback function used by the NSS libraries whenever information protected by a
+ password needs to be retrieved from the key or certificate databases.
+
+ .. rubric:: Syntax
+ :name: syntax_8
+
+ .. code::
+
+ #include <pk11func.h>
+ #include <prtypes.h>
+
+ .. code::
+
+ void PK11_SetPasswordFunc(PK11PasswordFunc func);
+
+ .. rubric:: Parameter
+ :name: parameter
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the callback function to set. |
+ | | |
+ | func | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_5
+
+ During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11
+ token (either a smart card or soft token) to access protected information, such as a private key.
+ Such information is protected with a password that can be retrieved by calling an
+ application-supplied callback function. The callback function is identified in a call to
+ ``PK11_SetPasswordFunc`` that takes place during NSS initialization.
+
+ The callback function set up by ``PK11_SetPasswordFunc`` has the following prototype:
+
+ .. code::
+
+ typedef char *(*PK11PasswordFunc)(
+ PK11SlotInfo *slot,
+ PRBool retry,
+ void *arg);
+
+ This callback function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a slot info structure. |
+ | | |
+ | slot | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | Set to ``PR_TRUE`` if this is a retry. This |
+ | | implies that the callback has previously |
+ | retry | returned the wrong password. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer supplied by the application that can |
+ | | be used to pass state information. Can be |
+ | arg | ``NULL``. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ This callback function returns one of these values:
+
+ - If successful, a pointer to the password. This memory must have been allocated with
+ ```PR_Malloc`` <../../../../../nspr/reference/html/prmem2.html#21428>`__ or
+ ```PL_strdup`` <../../../../../nspr/reference/html/plstr.html#21753>`__.
+ - If unsuccessful, returns ``NULL``.
+
+ Many tokens keep track of the number of attempts to enter a password and do not allow further
+ attempts after a certain point. Therefore, if the ``retry`` argument is ``PR_TRUE``, indicating
+ that the password was tried and is wrong, the callback function should return ``NULL`` to
+ indicate that it is unsuccessful, rather than attempting to return the same password again.
+ Failing to terminate when the ``retry`` argument is ``PR_TRUE`` can result in an endless loop.
+
+ Several functions in the NSS libraries use the password callback function to obtain the password
+ before performing operations that involve the protected information. The third parameter to the
+ password callback function is application-defined and can be used for any purpose. For example,
+ Communicator uses the parameter to pass information about which window is associated with the
+ modal dialog box requesting the password from the user. When NSS libraries call the password
+ callback function, the value they pass in the third parameter is determined by
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040`.
+
+ .. rubric:: See Also
+ :name: see_also
+
+ For examples of password callback functions, see the samples in the
+ :ref:`mozilla_projects_nss_nss_sample_code` directory. \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst
new file mode 100644
index 0000000000..677ec4f598
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst
@@ -0,0 +1,632 @@
+.. _mozilla_projects_nss_ssl_functions_sslcrt:
+
+sslcrt
+======
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: Certificate Functions
+ :name: Certificate_Functions
+
+ --------------
+
+.. _chapter_5_certificate_functions:
+
+`Chapter 5
+ <#chapter_5_certificate_functions>`__ Certificate Functions
+------------------------------------------------------------
+
+.. container::
+
+ This chapter describes the functions and related types used to work with a certificate database
+ such as the ``cert7.db`` database provided with Communicator.
+
+ | `Validating Certificates <#1060423>`__
+ | `Manipulating Certificates <#1056436>`__
+ | `Getting Certificate Information <#1056475>`__
+ | `Comparing SecItem Objects <#1055384>`__
+
+.. _validating_certificates:
+
+`Validating Certificates <#validating_certificates>`__
+------------------------------------------------------
+
+.. container::
+
+ | ```CERT_VerifyCertNow`` <#1058011>`__
+ | ```CERT_VerifyCertName`` <#1050342>`__
+ | ```CERT_CheckCertValidTimes`` <#1056662>`__
+ | ```NSS_CmpCertChainWCANames`` <#1056760>`__
+
+ .. rubric:: CERT_VerifyCertNow
+ :name: cert_verifycertnow
+
+ Checks that the current date is within the certificate's validity period and that the CA
+ signature on the certificate is valid.
+
+ .. rubric:: Syntax
+ :name: syntax
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ SECStatus CERT_VerifyCertNow(
+ CERTCertDBHandle *handle,
+ CERTCertificate *cert,
+ PRBool checkSig,
+ SECCertUsage certUsage,
+ void *wincx);
+
+ .. rubric:: Parameters
+ :name: parameters
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate database handle. |
+ | | |
+ | handle | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate to be checked. |
+ | | |
+ | cert | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | Indicates whether certificate signatures are to |
+ | | be checked. ``PR_TRUE`` means certificate |
+ | checkSig | signatures are to be checked. ``PR_FALSE`` |
+ | | means certificate signatures will not be |
+ | | checked. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | One of these values: |
+ | | |
+ | certUsage | - ``certUsageSSLClient`` |
+ | | - ``certUsageSSLServer`` |
+ | | - ``certUsageSSLServerWithStepUp`` |
+ | | - ``certUsageSSLCA`` |
+ | | - ``certUsageEmailSigner`` |
+ | | - ``certUsageEmailRecipient`` |
+ | | - ``certUsageObjectSigner`` |
+ | | - ``certUsageUserCertImport`` |
+ | | - ``certUsageVerifyCA`` |
+ | | - ``certUsageProtectedObjectSigner`` |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The PIN argument value to pass to PK11 |
+ | | functions. See description below for more |
+ | wincx | information. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error
+ code.
+
+ .. rubric:: Description
+ :name: description
+
+ The ``CERT_VerifyCertNow`` function must call one or more PK11 functions to obtain the services
+ of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in
+ the ``wincx`` parameter. To obtain the value to pass in the ``wincx`` parameter, call
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`.
+
+ .. rubric:: CERT_VerifyCertName
+ :name: cert_verifycertname
+
+ Compares the common name specified in the subject DN for a certificate with a specified hostname.
+
+ .. rubric:: Syntax
+ :name: syntax_2
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ SECStatus CERT_VerifyCertName(
+ CERTCertificate *cert,
+ char *hostname);
+
+ .. rubric:: Parameters
+ :name: parameters_2
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate against which to |
+ | | check the hostname referenced by ``hostname``. |
+ | cert | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The hostname to be checked. |
+ | | |
+ | hostname | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_2
+
+ The function returns one of these values:
+
+ - If the common name in the subject DN for the certificate matches the domain name passed in the
+ ``hostname`` parameter, ``SECSuccess``.
+ - If the common name in the subject DN for the certificate is not identical to the domain name
+ passed in the ``hostname`` parameter, ``SECFailure``. Use
+ ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error
+ code.
+
+ .. rubric:: Description
+ :name: description_2
+
+ The comparison performed by CERT_VerifyCertName is not a simple string comparison. Instead, it
+ takes account of the following rules governing the construction of common names in SSL server
+ certificates:
+
+ - ``*`` matches anything
+ - ``?`` matches one character
+ - ``\`` escapes a special character
+ - ``$`` matches the end of the string
+ - ``[abc]`` matches one occurrence of ``a``, ``b``, or ``c``. The only character that needs to
+ be escaped in this is ``]``, all others are not special.
+ - ``[a-z]`` matches any character between ``a`` and ``z``
+ - ``[^az]`` matches any character except ``a`` or ``z``
+ - ``~`` followed by another shell expression removes any pattern matching the shell expression
+ from the match list
+ - ``(foo|bar)`` matches either the substring ``foo`` or the substring ``bar``. These can be
+ shell expressions as well.
+
+ .. rubric:: CERT_CheckCertValidTimes
+ :name: cert_checkcertvalidtimes
+
+ Checks whether a specified time is within a certificate's validity period.
+
+ .. rubric:: Syntax
+ :name: syntax_3
+
+ .. code::
+
+ #include <cert.h>
+ #include <certt.h>
+
+ .. code::
+
+ SECCertTimeValidity CERT_CheckCertValidTimes(
+ CERTCertificate *cert,
+ int64 t);
+
+ .. rubric:: Parameters
+ :name: parameters_3
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate whose validity |
+ | | period you want to check against. |
+ | cert | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The time to check against the certificate's |
+ | | validity period. For more information, see the |
+ | t | NSPR header ``pr_time.h``. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_3
+
+ The function returns an enumerator of type ``SECCertTimeValidity``:
+
+ .. code::
+
+ typedef enum {
+ secCertTimeValid,
+ secCertTimeExpired,
+ secCertTimeNotValidYet
+ } SECCertTimeValidity;
+
+ .. rubric:: NSS_CmpCertChainWCANames
+ :name: nss_cmpcertchainwcanames
+
+ Determines whether any of the signers in the certificate chain for a specified certificate are on
+ a specified list of CA names.
+
+ .. rubric:: Syntax
+ :name: syntax_4
+
+ .. code::
+
+ #include <nss.h>
+
+ .. code::
+
+ SECStatus NSS_CmpCertChainWCANames(
+ CERTCertificate *cert,
+ CERTDistNames *caNames);
+
+ .. rubric:: Parameters
+ :name: parameters_4
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate structure for the |
+ | | certificate whose certificate chain is to be |
+ | cert | checked. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to a structure that contains a list |
+ | | of distinguished names (DNs) against which to |
+ | caNames | check the DNs for the signers in the |
+ | | certificate chain. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_4
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error
+ code.
+
+.. _manipulating_certificates:
+
+`Manipulating Certificates <#manipulating_certificates>`__
+----------------------------------------------------------
+
+.. container::
+
+ | ```CERT_DupCertificate`` <#1058344>`__
+ | ```CERT_DestroyCertificate`` <#1050532>`__
+
+ .. rubric:: CERT_DupCertificate
+ :name: cert_dupcertificate
+
+ Makes a shallow copy of a specified certificate.
+
+ .. rubric:: Syntax
+ :name: syntax_5
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ CERTCertificate *CERT_DupCertificate(CERTCertificate *c)
+
+ .. rubric:: Parameter
+ :name: parameter
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate object to be |
+ | | duplicated. |
+ | c | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_5
+
+ If successful, the function returns a pointer to a certificate object of type
+ ```CERTCertificate`` <ssltyp.html#1027387>`__.
+
+ .. rubric:: Description
+ :name: description_3
+
+ The ``CERT_DupCertificate`` function increments the reference count for the certificate passed in
+ the ``c`` parameter.
+
+ .. rubric:: CERT_DestroyCertificate
+ :name: cert_destroycertificate
+
+ Destroys a certificate object.
+
+ .. rubric:: Syntax
+ :name: syntax_6
+
+ .. code::
+
+ #include <cert.h>
+ #include <certt.h>
+
+ .. code::
+
+ void CERT_DestroyCertificate(CERTCertificate *cert);
+
+ .. rubric:: Parameters
+ :name: parameters_5
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate to destroy. |
+ | | |
+ | cert | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_4
+
+ Certificate and key structures are shared objects. When an application makes a copy of a
+ particular certificate or key structure that already exists in memory, SSL makes a *shallow*
+ copy--that is, it increments the reference count for that object rather than making a whole new
+ copy. When you call ```CERT_DestroyCertificate`` <#1050532>`__ or
+ ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__, the function decrements the reference
+ count and, if the reference count reaches zero as a result, both frees the memory and sets all
+ the bits to zero. The use of the word "destroy" in function names or in the description of a
+ function implies reference counting.
+
+ Never alter the contents of a certificate or key structure. If you attempt to do so, the change
+ affects all the shallow copies of that structure and can cause severe problems.
+
+.. _getting_certificate_information:
+
+`Getting Certificate Information <#getting_certificate_information>`__
+----------------------------------------------------------------------
+
+.. container::
+
+ | ```CERT_FindCertByName`` <#1050345>`__
+ | ```CERT_GetCertNicknames`` <#1050346>`__
+ | ```CERT_FreeNicknames`` <#1050349>`__
+ | ```CERT_GetDefaultCertDB`` <#1052308>`__
+ | ```NSS_FindCertKEAType`` <#1056950>`__
+
+ .. rubric:: CERT_FindCertByName
+ :name: cert_findcertbyname
+
+ Finds the certificate in the certificate database with a specified DN.
+
+ .. rubric:: Syntax
+ :name: syntax_7
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ CERTCertificate *CERT_FindCertByName (
+ CERTCertDBHandle *handle,
+ SECItem *name);
+
+ .. rubric:: Parameters
+ :name: parameters_6
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate database handle. |
+ | | |
+ | handle | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The subject DN of the certificate you wish to |
+ | | find. |
+ | name | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_6
+
+ If successful, the function returns a certificate object of type
+ ```CERTCertificate`` <ssltyp.html#1027387>`__.
+
+ .. rubric:: CERT_GetCertNicknames
+ :name: cert_getcertnicknames
+
+ Returns the nicknames of the certificates in a specified certificate database.
+
+ .. rubric:: Syntax
+ :name: syntax_8
+
+ .. code::
+
+ #include <cert.h>
+ #include <certt.h>
+
+ .. code::
+
+ CERTCertNicknames *CERT_GetCertNicknames (
+ CERTCertDBHandle *handle,
+ int what,
+ void *wincx);
+
+ .. rubric:: Parameters
+ :name: parameters_7
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the certificate database handle. |
+ | | |
+ | handle | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | One of these values: |
+ | | |
+ | what | - ``SEC_CERT_NICKNAMES_ALL`` |
+ | | - ``SEC_CERT_NICKNAMES_USER`` |
+ | | - ``SEC_CERT_NICKNAMES_SERVER`` |
+ | | - ``SEC_CERT_NICKNAMES_CA`` |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The PIN argument value to pass to PK11 |
+ | | functions. See description below for more |
+ | wincx | information. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_7
+
+ The function returns a ``CERTCertNicknames`` object containing the requested nicknames.
+
+ .. rubric:: Description
+ :name: description_5
+
+ ``CERT_GetCertNicknames`` must call one or more PK11 functions to obtain the services of a PKCS
+ #11 module. Some of the PK11 functions require a PIN argument (see
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in
+ the ``wincx`` parameter. To obtain the value to pass in the ``wincx`` parameter, call
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`.
+
+ .. rubric:: CERT_FreeNicknames
+ :name: cert_freenicknames
+
+ Frees a ``CERTCertNicknames`` structure. This structure is returned by
+ ```CERT_GetCertNicknames`` <#1050346>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_9
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ void CERT_FreeNicknames(CERTCertNicknames *nicknames);
+
+ .. rubric:: Parameters
+ :name: parameters_8
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the ``CERTCertNicknames`` |
+ | | structure to be freed. |
+ | nicknames | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: CERT_GetDefaultCertDB
+ :name: cert_getdefaultcertdb
+
+ Returns a handle to the default certificate database.
+
+ .. rubric:: Syntax
+ :name: syntax_10
+
+ .. code::
+
+ #include <cert.h>
+
+ .. code::
+
+ CERTCertDBHandle *CERT_GetDefaultCertDB(void);
+
+ .. rubric:: Returns
+ :name: returns_8
+
+ The function returns the ```CERTCertDBHandle`` <ssltyp.html#1028465>`__ for the default
+ certificate database.
+
+ .. rubric:: Description
+ :name: description_6
+
+ This function is useful for determining whether the default certificate database has been opened.
+
+ .. rubric:: NSS_FindCertKEAType
+ :name: nss_findcertkeatype
+
+ Returns key exchange type of the keys in an SSL server certificate.
+
+ .. rubric:: Syntax
+ :name: syntax_11
+
+ .. code::
+
+ #include <nss.h>
+
+ .. code::
+
+ SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
+
+ .. rubric:: Parameter
+ :name: parameter_2
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The certificate to check. |
+ | | |
+ | a | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_9
+
+ The function returns one of these values:
+
+ - ``kt_null = 0``
+ - ``kt_rsa``
+ - ``kt_dh``
+ - ``kt_fortezza``
+ - ``kt_kea_size``
+
+.. _comparing_secitem_objects:
+
+`Comparing SecItem Objects <#comparing_secitem_objects>`__
+----------------------------------------------------------
+
+.. container::
+
+ .. rubric:: SECITEM_CompareItem
+ :name: secitem_compareitem
+
+ Compares two ```SECItem`` <ssltyp.html#1026076>`__ objects and returns a ``SECComparison``
+ enumerator that shows the difference between them.
+
+ .. rubric:: Syntax
+ :name: syntax_12
+
+ .. code::
+
+ #include <secitem.h>
+ #include <seccomon.h>
+
+ .. code::
+
+ SECComparison SECITEM_CompareItem(
+ SECItem *a,
+ SECItem *b);
+
+ .. rubric:: Parameters
+ :name: parameters_9
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to one of the items to be compared. |
+ | | |
+ | a | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to one of the items to be compared. |
+ | | |
+ | b | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_10
+
+ The function returns an enumerator of type ``SECComparison``.
+
+ .. code::
+
+ typedef enum _SECComparison {
+ SECLessThan = -1,
+ SECEqual = 0,
+ SECGreaterThan = 1
+ } SECComparison; \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst
new file mode 100644
index 0000000000..50d5a19c81
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst
@@ -0,0 +1,1434 @@
+.. _mozilla_projects_nss_ssl_functions_sslerr:
+
+sslerr
+======
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: NSS and SSL Error Codes
+ :name: NSS_and_SSL_Error_Codes
+
+ --------------
+
+.. _chapter_8_nss_and_ssl_error_codes:
+
+`Chapter 8
+ <#chapter_8_nss_and_ssl_error_codes>`__\ NSS and SSL Error Codes
+-----------------------------------------------------------------
+
+.. container::
+
+ NSS error codes are retrieved using the NSPR function
+ `PR_GetError <../../../../../nspr/reference/html/prerr.html#PR_GetError>`__. In addition to the
+ `error codes defined by
+ NSPR <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prerr.h>`__, PR_GetError
+ retrieves the error codes described in this chapter.
+
+ | `SSL Error Codes <#1040263>`__
+ | `SEC Error Codes <#1039257>`__
+
+.. _ssl_error_codes:
+
+`SSL Error Codes <#ssl_error_codes>`__
+--------------------------------------
+
+.. container::
+
+ **Table 8.1 Error codes defined in sslerr.h**
+
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Constant** | **Value** | **Description** |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_EXPORT_ONLY_SERVER | -12288 | "Unable to communicate |
+ | | | securely. Peer does not |
+ | | | support high-grade |
+ | | | encryption." |
+ | | | |
+ | | | The local system was |
+ | | | configured to support the |
+ | | | cipher suites permitted for |
+ | | | domestic use. The remote |
+ | | | system was configured to |
+ | | | support only the cipher suites |
+ | | | permitted for export use. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_US_ONLY_SERVER | -12287 | "Unable to communicate |
+ | | | securely. Peer requires |
+ | | | high-grade encryption which is |
+ | | | not supported." |
+ | | | |
+ | | | The remote system was |
+ | | | configured to support the |
+ | | | cipher suites permitted for |
+ | | | domestic use. The local system |
+ | | | was configured to support only |
+ | | | the cipher suites permitted |
+ | | | for export use. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_NO_CYPHER_OVERLAP | -12286 | "Cannot communicate securely |
+ | | | with peer: no common |
+ | | | encryption algorithm(s)." |
+ | | | |
+ | | | The local and remote systems |
+ | | | share no cipher suites in |
+ | | | common. This can be due to a |
+ | | | misconfiguration at either |
+ | | | end. It can be due to a server |
+ | | | being misconfigured to use a |
+ | | | non-RSA certificate with the |
+ | | | RSA key exchange algorithm. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_NO_CERTIFICATE | -12285 | "Unable to find the |
+ | | | certificate or key necessary |
+ | | | for authentication." |
+ | | | |
+ | | | This error has many potential |
+ | | | causes; for example: |
+ | | | |
+ | | | Certificate or key not found |
+ | | | in database. |
+ | | | |
+ | | | Certificate not marked trusted |
+ | | | in database and Certificate's |
+ | | | issuer not marked trusted in |
+ | | | database. |
+ | | | |
+ | | | Wrong password for key |
+ | | | database. |
+ | | | |
+ | | | Missing database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_CERTIFICATE | -12284 | "Unable to communicate |
+ | | | securely with peer: peers's |
+ | | | certificate was rejected." |
+ | | | |
+ | | | A certificate was received |
+ | | | from the remote system and was |
+ | | | passed to the certificate |
+ | | | authentication callback |
+ | | | function provided by the local |
+ | | | application. That callback |
+ | | | function returned SECFailure, |
+ | | | and the bad certificate |
+ | | | callback function either was |
+ | | | not configured or did not |
+ | | | choose to override the error |
+ | | | code returned by the |
+ | | | certificate authentication |
+ | | | callback function. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | | -12283 | (unused) |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_CLIENT | -12282 | "The server has encountered |
+ | | | bad data from the client." |
+ | | | |
+ | | | This error code should occur |
+ | | | only on sockets that are |
+ | | | acting as servers. It is a |
+ | | | generic error, used when none |
+ | | | of the other more specific |
+ | | | error codes defined in this |
+ | | | file applies. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_SERVER | -12281 | "The client has encountered |
+ | | | bad data from the server." |
+ | | | |
+ | | | This error code should occur |
+ | | | only on sockets that are |
+ | | | acting as clients. It is a |
+ | | | generic error, used when none |
+ | | | of the other more specific |
+ | | | error codes defined in this |
+ | | | file applies. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERRO | -12280 | "Unsupported certificate |
+ | R_UNSUPPORTED_CERTIFICATE_TYPE | | type." |
+ | | | |
+ | | | The operation encountered a |
+ | | | certificate that was not one |
+ | | | of the well known certificate |
+ | | | types handled by the |
+ | | | certificate library. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_UNSUPPORTED_VERSION | -12279 | "Peer using unsupported |
+ | | | version of security protocol." |
+ | | | |
+ | | | On a client socket, this means |
+ | | | the remote server has |
+ | | | attempted to negotiate the use |
+ | | | of a version of SSL that is |
+ | | | not supported by the NSS |
+ | | | library, probably an invalid |
+ | | | version number. On a server |
+ | | | socket, this means the remote |
+ | | | client has requested the use |
+ | | | of a version of SSL older than |
+ | | | version 2. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | | -12278 | (unused) |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_WRONG_CERTIFICATE | -12277 | "Client authentication failed: |
+ | | | private key in key database |
+ | | | does not correspond to public |
+ | | | key in certificate database." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_CERT_DOMAIN | -12276 | "Unable to communicate |
+ | | | securely with peer: requested |
+ | | | domain name does not match the |
+ | | | server's certificate." |
+ | | | |
+ | | | This error code should be |
+ | | | returned by the certificate |
+ | | | authentication callback |
+ | | | function when it detects that |
+ | | | the Common Name in the remote |
+ | | | server's certificate does not |
+ | | | match the hostname sought by |
+ | | | the local client, according to |
+ | | | the matching rules specified |
+ | | | for |
+ | | | `CERT_VerifyCertN |
+ | | | ame <sslcrt.html#1050342>`__. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_POST_WARNING | -12275 | (unused) |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SSL2_DISABLED | -12274 | "Peer only supports SSL |
+ | | | version 2, which is locally |
+ | | | disabled." |
+ | | | |
+ | | | The remote server has asked to |
+ | | | use SSL version 2, and SSL |
+ | | | version 2 is disabled in the |
+ | | | local client's configuration. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_MAC_READ | -12273 | "SSL received a record with an |
+ | | | incorrect Message |
+ | | | Authentication Code." |
+ | | | |
+ | | | This usually indicates that |
+ | | | the client and server have |
+ | | | failed to come to agreement on |
+ | | | the set of keys used to |
+ | | | encrypt the application data |
+ | | | and to check message |
+ | | | integrity. If this occurs |
+ | | | frequently on a server, an |
+ | | | active attack (such as the |
+ | | | "million question" attack) may |
+ | | | be underway against the |
+ | | | server. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_MAC_ALERT | -12272 | "SSL peer reports incorrect |
+ | | | Message Authentication Code." |
+ | | | The remote system has reported |
+ | | | that it received a message |
+ | | | with a bad Message |
+ | | | Authentication Code from the |
+ | | | local system. This may |
+ | | | indicate that an attack on |
+ | | | that server is underway. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_CERT_ALERT | -12271 | "SSL peer cannot verify your |
+ | | | certificate." |
+ | | | |
+ | | | The remote system has received |
+ | | | a certificate from the local |
+ | | | system, and has rejected it |
+ | | | for some reason. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_REVOKED_CERT_ALERT | -12270 | "SSL peer rejected your |
+ | | | certificate as revoked." |
+ | | | |
+ | | | The remote system has received |
+ | | | a certificate from the local |
+ | | | system, and has determined |
+ | | | that the certificate has been |
+ | | | revoked. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_EXPIRED_CERT_ALERT | -12269 | "SSL peer rejected your |
+ | | | certificate as expired." |
+ | | | |
+ | | | The remote system has received |
+ | | | a certificate from the local |
+ | | | system, and has determined |
+ | | | that the certificate has |
+ | | | expired. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SSL_DISABLED | -12268 | "Cannot connect: SSL is |
+ | | | disabled." |
+ | | | |
+ | | | The local socket is configured |
+ | | | in such a way that it cannot |
+ | | | use any of the SSL cipher |
+ | | | suites. Possible causes |
+ | | | include: (a) both SSL2 and |
+ | | | SSL3 are disabled, (b) All the |
+ | | | individual SSL cipher suites |
+ | | | are disabled, or (c) the |
+ | | | socket is configured to |
+ | | | handshake as a server, but the |
+ | | | certificate associated with |
+ | | | that socket is inappropriate |
+ | | | for the Key Exchange Algorithm |
+ | | | selected. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_FORTEZZA_PQG | -12267 | "Cannot connect: SSL peer is |
+ | | | in another FORTEZZA domain." |
+ | | | |
+ | | | The local system and the |
+ | | | remote system are in different |
+ | | | FORTEZZA domains. They must be |
+ | | | in the same domain to |
+ | | | communicate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_UNKNOWN_CIPHER_SUITE | -12266 | "An unknown SSL cipher suite |
+ | | | has been requested." |
+ | | | |
+ | | | The application has attempted |
+ | | | to configure SSL to use an |
+ | | | unknown cipher suite. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_NO_CIPHERS_SUPPORTED | -12265 | "No cipher suites are present |
+ | | | and enabled in this program." |
+ | | | |
+ | | | Possible causes: (a) all |
+ | | | cipher suites have been |
+ | | | configured to be disabled, (b) |
+ | | | the only cipher suites that |
+ | | | are configured to be enabled |
+ | | | are those that are disallowed |
+ | | | by cipher export policy, (c) |
+ | | | the socket is configured to |
+ | | | handshake as a server, but the |
+ | | | certificate associated with |
+ | | | that socket is inappropriate |
+ | | | for the Key Exchange Algorithm |
+ | | | selected. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_BAD_BLOCK_PADDING | -12264 | "SSL received a record with |
+ | | | bad block padding." |
+ | | | |
+ | | | SSL was using a Block cipher, |
+ | | | and the last block in an SSL |
+ | | | record had incorrect padding |
+ | | | information in it. This |
+ | | | usually indicates that the |
+ | | | client and server have failed |
+ | | | to come to agreement on the |
+ | | | set of keys used to encrypt |
+ | | | the application data and to |
+ | | | check message integrity. If |
+ | | | this occurs frequently on a |
+ | | | server, an active attack (such |
+ | | | as the "million question" |
+ | | | attack) may be underway |
+ | | | against the server. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX_RECORD_TOO_LONG | -12263 | "SSL received a record that |
+ | | | exceeded the maximum |
+ | | | permissible length." |
+ | | | |
+ | | | This generally indicates that |
+ | | | the remote peer system has a |
+ | | | flawed implementation of SSL, |
+ | | | and is violating the SSL |
+ | | | specification. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_TX_RECORD_TOO_LONG | -12262 | "SSL attempted to send a |
+ | | | record that exceeded the |
+ | | | maximum permissible length." |
+ | | | |
+ | | | This error should never occur. |
+ | | | If it does, it indicates a |
+ | | | flaw in the NSS SSL library. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_CLOSE_NOTIFY_ALERT | -12230 | "SSL peer has closed this |
+ | | | connection." |
+ | | | |
+ | | | The local socket received an |
+ | | | SSL3 alert record from the |
+ | | | remote peer, reporting that |
+ | | | the remote peer has chosen to |
+ | | | end the connection. The |
+ | | | receipt of this alert is an |
+ | | | error only if it occurs while |
+ | | | a handshake is in progress. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12210 | "SSL Server attempted to use |
+ | OR_PUB_KEY_SIZE_LIMIT_EXCEEDED | | domestic-grade public key with |
+ | | | export cipher suite." |
+ | | | |
+ | | | On a client socket, this error |
+ | | | reports that the remote server |
+ | | | has failed to perform an "SSL |
+ | | | Step down" for an export |
+ | | | cipher. It has sent a |
+ | | | certificate bearing a |
+ | | | domestic-grade public key, but |
+ | | | has not sent a |
+ | | | ServerKeyExchange message |
+ | | | containing an export-grade |
+ | | | public key for the key |
+ | | | exchange algorithm. Such a |
+ | | | connection cannot be permitted |
+ | | | without violating U.S. export |
+ | | | policies. On a server socket, |
+ | | | this indicates a failure of |
+ | | | the local library. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -12206 | "Server has no key for the |
+ | SL_ERROR_NO_SERVER_KEY_FOR_ALG | | attempted key exchange |
+ | | | algorithm." |
+ | | | |
+ | | | An SSL client has requested an |
+ | | | SSL cipher suite that uses a |
+ | | | Key Exchange Algorithm for |
+ | | | which the local server has no |
+ | | | appropriate public key. This |
+ | | | indicates a configuration |
+ | | | error on the local server. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12205 | "PKCS #11 token was inserted |
+ | _ERROR_TOKEN_INSERTION_REMOVAL | | or removed while operation was |
+ | | | in progress." |
+ | | | |
+ | | | A cryptographic operation |
+ | | | required to complete the |
+ | | | handshake failed because the |
+ | | | token that was performing it |
+ | | | was removed while the |
+ | | | handshake was underway. |
+ | | | Another token may also have |
+ | | | been inserted into the same |
+ | | | slot. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_TOKEN_SLOT_NOT_FOUND | -12204 | "No PKCS#11 token could be |
+ | | | found to do a required |
+ | | | operation." |
+ | | | |
+ | | | A cryptographic operation |
+ | | | required a PKCS#11 token with |
+ | | | specific abilities, and no |
+ | | | token could be found in any |
+ | | | slot, including the "soft |
+ | | | token" in the internal virtual |
+ | | | slot, that could do the job. |
+ | | | May indicate a server |
+ | | | configuration error, such as |
+ | | | having a certificate that is |
+ | | | inappropriate for the Key |
+ | | | Exchange Algorithm selected. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12203 | "Cannot communicate securely |
+ | L_ERROR_NO_COMPRESSION_OVERLAP | | with peer: no common |
+ | | | compression algorithm(s)." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12202 | "Cannot initiate another SSL |
+ | _ERROR_HANDSHAKE_NOT_COMPLETED | | handshake until current |
+ | | | handshake is complete." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12201 | "Received incorrect handshakes |
+ | ERROR_BAD_HANDSHAKE_HASH_VALUE | | hash values from peer." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_CERT_KEA_MISMATCH | -12200 | "The certificate provided |
+ | | | cannot be used with the |
+ | | | selected key exchange |
+ | | | algorithm." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12199 | "No certificate authority is |
+ | ERROR_NO_TRUSTED_SSL_CLIENT_CA | | trusted for SSL client |
+ | | | authentication." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SESSION_NOT_FOUND | -12198 | "Client's SSL session ID not |
+ | | | found in server's session |
+ | | | cache." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12185 | "SSL server cache not |
+ | OR_SERVER_CACHE_NOT_CONFIGURED | | configured and not disabled |
+ | | | for this socket." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12176 | "Renegotiation is not allowed |
+ | RROR_RENEGOTIATION_NOT_ALLOWED | | on this SSL socket." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received a malformed (too | | |
+ | long or short or invalid | | |
+ | content) SSL handshake: ** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block indicate that | | |
+ | the local socket received an | | |
+ | improperly formatted SSL3 | | |
+ | handshake message from the | | |
+ | remote peer. This probably | | |
+ | indicates a flaw in the remote | | |
+ | peer's implementation. | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12261 | "SSL received a malformed |
+ | ROR_RX_MALFORMED_HELLO_REQUEST | | Hello Request handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12260 | "SSL received a malformed |
+ | RROR_RX_MALFORMED_CLIENT_HELLO | | Client Hello handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12259 | "SSL received a malformed |
+ | RROR_RX_MALFORMED_SERVER_HELLO | | Server Hello handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12258 | "SSL received a malformed |
+ | ERROR_RX_MALFORMED_CERTIFICATE | | Certificate handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR | -12257 | "SSL received a malformed |
+ | _RX_MALFORMED_SERVER_KEY_EXCH | | Server Key Exchange handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12256 | "SSL received a malformed |
+ | RROR_RX_MALFORMED_CERT_REQUEST | | Certificate Request handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12255 | "SSL received a malformed |
+ | _ERROR_RX_MALFORMED_HELLO_DONE | | Server Hello Done handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12254 | "SSL received a malformed |
+ | ERROR_RX_MALFORMED_CERT_VERIFY | | Certificate Verify handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR | -12253 | "SSL received a malformed |
+ | _RX_MALFORMED_CLIENT_KEY_EXCH | | Client Key Exchange handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -12252 | "SSL received a malformed |
+ | SL_ERROR_RX_MALFORMED_FINISHED | | Finished handshake message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_R | -12178 | "SSL received a malformed New |
+ | X_MALFORMED_NEW_SESSION_TICKET | | Session Ticket handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received a malformed (too | | |
+ | long or short) SSL record:** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block indicate that | | |
+ | the local socket received an | | |
+ | improperly formatted SSL3 | | |
+ | record from the remote peer. | | |
+ | This probably indicates a flaw | | |
+ | in the remote peer's | | |
+ | implementation. | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12251 | "SSL received a malformed |
+ | ROR_RX_MALFORMED_CHANGE_CIPHER | | Change Cipher Spec record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX_MALFORMED_ALERT | -12250 | "SSL received a malformed |
+ | | | Alert record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12249 | "SSL received a malformed |
+ | L_ERROR_RX_MALFORMED_HANDSHAKE | | Handshake record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12248 | "SSL received a malformed |
+ | RX_MALFORMED_APPLICATION_DATA | | Application Data record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received an SSL handshake | | |
+ | that was inappropriate for the | | |
+ | current state:** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block indicate that | | |
+ | the local socket received an | | |
+ | SSL3 handshake message from | | |
+ | the remote peer at a time when | | |
+ | it was inappropriate for the | | |
+ | peer to have sent this | | |
+ | message. For example, a server | | |
+ | received a message from | | |
+ | another server. This probably | | |
+ | indicates a flaw in the remote | | |
+ | peer's implementation. | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12247 | "SSL received an unexpected |
+ | OR_RX_UNEXPECTED_HELLO_REQUEST | | Hello Request handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12246 | "SSL received an unexpected |
+ | ROR_RX_UNEXPECTED_CLIENT_HELLO | | Client Hello handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12245 | "SSL received an unexpected |
+ | ROR_RX_UNEXPECTED_SERVER_HELLO | | Server Hello handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12244 | "SSL received an unexpected |
+ | RROR_RX_UNEXPECTED_CERTIFICATE | | Certificate handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12243 | "SSL received an unexpected |
+ | RX_UNEXPECTED_SERVER_KEY_EXCH | | Server Key Exchange handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12242 | "SSL received an unexpected |
+ | ROR_RX_UNEXPECTED_CERT_REQUEST | | Certificate Request handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12241 | "SSL received an unexpected |
+ | ERROR_RX_UNEXPECTED_HELLO_DONE | | Server Hello Done handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12240 | "SSL received an unexpected |
+ | RROR_RX_UNEXPECTED_CERT_VERIFY | | Certificate Verify handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12239 | "SSL received an unexpected |
+ | RX_UNEXPECTED_CLIENT_KEY_EXCH | | Client Key Exchange handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12238 | "SSL received an unexpected |
+ | L_ERROR_RX_UNEXPECTED_FINISHED | | Finished handshake message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX | -12179 | "SSL received an unexpected |
+ | _UNEXPECTED_NEW_SESSION_TICKET | | New Session Ticket handshake |
+ | | | message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received an SSL record that | | |
+ | was inappropriate for the | | |
+ | current state:** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block indicate that | | |
+ | the local socket received an | | |
+ | SSL3 record from the remote | | |
+ | peer at a time when it was | | |
+ | inappropriate for the peer to | | |
+ | have sent this message. This | | |
+ | probably indicates a flaw in | | |
+ | the remote peer's | | |
+ | implementation. | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12237 | "SSL received an unexpected |
+ | OR_RX_UNEXPECTED_CHANGE_CIPHER | | Change Cipher Spec record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX_UNEXPECTED_ALERT | -12236 | "SSL received an unexpected |
+ | | | Alert record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12235 | "SSL received an unexpected |
+ | _ERROR_RX_UNEXPECTED_HANDSHAKE | | Handshake record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12234 | "SSL received an unexpected |
+ | RX_UNEXPECTED_APPLICATION_DATA | | Application Data record." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received record/message with | | |
+ | unknown discriminant:** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block indicate that | | |
+ | the local socket received an | | |
+ | SSL3 record or handshake | | |
+ | message from the remote peer | | |
+ | that it was unable to | | |
+ | interpret because the byte | | |
+ | that identifies the type of | | |
+ | record or message contained an | | |
+ | unrecognized value. This | | |
+ | probably indicates a flaw in | | |
+ | the remote peer's | | |
+ | implementation. | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12233 | "SSL received a record with an |
+ | L_ERROR_RX_UNKNOWN_RECORD_TYPE | | unknown content type." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX_UNKNOWN_HANDSHAKE | -12232 | "SSL received a handshake |
+ | | | message with an unknown |
+ | | | message type." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_RX_UNKNOWN_ALERT | -12231 | "SSL received an alert record |
+ | | | with an unknown alert |
+ | | | description." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Received an alert report:** | | |
+ | | | |
+ | | All the error codes in the | | |
+ | following block indicate | | |
+ | that the local socket | | |
+ | received an SSL3 or TLS | | |
+ | alert record from the remote | | |
+ | peer, reporting some issue | | |
+ | that it had with an SSL | | |
+ | record or handshake message | | |
+ | it received. (Some \_Alert | | |
+ | codes are listed in other | | |
+ | blocks.) | | |
+ | | | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12229 | "SSL peer was not expecting a |
+ | ROR_HANDSHAKE_UNEXPECTED_ALERT | | handshake message it |
+ | | | received." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12228 | "SSL peer was unable to |
+ | OR_DECOMPRESSION_FAILURE_ALERT | | successfully decompress an SSL |
+ | | | record it received." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12227 | "SSL peer was unable to |
+ | _ERROR_HANDSHAKE_FAILURE_ALERT | | negotiate an acceptable set of |
+ | | | security parameters." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12226 | "SSL peer rejected a handshake |
+ | _ERROR_ILLEGAL_PARAMETER_ALERT | | message for unacceptable |
+ | | | content." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12225 | "SSL peer does not support |
+ | L_ERROR_UNSUPPORTED_CERT_ALERT | | certificates of the type it |
+ | | | received." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12224 | "SSL peer had some unspecified |
+ | RROR_CERTIFICATE_UNKNOWN_ALERT | | issue with the certificate it |
+ | | | received." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12197 | "Peer was unable to decrypt an |
+ | _ERROR_DECRYPTION_FAILED_ALERT | | SSL record it received." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -12196 | "Peer received an SSL record |
+ | SL_ERROR_RECORD_OVERFLOW_ALERT | | that was longer than is |
+ | | | permitted." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_UNKNOWN_CA_ALERT | -12195 | "Peer does not recognize and |
+ | | | trust the CA that issued your |
+ | | | certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ACCESS_DENIED_ALERT | -12194 | "Peer received a valid |
+ | | | certificate, but access was |
+ | | | denied." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_DECODE_ERROR_ALERT | -12193 | "Peer could not decode an SSL |
+ | | | handshake message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_DECRYPT_ERROR_ALERT | -12192 | "Peer reports failure of |
+ | | | signature verification or key |
+ | | | exchange." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ | -12191 | "Peer reports negotiation not |
+ | ERROR_EXPORT_RESTRICTION_ALERT | | in compliance with export |
+ | | | regulations." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12190 | "Peer reports incompatible or |
+ | L_ERROR_PROTOCOL_VERSION_ALERT | | unsupported protocol version." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12189 | "Server requires ciphers more |
+ | OR_INSUFFICIENT_SECURITY_ALERT | | secure than those supported by |
+ | | | client." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_INTERNAL_ERROR_ALERT | -12188 | "Peer reports it experienced |
+ | | | an internal error." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_USER_CANCELED_ALERT | -12187 | "Peer user canceled |
+ | | | handshake." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12186 | "Peer does not permit |
+ | L_ERROR_NO_RENEGOTIATION_ALERT | | renegotiation of SSL security |
+ | | | parameters." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12184 | "SSL peer does not support |
+ | OR_UNSUPPORTED_EXTENSION_ALERT | | requested TLS hello |
+ | | | extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12183 | "SSL peer could not obtain |
+ | CERTIFICATE_UNOBTAINABLE_ALERT | | your certificate from the |
+ | | | supplied URL." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12182 | "SSL peer has no certificate |
+ | _ERROR_UNRECOGNIZED_NAME_ALERT | | for the requested DNS name." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ | -12181 | "SSL peer was unable to get an |
+ | BAD_CERT_STATUS_RESPONSE_ALERT | | OCSP response for its |
+ | | | certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12180 | "SSL peer reported bad |
+ | RROR_BAD_CERT_HASH_VALUE_ALERT | | certificate hash value." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Unspecified errors that | | |
+ | occurred while attempting some | | |
+ | operation:** | | |
+ | | | |
+ | All the error codes in the | | |
+ | following block describe the | | |
+ | operation that was being | | |
+ | attempted at the time of the | | |
+ | unspecified failure. These | | |
+ | failures may be caused by the | | |
+ | system running out of memory, | | |
+ | or errors returned by PKCS#11 | | |
+ | routines that did not provide | | |
+ | meaningful error codes of | | |
+ | their own. These should rarely | | |
+ | be seen. (Certain of these | | |
+ | error codes have more specific | | |
+ | meanings, as described.) | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12223 | "SSL experienced a failure of |
+ | _ERROR_GENERATE_RANDOM_FAILURE | | its random number generator." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SIGN_HASHES_FAILURE | -12222 | "Unable to digitally sign data |
+ | | | required to verify your |
+ | | | certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ER | -12221 | "SSL was unable to extract the |
+ | ROR_EXTRACT_PUBLIC_KEY_FAILURE | | public key from the peer's |
+ | | | certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12220 | "Unspecified failure while |
+ | OR_SERVER_KEY_EXCHANGE_FAILURE | | processing SSL Server Key |
+ | | | Exchange handshake." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERR | -12219 | "Unspecified failure while |
+ | OR_CLIENT_KEY_EXCHANGE_FAILURE | | processing SSL Client Key |
+ | | | Exchange handshake." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_ENCRYPTION_FAILURE | -12218 | "Bulk data encryption |
+ | | | algorithm failed in selected |
+ | | | cipher suite." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_DECRYPTION_FAILURE | -12217 | "Bulk data decryption |
+ | | | algorithm failed in selected |
+ | | | cipher suite." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SOCKET_WRITE_FAILURE | -12216 | "Attempt to write encrypted |
+ | | | data to underlying socket |
+ | | | failed." |
+ | | | |
+ | | | After the data to be sent was |
+ | | | encrypted, the attempt to send |
+ | | | it out the socket failed. |
+ | | | Likely causes include that the |
+ | | | peer has closed the |
+ | | | connection. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_MD5_DIGEST_FAILURE | -12215 | "MD5 digest function failed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_SHA_DIGEST_FAILURE | -12214 | "SHA-1 digest function |
+ | | | failed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12213 | "Message Authentication Code |
+ | _ERROR_MAC_COMPUTATION_FAILURE | | computation failed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12212 | "Failure to create Symmetric |
+ | _ERROR_SYM_KEY_CONTEXT_FAILURE | | Key context." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SS | -12211 | "Failure to unwrap the |
+ | L_ERROR_SYM_KEY_UNWRAP_FAILURE | | Symmetric key in Client Key |
+ | | | Exchange message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_ERROR_IV_PARAM_FAILURE | -12209 | "PKCS11 code failed to |
+ | | | translate an IV into a param." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL_E | -12208 | "Failed to initialize the |
+ | RROR_INIT_CIPHER_SUITE_FAILURE | | selected cipher suite." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SSL | -12207 | "Failed to generate session |
+ | _ERROR_SESSION_KEY_GEN_FAILURE | | keys for SSL session." |
+ | | | |
+ | | | On a client socket, indicates |
+ | | | a failure of the PKCS11 key |
+ | | | generation function. On a |
+ | | | server socket, indicates a |
+ | | | failure of one of the |
+ | | | following: (a) to unwrap the |
+ | | | pre-master secret from the |
+ | | | ClientKeyExchange message, (b) |
+ | | | to derive the master secret |
+ | | | from the premaster secret, (c) |
+ | | | to derive the MAC secrets, |
+ | | | cryptographic keys, and |
+ | | | initialization vectors from |
+ | | | the master secret. If |
+ | | | encountered repeatedly on a |
+ | | | server socket, this can |
+ | | | indicate that the server is |
+ | | | actively under a "million |
+ | | | question" attack. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -12177 | "SSL received a compressed |
+ | SL_ERROR_DECOMPRESSION_FAILURE | | record that could not be |
+ | | | decompressed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+
+.. _sec_error_codes:
+
+`SEC Error Codes <#sec_error_codes>`__
+--------------------------------------
+
+.. container::
+
+ **Table 8.2 Security error codes defined in secerr.h**
+
+ +--------------------------------+--------------------------------+--------------------------------+
+ | **Constant** | **Value** | **Description** |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_IO | -8192 | An I/O error occurred during |
+ | | | authentication; or |
+ | | | an error occurred during |
+ | | | crypto operation (other than |
+ | | | signature verification). |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_LIBRARY_FAILURE | -8191 | Security library failure. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_DATA | -8190 | Security library: received bad |
+ | | | data. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OUTPUT_LEN | -8189 | Security library: output |
+ | | | length error. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INPUT_LEN | -8188 | Security library: input length |
+ | | | error. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_ARGS | -8187 | Security library: invalid |
+ | | | arguments. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_ALGORITHM | -8186 | Security library: invalid |
+ | | | algorithm. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_AVA | -8185 | Security library: invalid AVA. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_TIME | -8184 | Security library: invalid |
+ | | | time. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_DER | -8183 | Security library: improperly |
+ | | | formatted DER-encoded message. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_SIGNATURE | -8182 | Peer's certificate has an |
+ | | | invalid signature. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_EXPIRED_CERTIFICATE | -8181 | Peer's certificate has |
+ | | | expired. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_REVOKED_CERTIFICATE | -8180 | Peer's certificate has been |
+ | | | revoked. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNKNOWN_ISSUER | -8179 | Peer's certificate issuer is |
+ | | | not recognized. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_KEY | -8178 | Peer's public key is invalid |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_PASSWORD | -8177 | The password entered is |
+ | | | incorrect. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_RETRY_PASSWORD | -8176 | New password entered |
+ | | | incorrectly. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_NODELOCK | -8175 | Security library: no nodelock. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_DATABASE | -8174 | Security library: bad |
+ | | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_MEMORY | -8173 | Security library: memory |
+ | | | allocation failure. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNTRUSTED_ISSUER | -8172 | Peer's certificate issuer has |
+ | | | been marked as not trusted by |
+ | | | the user. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNTRUSTED_CERT | -8171 | Peer's certificate has been |
+ | | | marked as not trusted by the |
+ | | | user. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_DUPLICATE_CERT | -8170 | Certificate already exists in |
+ | | | your database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_DUPLICATE_CERT_NAME | -8169 | Downloaded certificate's name |
+ | | | duplicates one already in your |
+ | | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_ADDING_CERT | -8168 | Error adding certificate to |
+ | | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_FILING_KEY | -8167 | Error refiling the key for |
+ | | | this certificate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_KEY | -8166 | The private key for this |
+ | | | certificate cannot be found in |
+ | | | key database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CERT_VALID | -8165 | This certificate is valid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CERT_NOT_VALID | -8164 | This certificate is not valid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CERT_NO_RESPONSE | -8163 | Certificate library: no |
+ | | | response. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8162 | The certificate issuer's |
+ | ROR_EXPIRED_ISSUER_CERTIFICATE | | certificate has expired. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_EXPIRED | -8161 | The CRL for the certificate's |
+ | | | issuer has expired. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_BAD_SIGNATURE | -8160 | The CRL for the certificate's |
+ | | | issuer has an invalid |
+ | | | signature. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_INVALID | -8159 | New CRL has an invalid format. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC | -8158 | Certificate extension value is |
+ | _ERROR_EXTENSION_VALUE_INVALID | | invalid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_EXTENSION_NOT_FOUND | -8157 | Certificate extension not |
+ | | | found. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CA_CERT_INVALID | -8156 | Issuer certificate is invalid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERR | -8155 | Certificate path length |
+ | OR_PATH_LEN_CONSTRAINT_INVALID | | constraint is invalid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CERT_USAGES_INVALID | -8154 | Certificate usages field is |
+ | | | invalid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_INTERNAL_ONLY | -8153 | Internal-only module. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_KEY | -8152 | The key does not support the |
+ | | | requested operation. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8151 | Certificate contains unknown |
+ | ROR_UNKNOWN_CRITICAL_EXTENSION | | critical extension. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OLD_CRL | -8150 | New CRL is not later than the |
+ | | | current one. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_EMAIL_CERT | -8149 | Not encrypted or signed: you |
+ | | | do not yet have an email |
+ | | | certificate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8148 | Not encrypted: you do not have |
+ | ERROR_NO_RECIPIENT_CERTS_QUERY | | certificates for each of the |
+ | | | recipients. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NOT_A_RECIPIENT | -8147 | Cannot decrypt: you are not a |
+ | | | recipient, or matching |
+ | | | certificate and private key |
+ | | | not found. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8146 | Cannot decrypt: key encryption |
+ | EC_ERROR_PKCS7_KEYALG_MISMATCH | | algorithm does not match your |
+ | | | certificate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS7_BAD_SIGNATURE | -8145 | Signature verification failed: |
+ | | | no signer found, too many |
+ | | | signers found, \\ |
+ | | | or improper or corrupted data. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNSUPPORTED_KEYALG | -8144 | Unsupported or unknown key |
+ | | | algorithm. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8143 | Cannot decrypt: encrypted |
+ | EC_ERROR_DECRYPTION_DISALLOWED | | using a disallowed algorithm |
+ | | | or key size. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_BAD_CARD | -8142 | FORTEZZA card has not been |
+ | | | properly initialized. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_NO_CARD | -8141 | No FORTEZZA cards found. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_NONE_SELECTED | -8140 | No FORTEZZA card selected. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_MORE_INFO | -8139 | Please select a personality to |
+ | | | get more info on. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP | -8138 | Personality not found |
+ | _SEC_FORTEZZA_PERSON_NOT_FOUND | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_NO_MORE_INFO | -8137 | No more information on that |
+ | | | personality. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_BAD_PIN | -8136 | Invalid PIN. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_SEC_FORTEZZA_PERSON_ERROR | -8135 | Couldn't initialize FORTEZZA |
+ | | | personalities. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_KRL | -8134 | No KRL for this site's |
+ | | | certificate has been found. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_KRL_EXPIRED | -8133 | The KRL for this site's |
+ | | | certificate has expired. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_KRL_BAD_SIGNATURE | -8132 | The KRL for this site's |
+ | | | certificate has an invalid |
+ | | | signature. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_REVOKED_KEY | -8131 | The key for this site's |
+ | | | certificate has been revoked. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_KRL_INVALID | -8130 | New KRL has an invalid format. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NEED_RANDOM | -8129 | Security library: need random |
+ | | | data. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_MODULE | -8128 | Security library: no security |
+ | | | module can perform the |
+ | | | requested operation. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_TOKEN | -8127 | The security card or token |
+ | | | does not exist, needs to be |
+ | | | initialized, or has been |
+ | | | removed. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_READ_ONLY | -8126 | Security library: read-only |
+ | | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_SLOT_SELECTED | -8125 | No slot or token was selected. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC | -8124 | A certificate with the same |
+ | _ERROR_CERT_NICKNAME_COLLISION | | nickname already exists. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8123 | A key with the same nickname |
+ | C_ERROR_KEY_NICKNAME_COLLISION | | already exists. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_SAFE_NOT_CREATED | -8122 | Error while creating safe |
+ | | | object. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAGGAGE_NOT_CREATED | -8121 | Error while creating baggage |
+ | | | object. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_JAVA_REMOVE_PRINCIPAL_ERROR | -8120 | Couldn't remove the principal. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_JAVA_DELETE_PRIVILEGE_ERROR | -8119 | Couldn't delete the privilege |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | XP_JAVA_CERT_NOT_EXISTS_ERROR | -8118 | This principal doesn't have a |
+ | | | certificate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_EXPORT_ALGORITHM | -8117 | Required algorithm is not |
+ | | | allowed. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8116 | Error attempting to export |
+ | C_ERROR_EXPORTING_CERTIFICATES | | certificates. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8115 | Error attempting to import |
+ | C_ERROR_IMPORTING_CERTIFICATES | | certificates. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS12_DECODING_PFX | -8114 | Unable to import. Decoding |
+ | | | error. File not valid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS12_INVALID_MAC | -8113 | Unable to import. Invalid MAC. |
+ | | | Incorrect password or corrupt |
+ | | | file. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PK | -8112 | Unable to import. MAC |
+ | CS12_UNSUPPORTED_MAC_ALGORITHM | | algorithm not supported. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKC | -8111 | Unable to import. Only |
+ | S12_UNSUPPORTED_TRANSPORT_MODE | | password integrity and privacy |
+ | | | modes supported. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR | -8110 | Unable to import. File |
+ | _PKCS12_CORRUPT_PFX_STRUCTURE | | structure is corrupt. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PK | -8109 | Unable to import. Encryption |
+ | CS12_UNSUPPORTED_PBE_ALGORITHM | | algorithm not supported. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8108 | Unable to import. File version |
+ | ROR_PKCS12_UNSUPPORTED_VERSION | | not supported. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKC | -8107 | Unable to import. Incorrect |
+ | S12_PRIVACY_PASSWORD_INCORRECT | | privacy password. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8106 | Unable to import. Same |
+ | EC_ERROR_PKCS12_CERT_COLLISION | | nickname already exists in |
+ | | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_USER_CANCELLED | -8105 | The user clicked cancel. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8104 | Not imported, already in |
+ | EC_ERROR_PKCS12_DUPLICATE_DATA | | database. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_MESSAGE_SEND_ABORTED | -8103 | Message not sent. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INADEQUATE_KEY_USAGE | -8102 | Certificate key usage |
+ | | | inadequate for attempted |
+ | | | operation. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INADEQUATE_CERT_TYPE | -8101 | Certificate type not approved |
+ | | | for application. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CERT_ADDR_MISMATCH | -8100 | Address in signing certificate |
+ | | | does not match address in |
+ | | | message headers. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERR | -8099 | Unable to import. Error |
+ | OR_PKCS12_UNABLE_TO_IMPORT_KEY | | attempting to import private |
+ | | | key. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERR | -8098 | Unable to import. Error |
+ | OR_PKCS12_IMPORTING_CERT_CHAIN | | attempting to import |
+ | | | certificate chain. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS12_U | -8097 | Unable to export. Unable to |
+ | NABLE_TO_LOCATE_OBJECT_BY_NAME | | locate certificate or key by |
+ | | | nickname. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERRO | -8096 | Unable to export. Private key |
+ | R_PKCS12_UNABLE_TO_EXPORT_KEY | | could not be located and |
+ | | | exported. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8095 | Unable to export. Unable to |
+ | C_ERROR_PKCS12_UNABLE_TO_WRITE | | write the export file. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8094 | Unable to import. Unable to |
+ | EC_ERROR_PKCS12_UNABLE_TO_READ | | read the import file. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS1 | -8093 | Unable to export. Key database |
+ | 2_KEY_DATABASE_NOT_INITIALIZED | | corrupt or deleted. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_KEYGEN_FAIL | -8092 | Unable to generate |
+ | | | public-private key pair. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INVALID_PASSWORD | -8091 | Password entered is invalid. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_RETRY_OLD_PASSWORD | -8090 | Old password entered |
+ | | | incorrectly. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_NICKNAME | -8089 | Certificate nickname already |
+ | | | in use. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NOT_FORTEZZA_ISSUER | -8088 | Peer FORTEZZA chain has a |
+ | | | non-FORTEZZA Certificate. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8087 | "A sensitive key cannot be |
+ | RROR_CANNOT_MOVE_SENSITIVE_KEY | | moved to the slot where it is |
+ | | | needed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8086 | Invalid module name. |
+ | C_ERROR_JS_INVALID_MODULE_NAME | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_JS_INVALID_DLL | -8085 | Invalid module path/filename. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_JS_ADD_MOD_FAILURE | -8084 | Unable to add module. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_JS_DEL_MOD_FAILURE | -8083 | Unable to delete module. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OLD_KRL | -8082 | New KRL is not later than the |
+ | | | current one. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CKL_CONFLICT | -8081 | New CKL has different issuer |
+ | | | than current CKL. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8080 | Certificate issuer is not |
+ | C_ERROR_CERT_NOT_IN_NAME_SPACE | | permitted to issue a |
+ | | | certificate with this name. |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_KRL_NOT_YET_VALID | -8079 | "The key revocation list for |
+ | | | this certificate is not yet |
+ | | | valid." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_NOT_YET_VALID | -8078 | "The certificate revocation |
+ | | | list for this certificate is |
+ | | | not yet valid." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNKNOWN_CERT | -8077 | "The requested certificate |
+ | | | could not be found." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNKNOWN_SIGNER | -8076 | "The signer's certificate |
+ | | | could not be found." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8075 | "The location for the |
+ | ERROR_CERT_BAD_ACCESS_LOCATION | | certificate status server has |
+ | | | invalid format." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8074 | "The OCSP response cannot be |
+ | ROR_OCSP_UNKNOWN_RESPONSE_TYPE | | fully decoded; it is of an |
+ | | | unknown type." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8073 | "The OCSP server returned |
+ | C_ERROR_OCSP_BAD_HTTP_RESPONSE | | unexpected/invalid HTTP data." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8072 | "The OCSP server found the |
+ | C_ERROR_OCSP_MALFORMED_REQUEST | | request to be corrupted or |
+ | | | improperly formed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_SERVER_ERROR | -8071 | "The OCSP server experienced |
+ | | | an internal error." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8070 | "The OCSP server suggests |
+ | EC_ERROR_OCSP_TRY_SERVER_LATER | | trying again later." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8069 | "The OCSP server requires a |
+ | C_ERROR_OCSP_REQUEST_NEEDS_SIG | | signature on this request." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8068 | "The OCSP server has refused |
+ | RROR_OCSP_UNAUTHORIZED_REQUEST | | this request as unauthorized." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERRO | -8067 | "The OCSP server returned an |
+ | R_OCSP_UNKNOWN_RESPONSE_STATUS | | unrecognizable status." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_UNKNOWN_CERT | -8066 | "The OCSP server has no status |
+ | | | for the certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_NOT_ENABLED | -8065 | "You must enable OCSP before |
+ | | | performing this operation." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8064 | "You must set the OCSP default |
+ | RROR_OCSP_NO_DEFAULT_RESPONDER | | responder before performing |
+ | | | this operation." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC | -8063 | "The response from the OCSP |
+ | _ERROR_OCSP_MALFORMED_RESPONSE | | server was corrupted or |
+ | | | improperly formed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8062 | "The signer of the OCSP |
+ | ROR_OCSP_UNAUTHORIZED_RESPONSE | | response is not authorized to |
+ | | | give status for this |
+ | | | certificate." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_FUTURE_RESPONSE | -8061 | "The OCSP response is not yet |
+ | | | valid (contains a date in the |
+ | | | future)." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_OLD_RESPONSE | -8060 | "The OCSP response contains |
+ | | | out-of-date information." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_DIGEST_NOT_FOUND | -8059 | "The CMS or PKCS #7 Digest was |
+ | | | not found in signed message." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8058 | "The CMS or PKCS #7 Message |
+ | ERROR_UNSUPPORTED_MESSAGE_TYPE | | type is unsupported." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_MODULE_STUCK | -8057 | "PKCS #11 module could not be |
+ | | | removed because it is still in |
+ | | | use." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_TEMPLATE | -8056 | "Could not decode ASN.1 data. |
+ | | | Specified template was |
+ | | | invalid." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_NOT_FOUND | -8055 | "No matching CRL was found." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8054 | "You are attempting to import |
+ | ERROR_REUSED_ISSUER_AND_SERIAL | | a cert with the same |
+ | | | issuer/serial as an existing |
+ | | | cert, but that is not the same |
+ | | | cert." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BUSY | -8053 | "NSS could not shutdown. |
+ | | | Objects are still in use." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_EXTRA_INPUT | -8052 | "DER-encoded message contained |
+ | | | extra unused data." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ER | -8051 | "Unsupported elliptic curve." |
+ | ROR_UNSUPPORTED_ELLIPTIC_CURVE | | |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8050 | "Unsupported elliptic curve |
+ | RROR_UNSUPPORTED_EC_POINT_FORM | | point form." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNRECOGNIZED_OID | -8049 | "Unrecognized Object |
+ | | | IDentifier." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8048 | "Invalid OCSP signing |
+ | RROR_OCSP_INVALID_SIGNING_CERT | | certificate in OCSP response." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC | -8047 | "Certificate is revoked in |
+ | _ERROR_REVOKED_CERTIFICATE_CRL | | issuer's certificate |
+ | | | revocation list." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8046 | "Issuer's OCSP responder |
+ | ERROR_REVOKED_CERTIFICATE_OCSP | | reports certificate is |
+ | | | revoked." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_INVALID_VERSION | -8045 | "Issuer's Certificate |
+ | | | Revocation List has an unknown |
+ | | | version number." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8044 | "Issuer's V1 Certificate |
+ | RROR_CRL_V1_CRITICAL_EXTENSION | | Revocation List has a critical |
+ | | | extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_ | -8043 | "Issuer's V2 Certificate |
+ | CRL_UNKNOWN_CRITICAL_EXTENSION | | Revocation List has an unknown |
+ | | | critical extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNKNOWN_OBJECT_TYPE | -8042 | "Unknown object type |
+ | | | specified." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_INCOMPATIBLE_PKCS11 | -8041 | "PKCS #11 driver violates the |
+ | | | spec in an incompatible way." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NO_EVENT | -8040 | "No new slot event is |
+ | | | available at this time." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_ALREADY_EXISTS | -8039 | "CRL already exists." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_NOT_INITIALIZED | -8038 | "NSS is not initialized." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_TOKEN_NOT_LOGGED_IN | -8037 | "The operation failed because |
+ | | | the PKCS#11 token is not |
+ | | | logged in." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERR | -8036 | "The configured OCSP |
+ | OR_OCSP_RESPONDER_CERT_INVALID | | responder's certificate is |
+ | | | invalid." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OCSP_BAD_SIGNATURE | -8035 | "OCSP response has an invalid |
+ | | | signature." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_OUT_OF_SEARCH_LIMITS | -8034 | "Certification validation |
+ | | | search is out of search |
+ | | | limits." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8033 | "Policy mapping contains |
+ | C_ERROR_INVALID_POLICY_MAPPING | | any-policy." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8032 | "Certificate chain fails |
+ | ERROR_POLICY_VALIDATION_FAILED | | policy validation." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_E | -8031 | "Unknown location type in |
+ | RROR_UNKNOWN_AIA_LOCATION_TYPE | | certificate AIA extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_HTTP_RESPONSE | -8030 | "Server returned a bad HTTP |
+ | | | response." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_BAD_LDAP_RESPONSE | -8029 | "Server returned a bad LDAP |
+ | | | response." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | S | -8028 | "Failed to encode data with |
+ | EC_ERROR_FAILED_TO_ENCODE_DATA | | ASN.1 encoder." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ | -8027 | "Bad information access |
+ | ERROR_BAD_INFO_ACCESS_LOCATION | | location in certificate |
+ | | | extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_LIBPKIX_INTERNAL | -8026 | "Libpkix internal error |
+ | | | occurred during cert |
+ | | | validation." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS11_GENERAL_ERROR | -8025 | "A PKCS #11 module returned |
+ | | | CKR_GENERAL_ERROR, indicating |
+ | | | that an unrecoverable error |
+ | | | has occurred." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8024 | "A PKCS #11 module returned |
+ | C_ERROR_PKCS11_FUNCTION_FAILED | | CKR_FUNCTION_FAILED, |
+ | | | indicating that the requested |
+ | | | function could not be |
+ | | | performed. Trying the same |
+ | | | operation again might |
+ | | | succeed." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_PKCS11_DEVICE_ERROR | -8023 | "A PKCS #11 module returned |
+ | | | CKR_DEVICE_ERROR, indicating |
+ | | | that a problem has occurred |
+ | | | with the token or slot." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SE | -8022 | "Unknown information access |
+ | C_ERROR_BAD_INFO_ACCESS_METHOD | | method in certificate |
+ | | | extension." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_CRL_IMPORT_FAILED | -8021 | "Error attempting to import a |
+ | | | CRL." |
+ +--------------------------------+--------------------------------+--------------------------------+
+ | SEC_ERROR_UNKNOWN_PKCS11_ERROR | -8018 | "Unknown PKCS #11 error." |
+ | | | (unknown error value mapping) |
+ +--------------------------------+--------------------------------+--------------------------------+ \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst
new file mode 100644
index 0000000000..4d3f020faf
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst
@@ -0,0 +1,3595 @@
+.. _mozilla_projects_nss_ssl_functions_sslfnc:
+
+sslfnc
+======
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to
+ help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: SSL Functions
+ :name: SSL_Functions
+
+ --------------
+
+.. _chapter_4_ssl_functions:
+
+`Chapter 4 SSL Functions <#chapter_4_ssl_functions>`__
+------------------------------------------------------
+
+.. container::
+
+ This chapter describes the core SSL functions.
+
+ - `SSL Initialization Functions <#ssl_initialization_functions>`__
+ - `SSL Export Policy Functions <#ssl_export_policy_functions>`__
+ - `SSL Configuration Functions <#ssl_configuration_functions>`__
+ - `SSL Communication Functions <#ssl_communication_functions>`__
+ - `SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__
+ - `SSL Handshake Functions <#ssl_handshake_functions>`__
+ - `NSS Shutdown Function <#nss_shutdown_function>`__
+ - `Deprecated Functions <#deprecated_functions>`__
+
+.. _ssl_initialization_functions:
+
+`SSL Initialization Functions <#ssl_initialization_functions>`__
+----------------------------------------------------------------
+
+.. container::
+
+ This section describes the initialization functions that are specific to SSL. For a complete list
+ of NSS initialization functions, see `Initialization <sslintro.html#1027662>`__.
+
+ Note that at least one of the functions listed in `SSL Export Policy Functions <#1098841>`__ must
+ also be called during NSS initialization.
+
+ | ```NSS_Init`` <#1067601>`__
+ | ```NSS_InitReadWrite`` <#1237143>`__
+ | ```NSS_NoDB_Init`` <#1234224>`__
+ | ```SSL_OptionSetDefault`` <#1068466>`__
+ | ```SSL_OptionGetDefault`` <#1204897>`__
+ | ```SSL_CipherPrefSetDefault`` <#1084747>`__
+ | ```SSL_CipherPrefGetDefault`` <#1208119>`__
+ | ```SSL_ClearSessionCache`` <#1138601>`__
+ | ```SSL_ConfigServerSessionIDCache`` <#1143851>`__
+ | ```SSL_ConfigMPServerSIDCache`` <#1142625>`__
+ | ```SSL_InheritMPServerSIDCache`` <#1162055>`__
+
+ .. rubric:: NSS_Init
+ :name: nss_init
+
+ Sets up configuration files and performs other tasks required to run Network Security Services.
+ Database files are opened read-only.
+
+ .. rubric:: Syntax
+ :name: syntax
+
+ .. code::
+
+ #include "nss.h"
+
+ .. code::
+
+ SECStatus NSS_Init(char *configdir);
+
+ .. rubric:: Parameter
+ :name: parameter
+
+ This function has the following parameter:
+
+ +---------------+---------------------------------------------------------------------------------+
+ | ``configdir`` | A pointer to a string containing the pathname of the directory where the |
+ | | certificate, key, and security module databases reside. |
+ +---------------+---------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code.
+
+ .. rubric:: Description
+ :name: description
+
+ ``NSS_Init`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db`` files
+ (where\ *N* is a numeric digit) in the specified directory. ``NSS_Init`` is\ *not* idempotent, so
+ call it only once.
+
+ ``NSS_Init`` opens the database files read-only. If you are performing operations that require
+ write permission, for example S/MIME operations such as adding a certificate, use
+ ```NSS_InitReadWrite`` <#1237143>`__ instead.
+
+ Before calling ``NSS_Init``, your program must call ``PR_Init``.
+
+ The policy flags for all cipher suites are turned off by default, disallowing all cipher suites.
+ Therefore, an application cannot use NSS to perform any cryptographic operations until after it
+ enables appropriate cipher suites by calling one of the `SSL Export Policy
+ Functions <#1098841>`__:
+
+ - ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and
+ ```NSS_SetFrancePolicy`` <#1105952>`__ configure the cipher suites for domestic,
+ international, and French versions of software products with encryption features.
+ - ```SSL_CipherPolicySet`` <#1104647>`__ sets policy flags for individual cipher suites, one at
+ a time. This may be helpful if you have an export license that permits more or fewer
+ capabilities than those allowed by the other export policy functions.
+
+ .. rubric:: NSS_InitReadWrite
+ :name: nss_initreadwrite
+
+ Sets up configuration files and performs other tasks required to run Network Security Services.
+ Unlike ```NSS_Init`` <#1067601>`__, ``NSS_InitReadWrite`` provides both read and write access to
+ database files.
+
+ .. rubric:: Syntax
+ :name: syntax_2
+
+ .. code::
+
+ #include "nss.h"
+
+ .. code::
+
+ SECStatus NSS_InitReadWrite(char *configdir);
+
+ .. rubric:: Parameter
+ :name: parameter_2
+
+ This function has the following parameter:
+
+ +---------------+---------------------------------------------------------------------------------+
+ | ``configdir`` | A pointer to a string containing the pathname of the directory where the |
+ | | certificate, key, and security module databases reside. |
+ +---------------+---------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_2
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code.
+
+ .. rubric:: Description
+ :name: description_2
+
+ ``NSS_InitReadWrite`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db``
+ files (where\ *N* is a numeric digit) with both read and write permission in the specified
+ directory. ``NSS_InitReadWrite`` is\ *not* idempotent, so call it only once.
+
+ Use ``NSS_InitReadWrite`` rather than ```NSS_Init`` <#1067601>`__ if you are performing
+ operations that require write permission, such as some S/MIME operations.
+
+ Before calling ``NSS_InitReadWrite``, your program must call ``PR_Init``.
+
+ The policy flags for all cipher suites are turned off by default, disallowing all cipher suites.
+ Therefore, an application cannot use NSS to perform any cryptographic operations until after it
+ enables appropriate cipher suites by calling one of the `SSL Export Policy
+ Functions <#1098841>`__.
+
+ .. rubric:: NSS_NoDB_Init
+ :name: nss_nodb_init
+
+ Performs tasks required to run Network Security Services without setting up configuration files.
+ **Important:** This NSS function is not intended for use with SSL, which requires that the
+ certificate and key database files be opened.
+
+ .. rubric:: Syntax
+ :name: syntax_3
+
+ .. code::
+
+ #include "nss.h"
+
+ .. code::
+
+ SECStatus NSS_NoDB_Init(char *reserved);
+
+ .. rubric:: Parameter
+ :name: parameter_3
+
+ This function has the following parameter:
+
+ ============ ====================
+ ``reserved`` Should be ``NULL``..
+ ============ ====================
+
+ .. rubric:: Returns
+ :name: returns_3
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code.
+
+ .. rubric:: Description
+ :name: description_3
+
+ ``NSS_NoDB_Init`` opens only the temporary database and the internal PKCS #112 module. Unlike
+ ``NSS_Init``, ``NSS_NoDB_Init`` allows applications that do not have access to storage for
+ databases to run raw crypto, hashing, and certificate functions.
+
+ ``NSS_NoDB_Init`` is\ *not* idempotent, so call it only once.
+
+ Before calling ``NSS_NoDB_Init``, your program must call ``PR_Init``.
+
+ The policy flags for all cipher suites are turned off by default, disallowing all cipher suites.
+ Therefore, an application cannot use NSS to perform any cryptographic operations until after it
+ enables appropriate cipher suites by calling one of the `SSL Export Policy
+ Functions <#1098841>`__.
+
+ .. rubric:: SSL_OptionSetDefault
+ :name: ssl_optionsetdefault
+
+ Changes the default value of a specified SSL option for all subsequently opened sockets as long
+ as the current application program is running.
+
+ ``SSL_OptionSetDefault`` replaces the deprecated function ```SSL_EnableDefault`` <#1206365>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_4
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on);
+
+ .. rubric:: Parameters
+ :name: parameters
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``option`` | One of the following values (except as noted, |
+ | | the factory setting is "off"): |
+ | | |
+ | | - ``SSL_SECURITY`` enables use of security |
+ | | protocol. Factory setting is on. WARNING: If |
+ | | you turn this option off, the session will |
+ | | not be an SSL session and will not have |
+ | | certificate-based authentication, tamper |
+ | | detection, or encryption. |
+ | | - ``SSL_REQUEST_CERTIFICATE`` is a server |
+ | | option that requests a client to |
+ | | authenticate itself. |
+ | | - ``SSL_REQUIRE_CERTIFICATE`` is a server |
+ | | option that requires a client to |
+ | | authenticate itself (only if |
+ | | ``SSL_REQUEST_CERTIFICATE`` is also on). If |
+ | | client does not provide certificate, the |
+ | | connection terminates. Default state is a |
+ | | third state similar to on, that provides |
+ | | backward compatibility with older Netscape |
+ | | server products. |
+ | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the |
+ | | behavior of ``PR_Accept``,. If this option |
+ | | is off, the ``PR_Accept`` configures the SSL |
+ | | socket to handshake as a server. If it is |
+ | | on, then ``PR_Accept`` configures the SSL |
+ | | socket to handshake as a client, even though |
+ | | it accepted the connection as a TCP server. |
+ | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the |
+ | | behavior of ``PR_Connect``. If this option |
+ | | is off, then ``PR_Connect`` configures the |
+ | | SSL socket to handshake as a client. If it |
+ | | is on, then ``PR_Connect`` configures the |
+ | | SSL socket to handshake as a server, even |
+ | | though it connected as a TCP client. |
+ | | - ``SSL_ENABLE_FDX`` tells the SSL library |
+ | | whether the application will have two |
+ | | threads, one reading and one writing, or |
+ | | just one thread doing reads and writes |
+ | | alternately. The factory setting for this |
+ | | option (which is the default, unless the |
+ | | application changes the default) is off |
+ | | (``PR_FALSE``), which means that the |
+ | | application will not do simultaneous reads |
+ | | and writes. An application that wishes to do |
+ | | sumultaneous reads and writes should set |
+ | | this to ``PR_TRUE``. |
+ | | |
+ | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only |
+ | | affects the behavior of non-blocking SSL |
+ | | sockets. See the description below for more |
+ | | information on this option. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | | - ``SSL_ENABLE_SSL3`` enables the application |
+ | | to communicate with SSL v3. Factory setting |
+ | | is on. If you turn this option off, an |
+ | | attempt to establish a connection with a |
+ | | peer that only understands SSL v3 will fail. |
+ | | - ``SSL_ENABLE_SSL2`` enables the application |
+ | | to communicate with SSL v2. Factory setting |
+ | | is on. If you turn this option off, an |
+ | | attempt to establish a connection with a |
+ | | peer that only understands SSL v2 will fail. |
+ | | - ``SSL_ENABLE_TLS`` is a peer of the |
+ | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` |
+ | | options. The IETF standard Transport Layer |
+ | | Security (TLS) protocol, RFC 2246, is a |
+ | | modified version of SSL3. It uses the SSL |
+ | | version number 3.1, appearing to be a |
+ | | "minor" revision of SSL 3.0. NSS 2.8 |
+ | | supports TLS in addition to SSL2 and SSL3. |
+ | | You can think of it as |
+ | | "``SSL_ENABLE_SSL3.1``". See the description |
+ | | below for more information about this |
+ | | option. |
+ | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL |
+ | | library whether or not to send SSL3 client |
+ | | hello messages in SSL2-compatible format. If |
+ | | set to ``PR_TRUE``, it will; otherwise, it |
+ | | will not. Factory setting is on |
+ | | (``PR_TRUE``). See the description below for |
+ | | more information on this option. |
+ | | - ``SSL_NO_CACHE`` disallows use of the |
+ | | session cache. Factory setting is off. If |
+ | | you turn this option on, this socket will be |
+ | | unable to resume a session begun by another |
+ | | socket. When this socket's session is |
+ | | finished, no other socket will be able to |
+ | | resume the session begun by this socket. |
+ | | - ``SSL_ROLLBACK_DETECTION`` disables |
+ | | detection of a rollback attack. Factory |
+ | | setting is on. You must turn this option off |
+ | | to interoperate with TLS clients ( such as |
+ | | certain versions of Microsoft Internet |
+ | | Explorer) that do not conform to the TLS |
+ | | specification regarding rollback attacks. |
+ | | Important: turning this option off means |
+ | | that your code will not comply with the TLS |
+ | | 3.1 and SSL 3.0 specifications regarding |
+ | | rollback attack and will therefore be |
+ | | vulnerable to this form of attack. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns |
+ | | option off. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_4
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_4
+
+ This function changes the default values for all subsequently opened sockets as long as the
+ current application program is running. This function must be called once for each default value
+ you want to change from the factory setting. To change a value in a socket that is already open,
+ use ```SSL_OptionSet`` <#1086543>`__.
+
+ Keep the following in mind when deciding on the operating parameters you want to use with a
+ particular socket:
+
+ Enabling the ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no
+ certificate and this option is enabled, the client's connection terminates with an error. The
+ user is likely to think something is wrong with either the client or the server, and is unlikely
+ to realize that the problem is the lack of a certificate. It is better to allow the SSL handshake
+ to complete and then have your application return an error message to the client that informs the
+ user of the need for a certificate.
+
+ - As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a
+ socket into SSL after the TCP connection on that socket has already been established, it must
+ call ``SSL_ResetHandshake`` to determine whether the socket is for a client or server. At
+ first glance this may seem unnecessary, since ``SSL_Enable`` can set
+ ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control
+ the behavior of
+ ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__
+ and
+ ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__
+ only; if you don't call one of those functions after importing a non-SSL socket with
+ ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to
+ know whether the application is functioning as a client or server. For a complete discussion
+ of the use of ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` with
+ ``SSL_EnableDefault`` and ``SSL_Enable``, see `SSL_OptionSet <#1086543>`__.
+ - The SSL protocol is defined to be able to handle simultaneous two-way communication between
+ applications at each end of an SSL connection. Two-way simultaneous communication is also
+ known as "Full Duplex", abbreviated FDX. However, most application protocols that use SSL are
+ not two-way simultaneous, but two-way alternate, also known as "Half Dupled"; that is, each
+ end takes turns sending, and each end is either sending, or receiving, but not both at the
+ same time.
+
+ For an application to do full duplex, it would typically have two threads sharing the socket; one
+ doing all the reading and the other doing all the writing.
+
+ The ``SSL_ENABLE_FDX`` option tells the SSL library whether the application will have two
+ threads, one reading and one writing, or just one thread doing reads and writes alternately.
+
+ - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello
+ messages in SSL2-compatible format. If an SSL3 client hello message is sent to a server that
+ only understands SSL2 and not SSL3, then the server will interpret the SSL3 client hello as a
+ very large message, and the connection will usually seem to "hang" while the SSL2 server
+ expects more data that will never arrive. For this reason, the SSL3 spec allows SSL3 client
+ hellos to be sent in SSL2 format, and it recommends that SSL3 servers all accept SSL3 client
+ hellos in SSL2 format. When an SSL2-only server receives an SSL3 client hello in SSL2 format,
+ it can (and probably will) negotiate the protocol version correctly, not causing a "hang".
+
+ Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in
+ SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does
+ not understand SSL2-compatible client hello messages.
+
+ Note that calling ``SSL_Enable`` to set ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly
+ also sets the ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that SSL socket. Calling
+ ``SSL_EnableDefault`` to change the application default setting for ``SSL_V2_COMPATIBLE_HELLO``
+ to ``PR_FALSE`` implicitly also sets the default value for ``SSL_ENABLE_SSL2`` option to
+ ``PR_FALSE`` for that application.
+
+ - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set
+ to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 will negotiate the higest
+ protocol version with the peer application from among the set of protocols that are commonly
+ enabled in both applications.
+
+ Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled,
+ all SSL3/TLS ciphersuites that are enabled are enabled for both SSL3 and TLS.
+
+ .. rubric:: SSL_OptionGetDefault
+ :name: ssl_optiongetdefault
+
+ Gets the value of a specified SSL default option.
+
+ ``SSL_OptionGetDefault`` is the complementary function for
+ ```SSL_OptionSetDefault`` <#1068466>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_5
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on)
+
+ .. rubric:: Parameters
+ :name: parameters_2
+
+ This function has the parameters listed below.
+
+ +------------+------------------------------------------------------------------------------------+
+ | ``option`` | The value of the option whose default setting you wish to get. For information |
+ | | about the options available and the possible values to pass in this parameter, see |
+ | | the description of the ``option`` parameter under |
+ | | ```SSL_OptionSetDefault`` <#1068466>`__. |
+ +------------+------------------------------------------------------------------------------------+
+ | ``on`` | A pointer to the value of the option specified in the option parameter. |
+ | | ``PR_TRUE`` indicates that the option is on; ``PR_FALSE`` indicates that the |
+ | | option is off. |
+ +------------+------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_5
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain error code.
+
+ .. rubric:: Description
+ :name: description_5
+
+ ``SSL_CipherPrefGetDefault`` gets the application default preference for the specified SSL2,
+ SSL3, or TLS cipher A cipher suite is used only if the policy allows it and the preference for it
+ is set to ``PR_TRUE``.
+
+ .. rubric:: SSL_CipherPrefSetDefault
+ :name: ssl_cipherprefsetdefault
+
+ Enables or disables SSL2 or SSL3 cipher suites (subject to which cipher suites are permitted or
+ disallowed by previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__).
+ This function must be called once for each cipher you want to enable or disable by default.
+
+ .. rubric:: Syntax
+ :name: syntax_6
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool enabled);
+
+ .. rubric:: Parameters
+ :name: parameters_3
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cipher`` | One of the following values for SSL2 (factory |
+ | | settings for all are enabled): |
+ | | |
+ | | ``SSL_EN_RC4_128_WITH_ |
+ | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 |
+ | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 |
+ | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W |
+ | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` |
+ | | |
+ | | Or one of the following values for SSL3/TLS |
+ | | (unless indicated otherwise, factory settings |
+ | | for all are enabled): |
+ | | |
+ | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled |
+ | | by default) |
+ | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` |
+ | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_RSA_WITH_RC4_128_MD5`` |
+ | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by |
+ | | default) |
+ | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled |
+ | | by default) |
+ | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` |
+ | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_DES_CBC_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` |
+ | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by |
+ | | default) |
+ | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by |
+ | | default) |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``enabled`` | If nonzero, the specified cipher is enabled. If |
+ | | zero, the cipher is disabled. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_6
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_6
+
+ The CipherPrefSetDefault function enables or disables individual cipher suites globally. You
+ typically call this in response to changes in user-controlled settings. You must call this
+ function once for each cipher you want to enable or disable. To enable or disable cipher suites
+ for an individual socket, use ```SSL_CipherPrefSet`` <#1214758>`__.
+
+ The set of available SSL cipher suites may grow from release to release of NSS. Applications will
+ find it desirable to determine, at run time, what SSL2 cipher kinds and SSL3 cipher suites are
+ actually implememted in a particular release. Applications may disable any cipher suites that
+ they don't know about (for example, that they cannot present to the user via a GUI). To that end,
+ NSS provides a table that can be examined at run time. All aspects of this table are declared in
+ ``ssl.h``.
+
+ ``SSL_ImplementedCiphers[]`` is an external array of unsigned 16-bit integers whose values are
+ either SSL2 cipher kinds or SSL3 cipher suites. The values are the same as the values used to
+ enable or disable a cipher suite via calls to ```SSL_CipherPrefSetDefault`` <#1084747>`__, and
+ are defined in ``sslproto.h``. The number of values in the table is contained in an external
+ 16-bit integer named ``SSL_NumImplementedCiphers``. The macro ``SSL_IS_SSL2_CIPHER`` can be used
+ to determine whether a particular value is an SSL2 or an SSL3 cipher.
+
+ **WARNING**: Using the external array ``SSL_ImplementedCiphers[]`` directly is deprecated. It
+ causes dynamic linking issues at run-time after an update of NSS because the actual size of the
+ array changes between releases. The recommended way of accessing the array is through the
+ ``SSL_GetImplementedCiphers()`` and ``SSL_GetNumImplementedCiphers()`` accessors.
+
+ By default, all SSL2 and 12 SSL3/TLS cipher suites are enabled. However, this does not
+ necessarily mean that they are all permitted. The ``SSL_CipherPrefSetDefault`` function cannot
+ override cipher suite policy settings that are not permitted; see `SSL Export Policy
+ Functions <#1098841>`__ for details. Your application must call one of the export policy
+ functions before it can perform any cryptographic operations.
+
+ The ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` and ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` cipher
+ suites are defined in RFC 2246. They work with both SSL3 and TLS. They use symmetric ciphers with
+ an effective key size of 56 bits. The so-called 56-bit export browsers and servers use these
+ cipher suites.
+
+ The cipher suite numbers for the ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` and
+ ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` cipher suites have been changed so that they are no longer
+ "experimental" values. If an application attempts to set or set the policy or preference for one
+ of the old FIPS cipher suite numbers, the library recognizes the old number and sets or gets the
+ value for the new cipher suite number instead.
+
+ In this release, the three ``SSL_FORTEZZA_`` cipher suites cannot be enabled unless there is a
+ PKCS #11 module available with a FORTEZZA-enabled token. The ``SSL_FORTEZZA_`` cipher suites will
+ be removed in NSS 3.11.
+
+ .. rubric:: SSL_CipherPrefGetDefault
+ :name: ssl_cipherprefgetdefault
+
+ Gets the current default preference setting for a specified SSL2 or SSL3 cipher suite.
+
+ .. rubric:: Syntax
+ :name: syntax_7
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool *enabled);
+
+ .. rubric:: Parameters
+ :name: parameters_4
+
+ This function has the parameters listed below.
+
+ +---------+---------------------------------------------------------------------------------------+
+ | cipher | The cipher suite whose default preference setting you want to get. For a list of the |
+ | | cipher suites you can specify, see ```SSL_CipherPrefSetDefault`` <#1084747>`__. |
+ +---------+---------------------------------------------------------------------------------------+
+ | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` |
+ | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is |
+ | | disabled. |
+ +---------+---------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_7
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain error code.
+
+ .. rubric:: Description
+ :name: description_7
+
+ ``SSL_CipherPrefGetDefault`` performs the complementary function to ``SSL_CipherPrefSetDefault``.
+ It returns the application process' current default preference value for the specified cipher
+ suite. If the application has not previously set the default preference,
+ ``SSL_CipherPrefGetDefault`` returns the factory setting.
+
+ .. rubric:: SSL_ClearSessionCache
+ :name: ssl_clearsessioncache
+
+ Empties the SSL client session ID cache.
+
+ .. rubric:: Syntax
+ :name: syntax_8
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ void SSL_ClearSessionCache(void);
+
+ .. rubric:: Description
+ :name: description_8
+
+ You must call ``SSL_ClearSessionCache`` after you use one of the `SSL Export Policy
+ Functions <#1098841>`__ to change cipher suite policy settings or use
+ ```SSL_CipherPrefSetDefault`` <#1084747>`__ to enable or disable any cipher suite. Otherwise, the
+ old settings remain in the session cache and will be used instead of the new settings.
+
+ This function clears only the client cache. The client cache is not configurable. It is located
+ in RAM (not on disk), and has the following characteristics:
+
+ - maximum number of entries: unlimited
+ - SSL 2.0 timeout value: 100 seconds
+ - SSL 3.0 timeout value: 24 hours
+
+ ..
+
+ **NOTE:** If an SSL client application does not call ``SSL_ClearSessionCache`` before
+ shutdown, ```NSS_Shutdown`` <#1061858>`__ fails with the error code ``SEC_ERROR_BUSY``.
+
+ .. rubric:: SSL_ConfigServerSessionIDCache
+ :name: ssl_configserversessionidcache
+
+ Sets up parameters for and opens the server session cache for a single-process application.
+
+ .. rubric:: Syntax
+ :name: syntax_9
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_ConfigServerSessionIDCache(
+ int maxCacheEntries,
+ PRUint32 timeout,
+ PRUint32 ssl3_timeout,
+ const char *directory);
+
+ .. rubric:: Parameters
+ :name: parameters_5
+
+ This function has the parameters listed below.
+
+ +---------------------+---------------------------------------------------------------------------+
+ | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is |
+ | | passed, the server default value of 10,000 is used. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is |
+ | | 5 seconds and the maximum is 24 hours. Values outside this range are |
+ | | replaced by the server default value of 100 seconds. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is |
+ | | 5 seconds and the maximum is 24 hours. Values outside this range are |
+ | | replaced by the server default value of 24 hours. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``directory`` | A pointer to a string specifying the pathname of the directory that will |
+ | | contain the session cache. If a ``NULL`` value is passed, the server |
+ | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). |
+ +---------------------+---------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_8
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain error code.
+
+ .. rubric:: Description
+ :name: description_9
+
+ If you are writing an application that will use SSL sockets that handshake as a server, you must
+ call ``SSL_ConfigServerSessionIDCache`` to configure additional session caches for *server*
+ sessions. If your server application uses multiple processes (instead of or in addition to
+ multiple threads), use ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ instead. You must use one of
+ these functions to create a server cache. This function creates two caches: the\ *server session
+ ID cache* (also called the server session cache, or server cache), and the\ *client-auth
+ certificate cache* (also called the client cert cache, or client auth cache). Both caches are
+ used only for sessions where the program handshakes as a server. The client-auth certificate
+ cache is used to remember the certificates previously presented by clients for client certificate
+ authentication.
+
+ Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the
+ server default value to be used in the server cache. The values that you pass affect only the
+ server cache, not the client cache.
+
+.. _initializing_multi-processing_with_a_shared_ssl_server_cache:
+
+`Initializing Multi-Processing with a Shared SSL Server Cache <#initializing_multi-processing_with_a_shared_ssl_server_cache>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ To start a multi-processing application, the initial parent process calls
+ ```SSL_ConfigMPServerSIDCache`` <#1142625>`__, and then creates child processes, by one of these
+ methods:
+
+ - Call ``fork`` and then ``exec`` (Unix)
+ - Call ``CreateProcess`` (Win32)
+ - Call ``PR_CreateProcess`` (both Unix and Win32)
+
+ It is essential that the parent allow the child to inherit the file descriptors. WIN32's
+ ``CreateProcess`` takes an argument that tells it whether or not to permit files to be inherited;
+ this argument must be ``TRUE``.
+
+ When a new child that has been created by either ``CreateProcess`` or ``exec`` begins, it may
+ have inherited file descriptors (FDs), but not the parent's memory. Therefore, to find out what
+ FDs it has inherited, it must be told about them. To that end, the function
+ ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ sets an environment variable named
+ ``SSL_INHERITANCE``. The value of the variable is a printable ASCII string, containing all the
+ information needed to set up and use the inherited FDs.
+
+ There are two ways to transfer the content of ``SSL_INHERITANCE`` from parent to child:
+
+ - The child inherits the parent's environment, which must include the ``SSL_INHERITANCE``
+ variable. For the child to inherit the parent's environment you must set a specific argument
+ to ``CreateProcess`` or ``PR_CreateProcess``.
+ - The parent transmits the content of ``SSL_INHERITANCE`` to the child by some other means, such
+ as on the command line, or in another file or pipe.
+
+ In either case, the child must call ```SSL_InheritMPServerSIDCache`` <#1162055>`__ to complete
+ the inheritance of the shared cache FDs/handles.
+
+ .. rubric:: SSL_ConfigMPServerSIDCache
+ :name: ssl_configmpserversidcache
+
+ Sets up parameters for and opens the server session cache for a multi-process application.
+
+ .. rubric:: Syntax
+ :name: syntax_10
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_ConfigMPServerSIDCache(
+ int maxCacheEntries,
+ PRUint32 timeout,
+ PRUint32 ssl3_timeout,
+ const char *directory);
+
+ .. rubric:: Parameters
+ :name: parameters_6
+
+ This function has the parameters listed below.
+
+ +---------------------+---------------------------------------------------------------------------+
+ | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is |
+ | | passed, the server default value of 10,000 is used. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is |
+ | | 5 seconds and the maximum is 24 hours. Values outside this range are |
+ | | replaced by the server default value of 100 seconds. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is |
+ | | 5 seconds and the maximum is 24 hours. Values outside this range are |
+ | | replaced by the server default value of 24 hours. |
+ +---------------------+---------------------------------------------------------------------------+
+ | ``directory`` | A pointer to a string specifying the pathname of the directory that will |
+ | | contain the session cache. If a ``NULL`` value is passed, the server |
+ | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). |
+ +---------------------+---------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_9
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain error code.
+
+ .. rubric:: Description
+ :name: description_10
+
+ This function is identical to ```SSL_ConfigServerSessionIDCache`` <#1143851>`__, except that it
+ is for use with applications that use multiple processes. You must use one or the other of these
+ functions to create a server cache, not both.
+
+ If your application will use multiple processes (instead of, or in addition to, multiple
+ threads), and all of the processes appear to be on the same server (same IP address and port
+ number), then those processes must share a common SSL session cache. The common parent of all the
+ processes must call this function to create the cache before creating the other processes.
+
+ An application uses multiple processes\ *only* if it uses the Unix function ``fork``, or the
+ Win32 function ``CreateProcess``. This is not the same as using multiple threads or multiple
+ processors. Note that an SSL server that uses Fortezza hardware devices is limited to a single
+ process. It can use multiple threads, and thereby make use of multiple processors, but this must
+ all be done from a single process.
+
+ This function creates two caches: the\ *server session ID cache* (also called the server session
+ cache, or server cache), and the\ *client-auth certificate cache* (also called the client cert
+ cache, or client auth cache). Both caches are used only for sessions where the program handshakes
+ as a server. The client-auth certificate cache is used to remember the certificates previously
+ presented by clients for client certificate authentication.
+
+ Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the
+ server default value to be used in the server cache. The values that you pass affect only the
+ server cache, not the client cache. Before the cache can be used in the child process, the child
+ process must complete its initialization using ```SSL_InheritMPServerSIDCache`` <#1162055>`__.
+
+ .. rubric:: SSL_InheritMPServerSIDCache
+ :name: ssl_inheritmpserversidcache
+
+ Ensures the inheritance of file descriptors to a child process.
+
+ .. rubric:: Syntax
+ :name: syntax_11
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_InheritMPServerSIDCache (const char *envString);
+
+ .. rubric:: Parameters
+ :name: parameters_7
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``envString`` | A pointer to the location of the inheritance |
+ | | information. The value depends on how you are |
+ | | passing the information. |
+ | | |
+ | | If a ``NULL`` value is passed, the function |
+ | | looks for the ``SSL_INHERITANCE`` variable that |
+ | | has been inherited as part of the child's |
+ | | environment. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_10
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_11
+
+ This function completes the inheritance of file descriptors from a parent to a child process.
+ After the child process is created, it must call this function to complete its initialization.
+
+ The value of the ``envString`` argument depends on which of the two possible inheritance schemes
+ you have used. (See `Initializing Multi-Processing with a Shared SSL Server Cache <#1154189>`__.)
+
+ - If the ``SSL_INHERITANCE`` variable has been inherited as part of the child's environment, the
+ child must pass a ``NULL`` pointer as the ``envString`` argument. This causes the function to
+ look in the environment for the variable.
+ - If the parent has transmitted the value of the ``SSL_INHERITANCE`` variable to the child by
+ some other means, the child must pass a pointer to that string as the ``envString`` argument
+ to complete the inheritance.
+
+ When this function returns ``SECSuccess``, the server cache is ready to be used by the SSL code.
+
+.. _ssl_export_policy_functions:
+
+`SSL Export Policy Functions <#ssl_export_policy_functions>`__
+--------------------------------------------------------------
+
+.. container::
+
+ The SSL export policy functions determine which cipher suites are\ *permitted* for use in an SSL
+ session. They do not determine which cipher suites are actually\ *enabled*--that is, turned on
+ and ready to use. To enable or disable a permitted cipher suite, use
+ ```SSL_CipherPrefSetDefault`` <#1084747>`__; but bear in mind that
+ ```SSL_CipherPrefSetDefault`` <#1084747>`__ can't enable any cipher suite that is not explicitly
+ permitted as a result of a call to one of the export policy functions.
+
+ By default, none of the cipher suites supported by SSL are permitted. The functions
+ ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and
+ ```NSS_SetFrancePolicy`` <#1105952>`__ permit the use of approved cipher suites for domestic,
+ international, and French versions, respectively, of software products with encryption features.
+ The policy settings permitted by these functions conform with current U.S. export regulations as
+ understood by Netscape (for products with and without "retail status" as defined by the `latest
+ U.S. Export Regulations <http://w3.access.gpo.gov/bxa/ear/ear_data.html>`__) and French import
+ regulations.
+
+ Under some circumstances, you may be required to abide by the terms of an export license that
+ permits more or fewer capabilities than those allowed by these three functions. In such cases,
+ use ```SSL_CipherPolicySet`` <#1104647>`__ to explicitly enable those cipher suites you may
+ legally export.
+
+ For descriptions of cipher suites supported by SSL, see `Introduction to
+ SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__.
+
+ Applications must call one of the export policy functions before attempting to perform any
+ cryptographic operations:
+
+ | ```NSS_SetDomesticPolicy`` <#1228530>`__
+ | ```NSS_SetExportPolicy`` <#1100285>`__
+ | ```NSS_SetFrancePolicy`` <#1105952>`__
+ | ```SSL_CipherPolicySet`` <#1104647>`__
+
+ The following function is also described in this section:
+
+ ```SSL_CipherPolicyGet`` <#1210463>`__
+
+ .. rubric:: NSS_SetDomesticPolicy
+ :name: nss_setdomesticpolicy
+
+ Configures cipher suites to conform with current U.S. export regulations related to domestic
+ software products with encryption features.
+
+ .. rubric:: Syntax
+ :name: syntax_12
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ extern SECStatus NSS_SetDomesticPolicy(void);
+
+ .. rubric:: Returns
+ :name: returns_11
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_12
+
+ ``NSS_SetDomesticPolicy`` configures all the cipher suites listed under
+ ```SSL_CipherPolicySet`` <#1104647>`__ for software that is\ *not* intended for export, and is
+ thus not required to conform with U.S. export regulations related to domestic software products
+ with encryption features. After calling this function, all cipher suites listed are permitted
+ (but not necessarily enabled; see `SSL Export Policy Functions <#1098841>`__) for the calling
+ application.
+
+ When an SSL connection is established, SSL permits the use of the strongest cipher suites that
+ are both permitted and enabled for the software on both ends of the connection. For example, if a
+ client that has called ``NSS_SetDomesticPolicy`` establishes an SSL connection with a server for
+ which some cipher suites are either not permitted or not enabled (such as an international
+ version of Netscape server software), SSL uses the strongest cipher suites supported by the
+ server that are also supported by the client.
+
+ Under some circumstances, you may be required to abide by the terms of an export license that
+ permits more or fewer capabilities than those allowed by ``NSS_SetDomesticPolicy``. In that case,
+ first call ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or
+ ```NSS_SetFrancePolicy`` <#1105952>`__, then call ```SSL_CipherPolicySet`` <#1104647>`__
+ repeatedly to explicitly allow or disallow cipher suites until only those that you may legally
+ export are permitted.
+
+ .. rubric:: Important
+ :name: important
+
+ If you call ``NSS_SetDomesticPolicy`` sometime after initialization to change cipher suite policy
+ settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the
+ session cache and will be used instead of the new settings.
+
+ .. rubric:: NSS_SetExportPolicy
+ :name: nss_setexportpolicy
+
+ Configures the SSL cipher suites to conform with current U.S. export regulations related to
+ international software products with encryption features.
+
+ .. rubric:: Syntax
+ :name: syntax_13
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ extern SECStatus NSS_SetExportPolicy(void);
+
+ .. rubric:: Returns
+ :name: returns_12
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_13
+
+ ``NSS_SetExportPolicy`` configures all the cipher suites listed under
+ ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations related to
+ international software products with encryption features (as Netscape understands them). Calling
+ this function permits use of cipher suites listed below (but doesn't necessarily enable them; see
+ `SSL Export Policy Functions <#1098841>`__). Policy for these suites is set to ``SSL_ALLOWED``
+ unless otherwise indicated. ``SSL_RESTRICTED`` means the suite can be used by clients only when
+ they are communicating with domestic server software or with international server software that
+ presents a Global ID certificate. For more details on policy settings, see
+ ```SSL_CipherPolicySet`` <#1104647>`__.
+
+ For SSL 2.0:
+
+ - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5``
+ - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5``
+
+ For SSL 3.0:
+
+ - ``SSL_RSA_WITH_NULL_MD5``
+ - ``SSL_RSA_WITH_RC4_128_MD5 (SSL_RESTRICTED)``
+ - ``SSL_RSA_WITH_3DES_EDE_CBC_SHA (SSL_RESTRICTED)``
+ - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5``
+ - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5``
+
+ Under some circumstances, you may be required to abide by the terms of an export license that
+ permits more or fewer capabilities than those allowed by ``NSS_SetExportPolicy``. In that case,
+ you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__,
+ ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call
+ ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites
+ until only those that you may legally export are permitted.
+
+ .. rubric:: Important
+ :name: important_2
+
+ If you call ``NSS_SetExportPolicy`` sometime after initialization to change cipher suite policy
+ settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the
+ session cache and will be used instead of the new settings.
+
+ .. rubric:: NSS_SetFrancePolicy
+ :name: nss_setfrancepolicy
+
+ Configures the SSL cipher suites to conform with French import regulations related to software
+ products with encryption features.
+
+ .. rubric:: Syntax
+ :name: syntax_14
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus NSS_SetFrancePolicy(void);
+
+ .. rubric:: Returns
+ :name: returns_13
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_14
+
+ ``NSS_SetFrancePolicy`` configures all the cipher suites listed under
+ ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations and French
+ import regulations (as Netscape understands them) related to software products with encryption
+ features. Calling this function permits use of cipher suites listed below (but doesn't
+ necessarily enable them; see `SSL Export Policy Functions <#1098841>`__). Policy for these suites
+ is set to ``SSL_ALLOWED``. For more details on policy settings, see
+ ```SSL_CipherPolicySet`` <#1104647>`__.
+
+ For SSL 2.0:
+
+ - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5``
+ - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5``
+
+ For SSL 3.0:
+
+ - ``SSL_RSA_WITH_NULL_MD5``
+ - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5``
+ - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5``
+
+ Under some circumstances, you may be required to abide by the terms of an export license that
+ permits more or fewer capabilities than those allowed by ``NSS_SetFrancePolicy``. In that case,
+ you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__,
+ ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call
+ ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites
+ until only those that you may legally export are permitted.
+
+ .. rubric:: Important
+ :name: important_3
+
+ If you call ``NSS_SetFrancePolicy`` sometime after initialization to change cipher suite policy
+ settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the
+ session cache and will be used instead of the new settings.
+
+ .. rubric:: SSL_CipherPolicySet
+ :name: ssl_cipherpolicyset
+
+ Sets policy for the use of individual cipher suites.
+
+ ``SSL_CipherPolicySet`` replaces the deprecated function ```SSL_SetPolicy`` <#1207350>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_15
+
+ .. code::
+
+ #include "ssl.h"
+ #include "proto.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy);
+
+ .. rubric:: Parameters
+ :name: parameters_8
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cipher`` | A value from one of the following lists. |
+ | | |
+ | | Values for SSL2 (all are disallowed by |
+ | | default): |
+ | | |
+ | | ``SSL_EN_RC4_128_WITH_ |
+ | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 |
+ | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 |
+ | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W |
+ | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` |
+ | | |
+ | | Values for SSL3/TLS (all are disallowed by |
+ | | default): |
+ | | |
+ | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (client |
+ | | side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (client |
+ | | side only) |
+ | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` |
+ | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (client side |
+ | | only) |
+ | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (client |
+ | | side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (client |
+ | | side only) |
+ | | ``SSL_RSA_WITH_RC4_128_MD5`` |
+ | | ``SSL_RSA_WITH_RC4_128_SHA`` |
+ | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` |
+ | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (client |
+ | | side only) |
+ | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (client |
+ | | side only) |
+ | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` |
+ | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (client side |
+ | | only) |
+ | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (client side |
+ | | only) |
+ | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_DES_CBC_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` |
+ | | ``SSL_RSA_WITH_NULL_SHA`` |
+ | | ``SSL_RSA_WITH_NULL_MD5`` |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``policy`` | One of the following values: |
+ | | |
+ | | - ``SSL_ALLOWED``. Cipher is always allowed by |
+ | | U.S. government policy. |
+ | | - ``SSL_RESTRICTED``. Cipher is allowed by |
+ | | U.S. government policy for servers with |
+ | | Global ID certificates. |
+ | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed |
+ | | by U.S. government policy. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_14
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_15
+
+ ``SSL_CipherPolicySet`` tells the SSL library that the specified cipher suite is allowed by the
+ application's export license, or is not allowed by the application's export license, or is
+ allowed to be used only with a Step-Up certificate. It overrides the factory default policy for
+ that cipher suite. The default policy for all cipher suites is ``SSL_NOT_ALLOWED``, meaning that
+ the application's export license does not approve the use of this cipher suite. A U.S. "domestic"
+ version of a product typically sets all cipher suites to ``SSL_ALLOWED``. This setting is used to
+ separate export and domestic versions of a product, and is not intended to express user cipher
+ preferences. This setting affects all SSL sockets in the application process that are opened
+ after a call to ``SSL_CipherPolicySet``.
+
+ Under some circumstances, you may be required to abide by the terms of an export license that
+ permits more or fewer capabilities than those allowed by
+ ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or
+ ```NSS_SetFrancePolicy`` <#1105952>`__. In that case, first call
+ ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or
+ ```NSS_SetFrancePolicy`` <#1105952>`__, then call ``SSL_CipherPolicySet`` repeatedly to
+ explicitly allow or disallow cipher suites until only those that you may legally export are
+ permitted.
+
+ In a domestic US product, all the cipher suites are (presently) allowed. In an export client
+ product, some cipher suites are always allowed (such as those with 40-bit keys), some are never
+ allowed (such as triple-DES), and some are allowed (such as RC4_128) for use with approved
+ servers, typically servers owned by banks with special Global ID certificates. (For details, see
+ ```NSS_SetExportPolicy`` <#1100285>`__ and ```NSS_SetFrancePolicy`` <#1105952>`__.) When an SSL
+ connection is established, SSL uses only cipher suites that have previously been explicitly
+ permitted by a call to one of the SSL export policy functions.
+
+ Note that the value ``SSL_RESTRICTED`` (passed in the ``policy`` parameter) is currently used
+ only by SSL clients, which can use it to set policy for connections with servers that have SSL
+ step-up certificates.
+
+ .. rubric:: Important
+ :name: important_4
+
+ If you call ``SSL_CipherPolicySet`` sometime after initialization to change cipher suite policy
+ settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the
+ session cache and will be used instead of the new settings.
+
+ .. rubric:: See Also
+ :name: see_also
+
+ Permitting a cipher suite is not necessarily the same as enabling it. For details, see `SSL
+ Export Policy Functions <#1098841>`__.
+
+ For descriptions of cipher suites supported by SSL, see `Introduction to
+ SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__.
+
+ .. rubric:: SSL_CipherPolicyGet
+ :name: ssl_cipherpolicyget
+
+ Gets the current policy setting for a specified cipher suite.
+
+ ``SSL_CipherPolicyGet`` is the complementary function for ```SSL_CipherPolicySet`` <#1104647>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_16
+
+ .. code::
+
+ #include "ssl.h"
+ #include "proto.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy);
+
+ .. rubric:: Parameters
+ :name: parameters_9
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cipher`` | A value identifying a cipher suite. For a list |
+ | | of possible values, see |
+ | | ```SSL_CipherPolicySet`` <#1104647>`__. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | policy | A pointer to one of the following values: |
+ | | |
+ | | - ``SSL_ALLOWED``. Cipher is always allowed by |
+ | | U.S. government policy. |
+ | | - ``SSL_RESTRICTED``. Cipher is allowed by |
+ | | U.S. government policy for servers with |
+ | | Global ID certificates. |
+ | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed |
+ | | by U.S. government policy. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_16
+
+ See the description above for ```SSL_CipherPolicySet`` <#1104647>`__.
+
+.. _ssl_configuration_functions:
+
+`SSL Configuration Functions <#ssl_configuration_functions>`__
+--------------------------------------------------------------
+
+.. container::
+
+ SSL configuration involves several NSPR functions in addition to the SSL functions listed here.
+ For a complete list of configuration functions, see `Configuration <sslintro.html#1027742>`__.
+
+ | `SSL Configuration <#1090577>`__
+ | `Callback Configuration <#1089578>`__
+
+.. _ssl_configuration:
+
+`SSL Configuration <#ssl_configuration>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ | ```SSL_ImportFD`` <#1085950>`__
+ | ```SSL_OptionSet`` <#1086543>`__
+ | ```SSL_OptionGet`` <#1194921>`__
+ | ```SSL_CipherPrefSet`` <#1214758>`__
+ | ```SSL_CipherPrefGet`` <#1214800>`__
+ | ```SSL_ConfigSecureServer`` <#1217647>`__
+ | ```SSL_SetURL`` <#1087792>`__
+ | ```SSL_SetPKCS11PinArg`` <#1088040>`__
+
+ .. rubric:: SSL_ImportFD
+ :name: ssl_importfd
+
+ Imports an existing NSPR file descriptor into SSL and returns a new SSL socket.
+
+ .. rubric:: Syntax
+ :name: syntax_17
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ PRFileDesc *SSL_ImportFD(
+ PRFileDesc *model,
+ PRFileDesc *fd);
+
+ .. rubric:: Parameters
+ :name: parameters_10
+
+ This function has the following parameters:
+
+ ========= ========================================================
+ ``model`` A pointer to the model file descriptor.
+ ``fd`` A pointer to the file descriptor for the new SSL socket.
+ ========= ========================================================
+
+ .. rubric:: Returns
+ :name: returns_15
+
+ The function returns one of these values:
+
+ - If successful, a pointer to a new socket file descriptor.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_17
+
+ Any SSL function that takes a pointer to a file descriptor (socket) as a parameter will have no
+ effect (even though the SSL function may return ``SECSuccess``) if the socket is not an SSL
+ socket. Sockets do not automatically become secure SSL sockets when they are created by the NSPR
+ functions. You must pass an NSPR socket's file descriptor to ``SSL_ImportFD`` to make it an SSL
+ socket before you call any other SSL function that takes the socket's file descriptor as a
+ parameter
+
+ ``SSL_ImportFD`` imports an existing NSPR file descriptor into SSL and returns a new SSL socket
+ file descriptor. If the ``model`` parameter is not ``NULL``, the configuration of the new file
+ descriptor is copied from the model. If the ``model`` parameter is ``NULL``, then the default SSL
+ configuration is used.
+
+ The new file descriptor returned by ``SSL_ImportFD`` is not necessarily equal to the original
+ NSPR file descriptor. If, after calling ``SSL_ImportFD``, the file descriptors are not equal, you
+ should perform all operations on the new ``PRFileDesc`` structure, never the old one. Even when
+ it's time to close the file descriptor, always close the new ``PRFileDesc`` structure, never the
+ old one.
+
+ .. rubric:: SSL_OptionSet
+ :name: ssl_optionset
+
+ Sets a single configuration parameter of a specified socket. Call once for each parameter you
+ want to change.
+
+ ``SSL_OptionSet`` replaces the deprecated function ```SSL_Enable`` <#1220189>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_18
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_OptionSet(
+ PRFileDesc *fd,
+ PRInt32 option,
+ PRBool on);
+
+ .. rubric:: Parameters
+ :name: parameters_11
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``fd`` | Pointer to the NSPR file descriptor for the SSL |
+ | | socket. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``option`` | One of the following values (default values are |
+ | | determined by the use of |
+ | | ```SSL_OptionSetDefault`` <#1068466>`__): |
+ | | |
+ | | - ``SSL_SECURITY`` enables use of security |
+ | | protocol. WARNING: If you turn this option |
+ | | off, the session will not be an SSL session |
+ | | and will not have certificate-based |
+ | | authentication, tamper detection, or |
+ | | encryption. |
+ | | - ``SSL_REQUEST_CERTIFICATE`` is a server |
+ | | option that requests a client to |
+ | | authenticate itself. |
+ | | - ``SSL_REQUIRE_CERTIFICATE`` is a server |
+ | | option that requires a client to |
+ | | authenticate itself (only if |
+ | | ``SSL_REQUEST_CERTIFICATE`` is also on). If |
+ | | client does not provide certificate, the |
+ | | connection terminates. |
+ | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the |
+ | | behavior of ``PR_Accept``,. If this option |
+ | | is off, the ``PR_Accept`` configures the SSL |
+ | | socket to handshake as a server. If it is |
+ | | on, then ``PR_Accept`` configures the SSL |
+ | | socket to handshake as a client, even though |
+ | | it accepted the connection as a TCP server. |
+ | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the |
+ | | behavior of ``PR_Connect``. If this option |
+ | | is off, then ``PR_Connect`` configures the |
+ | | SSL socket to handshake as a client. If it |
+ | | is on, then ``PR_Connect`` configures the |
+ | | SSL socket to handshake as a server, even |
+ | | though it connected as a TCP client. |
+ | | - ``SSL_ENABLE_FDX`` tells the SSL library |
+ | | whether the application will have two |
+ | | threads, one reading and one writing, or |
+ | | just one thread doing reads and writes |
+ | | alternately. The factory setting for this |
+ | | option (which is the default, unless the |
+ | | application changes the default) is off |
+ | | (``PR_FALSE``), which means that the |
+ | | application will not do simultaneous reads |
+ | | and writes. An application that needs to do |
+ | | simultaneous reads and writes should set |
+ | | this to ``PR_TRUE``. |
+ | | |
+ | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only |
+ | | affects the behavior of nonblocking SSL |
+ | | sockets. See the description below for more |
+ | | information on this option. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | | - ``SSL_ENABLE_SSL3`` enables the application |
+ | | to communicate with SSL v3. If you turn this |
+ | | option off, an attempt to establish a |
+ | | connection with a peer that understands only |
+ | | SSL v3 will fail. |
+ | | - ``SSL_ENABLE_SSL2`` enables the application |
+ | | to communicate with SSL v2. If you turn this |
+ | | option off, an attempt to establish a |
+ | | connection with a peer that understands only |
+ | | SSL v2 will fail. |
+ | | - ``SSL_ENABLE_TLS`` is a peer of the |
+ | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` |
+ | | options. The IETF standard Transport Layer |
+ | | Security (TLS) protocol, RFC 2246, is a |
+ | | modified version of SSL3. It uses the SSL |
+ | | version number 3.1, appearing to be a |
+ | | "minor" revision of SSL3.0. NSS 2.8 supports |
+ | | TLS in addition to SSL2 and SSL3. You can |
+ | | think of it as "``SSL_ENABLE_SSL3.1``." See |
+ | | the description below for more information |
+ | | about this option. |
+ | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL |
+ | | library whether or not to send SSL3 client |
+ | | hello messages in SSL2-compatible format. If |
+ | | set to ``PR_TRUE``, it will; otherwise, it |
+ | | will not. See the description below for more |
+ | | information on this option. |
+ | | - ``SSL_NO_CACHE`` disallows use of the |
+ | | session cache. Factory setting is off. If |
+ | | you turn this option on, this socket will be |
+ | | unable to resume a session begun by another |
+ | | socket. When this socket's session is |
+ | | finished, no other socket will be able to |
+ | | resume the session begun by this socket. |
+ | | - ``SSL_ROLLBACK_DETECTION`` disables |
+ | | detection of a rollback attack. Factory |
+ | | setting is on. You must turn this option off |
+ | | to interoperate with TLS clients ( such as |
+ | | certain versions of Microsoft Internet |
+ | | Explorer) that do not conform to the TLS |
+ | | specification regarding rollback attacks. |
+ | | Important: turning this option off means |
+ | | that your code will not comply with the TLS |
+ | | 3.1 and SSL 3.0 specifications regarding |
+ | | rollback attack and will therefore be |
+ | | vulnerable to this form of attack. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns |
+ | | option off. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_16
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_18
+
+ Keep the following in mind when deciding on the operating parameters you want to use with a
+ particular socket:
+
+ - Turning on ``SSL_REQUIRE_CERTIFICATE`` will have no effect unless ``SSL_REQUEST_CERTIFICATE``
+ is also turned on. If you enable ``SSL_REQUEST_CERTIFICATE``, then you should explicitly
+ enable or disable ``SSL_REQUIRE_CERTIFICATE`` rather than allowing it to default. Enabling the
+ ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no certificate and
+ this option is enabled, the client's connection terminates with an error. The user is likely
+ to think something is wrong with either the client or the server, and is unlikely to realize
+ that the problem is the lack of a certificate. It is better to allow the SSL handshake to
+ complete and then return an error message to the client that informs the user of the need for
+ a certificate.
+
+ Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in
+ SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does
+ not understand SSL2-compatible client hello messages.
+
+ ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello
+ messages in SSL2-compatible format. Note that calling ``SSL_OptionSet`` to set
+ ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the ``SSL_ENABLE_SSL2`` option
+ to ``PR_FALSE`` for that SSL socket. Calling ``SSL_EnableDefault`` to change the application
+ default setting for ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the default
+ value for ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that application.
+
+ - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set
+ to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 and later versions will
+ negotiate the highest protocol version with the peer application from among the set of
+ protocols that are commonly enabled in both applications.
+
+ Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled,
+ all SSL3/TLS cipher suites that are enabled are enabled for both SSL3 and TLS.
+
+ As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a socket
+ into SSL after the TCP connection on that socket has already been established, it must call
+ `SSL_ResetHandshake <#1058001>`__ to indicate whether the socket is for a client or server. At
+ first glance this may seem unnecessary, since ``SSL_OptionSet`` can set
+ ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control the
+ behavior of
+ ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__
+ and
+ ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__
+ only; if you don't call one of those functions after importing a non-SSL socket with
+ ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to know
+ whether the application is functioning as a client or server.
+
+ If a socket file descriptor is imported as an SSL socket before it is connected, it is implicitly
+ configured to handshake as a client or handshake as a server when the connection is made. If the
+ application calls ``PR_Connect`` (connecting as a TCP client), then the SSL socket is (by
+ default) configured to handshake as an SSL client. If the application calls ``PR_Accept``
+ (connecting the socket as a TCP server) then the SSL socket is (by default) configured to
+ handshake as an SSL server. ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` control
+ this implicit configuration.
+
+ Both ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` are initially set to off--that
+ is, the process default for both values is ``PR_FALSE`` when the process begins. The process
+ default can be changed from the initial values by using ``SSL_EnableDefault``, and the value for
+ a particular socket can be changed by using ``SSL_OptionSet``.
+
+ When you import a new SSL socket with ``SSL_ImportFD`` using a model file descriptor, the new SSL
+ socket inherits its values for ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` from
+ the model file descriptor.
+
+ When ``PR_Accept`` accepts a new connection from a listen file descriptor and creates a new file
+ descriptor for the new connection, the listen file descriptor also acts as a model for the new
+ file descriptor, and the new file descriptor inherits its values from the model.
+
+ ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` cannot both be turned on
+ simultaneously. If you use ``SSL_OptionSet`` to turn one of these on when the other one is
+ already turned on for a particular socket, the function returns with the error code set to
+ ``SEC_ERROR_INVALID_ARGS``. Likewise, using ``SSL_EnableDefault`` to turn on the global default
+ for one of these when the global default for the other one is already turned for a particular
+ socket generates the same error. However, there is no good reason for these to be mutually
+ exclusive. This restirction will be removed in future releases.
+
+ If a socket that is already connected gets imported into SSL after it has been connected (that
+ is, after ``PR_Accept`` or ``PR_Connect`` has returned), then no implicit SSL handshake
+ configuration as a client or server will have been done by ``PR_Connect`` or ``PR_Accept`` on
+ that socket. In this case, a call to ``SSL_ResetHandshake`` is required to explicitly configure
+ the socket to handshake as a client or as a server. If ``SSL_ResetHandshake`` is not called to
+ explicitly configure the socket handshake, a crash is likely to occur when the first I/O
+ operation is done on the socket after it is imported into SSL.
+
+ .. rubric:: SSL_OptionGet
+ :name: ssl_optionget
+
+ ``SSL_OptionGet`` gets the value of a specified SSL option on a specified SSL socket.
+
+ .. rubric:: Syntax
+ :name: syntax_19
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_OptionGet(
+ PRFileDesc *fd,
+ PRInt32 option,
+ PRBool *on);
+
+ .. rubric:: Parameters
+ :name: parameters_12
+
+ This function has the following parameters:
+
+ +------------+------------------------------------------------------------------------------------+
+ | ``fd`` | Pointer to the file descriptor for the SSL socket. |
+ +------------+------------------------------------------------------------------------------------+
+ | ``option`` | The value of the option whose default setting you wish to get. For information |
+ | | about the options available and the possible values to pass in this parameter, see |
+ | | the description of the ``option`` parameter under |
+ | | ```SSL_OptionSet`` <#1086543>`__. |
+ +------------+------------------------------------------------------------------------------------+
+ | ``on`` | ``PR_TRUE`` indicates the specified option is on; ``PR_FALSE`` indicates it is |
+ | | off. |
+ +------------+------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_17
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_19
+
+ See the description above for ```SSL_OptionSet`` <#1086543>`__.
+
+ .. rubric:: SSL_CipherPrefSet
+ :name: ssl_cipherprefset
+
+ ``SSL_CipherPrefSet`` specifies the use of a specified cipher suite on a specified SSL socket.
+
+ .. rubric:: Syntax
+ :name: syntax_20
+
+ .. code::
+
+ #include "ssl.h"
+ #include "proto.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPrefSet(
+ PRFileDesc *fd,
+ PRInt32 cipher,
+ PRBool enabled);
+
+ .. rubric:: Parameters
+ :name: parameters_13
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``fd`` | Pointer to the file descriptor for the SSL |
+ | | socket. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cipher`` | One of the following values for SSL2 (all are |
+ | | enabled by default): |
+ | | |
+ | | ``SSL_EN_RC4_128_WITH_ |
+ | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 |
+ | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 |
+ | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W |
+ | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` |
+ | | |
+ | | Or one of the following values for SSL3/TLS |
+ | | (unless indicated otherwise, all are enabled by |
+ | | default): |
+ | | |
+ | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled |
+ | | by default) |
+ | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` |
+ | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_RSA_WITH_RC4_128_MD5`` |
+ | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by |
+ | | default) |
+ | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled |
+ | | by default) |
+ | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not |
+ | | enabled by default; client side only) |
+ | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` |
+ | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled |
+ | | by default; client side only) |
+ | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_WITH_DES_CBC_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` |
+ | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` |
+ | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` |
+ | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` |
+ | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by |
+ | | default) |
+ | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by |
+ | | default) |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``enabled`` | If nonzero, the specified cipher is enabled. If |
+ | | zero, the cipher is disabled. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_20
+
+ ``SSL_CipherPrefSet`` is a new function in NSS 2.6 and later. It allows the application to set
+ the user preferences for cipher suites on an individual socket, overriding the default value for
+ the preference (which can be set with ```SSL_CipherPrefSetDefault`` <#1084747>`__). If an
+ application needs to set the cipher preferences on an individual socket, it should do so before
+ initiating an SSL handshake, not during an SSL handshake.
+
+ For more information on the use of the TLS and FIPS cipher suites, see
+ ```SSL_CipherPrefSetDefault`` <#1084747>`__.
+
+ .. rubric:: SSL_CipherPrefGet
+ :name: ssl_cipherprefget
+
+ Gets the current preference setting for a specified SSL2 or SSL3 cipher suite.
+
+ .. rubric:: Syntax
+ :name: syntax_21
+
+ .. code::
+
+ #include "ssl.h"
+ #include "proto.h"
+
+ .. code::
+
+ SECStatus SSL_CipherPrefGet(
+ PRFileDesc *fd,
+ PRInt32 cipher,
+ PRBool *enabled);
+
+ .. rubric:: Parameters
+ :name: parameters_14
+
+ This function has the parameters listed below.
+
+ +---------+---------------------------------------------------------------------------------------+
+ | ``fd`` | Pointer to the file descriptor for the SSL socket. |
+ +---------+---------------------------------------------------------------------------------------+
+ | cipher | The cipher suite whose default preference setting you want to get. For a list of the |
+ | | cipher suites you can specify, see ```SSL_CipherPrefSet`` <#1214758>`__. |
+ +---------+---------------------------------------------------------------------------------------+
+ | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` |
+ | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is |
+ | | disabled. |
+ +---------+---------------------------------------------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_21
+
+ ``SSL_CipherPrefGet`` performs the complementary function to ``SSL_CipherPrefSet``. It returns
+ the current preference setting for the SSL cipher suite for the socket. If the application has
+ not previously set the cipher preference for this cipher on this socket, the value will be either
+ the process default value or the value inherited from a listen socket or a model socket.
+
+ .. rubric:: SSL_ConfigSecureServer
+ :name: ssl_configsecureserver
+
+ Configures a listen socket with the information needed to handshake as an SSL server.
+ ``SSL_ConfigSecureServer`` requires the certificate for the server and the server's private key.
+ The arguments are copied.
+
+ .. rubric:: Syntax
+ :name: syntax_22
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_ConfigSecureServer(
+ PRFileDesc *fd,
+ CERTCertificate *cert,
+ SECKEYPrivateKey *key,
+ SSLKEAType keaType);
+
+ .. rubric:: Parameters
+ :name: parameters_15
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL |
+ | | listen socket. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cert`` | A pointer to the server's certificate |
+ | | structure. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``key`` | A pointer to the server's private key |
+ | | structure. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``keaType`` | Key exchange type for use with specified |
+ | | certificate and key. These values are currently |
+ | | valid: |
+ | | |
+ | | - ``kt_rsa`` |
+ | | - ``kt_dh`` |
+ | | - ``kt_fortezza`` |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_18
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_22
+
+ Before SSL can handshake as a server on a socket, it must be configured to do so with a call to
+ SSL_ConfigSecureServer (among other things). This function configures a listen socket. Child
+ sockets created by
+ ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__
+ inherit the configuration.
+
+ Servers can be configured with more than one certificate for a given port, and different
+ certificates can support different key-exchange algorithms. To find out what key-exchange
+ algorithm a particular certificate supports, pass the certificate structure to
+ ```NSS_FindCertKEAType`` <sslcrt.html#1056950>`__. You can then pass the ``SSLKEAType`` value
+ returned by ``NSS_FindCertKEAType`` in the ``keaType`` parameter of ``SSL_ConfigSecureServer``.
+ The server uses the specified key-exchange algorithm with the specified certificate and key.
+
+ When the ``keaType`` is ``kt_rsa``, this function generates a step-down key that is supplied as
+ part of the handshake if needed. (A step-down key is needed when the server's public key is
+ stronger than is allowed for export ciphers.) In this case, if the server is expected to continue
+ running for a long time, you should call this function periodically (once a day, for example) to
+ generate a new step-down key.
+
+ SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of
+ certificate and key structures. The application should destroy its copies when it has no further
+ use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and
+ ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__.
+
+ .. rubric:: SSL_SetURL
+ :name: ssl_seturl
+
+ Sets the domain name of the intended server in the client's SSL socket.
+
+ .. rubric:: Syntax
+ :name: syntax_23
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_SetURL(
+ PRFileDesc *fd,
+ char *url);
+
+ .. rubric:: Parameters
+ :name: parameters_16
+
+ This function has the following parameters:
+
+ ======= ==================================================================
+ ``fd`` A pointer to a file descriptor.
+ ``url`` A pointer to a string specifying the desired server's domain name.
+ ======= ==================================================================
+
+ .. rubric:: Returns
+ :name: returns_19
+
+ The function returns one of the following values:
+
+ - If successful, zero.
+ - If unsuccessful, ``-1``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_23
+
+ The client application's certificate authentication callback function needs to compare the domain
+ name in the server's certificate against the domain name of the server the client was attempting
+ to contact. This step is vital because it is the client's\ *only* protection against a
+ man-in-the-middle attack.
+
+ The client application uses ``SSL_SetURL`` to set the domain name of the desired server before
+ performing the first SSL handshake. The client application's certificate authentication callback
+ function gets this string by calling ```SSL_RevealURL`` <#1081175>`__.
+
+ .. rubric:: SSL_SetPKCS11PinArg
+ :name: ssl_setpkcs11pinarg
+
+ Sets the argument passed to the password callback function specified by a call to
+ ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_24
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a);
+
+ .. rubric:: Parameters
+ :name: parameters_17
+
+ This function has the following parameters:
+
+ +--------+----------------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +--------+----------------------------------------------------------------------------------------+
+ | ``a`` | A pointer supplied by the application that can be used to pass state information. This |
+ | | value is passed as the third argument of the application's password function. The |
+ | | meaning is determined solely by the application. |
+ +--------+----------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_20
+
+ The function returns one of the following values:
+
+ - If successful, zero.
+ - If unsuccessful, ``-1``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_24
+
+ During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11
+ token (either a smart card or soft token) to access protected information, such as a private key.
+ Such information is protected with a password that can be retrieved by calling an
+ application-supplied callback function. The callback function is specified in a call to
+ ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ that takes place during NSS initialization.
+
+ Several functions in the NSS libraries use the password callback function to obtain the password
+ before performing operations that involve the protected information. When NSS libraries call the
+ password callback function, the value they pass in as the third parameter is the value of the
+ ``a`` argument to ``PK11_SetPKCS11PinArg``. The third parameter to the password callback function
+ is application-defined and can be used for any purpose. For example, Communicator uses the
+ parameter to pass information about which window is associated with the modal dialog box
+ requesting the password from the user.
+
+ You can obtain the PIN argument by calling ```SSL_RevealPinArg`` <#1123385>`__.
+
+.. _callback_configuration:
+
+`Callback Configuration <#callback_configuration>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ At the beginning of an SSL application, it is often necessary to set up callback functions for
+ the SSL API to use when it needs to call the application. These functions are used to request
+ authentication information from the application or to inform the application when a handshake is
+ completed.
+
+ | ```SSL_AuthCertificateHook`` <#1088805>`__
+ | ```SSL_AuthCertificate`` <#1088888>`__
+ | ```SSL_BadCertHook`` <#1088928>`__
+ | ```SSL_GetClientAuthDataHook`` <#1126622>`__
+ | ```NSS_GetClientAuthData`` <#1106762>`__
+ | ```SSL_HandshakeCallback`` <#1112702>`__
+
+ Setting up the callback functions described in this section may be optional for some
+ applications. However, all applications must use
+ ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ to set up the password callback function during
+ NSS initialization.
+
+ For examples of the callback functions listed here, see `Chapter 2, "Getting Started With
+ SSL." <gtstd.html#1005439>`__
+
+ .. rubric:: SSL_AuthCertificateHook
+ :name: ssl_authcertificatehook
+
+ Specifies a certificate authentication callback function called to authenticate an incoming
+ certificate.
+
+ .. rubric:: Syntax
+ :name: syntax_25
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_AuthCertificateHook(
+ PRFileDesc *fd,
+ SSLAuthCertificate f,
+ void *arg);
+
+ .. rubric:: Parameters
+ :name: parameters_18
+
+ This function has the following parameters:
+
+ +---------+---------------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``f`` | A pointer to the callback function. If ``NULL``, the default callback function, |
+ | | ```SSL_AuthCertificate`` <#1088888>`__, will be used. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can |
+ | | be ``NULL``. |
+ +---------+---------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_21
+
+ The function returns one of the following values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_25
+
+ The callback function set up by ``SSL_AuthCertificateHook`` is called to authenticate an incoming
+ certificate. If the ``checksig`` parameter is set to ``PR_TRUE``, the callback function also
+ verifies the digital signature.
+
+ **NOTE:** If you do not call\ ``SSL_AuthCertificateHook`` to supply a certificate
+ authentication callback function, SSL uses the default callback function,
+ ```SSL_AuthCertificate`` <#1088888>`__.
+
+ The callback function has the following prototype:
+
+ .. code::
+
+ typedef SECStatus (*SSLAuthCertificate) (
+ void *arg,
+ PRFileDesc *fd,
+ PRBool checksig,
+ PRBool isServer);
+
+ This callback function has the following parameters:
+
+ +--------------+----------------------------------------------------------------------------------+
+ | ``arg`` | A pointer supplied by the application (in the call to |
+ | | ``SSL_AuthCertificateHook``) that can be used to pass state information. Can be |
+ | | ``NULL``. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to |
+ | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is |
+ | | normally ``PR_TRUE``.) |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a |
+ | | server does, treating the remote end as a client. ``PR_FALSE`` means the |
+ | | callback function should evaluate the certificate as a client does, treating the |
+ | | remote end as a server. |
+ +--------------+----------------------------------------------------------------------------------+
+
+ The callback function returns one of these values:
+
+ - If authentication is successful, ``SECSuccess``.
+ - If authentication is not successful, ``SECFailure``. If the callback returns ``SECFailure``,
+ the callback should indicate the reason for the failure (if possible) by calling
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ with the appropriate error code.
+
+ The callback function obtains the certificate to be authenticated by calling
+ ```SSL_PeerCertificate`` <#1096168>`__.
+
+ If ``isServer`` is false, the callback should also check that the domain name in the remote
+ server's certificate matches the desired domain name specified in a previous call to
+ ```SSL_SetURL`` <#1087792>`__. To obtain that domain name, the callback calls
+ ```SSL_RevealURL`` <#1081175>`__.
+
+ The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11
+ module. Some of the PK11 functions require a PIN argument (see
+ ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value that was set with
+ ```SSL_SetPKCS11PinArg`` <#1088040>`__, the callback calls ```SSL_RevealPinArg`` <#1123385>`__.
+
+ If the callback returns ``SECFailure``, the SSL connection is terminated immediately unless the
+ application has supplied a bad-certificate callback function by having previously called
+ ```SSL_BadCertHook`` <#1088928>`__. A bad-certificate callback function gives the application the
+ opportunity to choose to accept the certificate as authentic and authorized even though it failed
+ the check performed by the certificate authentication callback function.
+
+ .. rubric:: See Also
+ :name: see_also_2
+
+ For examples of certificate authentication callback functions, see the sample code referenced
+ from `Chapter 2, "Getting Started With SSL." <gtstd.html#1005439>`__
+
+ .. rubric:: SSL_AuthCertificate
+ :name: ssl_authcertificate
+
+ Default callback function used to authenticate certificates received from the remote end of an
+ SSL connection if the application has not previously called
+ ```SSL_AuthCertificateHook`` <#1088805>`__ to specify its own certificate authentication callback
+ function.
+
+ .. rubric:: Syntax
+ :name: syntax_26
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_AuthCertificate(
+ void *arg,
+ PRFileDesc *fd,
+ PRBool checksig,
+ PRBool isServer);
+
+ .. rubric:: Parameters
+ :name: parameters_19
+
+ This function has the following parameters:
+
+ +--------------+----------------------------------------------------------------------------------+
+ | ``arg`` | A pointer to the handle of the certificate database to be used in validating the |
+ | | certificate's signature. (This use of the ``arg`` parameter is required for |
+ | | ``SSL_AuthCertificate``, but not for all implementations of a certificate |
+ | | authentication callback function.) |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to |
+ | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is |
+ | | normally ``PR_TRUE``.) |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a |
+ | | server does, treating the remote end is a client. ``PR_FALSE`` means the |
+ | | callback function should evaluate the certificate as a client does, treating the |
+ | | remote end as a server. |
+ +--------------+----------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_22
+
+ The function returns one of these values:
+
+ - If authentication is successful, ``SECSuccess``.
+ - If authentication is not successful, ``SECFailure``.
+
+ .. rubric:: Description
+ :name: description_26
+
+ SSL calls ``SSL_AuthCertificate`` by default (if no other callback function is provided) to
+ authenticate an incoming certificate. If the ``checksig`` parameter is set to ``PR_TRUE`` (which
+ is normally the case), the function also verifies the digital signature and the certificate
+ chain.
+
+ If the socket is a client socket, ``SSL_AuthCertificate`` tests the domain name in the SSL socket
+ against the domain name in the server certificate's subject DN:
+
+ - If the domain name in the SSL socket doesn't match the domain name in the server certificate's
+ subject DN, the function fails.
+ - If the SSL socket has not had a domain name set (that is, if ```SSL_SetURL`` <#1087792>`__ has
+ not been called) or its domain name is set to an empty string, the function fails.
+
+ SSL_BadCertHook
+
+ Sets up a callback function to deal with a situation where the
+ ```SSL_AuthCertificate`` <#1088888>`__ callback function has failed. This callback function
+ allows the application to override the decision made by the certificate authorization callback
+ and authorize the certificate for use in the SSL connection.
+
+ .. rubric:: Syntax
+ :name: syntax_27
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_BadCertHook(
+ PRFileDesc *fd,
+ SSLBadCertHandler f,
+ void *arg);
+
+ .. rubric:: Parameters
+ :name: parameters_20
+
+ This function has the following parameters:
+
+ +---------+---------------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``f`` | A pointer to the application's callback function. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can |
+ | | be ``NULL``. |
+ +---------+---------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_23
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_27
+
+ The bad-certificate callback function gives the program an opportunity to do something (for
+ example, log the attempt or authorize the certificate) when certificate authentication is not
+ successful. If such a callback function is not provided by the application, the SSL connection
+ simply fails when certificate authentication is not successful.
+
+ The callback function set up by ``SSL_BadCertHook`` has the following prototype:
+
+ .. code::
+
+ typedef SECStatus (*SSLBadCertHandler)(
+ void *arg,
+ PRFileDesc *fd);
+
+ This callback function has the following parameters:
+
+ ======= ===================================================================
+ ``arg`` The ``arg`` parameter passed to ```SSL_BadCertHook`` <#1088928>`__.
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ======= ===================================================================
+
+ The callback function returns one of these values:
+
+ - ``SECSuccess``: The callback has chosen to authorize the certificate for use in this SSL
+ connection, despite the fact that it failed the examination by the certificate authentication
+ callback.
+ - ``SECFailure``: The certificate is not authorized for this SSL connection. The SSL connection
+ will be terminated immediately.
+
+ To obtain the certificate that was rejected by the certificate authentication callback, the
+ bad-certificate callback function calls ```SSL_PeerCertificate`` <#1096168>`__. Since it is
+ called immediately after the certificate authentication callback returns, the bad-certificate
+ callback function can obtain the error code set by the certificate authentication callback by
+ calling
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ immediately, as the first operation it performs. Note: once the bad-certificate callback function
+ returns, the peer certificate is destroyed, and SSL_PeerCertificate will fail.
+
+ The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11
+ module. Some of the PK11 functions require a PIN argument (see
+ ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value previously passed, the
+ callback calls ```SSL_RevealPinArg`` <#1123385>`__
+
+ .. rubric:: See Also
+ :name: see_also_3
+
+ SSL_GetClientAuthDataHook
+
+ Defines a callback function for SSL to use in a client application when a server asks for client
+ authentication information. This callback function is required if your client application is
+ going to support client authentication.
+
+ .. rubric:: Syntax
+ :name: syntax_28
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_GetClientAuthDataHook(
+ PRFileDesc *fd,
+ SSLGetClientAuthData f,
+ void *a);
+
+ .. rubric:: Parameters
+ :name: parameters_21
+
+ This function has the following parameters:
+
+ +---------+---------------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``f`` | A pointer to the application's callback function that delivers the key and |
+ | | certificate. |
+ +---------+---------------------------------------------------------------------------------------+
+ | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can |
+ | | be ``NULL``. |
+ +---------+---------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_24
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_28
+
+ The callback function set with ``SSL_GetClientAuthDataHook`` is used to get information from a
+ client application when authentication is requested by the server. The callback function
+ retrieves the client's private key and certificate.
+
+ SSL provides an implementation of this callback function; see
+ ```NSS_GetClientAuthData`` <#1106762>`__ for details. Unlike
+ ```SSL_AuthCertificate`` <#1088888>`__, ```NSS_GetClientAuthData`` <#1106762>`__ is not a default
+ callback function. You must set it explicitly with ``SSL_GetClientAuthDataHook`` if you want to
+ use it.
+
+ The callback function has the following prototype:
+
+ .. code::
+
+ typedef SECStatus (*SSLGetClientAuthData)(
+ void *arg,
+ PRFileDesc *fd,
+ CertDistNames *caNames,
+ CERTCertificate **pRetCert,
+ SECKEYPrivateKey **pRetKey);
+
+ This callback function has the following parameters:
+
+ ============ =================================================================================
+ ``arg`` The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``.
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ``caNames`` A pointer to distinguished names of CAs that the server accepts.
+ ``pRetCert`` A pointer to a pointer to a certificate structure, for returning the certificate.
+ ``pRetKey`` A pointer to a pointer to a key structure, for returning the private key.
+ ============ =================================================================================
+
+ The callback function returns one of these values:
+
+ - If data returned is valid, ``SECSuccess``.
+ - If the function cannot obtain a certificate, ``SECFailure``.
+
+ .. rubric:: NSS_GetClientAuthData
+ :name: nss_getclientauthdata
+
+ Callback function that a client application can use to get the client's private key and
+ certificate when authentication is requested by a remote server.
+
+ .. rubric:: Syntax
+ :name: syntax_29
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus NSS_GetClientAuthData(
+ void * arg,
+ PRFileDesc *socket,
+ struct CERTDistNamesStr *caNames,
+ struct CERTCertificateStr **pRetCert,
+ struct SECKEYPrivateKeyStr **pRetKey);
+
+ .. rubric:: Parameters
+ :name: parameters_22
+
+ This function has the following parameters:
+
+ +--------------+----------------------------------------------------------------------------------+
+ | ``arg`` | The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``, which should be a |
+ | | pointer to a ``NULL``-terminated string containing the nickname of the |
+ | | certificate and key pair to use. If ``arg`` is ``NULL``, |
+ | | ``NSS_GetClientAuthData`` searches the certificate and key databases for a |
+ | | suitable match and uses the certificate and key pair it finds, if any. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``socket`` | A pointer to the file descriptor for the SSL socket. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``caNames`` | A pointer to distinguished names of CAs that the server accepts. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``pRetCert`` | A pointer to a pointer to a certificate structure, for returning the |
+ | | certificate. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``pRetKey`` | A pointer to a pointer to a key structure, for returning the private key. |
+ +--------------+----------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_25
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_29
+
+ Unlike ```SSL_AuthCertificate`` <#1088888>`__, ``NSS_GetClientAuthData`` is not a default
+ callback function. You must set it explicitly with ```SSL_GetClientAuthDataHook`` <#1126622>`__
+ for each SSL client socket.
+
+ Once ``NSS_GetClientAuthData`` has been set for a client socket, SSL invokes it whenever SSL
+ needs to know what certificate and private key (if any) to use to respond to a request for client
+ authentication.
+
+ .. rubric:: SSL_HandshakeCallback
+ :name: ssl_handshakecallback
+
+ Sets up a callback function used by SSL to inform either a client application or a server
+ application when the handshake is completed.
+
+ .. rubric:: Syntax
+ :name: syntax_30
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_HandshakeCallback(
+ PRFileDesc *fd,
+ SSLHandshakeCallback cb,
+ void *client_data);
+
+ .. rubric:: Parameters
+ :name: parameters_23
+
+ This function has the following parameters:
+
+ +-----------------+-------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +-----------------+-------------------------------------------------------------------------------+
+ | ``cb`` | A pointer to the application's callback function. |
+ +-----------------+-------------------------------------------------------------------------------+
+ | ``client_data`` | A pointer to the value of the ``client_data`` argument that was passed to |
+ | | ``SSL_HandshakeCallback``. |
+ +-----------------+-------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_26
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_30
+
+ The callback function set by ``SSL_HandshakeCallback`` has the following prototype:
+
+ .. code::
+
+ typedef void (*SSLHandshakeCallback)(
+ PRFileDesc *fd,
+ void *client_data);
+
+ This callback function has the following parameters:
+
+ +-----------------+-------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +-----------------+-------------------------------------------------------------------------------+
+ | ``client_data`` | A pointer supplied by the application that can be used to pass state |
+ | | information. Can be ``NULL``. |
+ +-----------------+-------------------------------------------------------------------------------+
+
+ .. rubric:: See Also
+ :name: see_also_4
+
+.. _ssl_communication_functions:
+
+`SSL Communication Functions <#ssl_communication_functions>`__
+--------------------------------------------------------------
+
+.. container::
+
+ Most communication functions are described in the `NSPR
+ Reference <../../../../../nspr/reference/html/index.html>`__. For a complete list of
+ communication functions used by SSL-enabled applications, see
+ `Communication <sslintro.html#1027816>`__.
+
+ | ```SSL_InvalidateSession`` <#1089420>`__
+ | ```SSL_DataPending`` <#1092785>`__
+ | ```SSL_SecurityStatus`` <#1092805>`__
+ | ```SSL_GetSessionID`` <#1092869>`__
+ | ```SSL_SetSockPeerID`` <#1124562>`__
+
+ .. rubric:: SSL_InvalidateSession
+ :name: ssl_invalidatesession
+
+ Removes the current session on a particular SSL socket from the session cache.
+
+ .. rubric:: Syntax
+ :name: syntax_31
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_InvalidateSession(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_4
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_27
+
+ The function returns one of these values:
+
+ - If successful, zero.
+ - If unsuccessful, -1. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_31
+
+ After you call ``SSL_InvalidateSession``, the existing connection using the session can continue,
+ but no new connections can resume this SSL session.
+
+ .. rubric:: SSL_DataPending
+ :name: ssl_datapending
+
+ Returns the number of bytes waiting in internal SSL buffers to be read by the local application
+ from the SSL socket.
+
+ .. rubric:: Syntax
+ :name: syntax_32
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_DataPending(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_5
+
+ This function has the following parameter:
+
+ ====== ==========================================================
+ ``fd`` A pointer to a file descriptor for a connected SSL socket.
+ ====== ==========================================================
+
+ .. rubric:: Returns
+ :name: returns_28
+
+ The function returns an integer:
+
+ - If successful, the function returns the number of bytes waiting in internal SSL buffers for
+ the specified socket.
+ - If ``SSL_SECURITY`` has not been enabled with a call to
+ ```SSL_OptionSetDefault`` <#1068466>`__ or ```SSL_OptionSet`` <#1086543>`__, the function
+ returns zero.
+
+ .. rubric:: Description
+ :name: description_32
+
+ The ``SSL_DataPending`` function determines whether there is any received and decrypted
+ application data remaining in the SSL socket's receive buffers after a prior read operation. This
+ function does not reveal any information about data that has been received but has not yet been
+ decrypted. Hence, if this function returns zero, that does not necessarily mean that a subsequent
+ call to
+ ```PR_Read`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Read>`__
+ would block.
+
+ .. rubric:: SSL_SecurityStatus
+ :name: ssl_securitystatus
+
+ Gets information about the security parameters of the current connection.
+
+ .. rubric:: Syntax
+ :name: syntax_33
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_SecurityStatus(
+ PRFileDesc *fd,
+ int *on,
+ char **cipher,
+ int *keysize,
+ int *secretKeySize,
+ char **issuer,
+ char **subject);
+
+ .. rubric:: Parameters
+ :name: parameters_24
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``fd`` | The file descriptor for the SSL socket. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``on`` | A pointer to an integer. On output, the integer |
+ | | will be one of these values: |
+ | | |
+ | | - ``SSL_SECURITY_STATUS_ OFF (= 0)`` |
+ | | - ``SSL_SECURITY_STATUS_ ON_HIGH (= 1)`` |
+ | | - ``SSL_SECURITY_STATUS_ON_LOW (= 2)`` |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``cipher`` | A pointer to a string pointer. On output, the |
+ | | string pointer references a newly allocated |
+ | | string specifying the name of the cipher. For |
+ | | SSL v2, the string is one of the following: |
+ | | |
+ | | ``RC4`` |
+ | | ``RC4-Export`` |
+ | | |
+ | | ``RC2-CBC`` |
+ | | |
+ | | ``RC2-CBC-Export`` |
+ | | |
+ | | ``DES-CBC`` |
+ | | |
+ | | ``DES-EDE3-CBC`` |
+ | | |
+ | | For SSL v3, the string is one of the following: |
+ | | |
+ | | ``RC4`` |
+ | | ``RC4-40`` |
+ | | |
+ | | ``RC2-CBC`` |
+ | | |
+ | | ``RC2-CBC-40`` |
+ | | |
+ | | ``DES-CBC`` |
+ | | |
+ | | ``3DES-EDE-CBC`` |
+ | | |
+ | | ``DES-CBC-40`` |
+ | | |
+ | | ``FORTEZZA`` |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``keySize`` | A pointer to an integer. On output, the integer |
+ | | is the session key size used, in bits. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``secretKeySize`` | A pointer to an integer. On output, the integer |
+ | | indicates the size, in bits, of the secret |
+ | | portion of the session key used (also known as |
+ | | the "effective key size"). The secret key size |
+ | | is never greater than the session key size. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``issuer`` | A pointer to a string pointer. On output, the |
+ | | string pointer references a newly allocated |
+ | | string specifying the DN of the issuer of the |
+ | | certificate at the other end of the connection, |
+ | | in RFC1485 format. If no certificate is |
+ | | supplied, the string is "``no certificate``." |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``subject`` | A pointer to a string pointer specifying the |
+ | | distinguished name of the certificate at the |
+ | | other end of the connection, in RFC1485 format. |
+ | | If no certificate is supplied, the string is |
+ | | "``no certificate``." |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_29
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_33
+
+ The ``SSL_SecurityStatus`` function fills in values only if you supply pointers to values of the
+ appropriate type. Pointers passed can be ``NULL``, in which case the function does not supply
+ values. When you are finished with them, you should free all the returned values using
+ ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__.
+
+ .. rubric:: SSL_GetSessionID
+ :name: ssl_getsessionid
+
+ Returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL session ID
+ associated with a file descriptor.
+
+ .. rubric:: Syntax
+ :name: syntax_34
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECItem *SSL_GetSessionID(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_6
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_30
+
+ The function returns one of these values:
+
+ If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_34
+
+ This function returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL
+ session ID associated with the file descriptor ``fd``. When the application is finished with the
+ ``SECItem`` structure returned by this function, it should free the structure by calling
+ ``SECITEM_FreeItem(item, PR_TRUE)``.
+
+ .. rubric:: SSL_SetSockPeerID
+ :name: ssl_setsockpeerid
+
+ Associates a peer ID with a socket to facilitate looking up the SSL session when it is tunneling
+ through a proxy.
+
+ .. rubric:: Syntax
+ :name: syntax_35
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_SetSockPeerID(PRFileDesc *fd, char *peerID);
+
+ .. rubric:: Parameters
+ :name: parameters_25
+
+ This function has the following parameters:
+
+ +------------+------------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +------------+------------------------------------------------------------------------------------+
+ | ``peerID`` | An ID number assigned by the application to keep track of the SSL session |
+ | | associated with the peer. |
+ +------------+------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_31
+
+ The function returns one of these values:
+
+ - If successful, zero.
+ - If unsuccessful, -1. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_35
+
+ SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of
+ repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a
+ session cache, which retains information about each connection for some predetermined length of
+ time. For example, a client session cache includes the hostname and port number of each server
+ the client connects with, plus additional information such as the master secret generated during
+ the SSL handshake.
+
+ For a direct connection with a server, the hostname and port number are sufficient for the client
+ to identify the server as one for which it has an entry in its session cache. However, the
+ situation is more complicated if the client is on an intranet and is connecting to a server on
+ the Internet through a proxy. In this case, the client first connects to the proxy, and the
+ client and proxy exchange messages specified by the proxy protocol that allow the proxy, in turn,
+ to connect to the requested server on behalf of the client. This arrangement is known as SSL
+ tunneling.
+
+ Client session cache entries for SSL connections that tunnel through a particular proxy all have
+ the same hostname and port number--that is, the hostname and port number of the proxy. To
+ determine whether a particular server with which the client is attempting to connect has an entry
+ in the session cache, the session cache needs some additional information that identifies that
+ server. This additional identifying information is known as a peer ID. The peer ID is associated
+ with a socket, and must be set before the SSL handshake occurs--that is, before the SSL handshake
+ is initiated by a call to a function such as ``PR_Read`` or
+ ```SSL_ForceHandshake`` <#1133431>`__. To set the peer ID, you use ``SSL_SetSockPeerID``.
+
+ In summary, SSL uses three pieces of information to identify a server's entry in the client
+ session cache: the hostname, port number, and peer ID. In the case of a client that is tunneling
+ through a proxy, the hostname and port number identify the proxy, and the peer ID identifies the
+ desired server. Netscape recommends that the client set the peer ID to a string that consists of
+ the server's hostname and port number, like this: "``www.hostname.com:387``". This convention
+ guarantees that each server has a unique entry in the client session cache.
+
+ .. rubric:: See Also
+ :name: see_also_5
+
+ For information about configuring the session cache for a server, see
+ ```SSL_ConfigServerSessionIDCache`` <#1143851>`__.
+
+.. _ssl_functions_used_by_callbacks:
+
+`SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__
+----------------------------------------------------------------------
+
+.. container::
+
+ | ```SSL_PeerCertificate`` <#1096168>`__
+ | ```SSL_RevealURL`` <#1081175>`__
+ | ```SSL_RevealPinArg`` <#1123385>`__
+
+ .. rubric:: SSL_PeerCertificate
+ :name: ssl_peercertificate
+
+ Returns a pointer to the certificate structure for the certificate received from the remote end
+ of the SSL connection.
+
+ .. rubric:: Syntax
+ :name: syntax_36
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_7
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_32
+
+ The function returns one of these values:
+
+ - If successful, a pointer to a certificate structure.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_36
+
+ The ``SSL_PeerCertificate`` function is used by certificate authentication and bad-certificate
+ callback functions to obtain the certificate under scrutiny. If the client calls
+ ``SSL_PeerCertificate``, it always returns the server's certificate. If the server calls
+ ``SSL_PeerCertificate``, it may return ``NULL`` if client authentication is not enabled or if the
+ client had no certificate when asked.
+
+ SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of
+ certificate and key structures. The application should destroy its copies when it has no further
+ use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and
+ ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__.
+
+ .. rubric:: SSL_RevealURL
+ :name: ssl_revealurl
+
+ Returns a pointer to a newly allocated string containing the domain name of the desired server.
+
+ .. rubric:: Syntax
+ :name: syntax_37
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ char *SSL_RevealURL(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_8
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_33
+
+ The function returns one of the following values:
+
+ - If successful, returns a pointer to a newly allocated string containing the domain name of the
+ desired server.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_37
+
+ The ``SSL_RevealURL`` function is used by certificate authentication callback function to obtain
+ the domain name of the desired SSL server for the purpose of comparing it with the domain name in
+ the certificate presented by the server actually contacted. When the callback function is
+ finished with the string returned, the string should be freed with a call to
+ ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__.
+
+ .. rubric:: SSL_RevealPinArg
+ :name: ssl_revealpinarg
+
+ Returns the ``PKCS11PinArg`` value associated with the socket.
+
+ .. rubric:: Syntax
+ :name: syntax_38
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ void *SSL_RevealPinArg(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_9
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_34
+
+ The function returns one of the following values:
+
+ - If successful, the ``PKCS11PinArg`` value associated with the socket.
+ - If unsuccessful, ``NULL``.
+
+ .. rubric:: Description
+ :name: description_38
+
+ The ``SSL_RevealPinArg`` function is used by callback functions to obtain the PIN argument that
+ NSS passes to certain functions. The PIN argument points to memory allocated by the application.
+ The application is responsible for managing the memory referred to by this pointer. For more
+ information about this argument, see ```SSL_SetPKCS11PinArg`` <#1088040>`__.
+
+.. _ssl_handshake_functions:
+
+`SSL Handshake Functions <#ssl_handshake_functions>`__
+------------------------------------------------------
+
+.. container::
+
+ | ```SSL_ForceHandshake`` <#1133431>`__
+ | ```SSL_ReHandshake`` <#1232052>`__
+ | ```SSL_ResetHandshake`` <#1058001>`__
+
+ .. rubric:: SSL_ForceHandshake
+ :name: ssl_forcehandshake
+
+ Drives a handshake for a specified SSL socket to completion on a socket that has already been
+ prepared to do a handshake or is in the middle of doing a handshake.
+
+ .. rubric:: Syntax
+ :name: syntax_39
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_ForceHandshake(PRFileDesc *fd);
+
+ .. rubric:: Parameters
+ :name: parameters_26
+
+ This function has the following parameter:
+
+ ====== ==================================================
+ ``fd`` Pointer to the file descriptor for the SSL socket.
+ ====== ==================================================
+
+ .. rubric:: Returns
+ :name: returns_35
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_39
+
+ When you are forcing the initial handshake on a blocking socket, this function returns when the
+ handshake is complete. For subsequent handshakes, the function can return either because the
+ handshake is complete, or because application data has been received on the connection that must
+ be processed (that is, the application must read it) before the handshake can continue.
+
+ You can use ``SSL_ForceHandshake`` when a handshake is desired but neither end has anything to
+ say immediately. This occurs, for example, when an HTTPS server has received a request and
+ determines that before it can answer the request, it needs to request an authentication
+ certificate from the client. At the HTTP protocol level, nothing more is being said (that is, no
+ HTTP request or response is being sent), so the server uses ``SSL_ForceHandshake`` to make the
+ handshake occur.
+
+ ``SSL_ForceHandshake`` does not prepare a socket to do a handshake by itself. The following
+ functions prepare a socket (previously imported into SSL and configured as necessary) to do a
+ handshake:
+
+ - ``PR_Connect``
+ - ``PR_Accept``
+ - ```SSL_ReHandshake`` <#1232052>`__ (after the first handshake is finished)
+ - ```SSL_ResetHandshake`` <#1058001>`__ (for sockets that were connected or accepted prior to
+ being imported)
+
+ A call to ``SSL_ForceHandshake`` will almost always be preceded by one of those functions.
+
+ In versions prior to NSS 1.2, you cannot force a subsequent handshake. If you use this function
+ after the initial handshake, it returns immediately without forcing a handshake.
+
+ .. rubric:: SSL_ReHandshake
+ :name: ssl_rehandshake
+
+ Causes SSL to begin a new SSL 3.0 handshake on a connection that has already completed one
+ handshake.
+
+ ``SSL_ReHandshake`` replaces the deprecated function ```SSL_RedoHandshake`` <#1231825>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_40
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_RedoHandshake(PRFileDesc *fd, PRBool flushCache);
+
+ .. rubric:: Parameter
+ :name: parameter_10
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL |
+ | | socket. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``flushCache`` | If ``flushCache`` is non-zero, the SSL3 cache |
+ | | entry will be flushed first, ensuring that a |
+ | | full SSL handshake from scratch will occur. |
+ | | |
+ | | If ``flushCache`` is zero, and an SSL |
+ | | connection is established, it will do the much |
+ | | faster session restart handshake. This will |
+ | | regenerate the symmetric session keys without |
+ | | doing another private key operation. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_36
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error
+ code.
+
+ .. rubric:: Description
+ :name: description_40
+
+ If ``flushCache`` is non-zero, the ``SSL_ReHandshake`` function invalidates the current SSL
+ session associated with the specified ``fd`` from the session cache and starts another full SSL
+ 3.0 handshake. It is for use with SSL 3.0 only. You can call this function to redo the handshake
+ if you have changed one of the socket's configuration parameters (for example, if you are going
+ to request client authentication).
+
+ Setting ``flushCache`` to zero can be useful, for example, if you are using export ciphers and
+ want to keep changing the symmetric keys to foil potential attackers.
+
+ ``SSL_ReHandshake`` only initiates the new handshake by sending the first message of that
+ handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake``
+ or do another I/O operation (read or write) on the socket. A call to ``SSL_ReHandshake`` is
+ typically followed by a call to ``SSL_ForceHandshake``.
+
+ .. rubric:: SSL_ResetHandshake
+ :name: ssl_resethandshake
+
+ Resets the handshake state for a specified socket.
+
+ .. rubric:: Syntax
+ :name: syntax_41
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_ResetHandshake(
+ PRFileDesc *fd,
+ PRBool asServer);
+
+ .. rubric:: Parameters
+ :name: parameters_27
+
+ This function has the following parameters:
+
+ +--------------+----------------------------------------------------------------------------------+
+ | ``fd`` | A pointer to the file descriptor for the SSL socket. |
+ +--------------+----------------------------------------------------------------------------------+
+ | ``asServer`` | A Boolean value. ``PR_TRUE`` means the socket will attempt to handshake as a |
+ | | server the next time it tries, and ``PR_FALSE`` means the socket will attempt to |
+ | | handshake as a client the next time it tries. |
+ +--------------+----------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_37
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_41
+
+ Calling ``SSL_ResetHandshake`` causes the SSL handshake protocol to start from the beginning on
+ the next I/O operation. That is, the handshake starts with no cipher suite already in use, just
+ as it does on the first handshake on a new socket.
+
+ When an application imports a socket into SSL after the TCP connection on that socket has already
+ been established, it must call ``SSL_ResetHandshake`` to determine whether SSL should behave like
+ an SSL client or an SSL server. Note that this step would not be necessary if the socket weren't
+ already connected. For an SSL socket that is configured before it is connected, SSL figures this
+ out when the application calls
+ ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__
+ or
+ ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__.
+ If the socket is already connected before SSL gets involved, you must provide this extra hint.
+
+.. _nss_shutdown_function:
+
+`NSS Shutdown Function <#nss_shutdown_function>`__
+--------------------------------------------------
+
+.. container::
+
+ .. rubric:: NSS_Shutdown
+ :name: nss_shutdown
+
+ Closes the key and certificate databases that were opened by ```NSS_Init`` <#1067601>`__.
+
+ .. rubric:: Syntax
+ :name: syntax_42
+
+ .. code::
+
+ #include "nss.h"
+
+ .. code::
+
+ SECStatus NSS_Shutdown(void);
+
+ .. rubric:: Description
+ :name: description_42
+
+ Note that if any reference to an NSS object is leaked (for example, if an SSL client application
+ doesn't call ```SSL_ClearSessionCache`` <#1138601>`__ first), ``NSS_Shutdown`` fails with the
+ error code ``SEC_ERROR_BUSY``.
+
+.. _deprecated_functions:
+
+`Deprecated Functions <#deprecated_functions>`__
+------------------------------------------------
+
+.. container::
+
+ The following functions have been replaced with newer versions but are still supported:
+
+ | ```SSL_EnableDefault`` <#1206365>`__
+ | ```SSL_Enable`` <#1220189>`__
+ | ```SSL_EnableCipher`` <#1207298>`__
+ | ```SSL_SetPolicy`` <#1207350>`__
+
+ .. rubric:: SSL_EnableDefault
+ :name: ssl_enabledefault
+
+ Changes a default value for all subsequently opened sockets as long as the current application
+ program is running.
+
+ ``SSL_EnableDefault`` has been replaced by ```SSL_OptionSetDefault`` <#1068466>`__ and works the
+ same way.
+
+ .. rubric:: Syntax
+ :name: syntax_43
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_EnableDefault(int which, PRBool on);
+
+ .. rubric:: Parameters
+ :name: parameters_28
+
+ This function has the following parameters:
+
+ +-----------+-------------------------------------------------------------------------------------+
+ | ``which`` | For information about the values that can be passed in the ``which`` parameter, see |
+ | | ```SSL_OptionSetDefault`` <#1068466>`__. |
+ +-----------+-------------------------------------------------------------------------------------+
+ | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. |
+ +-----------+-------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_38
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_43
+
+ For detailed information about using ``SSL_Enable``, see the description of
+ ```SSL_OptionSetDefault`` <#1068466>`__.
+
+ .. rubric:: SSL_Enable
+ :name: ssl_enable
+
+ Sets a single configuration parameter of a specified socket. Call once for each parameter you
+ want to change.
+
+ ``SSL_Enable`` has been replaced by ```SSL_OptionSet`` <#1086543>`__ and works the same way.
+
+ .. rubric:: Syntax
+ :name: syntax_44
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ SECStatus SSL_Enable(
+ PRFileDesc *fd,
+ int which,
+ PRBool on);
+
+ .. rubric:: Parameters
+ :name: parameters_29
+
+ This function has the following parameters:
+
+ +-----------+-------------------------------------------------------------------------------------+
+ | ``fd`` | Pointer to the file descriptor for the SSL socket. |
+ +-----------+-------------------------------------------------------------------------------------+
+ | ``which`` | For information about the values that can be passed in the ``which`` parameter, see |
+ | | the description of the ``option`` parameter under ```SSL_OptionSet`` <#1086543>`__. |
+ +-----------+-------------------------------------------------------------------------------------+
+ | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. |
+ +-----------+-------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_39
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, returns ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_44
+
+ For detailed information about using ``SSL_Enable``, see the description of
+ ```SSL_OptionSet`` <#1086543>`__.
+
+ .. rubric:: SSL_EnableCipher
+ :name: ssl_enablecipher
+
+ Enables or disables cipher suites (subject to which cipher suites are permitted or disallowed by
+ previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__). This function
+ must be called once for each cipher you want to enable or disable.
+
+ ``SSL_EnableCipher`` has been replaced by ```SSL_CipherPrefSetDefault`` <#1084747>`__ and works
+ the same way.
+
+ .. rubric:: Syntax
+ :name: syntax_45
+
+ .. code::
+
+ #include "ssl.h"
+ #include "sslproto.h"
+
+ .. code::
+
+ SECStatus SSL_EnableCipher(long which, PRBool enabled);
+
+ .. rubric:: Parameters
+ :name: parameters_30
+
+ This function has the following parameters:
+
+ +-------------+-----------------------------------------------------------------------------------+
+ | ``which`` | The cipher suite whose default preference setting you want to set. For a list of |
+ | | the cipher suites you can specify, see |
+ | | ```SSL_CipherPrefSetDefault`` <#1084747>`__. |
+ +-------------+-----------------------------------------------------------------------------------+
+ | ``enabled`` | If nonzero, the specified cipher is enabled. If zero, the cipher is disabled. |
+ +-------------+-----------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_40
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_45
+
+ For detailed information about using ``SSL_EnableCipher``, see the description of
+ ```SSL_CipherPrefSetDefault`` <#1084747>`__.
+
+ .. rubric:: SSL_SetPolicy
+ :name: ssl_setpolicy
+
+ Sets policy for the use of individual cipher suites.
+
+ ``SSL_SetPolicy`` has been replaced by ```SSL_CipherPolicySet`` <#1104647>`__ and works the same
+ way.
+
+ .. rubric:: Syntax
+ :name: syntax_46
+
+ .. code::
+
+ #include <ssl.h>
+ #include <sslproto.h>
+
+ .. code::
+
+ SECStatus SSL_SetPolicy(long which, int policy);
+
+ .. rubric:: Parameters
+ :name: parameters_31
+
+ This function has the following parameters:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``which`` | The cipher suite for which you want to set |
+ | | policy. For a list of possible values, see |
+ | | ```SSL_CipherPolicySet`` <#1104647>`__. |
+ +-------------------------------------------------+-------------------------------------------------+
+ | ``policy`` | One of the following values: |
+ | | |
+ | | - ``SSL_ALLOWED``. Cipher is always allowed by |
+ | | U.S. government policy. |
+ | | - ``SSL_RESTRICTED``. Cipher is allowed by |
+ | | U.S. government policy for servers with |
+ | | Global ID certificates. |
+ | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed |
+ | | by U.S. government policy. |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_41
+
+ The function returns one of these values:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_46
+
+ For detailed information about using ``SSL_SetPolicy``, see the description of
+ ```SSL_CipherPolicySet`` <#1104647>`__.
+
+ .. rubric:: SSL_RedoHandshake
+ :name: ssl_redohandshake
+
+ Causes SSL to begin a full, new SSL 3.0 handshake from scratch on a connection that has already
+ completed one handshake.
+
+ .. rubric:: Syntax
+ :name: syntax_47
+
+ .. code::
+
+ #include "ssl.h"
+
+ .. code::
+
+ int SSL_RedoHandshake(PRFileDesc *fd);
+
+ .. rubric:: Parameter
+ :name: parameter_11
+
+ This function has the following parameter:
+
+ ====== ====================================================
+ ``fd`` A pointer to the file descriptor for the SSL socket.
+ ====== ====================================================
+
+ .. rubric:: Returns
+ :name: returns_42
+
+ The function returns one of these values:
+
+ - If successful, zero.
+ - If unsuccessful, -1. Use
+ ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__
+ to obtain the error code.
+
+ .. rubric:: Description
+ :name: description_47
+
+ The ``SSL_RedoHandshake`` function invalidates the current SSL session associated with the ``fd``
+ parameter from the session cache and starts another full SSL 3.0 handshake. It is for use with
+ SSL 3.0 only. You can call this function to redo the handshake if you have changed one of the
+ socket's configuration parameters (for example, if you are going to request client
+ authentication).
+
+ ``SSL_RedoHandshake`` only initiates the new handshake by sending the first message of that
+ handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake``
+ or do another I/O operation (read or write) on the socket. A call to ``SSL_RedoHandshake`` is
+ typically followed by a call to ``SSL_ForceHandshake``. \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst
new file mode 100644
index 0000000000..aeedd90b9c
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst
@@ -0,0 +1,291 @@
+.. _mozilla_projects_nss_ssl_functions_sslintro:
+
+sslintro
+========
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: Overview of an SSL Application
+ :name: Overview_of_an_SSL_Application
+
+ --------------
+
+.. _chapter_1_overview_of_an_ssl_application:
+
+`Chapter 1
+ <#chapter_1_overview_of_an_ssl_application>`__ Overview of an SSL Application
+------------------------------------------------------------------------------
+
+.. container::
+
+ SSL and related APIs allow compliant applications to configure sockets for authenticated,
+ tamper-proof, and encrypted communications. This chapter introduces some of the basic SSL
+ functions. `Chapter 2, "Getting Started With SSL" <gtstd.html#1005439>`__ illustrates their use
+ in sample client and server applications.
+
+ An SSL application typically includes five parts:
+
+ | `Initialization <#1027662>`__
+ | `Configuration <#1027742>`__
+ | `Communication <#1027816>`__
+ | `Functions Used by Callbacks <#1027820>`__
+ | `Cleanup <#1030535>`__
+
+ Although the details differ somewhat for client and server applications, the concepts and many of
+ the functions are the same for both.
+
+ **WARNING:** Some of the SSL header files provided as part of NSS 2.0 include both public APIs
+ documented in the NSS 2.0 documentation set and private APIs intended for internal use by the
+ NSS implementation of SSL. You should use only the SSL APIs (and related certificate, key, and
+ PKCS #11 APIs) that are described in this document, the SSL Reference. Other APIs that may be
+ exposed in the header files are not supported for application use.
+
+.. _initialization_2:
+
+` <#initialization_2>`__ Initialization
+---------------------------------------
+
+.. container::
+
+ Initialization includes setting up configuration files, setting global defaults, and setting up
+ callback functions. Functions used in the initialization part of an application can include the
+ following:
+
+ - ``PR_Init``. Initializes NSPR. Must be called before any other NSS functions.
+ - ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__. Sets the global callback function to
+ obtain passwords for PKCS #11 modules. Required.
+ - ``NSS_Init``. Sets up configuration files and performs other tasks required to run Network
+ Security Services. ``NSS_Init`` is *not* idempotent, so call it only once. Required.
+ - ``SSL_OptionSetDefault``. Changes default values for all subsequently opened sockets as long
+ as the application is running (compare with
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` which only configures the socket that
+ is currently open). This function must be called once for each default value that needs to be
+ changed. Optional.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530`,
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285`,
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952`, or
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647`. These functions tell the library
+ which cipher suites are permitted by policy (for example, to comply with export restrictions).
+ Cipher suites disabled by policy cannot be enabled by user preference. One of these functions
+ must be called before any cryptographic operations can be performed with NSS.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747`. Enables all ciphers chosen by user
+ preference. Optional.
+
+.. _initializing_caches:
+
+`Initializing Caches <#initializing_caches>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+ SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of
+ repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a
+ session cache, which retains information about each connection, such as the master secret
+ generated during the SSL handshake, for a predetermined length of time. If SSL can locate the
+ information about a previous connection in the local session cache, it can reestablish the
+ connection much more quickly than it can without the connection information.
+
+ By default, SSL allocates one session cache. This default cache is called the *client session ID
+ cache*, (also known as the client session cache, or simply the client cache). The client cache is
+ used for all sessions where the program handshakes as an SSL client. It is not configurable. You
+ can initialize the client cache with the function
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`.
+
+ If an application will use SSL sockets that handshake as a server, you must specifically create
+ and configure a server cache, using either
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` or
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. The server cache is used for all
+ sessions where the program handshakes as an SSL server.
+
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`. Clears all sessions from the client
+ session cache. Optional.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`. Sets up parameters for a server
+ session cache for a single-process application. Required for single-process server
+ applications.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. Sets up parameters for a server
+ cache for a multi-process application. Required for multi-process server applications. You can
+ use either this function or :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`, not
+ both.
+
+.. _configuration_2:
+
+` <#configuration_2>`__ Configuration
+-------------------------------------
+
+.. container::
+
+ The configuration portion of an SSL-enabled application typically begins by opening a new socket
+ and then importing the new socket into the SSL environment:
+
+ - ``PR_NewTCPSocket``. Opens a new socket. A legal NSPR socket is required to be passed to
+ ``SSL_ImportFD``, whether it is created with this function or by another method.
+ - ``SSL_ImportFD``. Makes an NSPR socket into an SSL socket. Required. Brings an ordinary NSPR
+ socket into the SSL library, returning a new NSPR socket that can be used to make SSL calls.
+ You can pass this function a *model* file descriptor to create the new SSL socket with the
+ same configuration state as the model.
+
+ It is also possible for an application to import a socket into SSL after the TCP connection on
+ that socket has already been established. In this case, initial configuration takes place in the
+ same way: pass the existing NSPR file descriptor to ``SSL_ImportFD`` and perform any additional
+ configuration that has not already been determined by the model file descriptor.
+
+ Configuration functions control the configuration of an individual socket.
+
+ - ``PR_GetSocketOption``. Retrieves the socket options currently set for a specified socket.
+ Optional.
+ - ``PR_SetSocketOption``. Sets the socket options for a specified socket., including making it
+ blocking or nonblocking. Optional.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543`. Sets a single configuration
+ parameter of a specified socket. This function must be called once for each parameter whose
+ settings you want to change from those established with ``SSL_OptionSetDefault``. Optional.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647`. For servers only. Configures the
+ socket with the information needed to handshake as an SSL server. Required for servers.
+ - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792`. For clients only. Records the
+ target server URL for comparison with the URL specified by the server certificate. Required
+ for clients.
+
+ Callbacks and helper functions allow you to specify such things as how authentication is
+ accomplished and what happens if it fails.
+
+ - ``SSL_SetPKCS11PinArg``. Sets the argument passed to the PKCS #11 password callback function.
+ Required.
+ - ``SSL_AuthCertificateHook``. Specifies a callback function used to authenticate an incoming
+ certificate (optional for servers, necessary for clients to avoid "man-in-the-middle"
+ attacks). Optional. If not specified, SSL uses the default callback function,
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888`.
+ - ``SSL_BadCertHook``. Specifies a callback function to deal with a situation where
+ authentication has failed. Optional.
+ - ``SSL_GetClientAuthDataHook``. Specifies a callback function for SSL to use when the server
+ asks for client authentication information. This callback is required if you want to do client
+ authentication. You can set the callback function to a standard one that is provided,
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762`.
+ - ``SSL_HandshakeCallback``. Specifies a callback function that will be used by SSL to inform
+ either a client application or a server application when the SSL handshake is completed.
+ Optional.
+
+.. _communication_2:
+
+` <#communication_2>`__ Communication
+-------------------------------------
+
+.. container::
+
+ At this point the application has set up the socket to communicate using SSL. For simple
+ encrypted and authenticated communications, no further calls to SSL functions are required. A
+ variety of additional SSL functions are available, however. These can be used, for example, when
+ interrupting and restarting socket communications, when the application needs to change socket
+ parameters, or when an application imports a socket into SSL after the TCP connection on that
+ socket has already been established.
+
+ Communication between SSL sockets always begins with the SSL handshake. The handshake occurs
+ automatically the first time communication is requested with a socket read/write or send/receive
+ call. It is also possible to force the handshake explicitly with
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` or repeat it explicitly with
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052`.
+
+ Once the SSL sockets have been configured, authentication and encryption happen automatically
+ whenever you use the communication functions from the NSPR library.
+
+ A server application typically uses these functions to establish a connection:
+
+ ``PR_Bind PR_Listen PR_Accept PR_GetSockName``
+
+ A client application typically uses these functions to establish a connection:
+
+ | ``PR_GetHostByName``
+ | ``PR_EnumerateHostEnt``
+ | ``PR_Connect``
+ | ``PR_GetConnectStatus``
+
+ When an application imports a socket into SSL after the TCP connection on that socket has already
+ been established, it must call :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` to
+ determine whether SSL should behave like an SSL client or an SSL server. Note that this step
+ would not be necessary if the socket weren't already connected. For an SSL socket that is
+ configured before it is connected, SSL figures this out when the application calls ``PR_Connect``
+ or ``PR_Accept``. If the socket is already connected before SSL gets involved, you must provide
+ this extra hint.
+
+ Functions that can be used by both clients and servers during communication include the
+ following:
+
+ | ``PR_Send`` or ``PR_Write``
+ | ``PR_Read`` or ``PR_Recv``
+ | ``PR_GetError``
+ | ``PR_GetPeerName``
+ | ``PR_Sleep``
+ | ``PR_Malloc``
+ | ``PR_Free``
+ | ``PR_Poll``
+ | ``PR_Now``
+ | ``PR_IntervalToMilliseconds``
+ | ``PR_MillisecondsToInterval``
+ | ``PR_Shutdown``
+ | ``PR_Close``
+ | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420`
+
+ After establishing a connection, an application first calls ``PR_Send``, ``PR_Recv``,
+ ``PR_Read``, ``PR_Write``, or ``SSL_ForceHandshake`` to initiate the handshake. The application's
+ protocol (for example, HTTP) determines which end has responsibility to talk first. The end that
+ has to talk first should call ``PR_Send`` or ``PR_Write``, and the other end should call
+ ``PR_Read`` or ``PR_Recv``.
+
+ Use :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` when the socket has been prepared
+ for a handshake but neither end has anything to say immediately. This occurs, for example, when
+ an HTTPS server has received a request and determines that before it can answer the request, it
+ needs to request an authentication certificate from the client. At the HTTP protocol level,
+ nothing more is being said (that is, no HTTP request or response is being sent), so the server
+ first uses :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` to begin a new handshake and
+ then call ``SSL_ForceHandshake`` to drive the handshake to completion.
+
+.. _functions_used_by_callbacks:
+
+`Functions Used by Callbacks <#functions_used_by_callbacks>`__
+--------------------------------------------------------------
+
+.. container::
+
+ An SSL application typically provides one or more callback functions that are called by the SSL
+ or PKCS #11 library code under certain circumstances. Numerous functions provided by the NSS
+ libraries are useful for such application callback functions, including these:
+
+ | ```CERT_CheckCertValidTimes`` <sslcrt.html#1056662>`__
+ | ```CERT_GetDefaultCertDB`` <sslcrt.html#1052308>`__
+ | ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__
+ | ```CERT_DupCertificate`` <sslcrt.html#1058344>`__
+ | ```CERT_FindCertByName`` <sslcrt.html#1050345>`__
+ | ```CERT_FreeNicknames`` <sslcrt.html#1050349>`__
+ | ```CERT_GetCertNicknames`` <sslcrt.html#1050346>`__
+ | ```CERT_VerifyCertName`` <sslcrt.html#1050342>`__
+ | ```CERT_VerifyCertNow`` <sslcrt.html#1058011>`__
+ | ```PK11_FindCertFromNickname`` <pkfnc.html#1035673>`__
+ | ```PK11_FindKeyByAnyCert`` <pkfnc.html#1026891>`__
+ | ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__
+ | ``PL_strcpy``
+ | ``PL_strdup``
+ | ``PL_strfree``
+ | ``PL_strlen``
+ | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168`
+ | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175`
+ | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`
+
+.. _cleanup_2:
+
+` <#cleanup_2>`__ Cleanup
+-------------------------
+
+.. container::
+
+ This portion of an SSL-enabled application consists primarily of closing the socket and freeing
+ memory. After these tasks have been performed, call
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061858` to close the certificate and key
+ databases opened by :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`, and ``PR_Cleanup``
+ to coordinate a graceful shutdown of NSPR. \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst
new file mode 100644
index 0000000000..eafd40314b
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst
@@ -0,0 +1,107 @@
+.. _mozilla_projects_nss_ssl_functions_sslkey:
+
+sslkey
+======
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to
+ help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: Key Functions
+ :name: Key_Functions
+
+ --------------
+
+.. _chapter_6_key_functions:
+
+`Chapter 6
+ <#chapter_6_key_functions>`__ Key Functions
+--------------------------------------------
+
+.. container::
+
+ This chapter describes two functions used to manipulate private keys and key databases such as
+ the ``key3.db`` database provided with Communicator.
+
+ | ```SECKEY_GetDefaultKeyDB`` <#1051479>`__
+ | ```SECKEY_DestroyPrivateKey`` <#1051017>`__
+
+ .. rubric:: SECKEY_GetDefaultKeyDB
+ :name: seckey_getdefaultkeydb
+
+ Returns a handle to the default key database opened by
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`.
+
+ .. rubric:: Syntax
+ :name: syntax
+
+ .. code::
+
+ #include <key.h>
+ #include <keyt.h>
+
+ .. code::
+
+ SECKEYKeyDBHandle *SECKEY_GetDefaultKeyDB(void);
+
+ .. rubric:: Returns
+ :name: returns
+
+ The function returns a handle of type ``SECKEYKeyDBHandle``.
+
+ .. rubric:: Description
+ :name: description
+
+ :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601` opens the certificate, key, and security
+ module databases that you specify for use with NSS. ``SECKEYKeyDBHandle`` returns a handle to the
+ key database opened by ``NSS_Init``.
+
+ .. rubric:: SECKEY_DestroyPrivateKey
+ :name: seckey_destroyprivatekey
+
+ Destroys a private key structure.
+
+ .. rubric:: Syntax
+ :name: syntax_2
+
+ .. code::
+
+ #include <key.h>
+ #include <keyt.h>
+
+ .. code::
+
+ void SECKEY_DestroyPrivateKey(SECKEYPrivateKey *key);
+
+ .. rubric:: Parameter
+ :name: parameter
+
+ This function has the following parameter:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | A pointer to the private key structure to |
+ | | destroy. |
+ | key | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+ .. rubric:: Description
+ :name: description_2
+
+ Certificate and key structures are shared objects. When an application makes a copy of a
+ particular certificate or key structure that already exists in memory, SSL makes a *shallow*
+ copy--that is, it increments the reference count for that object rather than making a whole new
+ copy. When you call ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ or
+ ```SECKEY_DestroyPrivateKey`` <#1051017>`__, the function decrements the reference count and, if
+ the reference count reaches zero as a result, both frees the memory and sets all the bits to
+ zero. The use of the word "destroy" in function names or in the description of a function implies
+ reference counting.
+
+ Never alter the contents of a certificate or key structure. If you attempt to do so, the change
+ affects all the shallow copies of that structure and can cause severe problems. \ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst b/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst
new file mode 100644
index 0000000000..1ec221042f
--- /dev/null
+++ b/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst
@@ -0,0 +1,343 @@
+.. _mozilla_projects_nss_ssl_functions_ssltyp:
+
+ssltyp
+======
+
+.. container::
+
+ .. note::
+
+ - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
+ we are migrating into the format described in the `MDN Style
+ Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are
+ inclined to help with this migration, your help would be very much appreciated.
+
+ - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference`
+
+ .. rubric:: Selected SSL Types and Structures
+ :name: Selected_SSL_Types_and_Structures
+
+ --------------
+
+.. _chapter_3_selected_ssl_types_and_structures:
+
+`Chapter 3
+ <#chapter_3_selected_ssl_types_and_structures>`__ Selected SSL Types and Structures
+------------------------------------------------------------------------------------
+
+.. container::
+
+ This chapter describes some of the most important types and structures used with the functions
+ described in the rest of this document, and how to manage the memory used for them. Additional
+ types are described with the functions that use them or in the header files.
+
+ | `Types and Structures <#1030559>`__
+ | `Managing SECItem Memory <#1029645>`__
+
+.. _types_and_structures:
+
+`Types and Structures <#types_and_structures>`__
+------------------------------------------------
+
+.. container::
+
+ These types and structures are described here:
+
+ | ```CERTCertDBHandle`` <#1028465>`__
+ | ```CERTCertificate`` <#1027387>`__
+ | ```PK11SlotInfo`` <#1028593>`__
+ | ```SECItem`` <#1026076>`__
+ | ```SECKEYPrivateKey`` <#1026727>`__
+ | ```SECStatus`` <#1026722>`__
+
+ Additional types used by a single function only are described with the function's entry in each
+ chapter. Some of these functions also use types defined by NSPR and described in the `NSPR
+ Reference <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference>`__.
+
+ <a id="> Many of the structures presented here (```CERTCertDBHandle`` <#1028465>`__,
+ ```CERTCertificate`` <#1027387>`__, ```PK11SlotInfo`` <#1028593>`__, and
+ ```SECKEYPrivateKey`` <#1026727>`__) are opaque--that is, they are types defined as structures
+ (for example, ``CERTCertDBHandleStr``) that may change in future releases of Network Security
+ Services. As long as you use the form shown here, your code will not need revision.
+
+ .. rubric:: CERTCertDBHandle
+ :name: certcertdbhandle
+
+ An opaque handle structure for open certificate databases.
+
+ .. rubric:: Syntax
+ :name: syntax
+
+ .. code::
+
+ #include <certt.h>
+
+ .. code::
+
+ typedef struct CERTCertDBHandleStr CERTCertDBHandle;
+
+ .. rubric:: CERTCertificate
+ :name: certcertificate
+
+ An opaque X.509 certificate object.
+
+ .. rubric:: Syntax
+ :name: syntax_2
+
+ .. code::
+
+ #include <certt.h>
+
+ .. code::
+
+ typedef struct CERTCertificateStr CERTCertificate;
+
+ .. rubric:: Description
+ :name: description
+
+ Certificate structures are shared objects. When an application makes a copy of a particular
+ certificate structure that already exists in memory, SSL makes a *shallow* copy--that is, it
+ increments the reference count for that object rather than making a whole new copy. When you call
+ ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__, the function decrements the reference
+ count and, if the reference count reaches zero as a result, frees the memory. The use of the word
+ "destroy" in function names or in the description of a function often implies reference counting.
+
+ Never alter the contents of a certificate structure. If you attempt to do so, the change affects
+ all the shallow copies of that structure and can cause severe problems.
+
+ .. rubric:: PK11SlotInfo
+ :name: pk11slotinfo
+
+ An opaque structure representing a physical or logical PKCS #11 slot.
+
+ .. rubric:: Syntax
+ :name: syntax_3
+
+ .. code::
+
+ #include <pk11expt.h>
+
+ ``typedef struct PK11SlotInfo``\ Str ``PK11SlotInfo``;
+
+ .. rubric:: SECItem
+ :name: secitem
+
+ A structure that points to other structures.
+
+ .. rubric:: Syntax
+ :name: syntax_4
+
+ .. code::
+
+ #include <seccomon.h>
+ #include <prtypes.h>
+ #include <secport.h>
+
+ .. code::
+
+ typedef enum {
+ siBuffer,
+ siClearDataBuffer,
+ siCipherDataBuffer,
+ siDERCertBuffer,
+ siEncodedCertBuffer,
+ siDERNameBuffer,
+ siEncodedNameBuffer,
+ siAsciiNameString,
+ siAsciiString,
+ siDEROID
+ } SECItemType;
+
+ .. code::
+
+ typedef struct SECItemStr SECItem;
+
+ .. code::
+
+ struct SECItemStr {
+ SECItemType type;
+ unsigned char *data;
+ unsigned int len;
+ };
+
+ .. rubric:: Description
+ :name: description_2
+
+ A ``SECItem`` structure can be used to associate your own data with an SSL socket.
+
+ To free a structure pointed to by a ``SECItem``, and, if desired, the ``SECItem`` structure
+ itself, use one the functions ```SECItem_FreeItem`` <#1030620>`__ or
+ ```SECItem_ZfreeItem`` <#1030773>`__.
+
+ .. rubric:: SECKEYPrivateKey
+ :name: seckeyprivatekey
+
+ An opaque, generic key structure.
+
+ .. rubric:: Syntax
+ :name: syntax_5
+
+ .. code::
+
+ #include <keyt.h>
+
+ .. code::
+
+ typedef struct SECKEYPrivateKeyStr SECKEYPrivateKey;
+
+ .. rubric:: Description
+ :name: description_3
+
+ Key structures are not shared objects. When an application makes a copy of a particular key
+ structure that already exists in memory, SSL makes a *deep* copy--that is, it makes a whole new
+ copy of that object. When you call ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__, the
+ function both frees the memory and sets all the bits to zero.
+
+ Never alter the contents of a key structure. Treat the structure as read only.
+
+ .. rubric:: SECStatus
+ :name: secstatus
+
+ The return value for many SSL functions.
+
+ .. rubric:: Syntax
+ :name: syntax_6
+
+ .. code::
+
+ #include <seccomon.h>
+
+ .. code::
+
+ typedef enum {
+ SECWouldBlock = -2,
+ SECFailure = -1,
+ SECSuccess = 0
+ } SECStatus;
+
+ .. rubric:: Enumerators
+ :name: enumerators
+
+ The enum includes the following enumerators:
+
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | Reserved for internal use. |
+ | | |
+ | SECWouldBlock | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The operation failed. To find out why, call |
+ | | ``PR_GetError``. |
+ | SECFailure | |
+ +-------------------------------------------------+-------------------------------------------------+
+ | .. code:: | The operation succeeded. In this case the value |
+ | | returned by ``PR_GetError`` is meaningless. |
+ | SECSuccess | |
+ +-------------------------------------------------+-------------------------------------------------+
+
+.. _managing_secitem_memory:
+
+`Managing SECItem Memory <#managing_secitem_memory>`__
+------------------------------------------------------
+
+.. container::
+
+ These functions are available for managing the memory associated with ``SECItem`` structures and
+ the structures to which they point.
+
+ | ```SECItem_FreeItem`` <#1030620>`__
+ | ```SECItem_ZfreeItem`` <#1030773>`__
+
+ .. rubric:: SECItem_FreeItem
+ :name: secitem_freeitem
+
+ Frees the memory associated with a ``SECItem`` structure.
+
+ .. rubric:: Syntax
+ :name: syntax_7
+
+ .. code::
+
+ #include <prtypes.h>
+
+ .. code::
+
+ SECStatus SECItem_FreeItem (
+ SECItem *item,
+ PRBool freeItem)
+
+ .. rubric:: Parameter
+ :name: parameter
+
+ This function has the following parameter:
+
+ +----------+--------------------------------------------------------------------------------------+
+ | ``item`` | A pointer to a ``SECItem`` structure. |
+ +----------+--------------------------------------------------------------------------------------+
+ | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the |
+ | | structure pointed to and the ``SECItem`` structure itself. |
+ +----------+--------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error
+ code.
+
+ .. rubric:: Description
+ :name: description_4
+
+ This function frees the memory associated with the structure to which the specified item points,
+ when that structure is no longer used. When ``freeItem`` is not ``PR_FALSE``, also frees the item
+ structure itself.
+
+ .. rubric:: SECItem_ZfreeItem
+ :name: secitem_zfreeitem
+
+ Zeroes and frees the memory associated with a ``SECItem`` structure.
+
+ .. rubric:: Syntax
+ :name: syntax_8
+
+ .. code::
+
+ #include <prtypes.h>
+
+ .. code::
+
+ SECStatus SECItem_ZfreeItem (
+ SECItem *item,
+ PRBool freeItem)
+
+ .. rubric:: Parameter
+ :name: parameter_2
+
+ This function has the following parameter:
+
+ +----------+--------------------------------------------------------------------------------------+
+ | ``item`` | A pointer to a ``SECItem`` structure. |
+ +----------+--------------------------------------------------------------------------------------+
+ | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the |
+ | | structure pointed to and the ``SECItem`` structure itself. |
+ +----------+--------------------------------------------------------------------------------------+
+
+ .. rubric:: Returns
+ :name: returns_2
+
+ The function returns one of these value\ ``s``:
+
+ - If successful, ``SECSuccess``.
+ - If unsuccessful, ``SECFailure``. Use
+ `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error
+ code.
+
+ .. rubric:: Description
+ :name: description_5
+
+ This function is similar to ```SECItem_FreeItem`` <#1030620>`__, except that it overwrites the
+ structures to be freed with zeroes before it frees them. Zeros and frees the memory associated
+ with the structure to which the specified item points, when that structure is no longer used.
+ When ``freeItem`` is not ``PR_FALSE``, also zeroes and frees the item structure itself. \ No newline at end of file