summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/libpkix/include/pkix_results.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_results.h')
-rwxr-xr-xsecurity/nss/lib/libpkix/include/pkix_results.h425
1 files changed, 425 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_results.h b/security/nss/lib/libpkix/include/pkix_results.h
new file mode 100755
index 000000000..bf4a381fa
--- /dev/null
+++ b/security/nss/lib/libpkix/include/pkix_results.h
@@ -0,0 +1,425 @@
+/* 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 */