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