mirror of
https://github.com/rn10950/RetroZilla.git
synced 2024-11-15 04:00:12 +01:00
426 lines
14 KiB
C
426 lines
14 KiB
C
/* 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 */
|