tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

pkix_results.h (14296B)

      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 */