1 /* 2 * NSS utility functions 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 7 8 #ifndef __nss_h_ 9 #define __nss_h_ 10 11 /* The private macro _NSS_CUSTOMIZED is for NSS internal use only. */ 12 #if defined(NSS_ALLOW_UNSUPPORTED_CRITICAL) 13 #define _NSS_CUSTOMIZED " (Customized build)" 14 #else 15 #define _NSS_CUSTOMIZED 16 #endif 17 18 /* 19 * NSS's major version, minor version, patch level, build number, and whether 20 * this is a beta release. 21 * 22 * The format of the version string should be 23 * "<major version>.<minor version>[.<patch level>[.<build number>]][ <ECC>][ <Beta>]" 24 */ 25 #define NSS_VERSION "3.36.8" _NSS_CUSTOMIZED 26 #define NSS_VMAJOR 3 27 #define NSS_VMINOR 36 28 #define NSS_VPATCH 8 29 #define NSS_VBUILD 0 30 #define NSS_BETA PR_FALSE 31 32 #ifndef RC_INVOKED 33 34 #include "seccomon.h" 35 36 typedef struct NSSInitParametersStr NSSInitParameters; 37 38 /* 39 * parameters used to initialize softoken. Mostly strings used to 40 * internationalize softoken. Memory for the strings are owned by the caller, 41 * who is free to free them once NSS_ContextInit returns. If the string 42 * parameter is NULL (as opposed to empty, zero length), then the softoken 43 * default is used. These are equivalent to the parameters for 44 * PK11_ConfigurePKCS11(). 45 * 46 * field names match their equivalent parameter names for softoken strings 47 * documented at https://developer.mozilla.org/en/PKCS11_Module_Specs. 48 * 49 * minPWLen 50 * Minimum password length in bytes. 51 * manufacturerID 52 * Override the default manufactureID value for the module returned in 53 * the CK_INFO, CK_SLOT_INFO, and CK_TOKEN_INFO structures with an 54 * internationalize string (UTF8). This value will be truncated at 32 55 * bytes (not including the trailing NULL, partial UTF8 characters will be 56 * dropped). 57 * libraryDescription 58 * Override the default libraryDescription value for the module returned in 59 * the CK_INFO structure with an internationalize string (UTF8). This value 60 * will be truncated at 32 bytes(not including the trailing NULL, partial 61 * UTF8 characters will be dropped). 62 * cryptoTokenDescription 63 * Override the default label value for the internal crypto token returned 64 * in the CK_TOKEN_INFO structure with an internationalize string (UTF8). 65 * This value will be truncated at 32 bytes (not including the trailing 66 * NULL, partial UTF8 characters will be dropped). 67 * dbTokenDescription 68 * Override the default label value for the internal DB token returned in 69 * the CK_TOKEN_INFO structure with an internationalize string (UTF8). This 70 * value will be truncated at 32 bytes (not including the trailing NULL, 71 * partial UTF8 characters will be dropped). 72 * FIPSTokenDescription 73 * Override the default label value for the internal FIPS token returned in 74 * the CK_TOKEN_INFO structure with an internationalize string (UTF8). This 75 * value will be truncated at 32 bytes (not including the trailing NULL, 76 * partial UTF8 characters will be dropped). 77 * cryptoSlotDescription 78 * Override the default slotDescription value for the internal crypto token 79 * returned in the CK_SLOT_INFO structure with an internationalize string 80 * (UTF8). This value will be truncated at 64 bytes (not including the 81 * trailing NULL, partial UTF8 characters will be dropped). 82 * dbSlotDescription 83 * Override the default slotDescription value for the internal DB token 84 * returned in the CK_SLOT_INFO structure with an internationalize string 85 * (UTF8). This value will be truncated at 64 bytes (not including the 86 * trailing NULL, partial UTF8 characters will be dropped). 87 * FIPSSlotDescription 88 * Override the default slotDecription value for the internal FIPS token 89 * returned in the CK_SLOT_INFO structure with an internationalize string 90 * (UTF8). This value will be truncated at 64 bytes (not including the 91 * trailing NULL, partial UTF8 characters will be dropped). 92 * 93 */ 94 struct NSSInitParametersStr { 95 unsigned int length; /* allow this structure to grow in the future, 96 * must be set */ 97 PRBool passwordRequired; 98 int minPWLen; 99 char *manufactureID; /* variable names for strings match the */ 100 char *libraryDescription; /* parameter name in softoken */ 101 char *cryptoTokenDescription; 102 char *dbTokenDescription; 103 char *FIPSTokenDescription; 104 char *cryptoSlotDescription; 105 char *dbSlotDescription; 106 char *FIPSSlotDescription; 107 }; 108 109 SEC_BEGIN_PROTOS 110 111 /* 112 * Return a boolean that indicates whether the underlying library 113 * will perform as the caller expects. 114 * 115 * The only argument is a string, which should be the version 116 * identifier of the NSS library. That string will be compared 117 * against a string that represents the actual build version of 118 * the NSS library. 119 */ 120 extern PRBool NSS_VersionCheck(const char *importedVersion); 121 122 /* 123 * Returns a const string of the NSS library version. 124 */ 125 extern const char *NSS_GetVersion(void); 126 127 /* 128 * Open the Cert, Key, and Security Module databases, read only. 129 * Initialize the Random Number Generator. 130 * Does not initialize the cipher policies or enables. 131 * Default policy settings disallow all ciphers. 132 */ 133 extern SECStatus NSS_Init(const char *configdir); 134 135 /* 136 * Returns whether NSS has already been initialized or not. 137 */ 138 extern PRBool NSS_IsInitialized(void); 139 140 /* 141 * Open the Cert, Key, and Security Module databases, read/write. 142 * Initialize the Random Number Generator. 143 * Does not initialize the cipher policies or enables. 144 * Default policy settings disallow all ciphers. 145 */ 146 extern SECStatus NSS_InitReadWrite(const char *configdir); 147 148 /* 149 * Open the Cert, Key, and Security Module databases, read/write. 150 * Initialize the Random Number Generator. 151 * Does not initialize the cipher policies or enables. 152 * Default policy settings disallow all ciphers. 153 * 154 * This allows using application defined prefixes for the cert and key db's 155 * and an alternate name for the secmod database. NOTE: In future releases, 156 * the database prefixes my not necessarily map to database names. 157 * 158 * configdir - base directory where all the cert, key, and module datbases live. 159 * certPrefix - prefix added to the beginning of the cert database example: " 160 * "https-server1-" 161 * keyPrefix - prefix added to the beginning of the key database example: " 162 * "https-server1-" 163 * secmodName - name of the security module database (usually "secmod.db"). 164 * flags - change the open options of NSS_Initialize as follows: 165 * NSS_INIT_READONLY - Open the databases read only. 166 * NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just 167 * initialize the volatile certdb. 168 * NSS_INIT_NOMODDB - Don't open the security module DB, just 169 * initialize the PKCS #11 module. 170 * NSS_INIT_FORCEOPEN - Continue to force initializations even if the 171 * databases cannot be opened. 172 * NSS_INIT_NOROOTINIT - Don't try to look for the root certs module 173 * automatically. 174 * NSS_INIT_OPTIMIZESPACE - Use smaller tables and caches. 175 * NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are 176 * thread-safe, ie. that support locking - either OS 177 * locking or NSS-provided locks . If a PKCS#11 178 * module isn't thread-safe, don't serialize its 179 * calls; just don't load it instead. This is necessary 180 * if another piece of code is using the same PKCS#11 181 * modules that NSS is accessing without going through 182 * NSS, for example the Java SunPKCS11 provider. 183 * NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED 184 * error when loading PKCS#11 modules. This is necessary 185 * if another piece of code is using the same PKCS#11 186 * modules that NSS is accessing without going through 187 * NSS, for example Java SunPKCS11 provider. 188 * NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any 189 * PKCS#11 module. This may be necessary in order to 190 * ensure continuous operation and proper shutdown 191 * sequence if another piece of code is using the same 192 * PKCS#11 modules that NSS is accessing without going 193 * through NSS, for example Java SunPKCS11 provider. 194 * The following limitation applies when this is set : 195 * SECMOD_WaitForAnyTokenEvent will not use 196 * C_WaitForSlotEvent, in order to prevent the need for 197 * C_Finalize. This call will be emulated instead. 198 * NSS_INIT_RESERVED - Currently has no effect, but may be used in the 199 * future to trigger better cooperation between PKCS#11 200 * modules used by both NSS and the Java SunPKCS11 201 * provider. This should occur after a new flag is defined 202 * for C_Initialize by the PKCS#11 working group. 203 * NSS_INIT_COOPERATE - Sets 4 recommended options for applications that 204 * use both NSS and the Java SunPKCS11 provider. 205 * 206 * Also NOTE: This is not the recommended method for initializing NSS. 207 * The preferred method is NSS_init(). 208 */ 209 #define NSS_INIT_READONLY 0x1 210 #define NSS_INIT_NOCERTDB 0x2 211 #define NSS_INIT_NOMODDB 0x4 212 #define NSS_INIT_FORCEOPEN 0x8 213 #define NSS_INIT_NOROOTINIT 0x10 214 #define NSS_INIT_OPTIMIZESPACE 0x20 215 #define NSS_INIT_PK11THREADSAFE 0x40 216 #define NSS_INIT_PK11RELOAD 0x80 217 #define NSS_INIT_NOPK11FINALIZE 0x100 218 #define NSS_INIT_RESERVED 0x200 219 220 #define NSS_INIT_COOPERATE NSS_INIT_PK11THREADSAFE | \ 221 NSS_INIT_PK11RELOAD | \ 222 NSS_INIT_NOPK11FINALIZE | \ 223 NSS_INIT_RESERVED 224 225 #define SECMOD_DB "secmod.db" 226 227 typedef struct NSSInitContextStr NSSInitContext; 228 229 extern SECStatus NSS_Initialize(const char *configdir, 230 const char *certPrefix, const char *keyPrefix, 231 const char *secmodName, PRUint32 flags); 232 233 extern NSSInitContext *NSS_InitContext(const char *configdir, 234 const char *certPrefix, const char *keyPrefix, 235 const char *secmodName, NSSInitParameters *initParams, PRUint32 flags); 236 237 extern SECStatus NSS_ShutdownContext(NSSInitContext *); 238 239 /* 240 * same as NSS_Init, but checks to see if we need to merge an 241 * old database in. 242 * updatedir is the directory where the old database lives. 243 * updCertPrefix is the certPrefix for the old database. 244 * updKeyPrefix is the keyPrefix for the old database. 245 * updateID is a unique identifier chosen by the application for 246 * the specific database. 247 * updatName is the name the user will be prompted for when 248 * asking to authenticate to the old database */ 249 extern SECStatus NSS_InitWithMerge(const char *configdir, 250 const char *certPrefix, const char *keyPrefix, const char *secmodName, 251 const char *updatedir, const char *updCertPrefix, 252 const char *updKeyPrefix, const char *updateID, 253 const char *updateName, PRUint32 flags); 254 /* 255 * initialize NSS without a creating cert db's, key db's, or secmod db's. 256 */ 257 SECStatus NSS_NoDB_Init(const char *configdir); 258 259 /* 260 * Allow applications and libraries to register with NSS so that they are called 261 * when NSS shuts down. 262 * 263 * void *appData application specific data passed in by the application at 264 * NSS_RegisterShutdown() time. 265 * void *nssData is NULL in this release, but is reserved for future versions of 266 * NSS to pass some future status information * back to the shutdown function. 267 * 268 * If the shutdown function returns SECFailure, 269 * Shutdown will still complete, but NSS_Shutdown() will return SECFailure. 270 */ 271 typedef SECStatus (*NSS_ShutdownFunc)(void *appData, void *nssData); 272 273 /* 274 * Register a shutdown function. 275 */ 276 SECStatus NSS_RegisterShutdown(NSS_ShutdownFunc sFunc, void *appData); 277 278 /* 279 * Remove an existing shutdown function (you may do this if your library is 280 * complete and going away, but NSS is still running). 281 */ 282 SECStatus NSS_UnregisterShutdown(NSS_ShutdownFunc sFunc, void *appData); 283 284 /* Available options for NSS_OptionSet() and NSS_OptionGet(). 285 */ 286 #define NSS_RSA_MIN_KEY_SIZE 0x001 287 #define NSS_DH_MIN_KEY_SIZE 0x002 288 #define NSS_DSA_MIN_KEY_SIZE 0x004 289 #define NSS_TLS_VERSION_MIN_POLICY 0x008 290 #define NSS_TLS_VERSION_MAX_POLICY 0x009 291 #define NSS_DTLS_VERSION_MIN_POLICY 0x00a 292 #define NSS_DTLS_VERSION_MAX_POLICY 0x00b 293 294 /* Until NSS 3.30, the PKCS#12 implementation used BMPString encoding 295 * for all passwords. This changed to use UTF-8 for non-PKCS#12 PBEs 296 * in NSS 3.31. 297 * 298 * For backward compatibility, this option reverts the behavior to the 299 * old NSS versions. This option might be removed in the future NSS 300 * releases; don't rely on it. */ 301 #define __NSS_PKCS12_DECODE_FORCE_UNICODE 0x00c 302 303 /* 304 * Set and get global options for the NSS library. 305 */ 306 SECStatus NSS_OptionSet(PRInt32 which, PRInt32 value); 307 SECStatus NSS_OptionGet(PRInt32 which, PRInt32 *value); 308 309 /* 310 * Close the Cert, Key databases. 311 */ 312 extern SECStatus NSS_Shutdown(void); 313 314 /* 315 * set the PKCS #11 strings for the internal token. 316 */ 317 void PK11_ConfigurePKCS11(const char *man, const char *libdesc, 318 const char *tokdesc, const char *ptokdesc, const char *slotdesc, 319 const char *pslotdesc, const char *fslotdesc, const char *fpslotdesc, 320 int minPwd, int pwRequired); 321 322 /* 323 * Dump the contents of the certificate cache and the temporary cert store. 324 * Use to detect leaked references of certs at shutdown time. 325 */ 326 void nss_DumpCertificateCacheInfo(void); 327 328 SEC_END_PROTOS 329 330 #endif /* RC_INVOKED */ 331 #endif /* __nss_h_ */ 332