The Tor Browser / file comparison

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

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

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:98f90c1fb0d7
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 the results used
6 * by the top-level functions.
7 *
8 */
9
10 #ifndef _PKIX_RESULTS_H
11 #define _PKIX_RESULTS_H
12
13 #include "pkixt.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 /* PKIX_ValidateResult
44 *
45 * PKIX_ValidateResult represents the result of a PKIX_ValidateChain call. It
46 * consists of the valid policy tree and public key resulting from validation,
47 * as well as the trust anchor used for this chain. Once created, a
48 * ValidateResult object is immutable.
49 */
50
51 /*
52 * FUNCTION: PKIX_ValidateResult_GetPolicyTree
53 * DESCRIPTION:
54 *
55 * Retrieves the PolicyNode component (representing the valid_policy_tree)
56 * from the ValidateResult object pointed to by "result" and stores it at
57 * "pPolicyTree".
58 *
59 * PARAMETERS:
60 * "result"
61 * Address of ValidateResult whose policy tree is to be stored. Must be
62 * non-NULL.
63 * "pPolicyTree"
64 * Address where object pointer will be stored. Must be non-NULL.
65 * "plContext"
66 * Platform-specific context pointer.
67 * THREAD SAFETY:
68 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
69 * RETURNS:
70 * Returns NULL if the function succeeds.
71 * Returns a Result Error if the function fails in a non-fatal way.
72 * Returns a Fatal Error if the function fails in an unrecoverable way.
73 */
74 PKIX_Error *
75 PKIX_ValidateResult_GetPolicyTree(
76 PKIX_ValidateResult *result,
77 PKIX_PolicyNode **pPolicyTree,
78 void *plContext);
79
80 /*
81 * FUNCTION: PKIX_ValidateResult_GetPublicKey
82 * DESCRIPTION:
83 *
84 * Retrieves the PublicKey component (representing the valid public_key) of
85 * the ValidateResult object pointed to by "result" and stores it at
86 * "pPublicKey".
87 *
88 * PARAMETERS:
89 * "result"
90 * Address of ValidateResult whose public key is to be stored.
91 * Must be non-NULL.
92 * "pPublicKey"
93 * Address where object pointer will be stored. Must be non-NULL.
94 * "plContext"
95 * Platform-specific context pointer.
96 * THREAD SAFETY:
97 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
98 * RETURNS:
99 * Returns NULL if the function succeeds.
100 * Returns a Result Error if the function fails in a non-fatal way.
101 * Returns a Fatal Error if the function fails in an unrecoverable way.
102 */
103 PKIX_Error *
104 PKIX_ValidateResult_GetPublicKey(
105 PKIX_ValidateResult *result,
106 PKIX_PL_PublicKey **pPublicKey,
107 void *plContext);
108
109 /*
110 * FUNCTION: PKIX_ValidateResult_GetTrustAnchor
111 * DESCRIPTION:
112 *
113 * Retrieves the TrustAnchor component (representing the trust anchor used
114 * during chain validation) of the ValidateResult object pointed to by
115 * "result" and stores it at "pTrustAnchor".
116 *
117 * PARAMETERS:
118 * "result"
119 * Address of ValidateResult whose trust anchor is to be stored.
120 * Must be non-NULL.
121 * "pTrustAnchor"
122 * Address where object pointer will be stored. Must be non-NULL.
123 * "plContext"
124 * Platform-specific context pointer.
125 * THREAD SAFETY:
126 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
127 * RETURNS:
128 * Returns NULL if the function succeeds.
129 * Returns a Result Error if the function fails in a non-fatal way.
130 * Returns a Fatal Error if the function fails in an unrecoverable way.
131 */
132 PKIX_Error *
133 PKIX_ValidateResult_GetTrustAnchor(
134 PKIX_ValidateResult *result,
135 PKIX_TrustAnchor **pTrustAnchor,
136 void *plContext);
137
138 /* PKIX_BuildResult
139 *
140 * PKIX_BuildResult represents the result of a PKIX_BuildChain call. It
141 * consists of a ValidateResult object, as well as the built and validated
142 * CertChain. Once created, a BuildResult object is immutable.
143 */
144
145 /*
146 * FUNCTION: PKIX_BuildResult_GetValidateResult
147 * DESCRIPTION:
148 *
149 * Retrieves the ValidateResult component (representing the build's validate
150 * result) of the BuildResult object pointed to by "result" and stores it at
151 * "pResult".
152 *
153 * PARAMETERS:
154 * "result"
155 * Address of BuildResult whose ValidateResult component is to be stored.
156 * Must be non-NULL.
157 * "pResult"
158 * Address where object pointer will be stored. Must be 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 Result 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_BuildResult_GetValidateResult(
170 PKIX_BuildResult *result,
171 PKIX_ValidateResult **pResult,
172 void *plContext);
173
174 /*
175 * FUNCTION: PKIX_BuildResult_GetCertChain
176 * DESCRIPTION:
177 *
178 * Retrieves the List of Certs (certChain) component (representing the built
179 * and validated CertChain) of the BuildResult object pointed to by "result"
180 * and stores it at "pChain".
181 *
182 * PARAMETERS:
183 * "result"
184 * Address of BuildResult whose CertChain component is to be stored.
185 * Must be non-NULL.
186 * "pChain"
187 * Address where object pointer will be stored. Must be non-NULL.
188 * "plContext"
189 * Platform-specific context pointer.
190 * THREAD SAFETY:
191 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
192 * RETURNS:
193 * Returns NULL if the function succeeds.
194 * Returns a Result Error if the function fails in a non-fatal way.
195 * Returns a Fatal Error if the function fails in an unrecoverable way.
196 */
197 PKIX_Error *
198 PKIX_BuildResult_GetCertChain(
199 PKIX_BuildResult *result,
200 PKIX_List **pChain,
201 void *plContext);
202
203 /* PKIX_PolicyNode
204 *
205 * PKIX_PolicyNode represents a node in the policy tree returned in
206 * ValidateResult. The policy tree is the same length as the validated
207 * certificate chain and the nodes are associated with a particular depth
208 * (corresponding to a particular certificate in the chain).
209 * PKIX_ValidateResult_GetPolicyTree returns the root node of the valid policy
210 * tree. Other nodes can be accessed using the getChildren and getParents
211 * functions, and individual elements of a node can be accessed with the
212 * appropriate gettors. Once created, a PolicyNode is immutable.
213 */
214
215 /*
216 * FUNCTION: PKIX_PolicyNode_GetChildren
217 * DESCRIPTION:
218 *
219 * Retrieves the List of PolicyNodes representing the child nodes of the
220 * Policy Node pointed to by "node" and stores it at "pChildren". If "node"
221 * has no child nodes, this function stores an empty List at "pChildren".
222 *
223 * Note that the List returned by this function is immutable.
224 *
225 * PARAMETERS:
226 * "node"
227 * Address of PolicyNode whose child nodes are to be stored.
228 * Must be non-NULL.
229 * "pChildren"
230 * Address where object pointer will be stored. Must be non-NULL.
231 * "plContext"
232 * Platform-specific context pointer.
233 * THREAD SAFETY:
234 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
235 * RETURNS:
236 * Returns NULL if the function succeeds.
237 * Returns a Result Error if the function fails in a non-fatal way.
238 * Returns a Fatal Error if the function fails in an unrecoverable way.
239 */
240 PKIX_Error *
241 PKIX_PolicyNode_GetChildren(
242 PKIX_PolicyNode *node,
243 PKIX_List **pChildren, /* list of PKIX_PolicyNode */
244 void *plContext);
245
246 /*
247 * FUNCTION: PKIX_PolicyNode_GetParent
248 * DESCRIPTION:
249 *
250 * Retrieves the PolicyNode representing the parent node of the PolicyNode
251 * pointed to by "node" and stores it at "pParent". If "node" has no parent
252 * node, this function stores NULL at "pParent".
253 *
254 * PARAMETERS:
255 * "node"
256 * Address of PolicyNode whose parent node is to be stored.
257 * Must be non-NULL.
258 * "pParent"
259 * Address where object pointer will be stored. Must be non-NULL.
260 * "plContext"
261 * Platform-specific context pointer.
262 * THREAD SAFETY:
263 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
264 * RETURNS:
265 * Returns NULL if the function succeeds.
266 * Returns a Result Error if the function fails in a non-fatal way.
267 * Returns a Fatal Error if the function fails in an unrecoverable way.
268 */
269 PKIX_Error *
270 PKIX_PolicyNode_GetParent(
271 PKIX_PolicyNode *node,
272 PKIX_PolicyNode **pParent,
273 void *plContext);
274
275 /*
276 * FUNCTION: PKIX_PolicyNode_GetValidPolicy
277 * DESCRIPTION:
278 *
279 * Retrieves the OID representing the valid policy of the PolicyNode pointed
280 * to by "node" and stores it at "pValidPolicy".
281 *
282 * PARAMETERS:
283 * "node"
284 * Address of PolicyNode whose valid policy is to be stored.
285 * Must be non-NULL.
286 * "pValidPolicy"
287 * Address where object pointer will be stored. Must be non-NULL.
288 * "plContext"
289 * Platform-specific context pointer.
290 * THREAD SAFETY:
291 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
292 * RETURNS:
293 * Returns NULL if the function succeeds.
294 * Returns a Result Error if the function fails in a non-fatal way.
295 * Returns a Fatal Error if the function fails in an unrecoverable way.
296 */
297 PKIX_Error *
298 PKIX_PolicyNode_GetValidPolicy(
299 PKIX_PolicyNode *node,
300 PKIX_PL_OID **pValidPolicy,
301 void *plContext);
302
303 /*
304 * FUNCTION: PKIX_PolicyNode_GetPolicyQualifiers
305 * DESCRIPTION:
306 *
307 * Retrieves the List of CertPolicyQualifiers representing the policy
308 * qualifiers associated with the PolicyNode pointed to by "node" and stores
309 * it at "pQualifiers". If "node" has no policy qualifiers, this function
310 * stores an empty List at "pQualifiers".
311 *
312 * Note that the List returned by this function is immutable.
313 *
314 * PARAMETERS:
315 * "node"
316 * Address of PolicyNode whose policy qualifiers are to be stored.
317 * Must be non-NULL.
318 * "pQualifiers"
319 * Address where object pointer will be stored. Must be non-NULL.
320 * "plContext"
321 * Platform-specific context pointer.
322 * THREAD SAFETY:
323 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
324 * RETURNS:
325 * Returns NULL if the function succeeds.
326 * Returns a Result Error if the function fails in a non-fatal way.
327 * Returns a Fatal Error if the function fails in an unrecoverable way.
328 */
329 PKIX_Error *
330 PKIX_PolicyNode_GetPolicyQualifiers(
331 PKIX_PolicyNode *node,
332 PKIX_List **pQualifiers, /* list of PKIX_PL_CertPolicyQualifier */
333 void *plContext);
334
335 /*
336 * FUNCTION: PKIX_PolicyNode_GetExpectedPolicies
337 * DESCRIPTION:
338 *
339 * Retrieves the List of OIDs representing the expected policies associated
340 * with the PolicyNode pointed to by "node" and stores it at "pExpPolicies".
341 *
342 * Note that the List returned by this function is immutable.
343 *
344 * PARAMETERS:
345 * "node"
346 * Address of PolicyNode whose expected policies are to be stored.
347 * Must be non-NULL.
348 * "pExpPolicies"
349 * Address where object pointer will be stored. Must be non-NULL.
350 * "plContext"
351 * Platform-specific context pointer.
352 * THREAD SAFETY:
353 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
354 * RETURNS:
355 * Returns NULL if the function succeeds.
356 * Returns a Result Error if the function fails in a non-fatal way.
357 * Returns a Fatal Error if the function fails in an unrecoverable way.
358 */
359 PKIX_Error *
360 PKIX_PolicyNode_GetExpectedPolicies(
361 PKIX_PolicyNode *node,
362 PKIX_List **pExpPolicies, /* list of PKIX_PL_OID */
363 void *plContext);
364
365 /*
366 * FUNCTION: PKIX_PolicyNode_IsCritical
367 * DESCRIPTION:
368 *
369 * Checks the criticality field of the PolicyNode pointed to by "node" and
370 * stores the Boolean result at "pCritical".
371 *
372 * PARAMETERS:
373 * "node"
374 * Address of PolicyNode whose criticality field is examined.
375 * Must be non-NULL.
376 * "pCritical"
377 * Address where Boolean will be stored. Must be non-NULL.
378 * "plContext"
379 * Platform-specific context pointer.
380 * THREAD SAFETY:
381 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
382 * RETURNS:
383 * Returns NULL if the function succeeds.
384 * Returns a Result Error if the function fails in a non-fatal way.
385 * Returns a Fatal Error if the function fails in an unrecoverable way.
386 */
387 PKIX_Error *
388 PKIX_PolicyNode_IsCritical(
389 PKIX_PolicyNode *node,
390 PKIX_Boolean *pCritical,
391 void *plContext);
392
393 /*
394 * FUNCTION: PKIX_PolicyNode_GetDepth
395 * DESCRIPTION:
396 *
397 * Retrieves the depth component of the PolicyNode pointed to by "node" and
398 * stores it at "pDepth".
399 *
400 * PARAMETERS:
401 * "node"
402 * Address of PolicyNode whose depth component is to be stored.
403 * Must be non-NULL.
404 * "pDepth"
405 * Address where PKIX_UInt32 will be stored. Must be non-NULL.
406 * "plContext"
407 * Platform-specific context pointer.
408 * THREAD SAFETY:
409 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
410 * RETURNS:
411 * Returns NULL if the function succeeds.
412 * Returns a Result Error if the function fails in a non-fatal way.
413 * Returns a Fatal Error if the function fails in an unrecoverable way.
414 */
415 PKIX_Error *
416 PKIX_PolicyNode_GetDepth(
417 PKIX_PolicyNode *node,
418 PKIX_UInt32 *pDepth,
419 void *plContext);
420
421 #ifdef __cplusplus
422 }
423 #endif
424
425 #endif /* _PKIX_RESULTS_H */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial