Delete bundled copy of NSS and replace with README.

nss/lib/libpkix/include/pkix_results.h

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