diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
| commit | 36d22d82aa202bb199967e9512281e9a53db42c9 (patch) | |
| tree | 105e8c98ddea1c1e4784a60a5a6410fa416be2de /security/nss/doc/rst/legacy/ssl_functions | |
| parent | Initial commit. (diff) | |
| download | firefox-esr-upstream.tar.xz firefox-esr-upstream.zip | |
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
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 |