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  */
8 
9 
10 #ifndef _PKIX_SAMPLEMODULES_H
11 #define _PKIX_SAMPLEMODULES_H
12 
13 #include "pkix_pl_common.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
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  */
43 
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  */
57 
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);
85 
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  */
96 
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);
119 
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  */
130 
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);
178 
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);
226 
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 */
254 
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  */
276 
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);
309 
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);
331 
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);
351 
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);
370 
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);
393 
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
419 
420 #endif /* _PKIX_SAMPLEMODULES_H */
421