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