Back to index

lightning-sunbird  0.9+nobinonly
nss.h
Go to the documentation of this file.
00001 /*
00002  * NSS utility functions
00003  *
00004  * ***** BEGIN LICENSE BLOCK *****
00005  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00006  *
00007  * The contents of this file are subject to the Mozilla Public License Version
00008  * 1.1 (the "License"); you may not use this file except in compliance with
00009  * the License. You may obtain a copy of the License at
00010  * http://www.mozilla.org/MPL/
00011  *
00012  * Software distributed under the License is distributed on an "AS IS" basis,
00013  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00014  * for the specific language governing rights and limitations under the
00015  * License.
00016  *
00017  * The Original Code is the Netscape security libraries.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either the GNU General Public License Version 2 or later (the "GPL"), or
00028  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039 /* $Id: nss.h,v 1.46.2.10 2006/11/15 23:40:26 christophe.ravel.bugs%sun.com Exp $ */
00040 
00041 #ifndef __nss_h_
00042 #define __nss_h_
00043 
00044 #include "seccomon.h"
00045 
00046 SEC_BEGIN_PROTOS
00047 
00048 /*
00049  * NSS's major version, minor version, patch level, and whether
00050  * this is a beta release.
00051  *
00052  * The format of the version string should be
00053  *     "<major version>.<minor version>[.<patch level>] [<Beta>]"
00054  */
00055 #ifdef NSS_ENABLE_ECC
00056 #ifdef NSS_ECC_MORE_THAN_SUITE_B
00057 #define NSS_VERSION  "3.11.4 Extended ECC"
00058 #else
00059 #define NSS_VERSION  "3.11.4 Basic ECC"
00060 #endif
00061 #else
00062 #define NSS_VERSION  "3.11.4"
00063 #endif
00064 #define NSS_VMAJOR   3
00065 #define NSS_VMINOR   11
00066 #define NSS_VPATCH   4
00067 #define NSS_BETA     PR_FALSE
00068 
00069 /*
00070  * Return a boolean that indicates whether the underlying library
00071  * will perform as the caller expects.
00072  *
00073  * The only argument is a string, which should be the verson
00074  * identifier of the NSS library. That string will be compared
00075  * against a string that represents the actual build version of
00076  * the NSS library.  It also invokes the version checking functions
00077  * of the dependent libraries such as NSPR.
00078  */
00079 extern PRBool NSS_VersionCheck(const char *importedVersion);
00080 
00081 /*
00082  * Open the Cert, Key, and Security Module databases, read only.
00083  * Initialize the Random Number Generator.
00084  * Does not initialize the cipher policies or enables.
00085  * Default policy settings disallow all ciphers.
00086  */
00087 extern SECStatus NSS_Init(const char *configdir);
00088 
00089 /*
00090  * Returns whether NSS has already been initialized or not.
00091  */
00092 extern PRBool NSS_IsInitialized(void);
00093 
00094 /*
00095  * Open the Cert, Key, and Security Module databases, read/write.
00096  * Initialize the Random Number Generator.
00097  * Does not initialize the cipher policies or enables.
00098  * Default policy settings disallow all ciphers.
00099  */
00100 extern SECStatus NSS_InitReadWrite(const char *configdir);
00101 
00102 /*
00103  * Open the Cert, Key, and Security Module databases, read/write.
00104  * Initialize the Random Number Generator.
00105  * Does not initialize the cipher policies or enables.
00106  * Default policy settings disallow all ciphers.
00107  *
00108  * This allows using application defined prefixes for the cert and key db's
00109  * and an alternate name for the secmod database. NOTE: In future releases,
00110  * the database prefixes my not necessarily map to database names.
00111  *
00112  * configdir - base directory where all the cert, key, and module datbases live.
00113  * certPrefix - prefix added to the beginning of the cert database example: "
00114  *                   "https-server1-"
00115  * keyPrefix - prefix added to the beginning of the key database example: "
00116  *                   "https-server1-"
00117  * secmodName - name of the security module database (usually "secmod.db").
00118  * flags - change the open options of NSS_Initialize as follows:
00119  *     NSS_INIT_READONLY - Open the databases read only.
00120  *     NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just 
00121  *                   initialize the volatile certdb.
00122  *     NSS_INIT_NOMODDB  - Don't open the security module DB, just 
00123  *                   initialize the       PKCS #11 module.
00124  *      NSS_INIT_FORCEOPEN - Continue to force initializations even if the 
00125  *                   databases cannot be opened.
00126  *      NSS_INIT_NOROOTINIT - Don't try to look for the root certs module
00127  *                   automatically.
00128  *      NSS_INIT_OPTIMIZESPACE - Use smaller tables and caches.
00129  *      NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are
00130  *                      thread-safe, ie. that support locking - either OS
00131  *                      locking or NSS-provided locks . If a PKCS#11
00132  *                      module isn't thread-safe, don't serialize its
00133  *                      calls; just don't load it instead. This is necessary
00134  *                      if another piece of code is using the same PKCS#11
00135  *                      modules that NSS is accessing without going through
00136  *                      NSS, for example the Java SunPKCS11 provider.
00137  *      NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED
00138  *                      error when loading PKCS#11 modules. This is necessary
00139  *                      if another piece of code is using the same PKCS#11
00140  *                      modules that NSS is accessing without going through
00141  *                      NSS, for example Java SunPKCS11 provider.
00142  *      NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any
00143  *                      PKCS#11 module. This may be necessary in order to
00144  *                      ensure continuous operation and proper shutdown
00145  *                      sequence if another piece of code is using the same
00146  *                      PKCS#11 modules that NSS is accessing without going
00147  *                      through NSS, for example Java SunPKCS11 provider.
00148  *                      The following limitation applies when this is set :
00149  *                      SECMOD_WaitForAnyTokenEvent will not use
00150  *                      C_WaitForSlotEvent, in order to prevent the need for
00151  *                      C_Finalize. This call will be emulated instead.
00152  *      NSS_INIT_RESERVED - Currently has no effect, but may be used in the
00153  *                      future to trigger better cooperation between PKCS#11
00154  *                      modules used by both NSS and the Java SunPKCS11
00155  *                      provider. This should occur after a new flag is defined
00156  *                      for C_Initialize by the PKCS#11 working group.
00157  *      NSS_INIT_COOPERATE - Sets 4 recommended options for applications that
00158  *                      use both NSS and the Java SunPKCS11 provider.
00159  *
00160  * Also NOTE: This is not the recommended method for initializing NSS. 
00161  * The prefered method is NSS_init().
00162  */
00163 #define NSS_INIT_READONLY   0x1
00164 #define NSS_INIT_NOCERTDB   0x2
00165 #define NSS_INIT_NOMODDB    0x4
00166 #define NSS_INIT_FORCEOPEN  0x8
00167 #define NSS_INIT_NOROOTINIT     0x10
00168 #define NSS_INIT_OPTIMIZESPACE  0x20
00169 #define NSS_INIT_PK11THREADSAFE   0x40
00170 #define NSS_INIT_PK11RELOAD       0x80
00171 #define NSS_INIT_NOPK11FINALIZE   0x100
00172 #define NSS_INIT_RESERVED         0x200
00173 
00174 #define NSS_INIT_COOPERATE NSS_INIT_PK11THREADSAFE | \
00175         NSS_INIT_PK11RELOAD | \
00176         NSS_INIT_NOPK11FINALIZE | \
00177         NSS_INIT_RESERVED
00178 
00179 #ifdef macintosh
00180 #define SECMOD_DB "Security Modules"
00181 #else
00182 #define SECMOD_DB "secmod.db"
00183 #endif
00184 
00185 extern SECStatus NSS_Initialize(const char *configdir, 
00186        const char *certPrefix, const char *keyPrefix, 
00187        const char *secmodName, PRUint32 flags);
00188 
00189 /*
00190  * initialize NSS without a creating cert db's, key db's, or secmod db's.
00191  */
00192 SECStatus NSS_NoDB_Init(const char *configdir);
00193 
00194 /*
00195  * Allow applications and libraries to register with NSS so that they are called
00196  * when NSS shuts down.
00197  *
00198  * void *appData application specific data passed in by the application at 
00199  * NSS_RegisterShutdown() time.
00200  * void *nssData is NULL in this release, but is reserved for future versions of 
00201  * NSS to pass some future status information * back to the shutdown function. 
00202  *
00203  * If the shutdown function returns SECFailure,
00204  * Shutdown will still complete, but NSS_Shutdown() will return SECFailure.
00205  */
00206 typedef SECStatus (*NSS_ShutdownFunc)(void *appData, void *nssData);
00207 
00208 /*
00209  * Register a shutdown function.
00210  */
00211 SECStatus NSS_RegisterShutdown(NSS_ShutdownFunc sFunc, void *appData);
00212 
00213 /*
00214  * Remove an existing shutdown function (you may do this if your library is
00215  * complete and going away, but NSS is still running).
00216  */
00217 SECStatus NSS_UnregisterShutdown(NSS_ShutdownFunc sFunc, void *appData);
00218 
00219 /* 
00220  * Close the Cert, Key databases.
00221  */
00222 extern SECStatus NSS_Shutdown(void);
00223 
00224 /*
00225  * set the PKCS #11 strings for the internal token.
00226  */
00227 void PK11_ConfigurePKCS11(const char *man, const char *libdes, 
00228        const char *tokdes, const char *ptokdes, const char *slotdes, 
00229        const char *pslotdes, const char *fslotdes, const char *fpslotdes,
00230         int minPwd, int pwRequired);
00231 
00232 /*
00233  * Dump the contents of the certificate cache and the temporary cert store.
00234  * Use to detect leaked references of certs at shutdown time.
00235  */
00236 void nss_DumpCertificateCacheInfo(void);
00237 
00238 SEC_END_PROTOS
00239 
00240 #endif /* __nss_h_ */