security/nss/lib/libpkix/include/pkix_sample_modules.h@b8a032363ba2
security/nss/lib/libpkix/include/pkix_sample_modules.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rwxr-xr-x
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4 /*
5 * This file defines functions associated with CertStore types.
6 *
7 */
10 #ifndef _PKIX_SAMPLEMODULES_H
11 #define _PKIX_SAMPLEMODULES_H
13 #include "pkix_pl_common.h"
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
19 /* General
20 *
21 * Please refer to the libpkix Programmer's Guide for detailed information
22 * about how to use the libpkix library. Certain key warnings and notices from
23 * that document are repeated here for emphasis.
24 *
25 * All identifiers in this file (and all public identifiers defined in
26 * libpkix) begin with "PKIX_". Private identifiers only intended for use
27 * within the library begin with "pkix_".
28 *
29 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
30 *
31 * Unless otherwise noted, for all accessor (gettor) functions that return a
32 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
33 * shared object. Therefore, the caller should treat this shared object as
34 * read-only and should not modify this shared object. When done using the
35 * shared object, the caller should release the reference to the object by
36 * using the PKIX_PL_Object_DecRef function.
37 *
38 * While a function is executing, if its arguments (or anything referred to by
39 * its arguments) are modified, free'd, or destroyed, the function's behavior
40 * is undefined.
41 *
42 */
44 /* PKIX_PL_CollectionCertStore
45 *
46 * A PKIX_CollectionCertStore provides an example for showing how to retrieve
47 * certificates and CRLs from a repository, such as a directory in the system.
48 * It is expected the directory is an absolute directory which contains CRL
49 * and Cert data files. CRL files are expected to have the suffix of .crl
50 * and Cert files are expected to have the suffix of .crt .
51 *
52 * Once the caller has created the CollectionCertStoreContext object, the caller
53 * then can call pkix_pl_CollectionCertStore_GetCert or
54 * pkix_pl_CollectionCertStore_GetCRL to obtain Lists of PKIX_PL_Cert or
55 * PKIX_PL_CRL objects, respectively.
56 */
58 /*
59 * FUNCTION: PKIX_PL_CollectionCertStore_Create
60 * DESCRIPTION:
61 *
62 * Creates a new CollectionCertStore and returns it at
63 * "pColCertStore".
64 *
65 * PARAMETERS:
66 * "storeDir"
67 * The absolute path where *.crl files are located.
68 * "pColCertStoreContext"
69 * Address where object pointer will be stored. Must be non-NULL.
70 * "plContext"
71 * Platform-specific context pointer.
72 * THREAD SAFETY:
73 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
74 * RETURNS:
75 * Returns NULL if the function succeeds.
76 * Returns a CollectionCertStoreContext Error if the function fails in
77 * a non-fatal way.
78 * Returns a Fatal Error if the function fails in an unrecoverable way.
79 */
80 PKIX_Error *
81 PKIX_PL_CollectionCertStore_Create(
82 PKIX_PL_String *storeDir,
83 PKIX_CertStore **pCertStore,
84 void *plContext);
86 /* PKIX_PL_PK11CertStore
87 *
88 * A PKIX_PL_PK11CertStore retrieves certificates and CRLs from a PKCS11
89 * database. The directory that contains the cert8.db, key3.db, and secmod.db
90 * files that comprise a PKCS11 database are specified in NSS initialization.
91 *
92 * Once the caller has created the Pk11CertStore object, the caller can call
93 * pkix_pl_Pk11CertStore_GetCert or pkix_pl_Pk11CertStore_GetCert to obtain
94 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
95 */
97 /*
98 * FUNCTION: PKIX_PL_Pk11CertStore_Create
99 * DESCRIPTION:
100 *
101 * Creates a new Pk11CertStore and returns it at "pPk11CertStore".
102 *
103 * PARAMETERS:
104 * "pPk11CertStore"
105 * Address where object pointer will be stored. Must be non-NULL.
106 * "plContext"
107 * Platform-specific context pointer.
108 * THREAD SAFETY:
109 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
110 * RETURNS:
111 * Returns NULL if the function succeeds.
112 * Returns a CertStore Error if the function fails in a non-fatal way.
113 * Returns a Fatal Error if the function fails in an unrecoverable way.
114 */
115 PKIX_Error *
116 PKIX_PL_Pk11CertStore_Create(
117 PKIX_CertStore **pPk11CertStore,
118 void *plContext);
120 #ifndef NSS_PKIX_NO_LDAP
121 /* PKIX_PL_LdapCertStore
122 *
123 * A PKIX_PL_LdapCertStore retrieves certificates and CRLs from an LDAP server
124 * over a socket connection. It used the LDAP protocol as described in RFC1777.
125 *
126 * Once the caller has created the LdapCertStore object, the caller can call
127 * pkix_pl_LdapCertStore_GetCert or pkix_pl_LdapCertStore_GetCert to obtain
128 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
129 */
131 /*
132 * FUNCTION: PKIX_PL_LdapDefaultClient_Create
133 * DESCRIPTION:
134 *
135 * Creates an LdapDefaultClient using the PRNetAddr poined to by "sockaddr",
136 * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
137 * and stores the address of the default LdapClient at "pClient".
138 *
139 * At the time of this version, there are unresolved questions about the LDAP
140 * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
141 * clear whether they are appropriate to this application. We have tested only
142 * using servers that do not expect authentication, and that reject BIND
143 * messages. It is not clear what values might be appropriate for the bindname
144 * and authentication fields, which are currently implemented as char strings
145 * supplied by the caller. (If this changes, the API and possibly the templates
146 * will have to change.) Therefore the Client_Create API contains a BindAPI
147 * structure, a union, which will have to be revised and extended when this
148 * area of the protocol is better understood.
149 *
150 * PARAMETERS:
151 * "sockaddr"
152 * Address of the PRNetAddr to be used for the socket connection. Must be
153 * non-NULL.
154 * "timeout"
155 * The PRIntervalTime value to be used as a timeout value in socket calls;
156 * a zero value indicates non-blocking I/O is to be used.
157 * "bindAPI"
158 * The address of a BindAPI to be used if a BIND message is required. If
159 * this argument is NULL, no Bind (or Unbind) will be sent.
160 * "pClient"
161 * Address where object pointer will be stored. Must be non-NULL.
162 * "plContext"
163 * Platform-specific context pointer.
164 * THREAD SAFETY:
165 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
166 * RETURNS:
167 * Returns NULL if the function succeeds.
168 * Returns a CertStore Error if the function fails in a non-fatal way.
169 * Returns a Fatal Error if the function fails in an unrecoverable way.
170 */
171 PKIX_Error *
172 PKIX_PL_LdapDefaultClient_Create(
173 PRNetAddr *sockaddr,
174 PRIntervalTime timeout,
175 LDAPBindAPI *bindAPI,
176 PKIX_PL_LdapDefaultClient **pClient,
177 void *plContext);
179 /*
180 * FUNCTION: PKIX_PL_LdapDefaultClient_CreateByName
181 * DESCRIPTION:
182 *
183 * Creates an LdapDefaultClient using the hostname poined to by "hostname",
184 * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
185 * and stores the address of the default LdapClient at "pClient".
186 *
187 * At the time of this version, there are unresolved questions about the LDAP
188 * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
189 * clear whether they are appropriate to this application. We have tested only
190 * using servers that do not expect authentication, and that reject BIND
191 * messages. It is not clear what values might be appropriate for the bindname
192 * and authentication fields, which are currently implemented as char strings
193 * supplied by the caller. (If this changes, the API and possibly the templates
194 * will have to change.) Therefore the Client_Create API contains a BindAPI
195 * structure, a union, which will have to be revised and extended when this
196 * area of the protocol is better understood.
197 *
198 * PARAMETERS:
199 * "hostname"
200 * Address of the hostname to be used for the socket connection. Must be
201 * non-NULL.
202 * "timeout"
203 * The PRIntervalTime value to be used as a timeout value in socket calls;
204 * a zero value indicates non-blocking I/O is to be used.
205 * "bindAPI"
206 * The address of a BindAPI to be used if a BIND message is required. If
207 * this argument is NULL, no Bind (or Unbind) will be sent.
208 * "pClient"
209 * Address where object pointer will be stored. Must be non-NULL.
210 * "plContext"
211 * Platform-specific context pointer.
212 * THREAD SAFETY:
213 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
214 * RETURNS:
215 * Returns NULL if the function succeeds.
216 * Returns a CertStore Error if the function fails in a non-fatal way.
217 * Returns a Fatal Error if the function fails in an unrecoverable way.
218 */
219 PKIX_Error *
220 PKIX_PL_LdapDefaultClient_CreateByName(
221 char *hostname,
222 PRIntervalTime timeout,
223 LDAPBindAPI *bindAPI,
224 PKIX_PL_LdapDefaultClient **pClient,
225 void *plContext);
227 /*
228 * FUNCTION: PKIX_PL_LdapCertStore_Create
229 * DESCRIPTION:
230 *
231 * Creates a new LdapCertStore using the LdapClient pointed to by "client",
232 * and stores the address of the CertStore at "pCertStore".
233 *
234 * PARAMETERS:
235 * "client"
236 * Address of the LdapClient to be used. Must be non-NULL.
237 * "pCertStore"
238 * Address where object pointer will be stored. Must be non-NULL.
239 * "plContext"
240 * Platform-specific context pointer.
241 * THREAD SAFETY:
242 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
243 * RETURNS:
244 * Returns NULL if the function succeeds.
245 * Returns a CertStore Error if the function fails in a non-fatal way.
246 * Returns a Fatal Error if the function fails in an unrecoverable way.
247 */
248 PKIX_Error *
249 PKIX_PL_LdapCertStore_Create(
250 PKIX_PL_LdapClient *client,
251 PKIX_CertStore **pCertStore,
252 void *plContext);
253 #endif /* !NSS_PKIX_NO_LDAP */
255 /* PKIX_PL_NssContext
256 *
257 * A PKIX_PL_NssContext provides an example showing how the "plContext"
258 * argument, that is part of every libpkix function call, can be used.
259 * The "plContext" is the Portability Layer Context, which can be used
260 * to communicate layer-specific information from the application to the
261 * underlying Portability Layer (while bypassing the Portable Code, which
262 * blindly passes the plContext on to every function call).
263 *
264 * In this case, NSS serves as both the application and the Portability Layer.
265 * We define an NSS-specific structure, which includes an arena and a number
266 * of SECCertificateUsage bit flags encoded as a PKIX_UInt32. A third argument,
267 * wincx, is used on Windows platforms for PKCS11 access, and should be set to
268 * NULL for other platforms.
269 * Before calling any of the libpkix functions, the caller should create the NSS
270 * context, by calling PKIX_PL_NssContext_Create, and provide that NSS context
271 * as the "plContext" argument in every libpkix function call the caller makes.
272 * When the caller is finished using the NSS context (usually just after he
273 * calls PKIX_Shutdown), the caller should call PKIX_PL_NssContext_Destroy to
274 * free the NSS context structure.
275 */
277 /*
278 * FUNCTION: PKIX_PL_NssContext_Create
279 * DESCRIPTION:
280 *
281 * Creates a new NssContext using the certificate usage(s) specified by
282 * "certUsage" and stores it at "pNssContext". This function also internally
283 * creates an arena and stores it as part of the NssContext structure. Unlike
284 * most other libpkix API functions, this function does not take a "plContext"
285 * parameter.
286 *
287 * PARAMETERS:
288 * "certUsage"
289 * The desired SECCertificateUsage(s).
290 * "useNssArena"
291 * Boolean flag indicates NSS Arena is used for memory allocation.
292 * "wincx"
293 * A Windows-dependent pointer for PKCS11 token handling.
294 * "pNssContext"
295 * Address where object pointer will be stored. Must be non-NULL.
296 * THREAD SAFETY:
297 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
298 * RETURNS:
299 * Returns NULL if the function succeeds.
300 * Returns a Context Error if the function fails in a non-fatal way.
301 * Returns a Fatal Error if the function fails in an unrecoverable way.
302 */
303 PKIX_Error *
304 PKIX_PL_NssContext_Create(
305 PKIX_UInt32 certificateUsage,
306 PKIX_Boolean useNssArena,
307 void *wincx,
308 void **pNssContext);
310 /*
311 * FUNCTION: PKIX_PL_NssContext_Destroy
312 * DESCRIPTION:
313 *
314 * Frees the structure pointed to by "nssContext" along with any of its
315 * associated memory. Unlike most other libpkix API functions, this function
316 * does not take a "plContext" parameter.
317 *
318 * PARAMETERS:
319 * "nssContext"
320 * Address of NssContext to be destroyed. Must be non-NULL.
321 * THREAD SAFETY:
322 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
323 * RETURNS:
324 * Returns NULL if the function succeeds.
325 * Returns a Context Error if the function fails in a non-fatal way.
326 * Returns a Fatal Error if the function fails in an unrecoverable way.
327 */
328 PKIX_Error *
329 PKIX_PL_NssContext_Destroy(
330 void *nssContext);
332 /*
333 * FUNCTION: PKIX_PL_NssContext_SetTimeout
334 * DESCRIPTION:
335 *
336 * Sets IO timeout for network operations like OCSP response and cert
337 * fetching.
338 *
339 * PARAMETERS:
340 * "nssContext"
341 * Address of NssContext to be destroyed. Must be non-NULL.
342 * THREAD SAFETY:
343 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
344 * RETURNS:
345 * Returns NULL if the function succeeds.
346 * Returns a Context Error if the function fails in a non-fatal way.
347 * Returns a Fatal Error if the function fails in an unrecoverable way.
348 */
349 PKIX_Error *
350 PKIX_PL_NssContext_SetTimeout(PKIX_UInt32 timeout, PKIX_PL_NssContext *nssContext);
352 /*
353 * FUNCTION: PKIX_PL_NssContext_SetMaxResponseLen
354 * DESCRIPTION:
355 *
356 * Sets maximum responce length allowed during network IO operations.
357 *
358 * PARAMETERS:
359 * "nssContext"
360 * Address of NssContext to be destroyed. Must be non-NULL.
361 * THREAD SAFETY:
362 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
363 * RETURNS:
364 * Returns NULL if the function succeeds.
365 * Returns a Context Error if the function fails in a non-fatal way.
366 * Returns a Fatal Error if the function fails in an unrecoverable way.
367 */
368 PKIX_Error *
369 PKIX_PL_NssContext_SetMaxResponseLen(PKIX_UInt32 len, PKIX_PL_NssContext *nssContext);
371 /*
372 * FUNCTION: PKIX_PL_NssContext_SetCrlReloadDelay
373 * DESCRIPTION:
374 *
375 * Sets user defined timeout between attempts to load crl using
376 * CRLDP.
377 *
378 * PARAMETERS:
379 * "delaySeconds"
380 * Reload delay in seconds.
381 * "nssContext"
382 * Address of NssContext to be destroyed. Must be non-NULL.
383 * THREAD SAFETY:
384 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
385 * RETURNS:
386 * Returns NULL if the function succeeds.
387 * Returns a Context Error if the function fails in a non-fatal way.
388 * Returns a Fatal Error if the function fails in an unrecoverable way.
389 */
390 PKIX_Error *
391 PKIX_PL_NssContext_SetCrlReloadDelay(PKIX_UInt32 delaySeconds,
392 PKIX_PL_NssContext *nssContext);
394 /*
395 * FUNCTION: PKIX_PL_NssContext_SetBadDerCrlReloadDelay
396 * DESCRIPTION:
397 *
398 * Sets user defined timeout between attempts to load crls
399 * that failed to decode.
400 *
401 * PARAMETERS:
402 * "delaySeconds"
403 * Reload delay in seconds.
404 * "nssContext"
405 * Address of NssContext to be destroyed. Must be non-NULL.
406 * THREAD SAFETY:
407 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
408 * RETURNS:
409 * Returns NULL if the function succeeds.
410 * Returns a Context Error if the function fails in a non-fatal way.
411 * Returns a Fatal Error if the function fails in an unrecoverable way.
412 */
413 PKIX_Error *
414 PKIX_PL_NssContext_SetBadDerCrlReloadDelay(PKIX_UInt32 delaySeconds,
415 PKIX_PL_NssContext *nssContext);
416 #ifdef __cplusplus
417 }
418 #endif
420 #endif /* _PKIX_SAMPLEMODULES_H */
