1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_results.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,425 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines functions associated with the results used
1.9 + * by the top-level functions.
1.10 + *
1.11 + */
1.12 +
1.13 +#ifndef _PKIX_RESULTS_H
1.14 +#define _PKIX_RESULTS_H
1.15 +
1.16 +#include "pkixt.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +/* General
1.23 + *
1.24 + * Please refer to the libpkix Programmer's Guide for detailed information
1.25 + * about how to use the libpkix library. Certain key warnings and notices from
1.26 + * that document are repeated here for emphasis.
1.27 + *
1.28 + * All identifiers in this file (and all public identifiers defined in
1.29 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.30 + * within the library begin with "pkix_".
1.31 + *
1.32 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.33 + *
1.34 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.35 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.36 + * shared object. Therefore, the caller should treat this shared object as
1.37 + * read-only and should not modify this shared object. When done using the
1.38 + * shared object, the caller should release the reference to the object by
1.39 + * using the PKIX_PL_Object_DecRef function.
1.40 + *
1.41 + * While a function is executing, if its arguments (or anything referred to by
1.42 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.43 + * is undefined.
1.44 + *
1.45 + */
1.46 +/* PKIX_ValidateResult
1.47 + *
1.48 + * PKIX_ValidateResult represents the result of a PKIX_ValidateChain call. It
1.49 + * consists of the valid policy tree and public key resulting from validation,
1.50 + * as well as the trust anchor used for this chain. Once created, a
1.51 + * ValidateResult object is immutable.
1.52 + */
1.53 +
1.54 +/*
1.55 + * FUNCTION: PKIX_ValidateResult_GetPolicyTree
1.56 + * DESCRIPTION:
1.57 + *
1.58 + * Retrieves the PolicyNode component (representing the valid_policy_tree)
1.59 + * from the ValidateResult object pointed to by "result" and stores it at
1.60 + * "pPolicyTree".
1.61 + *
1.62 + * PARAMETERS:
1.63 + * "result"
1.64 + * Address of ValidateResult whose policy tree is to be stored. Must be
1.65 + * non-NULL.
1.66 + * "pPolicyTree"
1.67 + * Address where object pointer will be stored. Must be non-NULL.
1.68 + * "plContext"
1.69 + * Platform-specific context pointer.
1.70 + * THREAD SAFETY:
1.71 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.72 + * RETURNS:
1.73 + * Returns NULL if the function succeeds.
1.74 + * Returns a Result Error if the function fails in a non-fatal way.
1.75 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.76 + */
1.77 +PKIX_Error *
1.78 +PKIX_ValidateResult_GetPolicyTree(
1.79 + PKIX_ValidateResult *result,
1.80 + PKIX_PolicyNode **pPolicyTree,
1.81 + void *plContext);
1.82 +
1.83 +/*
1.84 + * FUNCTION: PKIX_ValidateResult_GetPublicKey
1.85 + * DESCRIPTION:
1.86 + *
1.87 + * Retrieves the PublicKey component (representing the valid public_key) of
1.88 + * the ValidateResult object pointed to by "result" and stores it at
1.89 + * "pPublicKey".
1.90 + *
1.91 + * PARAMETERS:
1.92 + * "result"
1.93 + * Address of ValidateResult whose public key is to be stored.
1.94 + * Must be non-NULL.
1.95 + * "pPublicKey"
1.96 + * Address where object pointer will be stored. Must be non-NULL.
1.97 + * "plContext"
1.98 + * Platform-specific context pointer.
1.99 + * THREAD SAFETY:
1.100 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.101 + * RETURNS:
1.102 + * Returns NULL if the function succeeds.
1.103 + * Returns a Result Error if the function fails in a non-fatal way.
1.104 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.105 + */
1.106 +PKIX_Error *
1.107 +PKIX_ValidateResult_GetPublicKey(
1.108 + PKIX_ValidateResult *result,
1.109 + PKIX_PL_PublicKey **pPublicKey,
1.110 + void *plContext);
1.111 +
1.112 +/*
1.113 + * FUNCTION: PKIX_ValidateResult_GetTrustAnchor
1.114 + * DESCRIPTION:
1.115 + *
1.116 + * Retrieves the TrustAnchor component (representing the trust anchor used
1.117 + * during chain validation) of the ValidateResult object pointed to by
1.118 + * "result" and stores it at "pTrustAnchor".
1.119 + *
1.120 + * PARAMETERS:
1.121 + * "result"
1.122 + * Address of ValidateResult whose trust anchor is to be stored.
1.123 + * Must be non-NULL.
1.124 + * "pTrustAnchor"
1.125 + * Address where object pointer will be stored. Must be non-NULL.
1.126 + * "plContext"
1.127 + * Platform-specific context pointer.
1.128 + * THREAD SAFETY:
1.129 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.130 + * RETURNS:
1.131 + * Returns NULL if the function succeeds.
1.132 + * Returns a Result Error if the function fails in a non-fatal way.
1.133 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.134 + */
1.135 +PKIX_Error *
1.136 +PKIX_ValidateResult_GetTrustAnchor(
1.137 + PKIX_ValidateResult *result,
1.138 + PKIX_TrustAnchor **pTrustAnchor,
1.139 + void *plContext);
1.140 +
1.141 +/* PKIX_BuildResult
1.142 + *
1.143 + * PKIX_BuildResult represents the result of a PKIX_BuildChain call. It
1.144 + * consists of a ValidateResult object, as well as the built and validated
1.145 + * CertChain. Once created, a BuildResult object is immutable.
1.146 + */
1.147 +
1.148 +/*
1.149 + * FUNCTION: PKIX_BuildResult_GetValidateResult
1.150 + * DESCRIPTION:
1.151 + *
1.152 + * Retrieves the ValidateResult component (representing the build's validate
1.153 + * result) of the BuildResult object pointed to by "result" and stores it at
1.154 + * "pResult".
1.155 + *
1.156 + * PARAMETERS:
1.157 + * "result"
1.158 + * Address of BuildResult whose ValidateResult component is to be stored.
1.159 + * Must be non-NULL.
1.160 + * "pResult"
1.161 + * Address where object pointer will be stored. Must be non-NULL.
1.162 + * "plContext"
1.163 + * Platform-specific context pointer.
1.164 + * THREAD SAFETY:
1.165 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.166 + * RETURNS:
1.167 + * Returns NULL if the function succeeds.
1.168 + * Returns a Result Error if the function fails in a non-fatal way.
1.169 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.170 + */
1.171 +PKIX_Error *
1.172 +PKIX_BuildResult_GetValidateResult(
1.173 + PKIX_BuildResult *result,
1.174 + PKIX_ValidateResult **pResult,
1.175 + void *plContext);
1.176 +
1.177 +/*
1.178 + * FUNCTION: PKIX_BuildResult_GetCertChain
1.179 + * DESCRIPTION:
1.180 + *
1.181 + * Retrieves the List of Certs (certChain) component (representing the built
1.182 + * and validated CertChain) of the BuildResult object pointed to by "result"
1.183 + * and stores it at "pChain".
1.184 + *
1.185 + * PARAMETERS:
1.186 + * "result"
1.187 + * Address of BuildResult whose CertChain component is to be stored.
1.188 + * Must be non-NULL.
1.189 + * "pChain"
1.190 + * Address where object pointer will be stored. Must be non-NULL.
1.191 + * "plContext"
1.192 + * Platform-specific context pointer.
1.193 + * THREAD SAFETY:
1.194 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.195 + * RETURNS:
1.196 + * Returns NULL if the function succeeds.
1.197 + * Returns a Result Error if the function fails in a non-fatal way.
1.198 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.199 + */
1.200 +PKIX_Error *
1.201 +PKIX_BuildResult_GetCertChain(
1.202 + PKIX_BuildResult *result,
1.203 + PKIX_List **pChain,
1.204 + void *plContext);
1.205 +
1.206 +/* PKIX_PolicyNode
1.207 + *
1.208 + * PKIX_PolicyNode represents a node in the policy tree returned in
1.209 + * ValidateResult. The policy tree is the same length as the validated
1.210 + * certificate chain and the nodes are associated with a particular depth
1.211 + * (corresponding to a particular certificate in the chain).
1.212 + * PKIX_ValidateResult_GetPolicyTree returns the root node of the valid policy
1.213 + * tree. Other nodes can be accessed using the getChildren and getParents
1.214 + * functions, and individual elements of a node can be accessed with the
1.215 + * appropriate gettors. Once created, a PolicyNode is immutable.
1.216 + */
1.217 +
1.218 +/*
1.219 + * FUNCTION: PKIX_PolicyNode_GetChildren
1.220 + * DESCRIPTION:
1.221 + *
1.222 + * Retrieves the List of PolicyNodes representing the child nodes of the
1.223 + * Policy Node pointed to by "node" and stores it at "pChildren". If "node"
1.224 + * has no child nodes, this function stores an empty List at "pChildren".
1.225 + *
1.226 + * Note that the List returned by this function is immutable.
1.227 + *
1.228 + * PARAMETERS:
1.229 + * "node"
1.230 + * Address of PolicyNode whose child nodes are to be stored.
1.231 + * Must be non-NULL.
1.232 + * "pChildren"
1.233 + * Address where object pointer will be stored. Must be non-NULL.
1.234 + * "plContext"
1.235 + * Platform-specific context pointer.
1.236 + * THREAD SAFETY:
1.237 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.238 + * RETURNS:
1.239 + * Returns NULL if the function succeeds.
1.240 + * Returns a Result Error if the function fails in a non-fatal way.
1.241 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.242 + */
1.243 +PKIX_Error *
1.244 +PKIX_PolicyNode_GetChildren(
1.245 + PKIX_PolicyNode *node,
1.246 + PKIX_List **pChildren, /* list of PKIX_PolicyNode */
1.247 + void *plContext);
1.248 +
1.249 +/*
1.250 + * FUNCTION: PKIX_PolicyNode_GetParent
1.251 + * DESCRIPTION:
1.252 + *
1.253 + * Retrieves the PolicyNode representing the parent node of the PolicyNode
1.254 + * pointed to by "node" and stores it at "pParent". If "node" has no parent
1.255 + * node, this function stores NULL at "pParent".
1.256 + *
1.257 + * PARAMETERS:
1.258 + * "node"
1.259 + * Address of PolicyNode whose parent node is to be stored.
1.260 + * Must be non-NULL.
1.261 + * "pParent"
1.262 + * Address where object pointer will be stored. Must be non-NULL.
1.263 + * "plContext"
1.264 + * Platform-specific context pointer.
1.265 + * THREAD SAFETY:
1.266 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.267 + * RETURNS:
1.268 + * Returns NULL if the function succeeds.
1.269 + * Returns a Result Error if the function fails in a non-fatal way.
1.270 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.271 + */
1.272 +PKIX_Error *
1.273 +PKIX_PolicyNode_GetParent(
1.274 + PKIX_PolicyNode *node,
1.275 + PKIX_PolicyNode **pParent,
1.276 + void *plContext);
1.277 +
1.278 +/*
1.279 + * FUNCTION: PKIX_PolicyNode_GetValidPolicy
1.280 + * DESCRIPTION:
1.281 + *
1.282 + * Retrieves the OID representing the valid policy of the PolicyNode pointed
1.283 + * to by "node" and stores it at "pValidPolicy".
1.284 + *
1.285 + * PARAMETERS:
1.286 + * "node"
1.287 + * Address of PolicyNode whose valid policy is to be stored.
1.288 + * Must be non-NULL.
1.289 + * "pValidPolicy"
1.290 + * Address where object pointer will be stored. Must be non-NULL.
1.291 + * "plContext"
1.292 + * Platform-specific context pointer.
1.293 + * THREAD SAFETY:
1.294 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.295 + * RETURNS:
1.296 + * Returns NULL if the function succeeds.
1.297 + * Returns a Result Error if the function fails in a non-fatal way.
1.298 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.299 + */
1.300 +PKIX_Error *
1.301 +PKIX_PolicyNode_GetValidPolicy(
1.302 + PKIX_PolicyNode *node,
1.303 + PKIX_PL_OID **pValidPolicy,
1.304 + void *plContext);
1.305 +
1.306 +/*
1.307 + * FUNCTION: PKIX_PolicyNode_GetPolicyQualifiers
1.308 + * DESCRIPTION:
1.309 + *
1.310 + * Retrieves the List of CertPolicyQualifiers representing the policy
1.311 + * qualifiers associated with the PolicyNode pointed to by "node" and stores
1.312 + * it at "pQualifiers". If "node" has no policy qualifiers, this function
1.313 + * stores an empty List at "pQualifiers".
1.314 + *
1.315 + * Note that the List returned by this function is immutable.
1.316 + *
1.317 + * PARAMETERS:
1.318 + * "node"
1.319 + * Address of PolicyNode whose policy qualifiers are to be stored.
1.320 + * Must be non-NULL.
1.321 + * "pQualifiers"
1.322 + * Address where object pointer will be stored. Must be non-NULL.
1.323 + * "plContext"
1.324 + * Platform-specific context pointer.
1.325 + * THREAD SAFETY:
1.326 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.327 + * RETURNS:
1.328 + * Returns NULL if the function succeeds.
1.329 + * Returns a Result Error if the function fails in a non-fatal way.
1.330 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.331 + */
1.332 +PKIX_Error *
1.333 +PKIX_PolicyNode_GetPolicyQualifiers(
1.334 + PKIX_PolicyNode *node,
1.335 + PKIX_List **pQualifiers, /* list of PKIX_PL_CertPolicyQualifier */
1.336 + void *plContext);
1.337 +
1.338 +/*
1.339 + * FUNCTION: PKIX_PolicyNode_GetExpectedPolicies
1.340 + * DESCRIPTION:
1.341 + *
1.342 + * Retrieves the List of OIDs representing the expected policies associated
1.343 + * with the PolicyNode pointed to by "node" and stores it at "pExpPolicies".
1.344 + *
1.345 + * Note that the List returned by this function is immutable.
1.346 + *
1.347 + * PARAMETERS:
1.348 + * "node"
1.349 + * Address of PolicyNode whose expected policies are to be stored.
1.350 + * Must be non-NULL.
1.351 + * "pExpPolicies"
1.352 + * Address where object pointer will be stored. Must be non-NULL.
1.353 + * "plContext"
1.354 + * Platform-specific context pointer.
1.355 + * THREAD SAFETY:
1.356 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.357 + * RETURNS:
1.358 + * Returns NULL if the function succeeds.
1.359 + * Returns a Result Error if the function fails in a non-fatal way.
1.360 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.361 + */
1.362 +PKIX_Error *
1.363 +PKIX_PolicyNode_GetExpectedPolicies(
1.364 + PKIX_PolicyNode *node,
1.365 + PKIX_List **pExpPolicies, /* list of PKIX_PL_OID */
1.366 + void *plContext);
1.367 +
1.368 +/*
1.369 + * FUNCTION: PKIX_PolicyNode_IsCritical
1.370 + * DESCRIPTION:
1.371 + *
1.372 + * Checks the criticality field of the PolicyNode pointed to by "node" and
1.373 + * stores the Boolean result at "pCritical".
1.374 + *
1.375 + * PARAMETERS:
1.376 + * "node"
1.377 + * Address of PolicyNode whose criticality field is examined.
1.378 + * Must be non-NULL.
1.379 + * "pCritical"
1.380 + * Address where Boolean will be stored. Must be non-NULL.
1.381 + * "plContext"
1.382 + * Platform-specific context pointer.
1.383 + * THREAD SAFETY:
1.384 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.385 + * RETURNS:
1.386 + * Returns NULL if the function succeeds.
1.387 + * Returns a Result Error if the function fails in a non-fatal way.
1.388 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.389 + */
1.390 +PKIX_Error *
1.391 +PKIX_PolicyNode_IsCritical(
1.392 + PKIX_PolicyNode *node,
1.393 + PKIX_Boolean *pCritical,
1.394 + void *plContext);
1.395 +
1.396 +/*
1.397 + * FUNCTION: PKIX_PolicyNode_GetDepth
1.398 + * DESCRIPTION:
1.399 + *
1.400 + * Retrieves the depth component of the PolicyNode pointed to by "node" and
1.401 + * stores it at "pDepth".
1.402 + *
1.403 + * PARAMETERS:
1.404 + * "node"
1.405 + * Address of PolicyNode whose depth component is to be stored.
1.406 + * Must be non-NULL.
1.407 + * "pDepth"
1.408 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.409 + * "plContext"
1.410 + * Platform-specific context pointer.
1.411 + * THREAD SAFETY:
1.412 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.413 + * RETURNS:
1.414 + * Returns NULL if the function succeeds.
1.415 + * Returns a Result Error if the function fails in a non-fatal way.
1.416 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.417 + */
1.418 +PKIX_Error *
1.419 +PKIX_PolicyNode_GetDepth(
1.420 + PKIX_PolicyNode *node,
1.421 + PKIX_UInt32 *pDepth,
1.422 + void *plContext);
1.423 +
1.424 +#ifdef __cplusplus
1.425 +}
1.426 +#endif
1.427 +
1.428 +#endif /* _PKIX_RESULTS_H */
