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.23 2008/01/31 22:25:21 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 /* The private macro _NSS_ECC_STRING is for NSS internal use only. */
00049 #ifdef NSS_ENABLE_ECC
00050 #ifdef NSS_ECC_MORE_THAN_SUITE_B
00051 #define _NSS_ECC_STRING " Extended ECC"
00052 #else
00053 #define _NSS_ECC_STRING " Basic ECC"
00054 #endif
00055 #else
00056 #define _NSS_ECC_STRING ""
00057 #endif
00058 
00059 /* The private macro _NSS_CUSTOMIZED is for NSS internal use only. */
00060 #if defined(NSS_ALLOW_UNSUPPORTED_CRITICAL)
00061 #define _NSS_CUSTOMIZED " (Customized build)"
00062 #else
00063 #define _NSS_CUSTOMIZED 
00064 #endif
00065 
00066 /*
00067  * NSS's major version, minor version, patch level, and whether
00068  * this is a beta release.
00069  *
00070  * The format of the version string should be
00071  *     "<major version>.<minor version>[.<patch level>][ <ECC>][ <Beta>]"
00072  */
00073 #define NSS_VERSION  "3.11.9.0" _NSS_ECC_STRING _NSS_CUSTOMIZED
00074 #define NSS_VMAJOR   3
00075 #define NSS_VMINOR   11
00076 #define NSS_VPATCH   9
00077 #define NSS_BETA     PR_FALSE
00078 
00079 /*
00080  * Return a boolean that indicates whether the underlying library
00081  * will perform as the caller expects.
00082  *
00083  * The only argument is a string, which should be the verson
00084  * identifier of the NSS library. That string will be compared
00085  * against a string that represents the actual build version of
00086  * the NSS library.  It also invokes the version checking functions
00087  * of the dependent libraries such as NSPR.
00088  */
00089 extern PRBool NSS_VersionCheck(const char *importedVersion);
00090 
00091 /*
00092  * Open the Cert, Key, and Security Module databases, read only.
00093  * Initialize the Random Number Generator.
00094  * Does not initialize the cipher policies or enables.
00095  * Default policy settings disallow all ciphers.
00096  */
00097 extern SECStatus NSS_Init(const char *configdir);
00098 
00099 /*
00100  * Returns whether NSS has already been initialized or not.
00101  */
00102 extern PRBool NSS_IsInitialized(void);
00103 
00104 /*
00105  * Open the Cert, Key, and Security Module databases, read/write.
00106  * Initialize the Random Number Generator.
00107  * Does not initialize the cipher policies or enables.
00108  * Default policy settings disallow all ciphers.
00109  */
00110 extern SECStatus NSS_InitReadWrite(const char *configdir);
00111 
00112 /*
00113  * Open the Cert, Key, and Security Module databases, read/write.
00114  * Initialize the Random Number Generator.
00115  * Does not initialize the cipher policies or enables.
00116  * Default policy settings disallow all ciphers.
00117  *
00118  * This allows using application defined prefixes for the cert and key db's
00119  * and an alternate name for the secmod database. NOTE: In future releases,
00120  * the database prefixes my not necessarily map to database names.
00121  *
00122  * configdir - base directory where all the cert, key, and module datbases live.
00123  * certPrefix - prefix added to the beginning of the cert database example: "
00124  *                   "https-server1-"
00125  * keyPrefix - prefix added to the beginning of the key database example: "
00126  *                   "https-server1-"
00127  * secmodName - name of the security module database (usually "secmod.db").
00128  * flags - change the open options of NSS_Initialize as follows:
00129  *     NSS_INIT_READONLY - Open the databases read only.
00130  *     NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just 
00131  *                   initialize the volatile certdb.
00132  *     NSS_INIT_NOMODDB  - Don't open the security module DB, just 
00133  *                   initialize the       PKCS #11 module.
00134  *      NSS_INIT_FORCEOPEN - Continue to force initializations even if the 
00135  *                   databases cannot be opened.
00136  *      NSS_INIT_NOROOTINIT - Don't try to look for the root certs module
00137  *                   automatically.
00138  *      NSS_INIT_OPTIMIZESPACE - Use smaller tables and caches.
00139  *      NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are
00140  *                      thread-safe, ie. that support locking - either OS
00141  *                      locking or NSS-provided locks . If a PKCS#11
00142  *                      module isn't thread-safe, don't serialize its
00143  *                      calls; just don't load it instead. This is necessary
00144  *                      if another piece of code is using the same PKCS#11
00145  *                      modules that NSS is accessing without going through
00146  *                      NSS, for example the Java SunPKCS11 provider.
00147  *      NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED
00148  *                      error when loading PKCS#11 modules. This is necessary
00149  *                      if another piece of code is using the same PKCS#11
00150  *                      modules that NSS is accessing without going through
00151  *                      NSS, for example Java SunPKCS11 provider.
00152  *      NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any
00153  *                      PKCS#11 module. This may be necessary in order to
00154  *                      ensure continuous operation and proper shutdown
00155  *                      sequence if another piece of code is using the same
00156  *                      PKCS#11 modules that NSS is accessing without going
00157  *                      through NSS, for example Java SunPKCS11 provider.
00158  *                      The following limitation applies when this is set :
00159  *                      SECMOD_WaitForAnyTokenEvent will not use
00160  *                      C_WaitForSlotEvent, in order to prevent the need for
00161  *                      C_Finalize. This call will be emulated instead.
00162  *      NSS_INIT_RESERVED - Currently has no effect, but may be used in the
00163  *                      future to trigger better cooperation between PKCS#11
00164  *                      modules used by both NSS and the Java SunPKCS11
00165  *                      provider. This should occur after a new flag is defined
00166  *                      for C_Initialize by the PKCS#11 working group.
00167  *      NSS_INIT_COOPERATE - Sets 4 recommended options for applications that
00168  *                      use both NSS and the Java SunPKCS11 provider.
00169  *
00170  * Also NOTE: This is not the recommended method for initializing NSS. 
00171  * The prefered method is NSS_init().
00172  */
00173 #define NSS_INIT_READONLY   0x1
00174 #define NSS_INIT_NOCERTDB   0x2
00175 #define NSS_INIT_NOMODDB    0x4
00176 #define NSS_INIT_FORCEOPEN  0x8
00177 #define NSS_INIT_NOROOTINIT     0x10
00178 #define NSS_INIT_OPTIMIZESPACE  0x20
00179 #define NSS_INIT_PK11THREADSAFE   0x40
00180 #define NSS_INIT_PK11RELOAD       0x80
00181 #define NSS_INIT_NOPK11FINALIZE   0x100
00182 #define NSS_INIT_RESERVED         0x200
00183 
00184 #define NSS_INIT_COOPERATE NSS_INIT_PK11THREADSAFE | \
00185         NSS_INIT_PK11RELOAD | \
00186         NSS_INIT_NOPK11FINALIZE | \
00187         NSS_INIT_RESERVED
00188 
00189 #ifdef macintosh
00190 #define SECMOD_DB "Security Modules"
00191 #else
00192 #define SECMOD_DB "secmod.db"
00193 #endif
00194 
00195 extern SECStatus NSS_Initialize(const char *configdir, 
00196        const char *certPrefix, const char *keyPrefix, 
00197        const char *secmodName, PRUint32 flags);
00198 
00199 /*
00200  * initialize NSS without a creating cert db's, key db's, or secmod db's.
00201  */
00202 SECStatus NSS_NoDB_Init(const char *configdir);
00203 
00204 /*
00205  * Allow applications and libraries to register with NSS so that they are called
00206  * when NSS shuts down.
00207  *
00208  * void *appData application specific data passed in by the application at 
00209  * NSS_RegisterShutdown() time.
00210  * void *nssData is NULL in this release, but is reserved for future versions of 
00211  * NSS to pass some future status information * back to the shutdown function. 
00212  *
00213  * If the shutdown function returns SECFailure,
00214  * Shutdown will still complete, but NSS_Shutdown() will return SECFailure.
00215  */
00216 typedef SECStatus (*NSS_ShutdownFunc)(void *appData, void *nssData);
00217 
00218 /*
00219  * Register a shutdown function.
00220  */
00221 SECStatus NSS_RegisterShutdown(NSS_ShutdownFunc sFunc, void *appData);
00222 
00223 /*
00224  * Remove an existing shutdown function (you may do this if your library is
00225  * complete and going away, but NSS is still running).
00226  */
00227 SECStatus NSS_UnregisterShutdown(NSS_ShutdownFunc sFunc, void *appData);
00228 
00229 /* 
00230  * Close the Cert, Key databases.
00231  */
00232 extern SECStatus NSS_Shutdown(void);
00233 
00234 /*
00235  * set the PKCS #11 strings for the internal token.
00236  */
00237 void PK11_ConfigurePKCS11(const char *man, const char *libdes, 
00238        const char *tokdes, const char *ptokdes, const char *slotdes, 
00239        const char *pslotdes, const char *fslotdes, const char *fpslotdes,
00240         int minPwd, int pwRequired);
00241 
00242 /*
00243  * Dump the contents of the certificate cache and the temporary cert store.
00244  * Use to detect leaked references of certs at shutdown time.
00245  */
00246 void nss_DumpCertificateCacheInfo(void);
00247 
00248 SEC_END_PROTOS
00249 
00250 #endif /* __nss_h_ */