- This page is part of the SSL Reference that we are migrating into the format described in the MDN 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 Current NSS Reference
SSL Functions
Chapter 4
SSL Functions
This chapter describes the core SSL functions.
SSL Initialization Functions
SSL Export Policy Functions
SSL Configuration Functions
SSL Communication Functions
SSL Functions Used by Callbacks
SSL Handshake Functions
NSS Shutdown Function
Deprecated Functions
SSL Initialization Functions
This section describes the initialization functions that are specific to SSL. For a complete list of NSS initialization functions, see Initialization.
Note that at least one of the functions listed in SSL Export Policy Functions must also be called during NSS initialization.
NSS_Init
NSS_InitReadWrite
NSS_NoDB_Init
SSL_OptionSetDefault
SSL_OptionGetDefault
SSL_CipherPrefSetDefault
SSL_CipherPrefGetDefault
SSL_ClearSessionCache
SSL_ConfigServerSessionIDCache
SSL_ConfigMPServerSIDCache
SSL_InheritMPServerSIDCache
NSS_Init
Syntax
#include "nss.h"
SECStatus NSS_Init(char *configdir);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to retrieve the error code.
Description
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
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:
-
NSS_SetDomesticPolicy
,NSS_SetExportPolicy
, andNSS_SetFrancePolicy
configure the cipher suites for domestic, international, and French versions of software products with encryption features. -
SSL_CipherPolicySet
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.
NSS_InitReadWrite
Sets up configuration files and performs other tasks required to run Network Security Services. Unlike NSS_Init
, NSS_InitReadWrite
provides both read and write access to database files.
Syntax
#include "nss.h"
SECStatus NSS_InitReadWrite(char *configdir);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to retrieve the error code.
Description
Use NSS_InitReadWrite
rather than NSS_Init
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.
NSS_NoDB_Init
Syntax
#include "nss.h"
SECStatus NSS_NoDB_Init(char *reserved);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to retrieve the error code.
Description
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
isnot 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.
SSL_OptionSetDefault
SSL_OptionSetDefault
replaces the deprecated function SSL_EnableDefault
.
Syntax
#include "ssl.h"
SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
.
- As mentioned in Communication, 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, sinceSSL_Enable
can setSSL_HANDSHAKE_AS_CLIENT
orSSL_HANDSHAKE_AS_SERVER
. However, these settings control the behavior ofPR_Connect
andPR_Accept
only; if you don't call one of those functions after importing a non-SSL socket withSSL_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 ofSSL_HANDSHAKE_AS_CLIENT
andSSL_HANDSHAKE_AS_SERVER
withSSL_EnableDefault
andSSL_Enable
, see SSL_OptionSet. - 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.
SSL_OptionGetDefault
Gets the value of a specified SSL default option.
SSL_OptionGetDefault
is the complementary function for SSL_OptionSetDefault
.
Syntax
#include "ssl.h"
SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on)
Parameters
This function has the parameters listed below.
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain error code.
Description
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). This function must be called once for each cipher you want to enable or disable by default.
Syntax
#include "ssl.h"
SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool enabled);
Parameters
This function has the following parameters:
One of the following values for SSL2 (factory settings for all are enabled): |
|
If nonzero, the specified cipher is enabled. If zero, the cipher is disabled. |
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
.
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
, 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.
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 for details. Your application must call one of the export policy functions before it can perform any cryptographic operations.
SSL_CipherPrefGetDefault
Gets the current default preference setting for a specified SSL2 or SSL3 cipher suite.
Syntax
#include "ssl.h"
SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool *enabled);
Parameters
This function has the parameters listed below.
The cipher suite whose default preference setting you want to get. For a list of the cipher suites you can specify, see |
|
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain error code.
Description
SSL_ClearSessionCache
Empties the SSL client session ID cache.
Syntax
#include "ssl.h"
void SSL_ClearSessionCache(void);
Description
You must call SSL_ClearSessionCache
after you use one of the SSL Export Policy Functions to change cipher suite policy settings or use SSL_CipherPrefSetDefault
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.
- 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 callSSL_ClearSessionCache
before shutdown,NSS_Shutdown
fails with the error codeSEC_ERROR_BUSY
.
SSL_ConfigServerSessionIDCache
Sets up parameters for and opens the server session cache for a single-process application.
Syntax
#include "ssl.h"
SECStatus SSL_ConfigServerSessionIDCache( int maxCacheEntries, PRUint32 timeout, PRUint32 ssl3_timeout, const char *directory);
Parameters
This function has the parameters listed below.
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain error code.
Description
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
instead. You must use one of these functions to create a server cache. This function creates two caches: theserver session ID cache (also called the server session cache, or server cache), and theclient-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.
Initializing Multi-Processing with a Shared SSL Server Cache
To start a multi-processing application, the initial parent process calls SSL_ConfigMPServerSIDCache
, and then creates child processes, by one of these methods:
- Call
fork
and thenexec
(Unix) - Call
CreateProcess
(Win32) - Call
PR_CreateProcess
(both Unix and Win32)
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
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 toCreateProcess
orPR_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
to complete the inheritance of the shared cache FDs/handles.
SSL_ConfigMPServerSIDCache
Sets up parameters for and opens the server session cache for a multi-process application.
Syntax
#include "ssl.h"
SECStatus SSL_ConfigMPServerSIDCache( int maxCacheEntries, PRUint32 timeout, PRUint32 ssl3_timeout, const char *directory);
Parameters
This function has the parameters listed below.
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain error code.
Description
This function is identical to SSL_ConfigServerSessionIDCache
, 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.
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
.
SSL_InheritMPServerSIDCache
Ensures the inheritance of file descriptors to a child process.
Syntax
#include "ssl.h"
SECStatus SSL_InheritMPServerSIDCache (const char *envString);
Parameters
This function has the following parameter:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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.)
- If the
SSL_INHERITANCE
variable has been inherited as part of the child's environment, the child must pass aNULL
pointer as theenvString
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 theenvString
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
The SSL export policy functions determine which cipher suites arepermitted for use in an SSL session. They do not determine which cipher suites are actuallyenabled--that is, turned on and ready to use. To enable or disable a permitted cipher suite, use SSL_CipherPrefSetDefault
; but bear in mind that SSL_CipherPrefSetDefault
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
, NSS_SetExportPolicy
, and NSS_SetFrancePolicy
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) 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
to explicitly enable those cipher suites you may legally export.
For descriptions of cipher suites supported by SSL, see Introduction to SSL.
NSS_SetDomesticPolicy
NSS_SetExportPolicy
NSS_SetFrancePolicy
SSL_CipherPolicySet
The following function is also described in this section:
NSS_SetDomesticPolicy
Syntax
#include "ssl.h"
extern SECStatus NSS_SetDomesticPolicy(void);
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
NSS_SetDomesticPolicy
configures all the cipher suites listed under SSL_CipherPolicySet
for software that isnot 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) for the calling application.
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
, NSS_SetExportPolicy
, or NSS_SetFrancePolicy
, then call SSL_CipherPolicySet
repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
Important
NSS_SetExportPolicy
Syntax
#include "ssl.h"
extern SECStatus NSS_SetExportPolicy(void);
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
NSS_SetExportPolicy
configures all the cipher suites listed under SSL_CipherPolicySet
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). 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
.
-
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
, NSS_SetExportPolicy
, or NSS_SetFrancePolicy
, then call SSL_CipherPolicySet
repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
Important
NSS_SetFrancePolicy
Syntax
#include "ssl.h"
SECStatus NSS_SetFrancePolicy(void);
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
NSS_SetFrancePolicy
configures all the cipher suites listed under SSL_CipherPolicySet
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). Policy for these suites is set to SSL_ALLOWED
. For more details on policy settings, see 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_SetFrancePolicy
. In that case, you should first call NSS_SetDomesticPolicy
, NSS_SetExportPolicy
, or NSS_SetFrancePolicy
, then call SSL_CipherPolicySet
repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
Important
SSL_CipherPolicySet
Sets policy for the use of individual cipher suites.
SSL_CipherPolicySet
replaces the deprecated function SSL_SetPolicy
.
Syntax
#include "ssl.h" #include "proto.h"
SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy);
Parameters
This function has the following parameters:
A value from one of the following lists. Values for SSL2 (all are disallowed by default): |
|
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
, NSS_SetExportPolicy
, or NSS_SetFrancePolicy
. In that case, first call NSS_SetDomesticPolicy
, NSS_SetExportPolicy
, or NSS_SetFrancePolicy
, 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
and NSS_SetFrancePolicy
.) 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.
Important
See Also
Permitting a cipher suite is not necessarily the same as enabling it. For details, see SSL Export Policy Functions.
For descriptions of cipher suites supported by SSL, see Introduction to SSL.
SSL_CipherPolicyGet
Gets the current policy setting for a specified cipher suite.
SSL_CipherPolicyGet
is the complementary function for SSL_CipherPolicySet
.
Syntax
#include "ssl.h" #include "proto.h"
SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy);
Parameters
This function has the following parameters:
A value identifying a cipher suite. For a list of possible values, see |
|
Description
See the description above for SSL_CipherPolicySet
.
SSL Configuration Functions
SSL configuration involves several NSPR functions in addition to the SSL functions listed here. For a complete list of configuration functions, see Configuration.
SSL Configuration
Callback Configuration
SSL Configuration
SSL_ImportFD
SSL_OptionSet
SSL_OptionGet
SSL_CipherPrefSet
SSL_CipherPrefGet
SSL_ConfigSecureServer
SSL_SetURL
SSL_SetPKCS11PinArg
SSL_ImportFD
Imports an existing NSPR file descriptor into SSL and returns a new SSL socket.
Syntax
#include "ssl.h"
PRFileDesc *SSL_ImportFD( PRFileDesc *model, PRFileDesc *fd);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
Description
SSL_OptionSet
SSL_OptionSet
replaces the deprecated function SSL_Enable
.
Syntax
#include "ssl.h"
SECStatus SSL_OptionSet( PRFileDesc *fd, PRInt32 option, PRBool on);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
As mentioned in Communication, 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 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
and 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.
SSL_OptionGet
SSL_OptionGet
gets the value of a specified SSL option on a specified SSL socket.
Syntax
#include "ssl.h"
SECStatus SSL_OptionGet( PRFileDesc *fd, PRInt32 option, PRBool *on);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
See the description above for SSL_OptionSet
.
SSL_CipherPrefSet
SSL_CipherPrefSet
specifies the use of a specified cipher suite on a specified SSL socket.
Syntax
#include "ssl.h" #include "proto.h"
SECStatus SSL_CipherPrefSet( PRFileDesc *fd, PRInt32 cipher, PRBool enabled);
Parameters
This function has the following parameters:
One of the following values for SSL2 (all are enabled by default): |
|
If nonzero, the specified cipher is enabled. If zero, the cipher is disabled. |
Description
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
). 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
.
SSL_CipherPrefGet
Gets the current preference setting for a specified SSL2 or SSL3 cipher suite.
Syntax
#include "ssl.h" #include "proto.h"
SECStatus SSL_CipherPrefGet( PRFileDesc *fd, PRInt32 cipher, PRBool *enabled);
Parameters
This function has the parameters listed below.
The cipher suite whose default preference setting you want to get. For a list of the cipher suites you can specify, see |
|
Description
SSL_ConfigSecureServer
Syntax
#include "ssl.h"
SECStatus SSL_ConfigSecureServer( PRFileDesc *fd, CERTCertificate *cert, SECKEYPrivateKey *key, SSLKEAType keaType);
Parameters
This function has the following parameters:
Key exchange type for use with specified certificate and key. These values are currently valid: |
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
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
. 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.
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
and SECKEY_DestroyPrivateKey
.
SSL_SetURL
Sets the domain name of the intended server in the client's SSL socket.
Syntax
#include "ssl.h"
int SSL_SetURL( PRFileDesc *fd, char *url);
Parameters
This function has the following parameters:
A pointer to a string specifying the desired server's domain name. |
Returns
The function returns one of the following values:
- If successful, zero.
- If unsuccessful,
-1
. UsePR_GetError
to obtain the error code.
Description
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
.
SSL_SetPKCS11PinArg
Sets the argument passed to the password callback function specified by a call to PK11_SetPasswordFunc
.
Syntax
#include "ssl.h"
int SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a);
Parameters
This function has the following parameters:
Returns
The function returns one of the following values:
- If successful, zero.
- If unsuccessful,
-1
. UsePR_GetError
to obtain the error code.
Description
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
that takes place during NSS initialization.
You can obtain the PIN argument by calling SSL_RevealPinArg
.
Callback Configuration
SSL_AuthCertificateHook
SSL_AuthCertificate
SSL_BadCertHook
SSL_GetClientAuthDataHook
NSS_GetClientAuthData
SSL_HandshakeCallback
Setting up the callback functions described in this section may be optional for some applications. However, all applications must use PK11_SetPasswordFunc
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."
SSL_AuthCertificateHook
Syntax
#include "ssl.h"
SECStatus SSL_AuthCertificateHook( PRFileDesc *fd, SSLAuthCertificate f, void *arg);
Parameters
This function has the following parameters:
Returns
The function returns one of the following values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
NOTE: If you do not callSSL_AuthCertificateHook
to supply a certificate authentication callback function, SSL uses the default callback function,SSL_AuthCertificate
.
The callback function has the following prototype:
typedef SECStatus (*SSLAuthCertificate) ( void *arg, PRFileDesc *fd, PRBool checksig, PRBool isServer);
This callback function has the following parameters:
The callback function returns one of these values:
- If authentication is successful,
SECSuccess
. - If authentication is not successful,
SECFailure
. If the callback returnsSECFailure
, the callback should indicate the reason for the failure (if possible) by callingPR_GetError
with the appropriate error code.
The callback function obtains the certificate to be authenticated by calling SSL_PeerCertificate
.
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
. To obtain that domain name, the callback calls SSL_RevealURL
.
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
for details). To obtain the value that was set with SSL_SetPKCS11PinArg
, the callback calls SSL_RevealPinArg
.
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
. 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.
See Also
For examples of certificate authentication callback functions, see the sample code referenced from Chapter 2, "Getting Started With SSL."
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
to specify its own certificate authentication callback function.
Syntax
#include "ssl.h"
SECStatus SSL_AuthCertificate( void *arg, PRFileDesc *fd, PRBool checksig, PRBool isServer);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
Description
- 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
has not been called) or its domain name is set to an empty string, the function fails.
Sets up a callback function to deal with a situation where the SSL_AuthCertificate
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.
Syntax
#include "ssl.h"
SECStatus SSL_BadCertHook( PRFileDesc *fd, SSLBadCertHandler f, void *arg);
Parameters
This function has the following parameters:
A pointer supplied by the application that can be used to pass state information. Can be |
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
The callback function set up by SSL_BadCertHook
has the following prototype:
typedef SECStatus (*SSLBadCertHandler)( void *arg, PRFileDesc *fd);
This callback function has the following parameters:
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
. 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
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
for details). To obtain the value previously passed, the callback calls SSL_RevealPinArg
See Also
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.
Syntax
#include "ssl.h"
SECStatus SSL_GetClientAuthDataHook( PRFileDesc *fd, SSLGetClientAuthData f, void *a);
Parameters
This function has the following parameters:
A pointer to the application's callback function that delivers the key and certificate. |
|
A pointer supplied by the application that can be used to pass state information. Can be |
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
SSL provides an implementation of this callback function; see NSS_GetClientAuthData
for details. Unlike SSL_AuthCertificate
, NSS_GetClientAuthData
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:
typedef SECStatus (*SSLGetClientAuthData)( void *arg, PRFileDesc *fd, CertDistNames *caNames, CERTCertificate **pRetCert, SECKEYPrivateKey **pRetKey);
This callback function has the following parameters:
The callback function returns one of these values:
NSS_GetClientAuthData
Syntax
#include "ssl.h"
SECStatus NSS_GetClientAuthData( void * arg, PRFileDesc *socket, struct CERTDistNamesStr *caNames, struct CERTCertificateStr **pRetCert, struct SECKEYPrivateKeyStr **pRetKey);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
Unlike SSL_AuthCertificate
, NSS_GetClientAuthData
is not a default callback function. You must set it explicitly with SSL_GetClientAuthDataHook
for each SSL client socket.
SSL_HandshakeCallback
Syntax
#include "ssl.h"
SECStatus SSL_HandshakeCallback( PRFileDesc *fd, SSLHandshakeCallback cb, void *client_data);
Parameters
This function has the following parameters:
A pointer to the value of the |
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
The callback function set by SSL_HandshakeCallback
has the following prototype:
typedef void (*SSLHandshakeCallback)( PRFileDesc *fd, void *client_data);
This callback function has the following parameters:
A pointer supplied by the application that can be used to pass state information. Can be |
See Also
SSL Communication Functions
Most communication functions are described in the NSPR Reference. For a complete list of communication functions used by SSL-enabled applications, see Communication.
SSL_InvalidateSession
SSL_DataPending
SSL_SecurityStatus
SSL_GetSessionID
SSL_SetSockPeerID
SSL_InvalidateSession
Removes the current session on a particular SSL socket from the session cache.
Syntax
#include "ssl.h"
int SSL_InvalidateSession(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
- If successful, zero.
- If unsuccessful, -1. Use
PR_GetError
to obtain the error code.
Description
SSL_DataPending
Syntax
#include "ssl.h"
int SSL_DataPending(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
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 toSSL_OptionSetDefault
orSSL_OptionSet
, the function returns zero.
Description
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
would block.
SSL_SecurityStatus
Gets information about the security parameters of the current connection.
Syntax
#include "ssl.h"
SECStatus SSL_SecurityStatus( PRFileDesc *fd, int *on, char **cipher, int *keysize, int *secretKeySize, char **issuer, char **subject);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
.
SSL_GetSessionID
Returns a SECItem
structure containing the SSL session ID associated with a file descriptor.
Syntax
#include "ssl.h"
SECItem *SSL_GetSessionID(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
Description
This function returns a SECItem
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)
.
SSL_SetSockPeerID
Syntax
#include "ssl.h"
int SSL_SetSockPeerID(PRFileDesc *fd, char *peerID);
Parameters
This function has the following parameters:
An ID number assigned by the application to keep track of the SSL session associated with the peer. |
Returns
The function returns one of these values:
- If successful, zero.
- If unsuccessful, -1. Use
PR_GetError
to obtain the error code.
Description
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
. To set the peer ID, you use SSL_SetSockPeerID
.
See Also
For information about configuring the session cache for a server, see SSL_ConfigServerSessionIDCache
.
SSL Functions Used by Callbacks
SSL_PeerCertificate
SSL_RevealURL
SSL_RevealPinArg
SSL_PeerCertificate
Syntax
#include "ssl.h"
CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
Description
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
and SECKEY_DestroyPrivateKey
.
SSL_RevealURL
Returns a pointer to a newly allocated string containing the domain name of the desired server.
Syntax
#include "ssl.h"
char *SSL_RevealURL(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
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
.
Description
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
.
SSL_RevealPinArg
Returns the PKCS11PinArg
value associated with the socket.
Syntax
#include "ssl.h"
void *SSL_RevealPinArg(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
The function returns one of the following values:
Description
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
.
SSL Handshake Functions
SSL_ForceHandshake
SSL_ReHandshake
SSL_ResetHandshake
SSL_ForceHandshake
Syntax
#include "ssl.h"
SECStatus SSL_ForceHandshake(PRFileDesc *fd);
Parameters
This function has the following parameter:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
-
PR_Connect
-
PR_Accept
-
SSL_ReHandshake
(after the first handshake is finished) -
SSL_ResetHandshake
(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.
SSL_ReHandshake
SSL_ReHandshake
replaces the deprecated function SSL_RedoHandshake
.
Syntax
#include "ssl.h"
SECStatus SSL_RedoHandshake(PRFileDesc *fd, PRBool flushCache);
Parameter
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
SSL_ResetHandshake
Resets the handshake state for a specified socket.
Syntax
#include "ssl.h"
SECStatus SSL_ResetHandshake( PRFileDesc *fd, PRBool asServer);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
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
or PR_Accept
. If the socket is already connected before SSL gets involved, you must provide this extra hint.
NSS Shutdown Function
NSS_Shutdown
Closes the key and certificate databases that were opened by NSS_Init
.
Syntax
#include "nss.h"
SECStatus NSS_Shutdown(void);
Description
Note that if any reference to an NSS object is leaked (for example, if an SSL client application doesn't call SSL_ClearSessionCache
first), NSS_Shutdown
fails with the error code SEC_ERROR_BUSY
.
Deprecated Functions
The following functions have been replaced with newer versions but are still supported:
SSL_EnableDefault
SSL_Enable
SSL_EnableCipher
SSL_SetPolicy
SSL_EnableDefault
SSL_EnableDefault
has been replaced by SSL_OptionSetDefault
and works the same way.
Syntax
#include "ssl.h"
SECStatus SSL_EnableDefault(int which, PRBool on);
Parameters
This function has the following parameters:
For information about the values that can be passed in the |
|
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
For detailed information about using SSL_Enable
, see the description of SSL_OptionSetDefault
.
SSL_Enable
SSL_Enable
has been replaced by SSL_OptionSet
and works the same way.
Syntax
#include "ssl.h"
SECStatus SSL_Enable( PRFileDesc *fd, int which, PRBool on);
Parameters
This function has the following parameters:
For information about the values that can be passed in the |
|
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful, returns
SECFailure
. UsePR_GetError
to obtain the error code.
Description
For detailed information about using SSL_Enable
, see the description of SSL_OptionSet
.
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). This function must be called once for each cipher you want to enable or disable.
SSL_EnableCipher
has been replaced by SSL_CipherPrefSetDefault
and works the same way.
Syntax
#include "ssl.h" #include "sslproto.h"
SECStatus SSL_EnableCipher(long which, PRBool enabled);
Parameters
This function has the following parameters:
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
For detailed information about using SSL_EnableCipher
, see the description of SSL_CipherPrefSetDefault
.
SSL_SetPolicy
Sets policy for the use of individual cipher suites.
SSL_SetPolicy
has been replaced by SSL_CipherPolicySet
and works the same way.
Syntax
#include <ssl.h> #include <sslproto.h>
SECStatus SSL_SetPolicy(long which, int policy);
Parameters
This function has the following parameters:
The cipher suite for which you want to set policy. For a list of possible values, see |
|
Returns
The function returns one of these values:
- If successful,
SECSuccess
. - If unsuccessful,
SECFailure
. UsePR_GetError
to obtain the error code.
Description
For detailed information about using SSL_SetPolicy
, see the description of SSL_CipherPolicySet
.
SSL_RedoHandshake
Syntax
#include "ssl.h"
int SSL_RedoHandshake(PRFileDesc *fd);
Parameter
This function has the following parameter:
Returns
The function returns one of these values:
- If successful, zero.
- If unsuccessful, -1. Use
PR_GetError
to obtain the error code.
Description