The Tor Browser / file comparison

comparison: security/nss/lib/libpkix/include/pkix.h

security/nss/lib/libpkix/include/pkix.h

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:1609f33b3bef
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 the public API for libpkix. These are the top-level
6 * functions in the library. They perform the primary operations of this
7 * library: building and validating chains of X.509 certificates.
8 *
9 */
10
11 #ifndef _PKIX_H
12 #define _PKIX_H
13
14 #include "pkixt.h"
15 #include "pkix_util.h"
16 #include "pkix_results.h"
17 #include "pkix_certstore.h"
18 #include "pkix_certsel.h"
19 #include "pkix_crlsel.h"
20 #include "pkix_checker.h"
21 #include "pkix_revchecker.h"
22 #include "pkix_pl_system.h"
23 #include "pkix_pl_pki.h"
24 #include "pkix_params.h"
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /* General
31 *
32 * Please refer to the libpkix Programmer's Guide for detailed information
33 * about how to use the libpkix library. Certain key warnings and notices from
34 * that document are repeated here for emphasis.
35 *
36 * All identifiers in this file (and all public identifiers defined in
37 * libpkix) begin with "PKIX_". Private identifiers only intended for use
38 * within the library begin with "pkix_".
39 *
40 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
41 *
42 * Unless otherwise noted, for all accessor (gettor) functions that return a
43 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
44 * shared object. Therefore, the caller should treat this shared object as
45 * read-only and should not modify this shared object. When done using the
46 * shared object, the caller should release the reference to the object by
47 * using the PKIX_PL_Object_DecRef function.
48 *
49 * While a function is executing, if its arguments (or anything referred to by
50 * its arguments) are modified, free'd, or destroyed, the function's behavior
51 * is undefined.
52 *
53 */
54
55 /*
56 * FUNCTION: PKIX_Initialize
57 * DESCRIPTION:
58 *
59 * No PKIX_* types and functions should be used before this function is called
60 * and returns successfully. This function should only be called once. If it
61 * is called more than once, the behavior is undefined.
62 *
63 * NSS applications are expected to call NSS_Init, and need not know that
64 * NSS will call this function (with "platformInitNeeded" set to PKIX_FALSE).
65 * PKIX applications are expected instead to call this function with
66 * "platformInitNeeded" set to PKIX_TRUE.
67 *
68 * This function initializes data structures critical to the operation of
69 * libpkix. It also ensures that the API version (major.minor) desired by the
70 * caller (the "desiredMajorVersion", "minDesiredMinorVersion", and
71 * "maxDesiredMinorVersion") is compatible with the API version supported by
72 * the library. As such, the library must support the "desiredMajorVersion"
73 * of the API and must support a minor version that falls between
74 * "minDesiredMinorVersion" and "maxDesiredMinorVersion", inclusive. If
75 * compatibility exists, the function returns NULL and stores the library's
76 * actual minor version at "pActualMinorVersion" (which may be greater than
77 * "desiredMinorVersion"). If no compatibility exists, the function returns a
78 * PKIX_Error pointer. If the caller wishes to specify that the largest
79 * minor version available should be used, then maxDesiredMinorVersion should
80 * be set to the macro PKIX_MAX_MINOR_VERSION (defined in pkixt.h).
81 *
82 * PARAMETERS:
83 * "platformInitNeeded"
84 * Boolean indicating whether the platform layer initialization code
85 * has previously been run, or should be called from this function.
86 * "desiredMajorVersion"
87 * The major version of the libpkix API the application wishes to use.
88 * "minDesiredMinorVersion"
89 * The minimum minor version of the libpkix API the application wishes
90 * to use.
91 * "maxDesiredMinorVersion"
92 * The maximum minor version of the libpkix API the application wishes
93 * to use.
94 * "pActualMinorVersion"
95 * Address where PKIX_UInt32 will be stored. Must be non-NULL.
96 * "pPlContext"
97 * Address at which platform-specific context pointer is stored. Must
98 * be non-NULL.
99 * THREAD SAFETY:
100 * Not Thread Safe
101 * RETURNS:
102 * Returns NULL if the function succeeds.
103 * Returns an Initialize Error if the function fails in a non-fatal way.
104 * Returns a Fatal Error if the function fails in an unrecoverable way.
105 */
106 PKIX_Error *
107 PKIX_Initialize(
108 PKIX_Boolean platformInitNeeded,
109 PKIX_UInt32 desiredMajorVersion,
110 PKIX_UInt32 minDesiredMinorVersion,
111 PKIX_UInt32 maxDesiredMinorVersion,
112 PKIX_UInt32 *pActualMinorVersion,
113 void **pPlContext);
114
115 /*
116 * FUNCTION: PKIX_Shutdown
117 * DESCRIPTION:
118 *
119 * This function deallocates any memory used by libpkix and shuts down any
120 * ongoing operations. This function should only be called once. If it is
121 * called more than once, the behavior is undefined.
122 *
123 * No PKIX_* types and functions should be used after this function is called
124 * and returns successfully.
125 * PARAMETERS:
126 * "plContext" - Platform-specific context pointer.
127 * THREAD SAFETY:
128 * Not Thread Safe
129 * RETURNS:
130 * Returns NULL if the function succeeds.
131 * Returns a Fatal Error if the function fails in an unrecoverable way.
132 */
133 PKIX_Error *
134 PKIX_Shutdown(void *plContext);
135
136 /*
137 * FUNCTION: PKIX_ValidateChain
138 * DESCRIPTION:
139 *
140 * This function attempts to validate the CertChain that has been set in the
141 * ValidateParams pointed to by "params" using an RFC 3280-compliant
142 * algorithm. If successful, this function returns NULL and stores the
143 * ValidateResult at "pResult", which holds additional information, such as
144 * the policy tree and the target's public key. If unsuccessful, an Error is
145 * returned. Note: This function does not currently support non-blocking I/O.
146 *
147 * If "pVerifyTree" is non-NULL, a chain of VerifyNodes is created which
148 * tracks the results of the validation. That is, either each node in the
149 * chain has a NULL Error component, or the last node contains an Error
150 * which indicates why the validation failed.
151 *
152 * PARAMETERS:
153 * "params"
154 * Address of ValidateParams used to validate CertChain. Must be non-NULL.
155 * "pResult"
156 * Address where object pointer will be stored. Must be non-NULL.
157 * "pVerifyTree"
158 * Address where a VerifyTree is stored, if non-NULL.
159 * "plContext"
160 * Platform-specific context pointer.
161 * THREAD SAFETY:
162 * Thread Safe (See Thread Safety Definitions in Programmer's Guide)
163 * RETURNS:
164 * Returns NULL if the function succeeds.
165 * Returns a Validate Error if the function fails in a non-fatal way.
166 * Returns a Fatal Error if the function fails in an unrecoverable way.
167 */
168 PKIX_Error *
169 PKIX_ValidateChain(
170 PKIX_ValidateParams *params,
171 PKIX_ValidateResult **pResult,
172 PKIX_VerifyNode **pVerifyTree,
173 void *plContext);
174
175 /*
176 * FUNCTION: PKIX_ValidateChain_NB
177 * DESCRIPTION:
178 *
179 * This function is the equivalent of PKIX_ValidateChain, except that it
180 * supports non-blocking I/O. When called with "pNBIOContext" pointing to NULL
181 * it initiates a new chain validation as in PKIX_ValidateChain, ignoring the
182 * value in all input variables except "params". If forced to suspend
183 * processing by a WOULDBLOCK return from some operation, such as a CertStore
184 * request, it stores the platform-dependent I/O context at "pNBIOContext" and
185 * stores other intermediate variables at "pCertIndex", "pAnchorIndex",
186 * "pCheckerIndex", "pRevChecking", and "pCheckers".
187 *
188 * When called subsequently with that non-NULL value at "pNBIOContext", it
189 * relies on those intermediate values to be untouched, and it resumes chain
190 * validation where it left off. Its behavior is undefined if any of the
191 * intermediate values was not preserved.
192 *
193 * PARAMETERS:
194 * "params"
195 * Address of ValidateParams used to validate CertChain. Must be non-NULL.
196 * "pCertIndex"
197 * The UInt32 value of the index to the Cert chain, indicating which Cert
198 * is currently being processed.
199 * "pAnchorIndex"
200 * The UInt32 value of the index to the Anchor chain, indicating which
201 * Trust Anchor is currently being processed.
202 * "pCheckerIndex"
203 * The UInt32 value of the index to the List of CertChainCheckers,
204 * indicating which Checker is currently processing.
205 * "pRevChecking"
206 * The Boolean flag indicating whether normal checking or revocation
207 * checking is occurring for the Cert indicated by "pCertIndex".
208 * "pCheckers"
209 * The address of the List of CertChainCheckers. Must be non-NULL.
210 * "pNBIOContext"
211 * The address of the platform-dependend I/O context. Must be a non-NULL
212 * pointer to a NULL value for the call to initiate chain validation.
213 * "pResult"
214 * Address where ValidateResult object pointer will be stored. Must be
215 * non-NULL.
216 * "pVerifyTree"
217 * Address where a VerifyTree is stored, if non-NULL.
218 * "plContext"
219 * Platform-specific context pointer.
220 * THREAD SAFETY:
221 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
222 * RETURNS:
223 * Returns NULL if the function succeeds.
224 * Returns a VALIDATE Error if the function fails in a non-fatal way.
225 * Returns a Fatal Error if the function fails in an unrecoverable way.
226 */PKIX_Error *
227 PKIX_ValidateChain_NB(
228 PKIX_ValidateParams *params,
229 PKIX_UInt32 *pCertIndex,
230 PKIX_UInt32 *pAnchorIndex,
231 PKIX_UInt32 *pCheckerIndex,
232 PKIX_Boolean *pRevChecking,
233 PKIX_List **pCheckers,
234 void **pNBIOContext,
235 PKIX_ValidateResult **pResult,
236 PKIX_VerifyNode **pVerifyTree,
237 void *plContext);
238
239 /*
240 * FUNCTION: PKIX_BuildChain
241 * DESCRIPTION:
242 *
243 * If called with a NULL "state", this function attempts to build and validate
244 * a CertChain according to the ProcessingParams pointed to by "params", using
245 * an RFC 3280-compliant validation algorithm. If successful, this function
246 * returns NULL and stores the BuildResult at "pResult", which holds the built
247 * CertChain, as well as additional information, such as the policy tree and
248 * the target's public key. If unsuccessful, an Error is returned.
249 *
250 * If the chain building is blocked by a CertStore using non-blocking I/O, this
251 * function stores platform-dependent non-blocking I/O context at
252 * "pNBIOContext", its state at "pState", and NULL at "pResult". The caller
253 * may be able to determine, in a platform-dependent way, when the I/O has
254 * completed. In any case, calling the function again with "pState" containing
255 * the returned value will allow the chain building to resume.
256 *
257 * If chain building is completed, either successfully or unsuccessfully, NULL
258 * is stored at "pNBIOContext".
259 *
260 * If "pVerifyTree" is non-NULL, a tree of VerifyNodes is created which
261 * tracks the results of the building. That is, each node of the tree either
262 * has a NULL Error component, or it is a leaf node and it contains an Error
263 * which indicates why the chain building could not proceed on this branch.
264 *
265 * PARAMETERS:
266 * "params"
267 * Address of ProcessingParams used to build and validate CertChain.
268 * Must be non-NULL.
269 * "pNBIOContext"
270 * Address where platform-dependent information is store if the build
271 * is suspended waiting for non-blocking I/O. Must be non-NULL.
272 * "pState"
273 * Address of BuildChain state. Must be NULL on initial call, and the
274 * value previously returned on subsequent calls.
275 * "pResult"
276 * Address where object pointer will be stored. Must be non-NULL.
277 * "pVerifyTree"
278 * Address where a VerifyTree is stored, if non-NULL.
279 * "plContext"
280 * Platform-specific context pointer.
281 * THREAD SAFETY:
282 * Thread Safe (See Thread Safety Definitions in Programmer's Guide)
283 * RETURNS:
284 * Returns NULL if the function succeeds.
285 * Returns a Build Error if the function fails in a non-fatal way.
286 * Returns a Fatal Error if the function fails in an unrecoverable way.
287 */
288 PKIX_Error *
289 PKIX_BuildChain(
290 PKIX_ProcessingParams *params,
291 void **pNBIOContext,
292 void **pState,
293 PKIX_BuildResult **pResult,
294 PKIX_VerifyNode **pVerifyNode,
295 void *plContext);
296
297 #ifdef __cplusplus
298 }
299 #endif
300
301 #endif /* _PKIX_H */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial