|
|
SSL Functions
Table of Contents | Previous
| Next
| Index
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
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
SSL_EnableDefault
SSL_EnableCipher
SSL_ClearSessionCache
SSL_ConfigServerSessionIDCache
SSL_ConfigMPServerSIDCache
SSL_InheritMPServerSIDCache
Sets up configuration files and performs other tasks required to run Network Security Services.
#include <nss.h> SECStatus NSS_Init(char *configdir);
This function has the following parameter:
The function returns one of these values:
NSS_Init opens the CertN.db, KeyN.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.
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, and NSS_SetFrancePolicy configure the cipher suites for domestic, international, and French versions of software products with encryption features.
-
SSL_SetPolicy 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.
Changes a default value for all subsequently opened sockets as long as the current application program is running.
#include <ssl.h>
#include <seccomon.h> SECStatus SSL_EnableDefault(int which, PRBool on);
This function has the following parameters:
which |
One of the following values (except as noted, the default is "off"): -
SSL_SECURITY enables use of security protocol. On by default. 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. Off by default. -
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 forces handshake as a client, with or without authentication. On by default. -
SSL_HANDSHAKE_AS_SERVER forces handshake as a server, with or without authentication. Off by default. -
SSL_ENABLE_SSL3 enables the application to communicate with SSL v3. On by default. 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. On by default. If you turn this option off, an attempt to establish a connection with a peer that only understands SSL v2 will fail. -
SSL_NO_CACHE disallows use of the session cache. Off by default. 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.
|
on |
PR_TRUE turns option on; PR_FALSE turns option off.
|
The function returns one of these values:
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. To change a value in a socket that is already open, use SSL_Enable.
Keep the following in mind when deciding on the operating parameters you want to use with a particular socket:
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.
#include <ssl.h>
#include <sslproto.h>
#include <seccomon.h> SECStatus SSL_EnableCipher(long which, PRBool enabled);
This function has the following parameters:
The function returns one of these values:
The SSL_EnableCipher function enables or disables individual cipher suites globally. You typically call this in response to changes in user-controlled settings. You cannot enable or disable cipher suites for an individual socket. You must call this function once for each cipher you want to enable or disable.
By default, all cipher suites except SSL_RSA_WITH_NULL_MD5 and SSL_FORTEZZA_DMS_WITH_NULL_SHA are enabled. However, this does not necessarily mean that they are all permitted. The SSL_EnableCipher 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.
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.
Empties the SSL client session ID cache.
#include <ssl.h> void SSL_ClearSessionCache(void);
You must call SSL_ClearSessionCache after you use one of the SSL Export Policy Functions to change cipher suite policy settings or use SSL_EnableCipher 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:
Sets up parameters for and opens the server session cache for a single-process application.
#include <ssl.h>
#include <prtypes.h>
#include <seccomon.h> SECStatus SSL_ConfigServerSessionIDCache(
int maxCacheEntries,
PRUint32 timeout,
PRUint32 ssl3_timeout,
const char *directory);
This function has the parameters listed below.
The function returns one of these values:
If you are writing an application that will use SSL sockets that handshake as a
server, you must call SSL_ConfigServerSessionIDCach 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: 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.
To start a multi-processing application, the initial parent process calls SSL_ConfigMPServerSIDCache, and then creates child processes, by one of these methods:
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 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:
In either case, the child must call SSL_InheritMPServerSIDCache to complete the inheritance of the shared cache FDs/handles.
Sets up parameters for and opens the server session cache for a multi-process application.
#include <ssl.h>
#include <prtypes.h>
#include <seccomon.h> SECStatus SSL_ConfigMPServerSIDCache(
int maxCacheEntries,
PRUint32 timeout,
PRUint32 ssl3_timeout,
const char *directory);
This function has the parameters listed below.
The function returns one of these values:
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.
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.
Ensures the inheritance of file descriptors to a child process.
SECStatus SSL_InheritMPServerSIDCache (const char *envString);
This function has the following parameter:
The function returns one of these values:
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.)
When this function returns SECSuccess, the server cache is ready to be used by the SSL code.
Important
This section has not yet been updated to reflect the new export regulations.
Therefore, the information in this section is out of date. It will be updated when
the source code for NSS is posted to Mozilla.
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_EnableCipher; but bear in mind that SSL_EnableCipher 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) and French import regulations governing such products.
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_SetPolicy to explicitly enable those cipher suites you may legally export.
Applications must call one of the export policy functions before attempting to perform any cryptographic operations.
For descriptions of cipher suites supported by SSL, see Introduction to SSL.
Configures cipher suites to conform with current U.S. export regulations related to domestic software products with encryption features.
#include <nss.h> extern SECStatus NSS_SetDomesticPolicy(void);
The function returns one of these values:
NSS_SetDomesticPolicy configures all the cipher suites listed under SSL_SetPolicy 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) 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, NSS_SetExportPolicy, or NSS_SetFrancePolicy, then call SSL_SetPolicy repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
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.
Configures the SSL cipher suites to conform with current U.S. export regulations related to international software products with encryption features.
#include <nss.h> extern SECStatus NSS_SetExportPolicy(void);
The function returns one of these values:
NSS_SetExportPolicy configures all the cipher suites listed under SSL_SetPolicy 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_SetPolicy.
For SSL 2.0:
For SSL 3.0:
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_SetPolicy repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
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.
Configures the SSL cipher suites to conform with French import regulations related to software products with encryption features.
extern SECStatus NSS_SetFrancePolicy(void);
The function returns one of these values:
NSS_SetFrancePolicy configures all the cipher suites listed under SSL_SetPolicy 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_SetPolicy.
For SSL 2.0:
For SSL 3.0:
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_SetPolicy repeatedly to explicitly allow or disallow cipher suites until only those that you may legally export are permitted.
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.
Sets policy for the use of individual cipher suites.
#include <ssl.h>
#include <sslproto.h>
#include <seccomon.h> SECStatus SSL_SetPolicy(long which, int policy);
This function has the following parameters:
The function returns one of these values:
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_SetPolicy 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.
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 Global ID certificates.
If you call SSL_SetPolicy 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.
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 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_ImportFD
SSL_Enable
SSL_ConfigSecureServer
SSL_SetURL
SSL_SetPKCS11PinArg
Imports an existing NSPR file descriptor into SSL and returns a new SSL socket.
#include <ssl.h>
#include <prio.h> PRFileDesc *SSL_ImportFD(
PRFileDesc *model,
PRFileDesc *fd);
This function has the following parameters:
The function returns one of these values:
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.
Sets a single configuration parameter of a specified socket. Call once for each parameter you want to change.
#include <ssl.h>
#include <prio.h>
#include <prtypes.h>
#include <seccomon.h> SECStatus SSL_Enable(
PRFileDesc *fd,
int which,
PRBool on);
This function has the following parameters:
fd |
Pointer to the file descriptor for the SSL socket.
|
which |
One of the following values (default values are determined by the use of SSL_EnableDefault):
-
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 forces handshake as a client, with or without authentication. -
SSL_HANDSHAKE_AS_SERVER forces handshake as a server, with or without authentication. -
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_NO_CACHE disallows use of the session cache for this socket. 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.
|
on |
PR_TRUE turns option on; PR_FALSE turns option off.
|
The function returns one of these values:
Keep the following in mind when deciding on the configuration parameters you want to use with a particular socket:
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.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h>
#include <certt.h>
#include <keyt.h> SECStatus SSL_ConfigSecureServer(
PRFileDesc *fd,
CERTCertificate *cert,
SECKEYPrivateKey *key,
SSLKEAType keaType);
This function has the following parameters:
The function returns one of these values:
Your program always handshakes as a client unless you call SSL_ConfigSecureServer, or turn on the SSL_HANDSHAKE_AS_SERVER option with SSL_Enable or SSL_EnableDefault. Once you have used this function to configure the listen socket, child sockets created by calls to 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.
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 and SECKEY_DestroyPrivateKey.
Sets the domain name of the intended server in the client's SSL socket.
#include <ssl.h> int SSL_SetURL(
PRFileDesc *fd,
char *url);
This function has the following parameters:
The function returns one of the following values:
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.
Sets the argument passed to the password callback function specified by a call to PK11_SetPasswordFunc.
#include <ssl.h> int SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a);
This function has the following parameters:
The function returns one of the following values:
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.
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.
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
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."
Specifies a certificate authentication callback function called to authenticate an incoming certificate.
#include <ssl.h>
#include <prio.h>
#include <prtypes.h>
#include <seccomon.h> SECStatus SSL_AuthCertificateHook(
PRFileDesc *fd,
SSLAuthCertificate f,
void *arg);
This function has the following parameters:
The function returns one of the following values:
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.
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:
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.
For examples of certificate authentication callback functions, see the sample code referenced from Chapter 2, "Getting Started With SSL."
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.
#include <ssl.h>
#include <prio.h>
#include <prtypes.h>
#include <seccomon.h> SECStatus SSL_AuthCertificate(
void *arg,
PRFileDesc *fd,
PRBool checksig,
PRBool isServer);
This function has the following parameters:
The function returns one of these values:
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:
The implementation of the certificate authentication callback function shown in the client.c sample in the Samples directory is functionally identical to the implementation of SSL_AuthCertificate.
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.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> SECStatus SSL_BadCertHook(
PRFileDesc *fd,
SSLBadCertHandler f,
void *arg);
This function has the following parameters:
The function returns one of these values:
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:
typedef SECStatus (*SSLBadCertHandler)(
void *arg,
PRFileDesc *fd);
This callback function has the following parameters:
The callback function returns one of these values:
To obtain the certificate that was rejected by the certificate authentication callback, the 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.
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
For examples of bad certificate callback functions, see the client.c and server.c samples in the Samples directory.
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.
#include <ssl.h>
#include <prio.h>
#include <certt.h>
#include <keyt.h>
#include <seccomon.h> SECStatus SSL_GetClientAuthDataHook(
PRFileDesc *fd,
SSLGetClientAuthData f,
void *a);
This function has the following parameters:
The function returns one of these values:
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 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:
For an example of a client authentication data callback function, see the client.c sample in the Samples directory.
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.
#include <nss.h> SECStatus NSS_GetClientAuthData(
void * arg,
PRFileDesc *socket,
struct CERTDistNamesStr *caNames,
struct CERTCertificateStr **pRetCert,
struct SECKEYPrivateKeyStr **pRetKey);
This function has the following parameters:
The function returns one of these values:
Unlike SSL_AuthCertificate, NSS_GetClientAuthData is not a default callback function. You must set it explicitly with SSL_GetClientAuthDataHook 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.
The implementation of the certificate authentication data callback function shown in the client.c sample in the Samples directory is functionally identical to the implementation of NSS_GetClientAuthData. This implementation is provided as a convenience; applications can supply their own implementations.
Sets up a callback function used by SSL to inform either a client application or a server application when the handshake is completed.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> SECStatus SSL_HandshakeCallback(
PRFileDesc *fd,
SSLHandshakeCallback cb,
void *client_data);
This function has the following parameters:
The function returns one of these values:
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:
For examples of handshake callback functions, see the samples in the Samples directory.
Most communication functions are described in the Communication.
SSL_InvalidateSession
SSL_DataPending
SSL_SecurityStatus
SSL_GetSessionID
SSL_SetSockPeerID
Removes the current session on a particular SSL socket from the session cache.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> int SSL_InvalidateSession(PRFileDesc *fd);
This function has the following parameter:
The function returns one of these values:
After you call SSL_InvalidateSession, the existing connection using the session can continue, but it cannot be interrupted and then resume again without redoing the handshake.
Returns the number of bytes waiting in internal SSL buffers to be read by the local application from the SSL socket.
#include <ssl.h> int SSL_DataPending(PRFileDesc *fd);
This function has the following parameter:
The function returns an integer:
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.
Gets information about the security parameters of the current connection.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> SECStatus SSL_SecurityStatus(
PRFileDesc *fd,
int *on,
char **cipher,
int *keysize,
int *secretKeySize,
char **issuer,
char **subject);
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:
|
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."
|
The function returns one of these values:
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.
Returns a SECItem structure containing the SSL session ID associated with a file descriptor.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> SECItem *SSL_GetSessionID(PRFileDesc *fd);
This function has the following parameter:
The function returns one of these values:
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).
Associates a peer ID with a socket to facilitate looking up the SSL session when it is tunneling through a proxy.
int SSL_SetSockPeerID(PRFileDesc *fd, char *peerID);
This function has the following parameters:
The function returns one of these values:
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. 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.
For information about configuring the session cache for a server, see SSL_ConfigServerSessionIDCache.
SSL_PeerCertificate
SSL_RevealURL
SSL_RevealPinArg
Returns a pointer to the certificate structure for the certificate received from the remote end of the SSL connection.
CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd);
This function has the following parameter:
The function returns one of these values:
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 and SECKEY_DestroyPrivateKey.
Returns a pointer to a newly allocated string containing the domain name of the desired server.
char *SSL_RevealURL(PRFileDesc *fd);
This function has the following parameter:
The function returns one of the following values:
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.
Returns the PKCS11PinArg value associated with the socket.
void *SSL_RevealPinArg(PRFileDesc *fd);
This function has the following parameter:
The function returns one of the following values:
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_ForceHandshake
SSL_RedoHandshake
SSL_ResetHandshake
Forces the handshake for a specified SSL socket to complete before any other action can take place.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> int SSL_ForceHandshake(PRFileDesc *fd);
This function has the following parameter:
The function returns one of these values:
When you are forcing the initial handshake, 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. If the socket is a blocking socket, the function does not return until the SSL handshake is complete.
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.
Causes SSL to perform a full, new SSL 3.0 handshake from scratch.
#include <ssl.h>
#include <prio.h>
#include <seccomon.h> int SSL_RedoHandshake(PRFileDesc *fd);
This function has the following parameter:
The function returns one of these values:
The SSL_RedoHandshake function removes the current SSL session 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).
Resets the handshake state for a specified socket.
#include <ssl.h> SECStatus SSL_ResetHandshake(
PRFileDesc *fd,
PRBool asServer);
This function has the following parameters:
The function returns one of these values:
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.
Closes the key and certificate databases that were opened by NSS_Init.
#include <nss.h> void NSS_Shutdown(void);
Table of Contents | Previous
| Next
| Index
Last Updated: 01/17/00 16:36:30
|
