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