The Tor Browser: security/nss/lib/libpkix/include/pkix

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 /* This Source Code Form is subject to the terms of the Mozilla Public

     2  * License, v. 2.0. If a copy of the MPL was not distributed with this

     3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     4 /*

     5  * This file defines functions associated with the results used

     6  * by the top-level functions.

     7  *

     8  */

    10 #ifndef _PKIX_RESULTS_H

    11 #define _PKIX_RESULTS_H

    13 #include "pkixt.h"

    15 #ifdef __cplusplus

    16 extern "C" {

    17 #endif

    19 /* General

    20  *

    21  * Please refer to the libpkix Programmer's Guide for detailed information

    22  * about how to use the libpkix library. Certain key warnings and notices from

    23  * that document are repeated here for emphasis.

    24  *

    25  * All identifiers in this file (and all public identifiers defined in

    26  * libpkix) begin with "PKIX_". Private identifiers only intended for use

    27  * within the library begin with "pkix_".

    28  *

    29  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.

    30  *

    31  * Unless otherwise noted, for all accessor (gettor) functions that return a

    32  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a

    33  * shared object. Therefore, the caller should treat this shared object as

    34  * read-only and should not modify this shared object. When done using the

    35  * shared object, the caller should release the reference to the object by

    36  * using the PKIX_PL_Object_DecRef function.

    37  *

    38  * While a function is executing, if its arguments (or anything referred to by

    39  * its arguments) are modified, free'd, or destroyed, the function's behavior

    40  * is undefined.

    41  *

    42  */

    43 /* PKIX_ValidateResult

    44  *

    45  * PKIX_ValidateResult represents the result of a PKIX_ValidateChain call. It

    46  * consists of the valid policy tree and public key resulting from validation,

    47  * as well as the trust anchor used for this chain. Once created, a

    48  * ValidateResult object is immutable.

    49  */

    51 /*

    52  * FUNCTION: PKIX_ValidateResult_GetPolicyTree

    53  * DESCRIPTION:

    54  *

    55  *  Retrieves the PolicyNode component (representing the valid_policy_tree)

    56  *  from the ValidateResult object pointed to by "result" and stores it at

    57  *  "pPolicyTree".

    58  *

    59  * PARAMETERS:

    60  *  "result"

    61  *      Address of ValidateResult whose policy tree is to be stored. Must be

    62  *      non-NULL.

    63  *  "pPolicyTree"

    64  *      Address where object pointer will be stored. Must be non-NULL.

    65  *  "plContext"

    66  *      Platform-specific context pointer.

    67  * THREAD SAFETY:

    68  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

    69  * RETURNS:

    70  *  Returns NULL if the function succeeds.

    71  *  Returns a Result Error if the function fails in a non-fatal way.

    72  *  Returns a Fatal Error if the function fails in an unrecoverable way.

    73  */

    74 PKIX_Error *

    75 PKIX_ValidateResult_GetPolicyTree(

    76         PKIX_ValidateResult *result,

    77         PKIX_PolicyNode **pPolicyTree,

    78         void *plContext);

    80 /*

    81  * FUNCTION: PKIX_ValidateResult_GetPublicKey

    82  * DESCRIPTION:

    83  *

    84  *  Retrieves the PublicKey component (representing the valid public_key) of

    85  *  the ValidateResult object pointed to by "result" and stores it at

    86  *  "pPublicKey".

    87  *

    88  * PARAMETERS:

    89  *  "result"

    90  *      Address of ValidateResult whose public key is to be stored.

    91  *      Must be non-NULL.

    92  *  "pPublicKey"

    93  *      Address where object pointer will be stored. Must be non-NULL.

    94  *  "plContext"

    95  *      Platform-specific context pointer.

    96  * THREAD SAFETY:

    97  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

    98  * RETURNS:

    99  *  Returns NULL if the function succeeds.

   100  *  Returns a Result Error if the function fails in a non-fatal way.

   101  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   102  */

   103 PKIX_Error *

   104 PKIX_ValidateResult_GetPublicKey(

   105         PKIX_ValidateResult *result,

   106         PKIX_PL_PublicKey **pPublicKey,

   107         void *plContext);

   109 /*

   110  * FUNCTION: PKIX_ValidateResult_GetTrustAnchor

   111  * DESCRIPTION:

   112  *

   113  *  Retrieves the TrustAnchor component (representing the trust anchor used

   114  *  during chain validation) of the ValidateResult object pointed to by

   115  *  "result" and stores it at "pTrustAnchor".

   116  *

   117  * PARAMETERS:

   118  *  "result"

   119  *      Address of ValidateResult whose trust anchor is to be stored.

   120  *      Must be non-NULL.

   121  *  "pTrustAnchor"

   122  *      Address where object pointer will be stored. Must be non-NULL.

   123  *  "plContext"

   124  *      Platform-specific context pointer.

   125  * THREAD SAFETY:

   126  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   127  * RETURNS:

   128  *  Returns NULL if the function succeeds.

   129  *  Returns a Result Error if the function fails in a non-fatal way.

   130  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   131  */

   132 PKIX_Error *

   133 PKIX_ValidateResult_GetTrustAnchor(

   134         PKIX_ValidateResult *result,

   135         PKIX_TrustAnchor **pTrustAnchor,

   136         void *plContext);

   138 /* PKIX_BuildResult

   139  *

   140  * PKIX_BuildResult represents the result of a PKIX_BuildChain call. It

   141  * consists of a ValidateResult object, as well as the built and validated

   142  * CertChain. Once created, a BuildResult object is immutable.

   143  */

   145 /*

   146  * FUNCTION: PKIX_BuildResult_GetValidateResult

   147  * DESCRIPTION:

   148  *

   149  *  Retrieves the ValidateResult component (representing the build's validate

   150  *  result) of the BuildResult object pointed to by "result" and stores it at

   151  *  "pResult".

   152  *

   153  * PARAMETERS:

   154  *  "result"

   155  *      Address of BuildResult whose ValidateResult component is to be stored.

   156  *      Must be non-NULL.

   157  *  "pResult"

   158  *      Address where object pointer will be stored. Must be non-NULL.

   159  *  "plContext"

   160  *      Platform-specific context pointer.

   161  * THREAD SAFETY:

   162  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   163  * RETURNS:

   164  *  Returns NULL if the function succeeds.

   165  *  Returns a Result Error if the function fails in a non-fatal way.

   166  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   167  */

   168 PKIX_Error *

   169 PKIX_BuildResult_GetValidateResult(

   170         PKIX_BuildResult *result,

   171         PKIX_ValidateResult **pResult,

   172         void *plContext);

   174 /*

   175  * FUNCTION: PKIX_BuildResult_GetCertChain

   176  * DESCRIPTION:

   177  *

   178  *  Retrieves the List of Certs (certChain) component (representing the built

   179  *  and validated CertChain) of the BuildResult object pointed to by "result"

   180  *  and stores it at "pChain".

   181  *

   182  * PARAMETERS:

   183  *  "result"

   184  *      Address of BuildResult whose CertChain component is to be stored.

   185  *      Must be non-NULL.

   186  *  "pChain"

   187  *      Address where object pointer will be stored. Must be non-NULL.

   188  *  "plContext"

   189  *      Platform-specific context pointer.

   190  * THREAD SAFETY:

   191  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   192  * RETURNS:

   193  *  Returns NULL if the function succeeds.

   194  *  Returns a Result Error if the function fails in a non-fatal way.

   195  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   196  */

   197 PKIX_Error *

   198 PKIX_BuildResult_GetCertChain(

   199         PKIX_BuildResult *result,

   200         PKIX_List **pChain,

   201         void *plContext);

   203 /* PKIX_PolicyNode

   204  *

   205  * PKIX_PolicyNode represents a node in the policy tree returned in

   206  * ValidateResult. The policy tree is the same length as the validated

   207  * certificate chain and the nodes are associated with a particular depth

   208  * (corresponding to a particular certificate in the chain).

   209  * PKIX_ValidateResult_GetPolicyTree returns the root node of the valid policy

   210  * tree. Other nodes can be accessed using the getChildren and getParents

   211  * functions, and individual elements of a node can be accessed with the

   212  * appropriate gettors. Once created, a PolicyNode is immutable.

   213  */

   215 /*

   216  * FUNCTION: PKIX_PolicyNode_GetChildren

   217  * DESCRIPTION:

   218  *

   219  *  Retrieves the List of PolicyNodes representing the child nodes of the

   220  *  Policy Node pointed to by "node" and stores it at "pChildren". If "node"

   221  *  has no child nodes, this function stores an empty List at "pChildren".

   222  *

   223  *  Note that the List returned by this function is immutable.

   224  *

   225  * PARAMETERS:

   226  *  "node"

   227  *      Address of PolicyNode whose child nodes are to be stored.

   228  *      Must be non-NULL.

   229  *  "pChildren"

   230  *      Address where object pointer will be stored. Must be non-NULL.

   231  *  "plContext"

   232  *      Platform-specific context pointer.

   233  * THREAD SAFETY:

   234  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   235  * RETURNS:

   236  *  Returns NULL if the function succeeds.

   237  *  Returns a Result Error if the function fails in a non-fatal way.

   238  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   239  */

   240 PKIX_Error *

   241 PKIX_PolicyNode_GetChildren(

   242         PKIX_PolicyNode *node,

   243         PKIX_List **pChildren,  /* list of PKIX_PolicyNode */

   244         void *plContext);

   246 /*

   247  * FUNCTION: PKIX_PolicyNode_GetParent

   248  * DESCRIPTION:

   249  *

   250  *  Retrieves the PolicyNode representing the parent node of the PolicyNode

   251  *  pointed to by "node" and stores it at "pParent". If "node" has no parent

   252  *  node, this function stores NULL at "pParent".

   253  *

   254  * PARAMETERS:

   255  *  "node"

   256  *      Address of PolicyNode whose parent node is to be stored.

   257  *      Must be non-NULL.

   258  *  "pParent"

   259  *      Address where object pointer will be stored. Must be non-NULL.

   260  *  "plContext"

   261  *      Platform-specific context pointer.

   262  * THREAD SAFETY:

   263  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   264  * RETURNS:

   265  *  Returns NULL if the function succeeds.

   266  *  Returns a Result Error if the function fails in a non-fatal way.

   267  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   268  */

   269 PKIX_Error *

   270 PKIX_PolicyNode_GetParent(

   271         PKIX_PolicyNode *node,

   272         PKIX_PolicyNode **pParent,

   273         void *plContext);

   275 /*

   276  * FUNCTION: PKIX_PolicyNode_GetValidPolicy

   277  * DESCRIPTION:

   278  *

   279  *  Retrieves the OID representing the valid policy of the PolicyNode pointed

   280  *  to by "node" and stores it at "pValidPolicy".

   281  *

   282  * PARAMETERS:

   283  *  "node"

   284  *      Address of PolicyNode whose valid policy is to be stored.

   285  *      Must be non-NULL.

   286  *  "pValidPolicy"

   287  *      Address where object pointer will be stored. Must be non-NULL.

   288  *  "plContext"

   289  *      Platform-specific context pointer.

   290  * THREAD SAFETY:

   291  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   292  * RETURNS:

   293  *  Returns NULL if the function succeeds.

   294  *  Returns a Result Error if the function fails in a non-fatal way.

   295  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   296  */

   297 PKIX_Error *

   298 PKIX_PolicyNode_GetValidPolicy(

   299         PKIX_PolicyNode *node,

   300         PKIX_PL_OID **pValidPolicy,

   301         void *plContext);

   303 /*

   304  * FUNCTION: PKIX_PolicyNode_GetPolicyQualifiers

   305  * DESCRIPTION:

   306  *

   307  *  Retrieves the List of CertPolicyQualifiers representing the policy

   308  *  qualifiers associated with the PolicyNode pointed to by "node" and stores

   309  *  it at "pQualifiers". If "node" has no policy qualifiers, this function

   310  *  stores an empty List at "pQualifiers".

   311  *

   312  *  Note that the List returned by this function is immutable.

   313  *

   314  * PARAMETERS:

   315  *  "node"

   316  *      Address of PolicyNode whose policy qualifiers are to be stored.

   317  *      Must be non-NULL.

   318  *  "pQualifiers"

   319  *      Address where object pointer will be stored. Must be non-NULL.

   320  *  "plContext"

   321  *      Platform-specific context pointer.

   322  * THREAD SAFETY:

   323  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   324  * RETURNS:

   325  *  Returns NULL if the function succeeds.

   326  *  Returns a Result Error if the function fails in a non-fatal way.

   327  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   328  */

   329 PKIX_Error *

   330 PKIX_PolicyNode_GetPolicyQualifiers(

   331         PKIX_PolicyNode *node,

   332         PKIX_List **pQualifiers,  /* list of PKIX_PL_CertPolicyQualifier */

   333         void *plContext);

   335 /*

   336  * FUNCTION: PKIX_PolicyNode_GetExpectedPolicies

   337  * DESCRIPTION:

   338  *

   339  *  Retrieves the List of OIDs representing the expected policies associated

   340  *  with the PolicyNode pointed to by "node" and stores it at "pExpPolicies".

   341  *

   342  *  Note that the List returned by this function is immutable.

   343  *

   344  * PARAMETERS:

   345  *  "node"

   346  *      Address of PolicyNode whose expected policies are to be stored.

   347  *      Must be non-NULL.

   348  *  "pExpPolicies"

   349  *      Address where object pointer will be stored. Must be non-NULL.

   350  *  "plContext"

   351  *      Platform-specific context pointer.

   352  * THREAD SAFETY:

   353  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   354  * RETURNS:

   355  *  Returns NULL if the function succeeds.

   356  *  Returns a Result Error if the function fails in a non-fatal way.

   357  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   358  */

   359 PKIX_Error *

   360 PKIX_PolicyNode_GetExpectedPolicies(

   361         PKIX_PolicyNode *node,

   362         PKIX_List **pExpPolicies,  /* list of PKIX_PL_OID */

   363         void *plContext);

   365 /*

   366  * FUNCTION: PKIX_PolicyNode_IsCritical

   367  * DESCRIPTION:

   368  *

   369  *  Checks the criticality field of the PolicyNode pointed to by "node" and

   370  *  stores the Boolean result at "pCritical".

   371  *

   372  * PARAMETERS:

   373  *  "node"

   374  *      Address of PolicyNode whose criticality field is examined.

   375  *      Must be non-NULL.

   376  *  "pCritical"

   377  *      Address where Boolean will be stored. Must be non-NULL.

   378  *  "plContext"

   379  *      Platform-specific context pointer.

   380  * THREAD SAFETY:

   381  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   382  * RETURNS:

   383  *  Returns NULL if the function succeeds.

   384  *  Returns a Result Error if the function fails in a non-fatal way.

   385  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   386  */

   387 PKIX_Error *

   388 PKIX_PolicyNode_IsCritical(

   389         PKIX_PolicyNode *node,

   390         PKIX_Boolean *pCritical,

   391         void *plContext);

   393 /*

   394  * FUNCTION: PKIX_PolicyNode_GetDepth

   395  * DESCRIPTION:

   396  *

   397  *  Retrieves the depth component of the PolicyNode pointed to by "node" and

   398  *  stores it at "pDepth".

   399  *

   400  * PARAMETERS:

   401  *  "node"

   402  *      Address of PolicyNode whose depth component is to be stored.

   403  *      Must be non-NULL.

   404  *  "pDepth"

   405  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.

   406  *  "plContext"

   407  *      Platform-specific context pointer.

   408  * THREAD SAFETY:

   409  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)

   410  * RETURNS:

   411  *  Returns NULL if the function succeeds.

   412  *  Returns a Result Error if the function fails in a non-fatal way.

   413  *  Returns a Fatal Error if the function fails in an unrecoverable way.

   414  */

   415 PKIX_Error *

   416 PKIX_PolicyNode_GetDepth(

   417         PKIX_PolicyNode *node,

   418         PKIX_UInt32 *pDepth,

   419         void *plContext);

   421 #ifdef __cplusplus

   422 }

   423 #endif

   425 #endif /* _PKIX_RESULTS_H */

The Tor Browser / file revision

security/nss/lib/libpkix/include/pkix_results.h@b8a032363ba2

security/nss/lib/libpkix/include/pkix_results.h