The Tor Browser: security/nss/lib/libpkix/include/pkix

security/nss/lib/libpkix/include/pkix_results.h@b8a032363ba2 (annotated)

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

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rwxr-xr-x

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 /*
  * This file defines functions associated with the results used
  * by the top-level functions.
  *
  */
 #ifndef _PKIX_RESULTS_H
 #define _PKIX_RESULTS_H
 #include "pkixt.h"
 #ifdef __cplusplus
 extern "C" {
 #endif
 /* General
  *
  * Please refer to the libpkix Programmer's Guide for detailed information
  * about how to use the libpkix library. Certain key warnings and notices from
  * that document are repeated here for emphasis.
  *
  * All identifiers in this file (and all public identifiers defined in
  * libpkix) begin with "PKIX_". Private identifiers only intended for use
  * within the library begin with "pkix_".
  *
  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
  *
  * Unless otherwise noted, for all accessor (gettor) functions that return a
  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
  * shared object. Therefore, the caller should treat this shared object as
  * read-only and should not modify this shared object. When done using the
  * shared object, the caller should release the reference to the object by
  * using the PKIX_PL_Object_DecRef function.
  *
  * While a function is executing, if its arguments (or anything referred to by
  * its arguments) are modified, free'd, or destroyed, the function's behavior
  * is undefined.
  *
  */
 /* PKIX_ValidateResult
  *
  * PKIX_ValidateResult represents the result of a PKIX_ValidateChain call. It
  * consists of the valid policy tree and public key resulting from validation,
  * as well as the trust anchor used for this chain. Once created, a
  * ValidateResult object is immutable.
  */
 /*
  * FUNCTION: PKIX_ValidateResult_GetPolicyTree
  * DESCRIPTION:
  *
  *  Retrieves the PolicyNode component (representing the valid_policy_tree)
  *  from the ValidateResult object pointed to by "result" and stores it at
  *  "pPolicyTree".
  *
  * PARAMETERS:
  *  "result"
  *      Address of ValidateResult whose policy tree is to be stored. Must be
  *      non-NULL.
  *  "pPolicyTree"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_ValidateResult_GetPolicyTree(
         PKIX_ValidateResult *result,
         PKIX_PolicyNode **pPolicyTree,
         void *plContext);
 /*
  * FUNCTION: PKIX_ValidateResult_GetPublicKey
  * DESCRIPTION:
  *
  *  Retrieves the PublicKey component (representing the valid public_key) of
  *  the ValidateResult object pointed to by "result" and stores it at
  *  "pPublicKey".
  *
  * PARAMETERS:
  *  "result"
  *      Address of ValidateResult whose public key is to be stored.
  *      Must be non-NULL.
  *  "pPublicKey"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_ValidateResult_GetPublicKey(
         PKIX_ValidateResult *result,
         PKIX_PL_PublicKey **pPublicKey,
         void *plContext);
 /*
  * FUNCTION: PKIX_ValidateResult_GetTrustAnchor
  * DESCRIPTION:
  *
  *  Retrieves the TrustAnchor component (representing the trust anchor used
  *  during chain validation) of the ValidateResult object pointed to by
  *  "result" and stores it at "pTrustAnchor".
  *
  * PARAMETERS:
  *  "result"
  *      Address of ValidateResult whose trust anchor is to be stored.
  *      Must be non-NULL.
  *  "pTrustAnchor"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_ValidateResult_GetTrustAnchor(
         PKIX_ValidateResult *result,
         PKIX_TrustAnchor **pTrustAnchor,
         void *plContext);
 /* PKIX_BuildResult
  *
  * PKIX_BuildResult represents the result of a PKIX_BuildChain call. It
  * consists of a ValidateResult object, as well as the built and validated
  * CertChain. Once created, a BuildResult object is immutable.
  */
 /*
  * FUNCTION: PKIX_BuildResult_GetValidateResult
  * DESCRIPTION:
  *
  *  Retrieves the ValidateResult component (representing the build's validate
  *  result) of the BuildResult object pointed to by "result" and stores it at
  *  "pResult".
  *
  * PARAMETERS:
  *  "result"
  *      Address of BuildResult whose ValidateResult component is to be stored.
  *      Must be non-NULL.
  *  "pResult"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_BuildResult_GetValidateResult(
         PKIX_BuildResult *result,
         PKIX_ValidateResult **pResult,
         void *plContext);
 /*
  * FUNCTION: PKIX_BuildResult_GetCertChain
  * DESCRIPTION:
  *
  *  Retrieves the List of Certs (certChain) component (representing the built
  *  and validated CertChain) of the BuildResult object pointed to by "result"
  *  and stores it at "pChain".
  *
  * PARAMETERS:
  *  "result"
  *      Address of BuildResult whose CertChain component is to be stored.
  *      Must be non-NULL.
  *  "pChain"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_BuildResult_GetCertChain(
         PKIX_BuildResult *result,
         PKIX_List **pChain,
         void *plContext);
 /* PKIX_PolicyNode
  *
  * PKIX_PolicyNode represents a node in the policy tree returned in
  * ValidateResult. The policy tree is the same length as the validated
  * certificate chain and the nodes are associated with a particular depth
  * (corresponding to a particular certificate in the chain).
  * PKIX_ValidateResult_GetPolicyTree returns the root node of the valid policy
  * tree. Other nodes can be accessed using the getChildren and getParents
  * functions, and individual elements of a node can be accessed with the
  * appropriate gettors. Once created, a PolicyNode is immutable.
  */
 /*
  * FUNCTION: PKIX_PolicyNode_GetChildren
  * DESCRIPTION:
  *
  *  Retrieves the List of PolicyNodes representing the child nodes of the
  *  Policy Node pointed to by "node" and stores it at "pChildren". If "node"
  *  has no child nodes, this function stores an empty List at "pChildren".
  *
  *  Note that the List returned by this function is immutable.
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose child nodes are to be stored.
  *      Must be non-NULL.
  *  "pChildren"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetChildren(
         PKIX_PolicyNode *node,
         PKIX_List **pChildren,  /* list of PKIX_PolicyNode */
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_GetParent
  * DESCRIPTION:
  *
  *  Retrieves the PolicyNode representing the parent node of the PolicyNode
  *  pointed to by "node" and stores it at "pParent". If "node" has no parent
  *  node, this function stores NULL at "pParent".
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose parent node is to be stored.
  *      Must be non-NULL.
  *  "pParent"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetParent(
         PKIX_PolicyNode *node,
         PKIX_PolicyNode **pParent,
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_GetValidPolicy
  * DESCRIPTION:
  *
  *  Retrieves the OID representing the valid policy of the PolicyNode pointed
  *  to by "node" and stores it at "pValidPolicy".
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose valid policy is to be stored.
  *      Must be non-NULL.
  *  "pValidPolicy"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetValidPolicy(
         PKIX_PolicyNode *node,
         PKIX_PL_OID **pValidPolicy,
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_GetPolicyQualifiers
  * DESCRIPTION:
  *
  *  Retrieves the List of CertPolicyQualifiers representing the policy
  *  qualifiers associated with the PolicyNode pointed to by "node" and stores
  *  it at "pQualifiers". If "node" has no policy qualifiers, this function
  *  stores an empty List at "pQualifiers".
  *
  *  Note that the List returned by this function is immutable.
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose policy qualifiers are to be stored.
  *      Must be non-NULL.
  *  "pQualifiers"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetPolicyQualifiers(
         PKIX_PolicyNode *node,
         PKIX_List **pQualifiers,  /* list of PKIX_PL_CertPolicyQualifier */
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_GetExpectedPolicies
  * DESCRIPTION:
  *
  *  Retrieves the List of OIDs representing the expected policies associated
  *  with the PolicyNode pointed to by "node" and stores it at "pExpPolicies".
  *
  *  Note that the List returned by this function is immutable.
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose expected policies are to be stored.
  *      Must be non-NULL.
  *  "pExpPolicies"
  *      Address where object pointer will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetExpectedPolicies(
         PKIX_PolicyNode *node,
         PKIX_List **pExpPolicies,  /* list of PKIX_PL_OID */
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_IsCritical
  * DESCRIPTION:
  *
  *  Checks the criticality field of the PolicyNode pointed to by "node" and
  *  stores the Boolean result at "pCritical".
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose criticality field is examined.
  *      Must be non-NULL.
  *  "pCritical"
  *      Address where Boolean will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_IsCritical(
         PKIX_PolicyNode *node,
         PKIX_Boolean *pCritical,
         void *plContext);
 /*
  * FUNCTION: PKIX_PolicyNode_GetDepth
  * DESCRIPTION:
  *
  *  Retrieves the depth component of the PolicyNode pointed to by "node" and
  *  stores it at "pDepth".
  *
  * PARAMETERS:
  *  "node"
  *      Address of PolicyNode whose depth component is to be stored.
  *      Must be non-NULL.
  *  "pDepth"
  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
  *  "plContext"
  *      Platform-specific context pointer.
  * THREAD SAFETY:
  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  * RETURNS:
  *  Returns NULL if the function succeeds.
  *  Returns a Result Error if the function fails in a non-fatal way.
  *  Returns a Fatal Error if the function fails in an unrecoverable way.
  */
 PKIX_Error *
 PKIX_PolicyNode_GetDepth(
         PKIX_PolicyNode *node,
         PKIX_UInt32 *pDepth,
         void *plContext);
 #ifdef __cplusplus
 }
 #endif
 #endif /* _PKIX_RESULTS_H */

The Tor Browser / annotate

security/nss/lib/libpkix/include/pkix_results.h@b8a032363ba2 (annotated)

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