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.98" _NSS_CUSTOMIZED
26#define NSS_VMAJOR 3
27#define NSS_VMINOR 98
28#define NSS_VPATCH 0
29#define NSS_VBUILD 0
30#define NSS_BETA PR_FALSE
31
32#ifndef RC_INVOKED
33
34#include "seccomon.h"
35
36typedef 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 */
94struct 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
109SEC_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 */
120extern PRBool NSS_VersionCheck(const char *importedVersion);
121
122/*
123 * Returns a const string of the NSS library version.
124 */
125extern 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 */
133extern SECStatus NSS_Init(const char *configdir);
134
135/*
136 * Returns whether NSS has already been initialized or not.
137 */
138extern 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 */
146extern 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
227typedef struct NSSInitContextStr NSSInitContext;
228
229extern SECStatus NSS_Initialize(const char *configdir,
230 const char *certPrefix, const char *keyPrefix,
231 const char *secmodName, PRUint32 flags);
232
233extern NSSInitContext *NSS_InitContext(const char *configdir,
234 const char *certPrefix, const char *keyPrefix,
235 const char *secmodName, NSSInitParameters *initParams, PRUint32 flags);
236
237extern 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 */
249extern 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 */
257SECStatus 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 */
271typedef SECStatus (*NSS_ShutdownFunc)(void *appData, void *nssData);
272
273/*
274 * Register a shutdown function.
275 */
276SECStatus 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 */
282SECStatus 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#define NSS_DEFAULT_LOCKS 0x00d /* lock default values */
303#define NSS_DEFAULT_SSL_LOCK 1 /* lock the ssl default values */
304
305/* NSS_KEY_SIZE_POLICY controls what kinds of operations are subject to
306 * the NSS_XXX_MIN_KEY_SIZE values.
307 * NSS_KEY_SIZE_POLICY_FLAGS sets and clears all the flags to the input
308 * value
309 * On get it returns all the flags
310 * NSS_KEY_SIZE_POLICY_SET_FLAGS sets only the flags=1 in theinput value and
311 * does not affect the other flags
312 * On get it returns all the flags
313 * NSS_KEY_SIZE_POLICY_CLEAR_FLAGS clears only the flags=1 in the input
314 * value and does not affect the other flags
315 * On get it returns all the compliment of all the flags
316 * (cleared flags == 1) */
317#define NSS_KEY_SIZE_POLICY_FLAGS 0x00e
318#define NSS_KEY_SIZE_POLICY_SET_FLAGS 0x00f
319#define NSS_KEY_SIZE_POLICY_CLEAR_FLAGS 0x010
320/* currently defined flags */
321#define NSS_KEY_SIZE_POLICY_SSL_FLAG 1
322#define NSS_KEY_SIZE_POLICY_VERIFY_FLAG 2
323#define NSS_KEY_SIZE_POLICY_SIGN_FLAG 4
324
325#define NSS_ECC_MIN_KEY_SIZE 0x011
326
327/*
328 * Set and get global options for the NSS library.
329 */
330SECStatus NSS_OptionSet(PRInt32 which, PRInt32 value);
331SECStatus NSS_OptionGet(PRInt32 which, PRInt32 *value);
332
333/*
334 * Close the Cert, Key databases.
335 */
336extern SECStatus NSS_Shutdown(void);
337
338/*
339 * set the PKCS #11 strings for the internal token.
340 */
341void PK11_ConfigurePKCS11(const char *man, const char *libdesc,
342 const char *tokdesc, const char *ptokdesc, const char *slotdesc,
343 const char *pslotdesc, const char *fslotdesc, const char *fpslotdesc,
344 int minPwd, int pwRequired);
345
346/*
347 * Dump the contents of the certificate cache and the temporary cert store.
348 * Use to detect leaked references of certs at shutdown time.
349 */
350void nss_DumpCertificateCacheInfo(void);
351
352SEC_END_PROTOS
353
354#endif /* RC_INVOKED */
355#endif /* __nss_h_ */
356

source code of include/nss/nss.h