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 | |
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 { |
95 | unsigned int ; /* allow this structure to grow in the future, |
96 | * must be set */ |
97 | PRBool ; |
98 | int ; |
99 | char *; /* variable names for strings match the */ |
100 | char *; /* parameter name in softoken */ |
101 | char *; |
102 | char *; |
103 | char *; |
104 | char *; |
105 | char *; |
106 | char *; |
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 | #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 | */ |
330 | SECStatus NSS_OptionSet(PRInt32 which, PRInt32 value); |
331 | SECStatus NSS_OptionGet(PRInt32 which, PRInt32 *value); |
332 | |
333 | /* |
334 | * Close the Cert, Key databases. |
335 | */ |
336 | extern SECStatus NSS_Shutdown(void); |
337 | |
338 | /* |
339 | * set the PKCS #11 strings for the internal token. |
340 | */ |
341 | void 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 | */ |
350 | void nss_DumpCertificateCacheInfo(void); |
351 | |
352 | SEC_END_PROTOS |
353 | |
354 | #endif /* RC_INVOKED */ |
355 | #endif /* __nss_h_ */ |
356 | |