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