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

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the PKIX-C library.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Sun Microsystems, Inc.
  18  * Portions created by the Initial Developer are
  19  * Copyright 2004-2007 Sun Microsystems, Inc.  All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Sun Microsystems, Inc.
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37 /*
  38  * This file defines functions associated with the results used
  39  * by the top-level functions.
  40  *
  41  */
  42
  43 #ifndef _PKIX_RESULTS_H
  44 #define _PKIX_RESULTS_H
  45
  46 #include "pkixt.h"
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /* General
  53  *
  54  * Please refer to the libpkix Programmer's Guide for detailed information
  55  * about how to use the libpkix library. Certain key warnings and notices from
  56  * that document are repeated here for emphasis.
  57  *
  58  * All identifiers in this file (and all public identifiers defined in
  59  * libpkix) begin with "PKIX_". Private identifiers only intended for use
  60  * within the library begin with "pkix_".
  61  *
  62  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
  63  *
  64  * Unless otherwise noted, for all accessor (gettor) functions that return a
  65  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
  66  * shared object. Therefore, the caller should treat this shared object as
  67  * read-only and should not modify this shared object. When done using the
  68  * shared object, the caller should release the reference to the object by
  69  * using the PKIX_PL_Object_DecRef function.
  70  *
  71  * While a function is executing, if its arguments (or anything referred to by
  72  * its arguments) are modified, free'd, or destroyed, the function's behavior
  73  * is undefined.
  74  *
  75  */
  76 /* PKIX_ValidateResult
  77  *
  78  * PKIX_ValidateResult represents the result of a PKIX_ValidateChain call. It
  79  * consists of the valid policy tree and public key resulting from validation,
  80  * as well as the trust anchor used for this chain. Once created, a
  81  * ValidateResult object is immutable.
  82  */
  83
  84 /*
  85  * FUNCTION: PKIX_ValidateResult_GetPolicyTree
  86  * DESCRIPTION:
  87  *
  88  *  Retrieves the PolicyNode component (representing the valid_policy_tree)
  89  *  from the ValidateResult object pointed to by "result" and stores it at
  90  *  "pPolicyTree".
  91  *
  92  * PARAMETERS:
  93  *  "result"
  94  *      Address of ValidateResult whose policy tree is to be stored. Must be
  95  *      non-NULL.
  96  *  "pPolicyTree"
  97  *      Address where object pointer will be stored. Must be non-NULL.
  98  *  "plContext"
  99  *      Platform-specific context pointer.
 100  * THREAD SAFETY:
 101  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 102  * RETURNS:
 103  *  Returns NULL if the function succeeds.
 104  *  Returns a Result Error if the function fails in a non-fatal way.
 105  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 106  */
 107 PKIX_Error *
 108 PKIX_ValidateResult_GetPolicyTree(
 109         PKIX_ValidateResult *result,
 110         PKIX_PolicyNode **pPolicyTree,
 111         void *plContext);
 112
 113 /*
 114  * FUNCTION: PKIX_ValidateResult_GetPublicKey
 115  * DESCRIPTION:
 116  *
 117  *  Retrieves the PublicKey component (representing the valid public_key) of
 118  *  the ValidateResult object pointed to by "result" and stores it at
 119  *  "pPublicKey".
 120  *
 121  * PARAMETERS:
 122  *  "result"
 123  *      Address of ValidateResult whose public key is to be stored.
 124  *      Must be non-NULL.
 125  *  "pPublicKey"
 126  *      Address where object pointer will be stored. Must be non-NULL.
 127  *  "plContext"
 128  *      Platform-specific context pointer.
 129  * THREAD SAFETY:
 130  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 131  * RETURNS:
 132  *  Returns NULL if the function succeeds.
 133  *  Returns a Result Error if the function fails in a non-fatal way.
 134  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 135  */
 136 PKIX_Error *
 137 PKIX_ValidateResult_GetPublicKey(
 138         PKIX_ValidateResult *result,
 139         PKIX_PL_PublicKey **pPublicKey,
 140         void *plContext);
 141
 142 /*
 143  * FUNCTION: PKIX_ValidateResult_GetTrustAnchor
 144  * DESCRIPTION:
 145  *
 146  *  Retrieves the TrustAnchor component (representing the trust anchor used
 147  *  during chain validation) of the ValidateResult object pointed to by
 148  *  "result" and stores it at "pTrustAnchor".
 149  *
 150  * PARAMETERS:
 151  *  "result"
 152  *      Address of ValidateResult whose trust anchor is to be stored.
 153  *      Must be non-NULL.
 154  *  "pTrustAnchor"
 155  *      Address where object pointer will be stored. Must be non-NULL.
 156  *  "plContext"
 157  *      Platform-specific context pointer.
 158  * THREAD SAFETY:
 159  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 160  * RETURNS:
 161  *  Returns NULL if the function succeeds.
 162  *  Returns a Result Error if the function fails in a non-fatal way.
 163  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 164  */
 165 PKIX_Error *
 166 PKIX_ValidateResult_GetTrustAnchor(
 167         PKIX_ValidateResult *result,
 168         PKIX_TrustAnchor **pTrustAnchor,
 169         void *plContext);
 170
 171 /* PKIX_BuildResult
 172  *
 173  * PKIX_BuildResult represents the result of a PKIX_BuildChain call. It
 174  * consists of a ValidateResult object, as well as the built and validated
 175  * CertChain. Once created, a BuildResult object is immutable.
 176  */
 177
 178 /*
 179  * FUNCTION: PKIX_BuildResult_GetValidateResult
 180  * DESCRIPTION:
 181  *
 182  *  Retrieves the ValidateResult component (representing the build's validate
 183  *  result) of the BuildResult object pointed to by "result" and stores it at
 184  *  "pResult".
 185  *
 186  * PARAMETERS:
 187  *  "result"
 188  *      Address of BuildResult whose ValidateResult component is to be stored.
 189  *      Must be non-NULL.
 190  *  "pResult"
 191  *      Address where object pointer will be stored. Must be non-NULL.
 192  *  "plContext"
 193  *      Platform-specific context pointer.
 194  * THREAD SAFETY:
 195  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 196  * RETURNS:
 197  *  Returns NULL if the function succeeds.
 198  *  Returns a Result Error if the function fails in a non-fatal way.
 199  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 200  */
 201 PKIX_Error *
 202 PKIX_BuildResult_GetValidateResult(
 203         PKIX_BuildResult *result,
 204         PKIX_ValidateResult **pResult,
 205         void *plContext);
 206
 207 /*
 208  * FUNCTION: PKIX_BuildResult_GetCertChain
 209  * DESCRIPTION:
 210  *
 211  *  Retrieves the List of Certs (certChain) component (representing the built
 212  *  and validated CertChain) of the BuildResult object pointed to by "result"
 213  *  and stores it at "pChain".
 214  *
 215  * PARAMETERS:
 216  *  "result"
 217  *      Address of BuildResult whose CertChain component is to be stored.
 218  *      Must be non-NULL.
 219  *  "pChain"
 220  *      Address where object pointer will be stored. Must be non-NULL.
 221  *  "plContext"
 222  *      Platform-specific context pointer.
 223  * THREAD SAFETY:
 224  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 225  * RETURNS:
 226  *  Returns NULL if the function succeeds.
 227  *  Returns a Result Error if the function fails in a non-fatal way.
 228  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 229  */
 230 PKIX_Error *
 231 PKIX_BuildResult_GetCertChain(
 232         PKIX_BuildResult *result,
 233         PKIX_List **pChain,
 234         void *plContext);
 235
 236 /* PKIX_PolicyNode
 237  *
 238  * PKIX_PolicyNode represents a node in the policy tree returned in
 239  * ValidateResult. The policy tree is the same length as the validated
 240  * certificate chain and the nodes are associated with a particular depth
 241  * (corresponding to a particular certificate in the chain).
 242  * PKIX_ValidateResult_GetPolicyTree returns the root node of the valid policy
 243  * tree. Other nodes can be accessed using the getChildren and getParents
 244  * functions, and individual elements of a node can be accessed with the
 245  * appropriate gettors. Once created, a PolicyNode is immutable.
 246  */
 247
 248 /*
 249  * FUNCTION: PKIX_PolicyNode_GetChildren
 250  * DESCRIPTION:
 251  *
 252  *  Retrieves the List of PolicyNodes representing the child nodes of the
 253  *  Policy Node pointed to by "node" and stores it at "pChildren". If "node"
 254  *  has no child nodes, this function stores an empty List at "pChildren".
 255  *
 256  *  Note that the List returned by this function is immutable.
 257  *
 258  * PARAMETERS:
 259  *  "node"
 260  *      Address of PolicyNode whose child nodes are to be stored.
 261  *      Must be non-NULL.
 262  *  "pChildren"
 263  *      Address where object pointer will be stored. Must be non-NULL.
 264  *  "plContext"
 265  *      Platform-specific context pointer.
 266  * THREAD SAFETY:
 267  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 268  * RETURNS:
 269  *  Returns NULL if the function succeeds.
 270  *  Returns a Result Error if the function fails in a non-fatal way.
 271  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 272  */
 273 PKIX_Error *
 274 PKIX_PolicyNode_GetChildren(
 275         PKIX_PolicyNode *node,
 276         PKIX_List **pChildren,  /* list of PKIX_PolicyNode */
 277         void *plContext);
 278
 279 /*
 280  * FUNCTION: PKIX_PolicyNode_GetParent
 281  * DESCRIPTION:
 282  *
 283  *  Retrieves the PolicyNode representing the parent node of the PolicyNode
 284  *  pointed to by "node" and stores it at "pParent". If "node" has no parent
 285  *  node, this function stores NULL at "pParent".
 286  *
 287  * PARAMETERS:
 288  *  "node"
 289  *      Address of PolicyNode whose parent node is to be stored.
 290  *      Must be non-NULL.
 291  *  "pParent"
 292  *      Address where object pointer will be stored. Must be non-NULL.
 293  *  "plContext"
 294  *      Platform-specific context pointer.
 295  * THREAD SAFETY:
 296  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 297  * RETURNS:
 298  *  Returns NULL if the function succeeds.
 299  *  Returns a Result Error if the function fails in a non-fatal way.
 300  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 301  */
 302 PKIX_Error *
 303 PKIX_PolicyNode_GetParent(
 304         PKIX_PolicyNode *node,
 305         PKIX_PolicyNode **pParent,
 306         void *plContext);
 307
 308 /*
 309  * FUNCTION: PKIX_PolicyNode_GetValidPolicy
 310  * DESCRIPTION:
 311  *
 312  *  Retrieves the OID representing the valid policy of the PolicyNode pointed
 313  *  to by "node" and stores it at "pValidPolicy".
 314  *
 315  * PARAMETERS:
 316  *  "node"
 317  *      Address of PolicyNode whose valid policy is to be stored.
 318  *      Must be non-NULL.
 319  *  "pValidPolicy"
 320  *      Address where object pointer will be stored. Must be non-NULL.
 321  *  "plContext"
 322  *      Platform-specific context pointer.
 323  * THREAD SAFETY:
 324  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 325  * RETURNS:
 326  *  Returns NULL if the function succeeds.
 327  *  Returns a Result Error if the function fails in a non-fatal way.
 328  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 329  */
 330 PKIX_Error *
 331 PKIX_PolicyNode_GetValidPolicy(
 332         PKIX_PolicyNode *node,
 333         PKIX_PL_OID **pValidPolicy,
 334         void *plContext);
 335
 336 /*
 337  * FUNCTION: PKIX_PolicyNode_GetPolicyQualifiers
 338  * DESCRIPTION:
 339  *
 340  *  Retrieves the List of CertPolicyQualifiers representing the policy
 341  *  qualifiers associated with the PolicyNode pointed to by "node" and stores
 342  *  it at "pQualifiers". If "node" has no policy qualifiers, this function
 343  *  stores an empty List at "pQualifiers".
 344  *
 345  *  Note that the List returned by this function is immutable.
 346  *
 347  * PARAMETERS:
 348  *  "node"
 349  *      Address of PolicyNode whose policy qualifiers are to be stored.
 350  *      Must be non-NULL.
 351  *  "pQualifiers"
 352  *      Address where object pointer will be stored. Must be non-NULL.
 353  *  "plContext"
 354  *      Platform-specific context pointer.
 355  * THREAD SAFETY:
 356  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 357  * RETURNS:
 358  *  Returns NULL if the function succeeds.
 359  *  Returns a Result Error if the function fails in a non-fatal way.
 360  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 361  */
 362 PKIX_Error *
 363 PKIX_PolicyNode_GetPolicyQualifiers(
 364         PKIX_PolicyNode *node,
 365         PKIX_List **pQualifiers,  /* list of PKIX_PL_CertPolicyQualifier */
 366         void *plContext);
 367
 368 /*
 369  * FUNCTION: PKIX_PolicyNode_GetExpectedPolicies
 370  * DESCRIPTION:
 371  *
 372  *  Retrieves the List of OIDs representing the expected policies associated
 373  *  with the PolicyNode pointed to by "node" and stores it at "pExpPolicies".
 374  *
 375  *  Note that the List returned by this function is immutable.
 376  *
 377  * PARAMETERS:
 378  *  "node"
 379  *      Address of PolicyNode whose expected policies are to be stored.
 380  *      Must be non-NULL.
 381  *  "pExpPolicies"
 382  *      Address where object pointer will be stored. Must be non-NULL.
 383  *  "plContext"
 384  *      Platform-specific context pointer.
 385  * THREAD SAFETY:
 386  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 387  * RETURNS:
 388  *  Returns NULL if the function succeeds.
 389  *  Returns a Result Error if the function fails in a non-fatal way.
 390  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 391  */
 392 PKIX_Error *
 393 PKIX_PolicyNode_GetExpectedPolicies(
 394         PKIX_PolicyNode *node,
 395         PKIX_List **pExpPolicies,  /* list of PKIX_PL_OID */
 396         void *plContext);
 397
 398 /*
 399  * FUNCTION: PKIX_PolicyNode_IsCritical
 400  * DESCRIPTION:
 401  *
 402  *  Checks the criticality field of the PolicyNode pointed to by "node" and
 403  *  stores the Boolean result at "pCritical".
 404  *
 405  * PARAMETERS:
 406  *  "node"
 407  *      Address of PolicyNode whose criticality field is examined.
 408  *      Must be non-NULL.
 409  *  "pCritical"
 410  *      Address where Boolean will be stored. Must be non-NULL.
 411  *  "plContext"
 412  *      Platform-specific context pointer.
 413  * THREAD SAFETY:
 414  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 415  * RETURNS:
 416  *  Returns NULL if the function succeeds.
 417  *  Returns a Result Error if the function fails in a non-fatal way.
 418  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 419  */
 420 PKIX_Error *
 421 PKIX_PolicyNode_IsCritical(
 422         PKIX_PolicyNode *node,
 423         PKIX_Boolean *pCritical,
 424         void *plContext);
 425
 426 /*
 427  * FUNCTION: PKIX_PolicyNode_GetDepth
 428  * DESCRIPTION:
 429  *
 430  *  Retrieves the depth component of the PolicyNode pointed to by "node" and
 431  *  stores it at "pDepth".
 432  *
 433  * PARAMETERS:
 434  *  "node"
 435  *      Address of PolicyNode whose depth component is to be stored.
 436  *      Must be non-NULL.
 437  *  "pDepth"
 438  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
 439  *  "plContext"
 440  *      Platform-specific context pointer.
 441  * THREAD SAFETY:
 442  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 443  * RETURNS:
 444  *  Returns NULL if the function succeeds.
 445  *  Returns a Result Error if the function fails in a non-fatal way.
 446  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 447  */
 448 PKIX_Error *
 449 PKIX_PolicyNode_GetDepth(
 450         PKIX_PolicyNode *node,
 451         PKIX_UInt32 *pDepth,
 452         void *plContext);
 453
 454 #ifdef __cplusplus
 455 }
 456 #endif
 457
 458 #endif /* _PKIX_RESULTS_H */