/security/nss/lib/libpkix/include/pkix_revchecker.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 PKIX_RevocationChecker
 39 * type.
 40 *
 41 */
 42
 43#ifndef _PKIX_REVCHECKER_H
 44#define _PKIX_REVCHECKER_H
 45
 46#include "pkixt.h"
 47#include "pkix_pl_pki.h"
 48
 49#ifdef __cplusplus
 50extern "C" {
 51#endif
 52
 53/* General
 54 *
 55 * Please refer to the libpkix Programmer's Guide for detailed information
 56 * about how to use the libpkix library. Certain key warnings and notices from
 57 * that document are repeated here for emphasis.
 58 *
 59 * All identifiers in this file (and all public identifiers defined in
 60 * libpkix) begin with "PKIX_". Private identifiers only intended for use
 61 * within the library begin with "pkix_".
 62 *
 63 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
 64 *
 65 * Unless otherwise noted, for all accessor (gettor) functions that return a
 66 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
 67 * shared object. Therefore, the caller should treat this shared object as
 68 * read-only and should not modify this shared object. When done using the
 69 * shared object, the caller should release the reference to the object by
 70 * using the PKIX_PL_Object_DecRef function.
 71 *
 72 * While a function is executing, if its arguments (or anything referred to by
 73 * its arguments) are modified, free'd, or destroyed, the function's behavior
 74 * is undefined.
 75 *
 76 */
 77
 78/* PKIX_RevocationChecker
 79 *
 80 * PKIX_RevocationChecker provides a standard way of revocation checking.
 81 * Caller should configure two set of tests(represented at lists of
 82 * RevocationMethod objects) to be performed on the leaf and on the rest of
 83 * the chain certificates.
 84 *
 85 * PKIX_RevocationMethods provide a standard way for the caller to insert
 86 * their own custom revocation checks to verify the revocation status of
 87 * certificates. This may be useful in many scenarios, including when the
 88 * caller wishes to use their own revocation checking mechanism instead of (or
 89 * in addition to) the default revocation checking mechanism provided by
 90 * libpkix, which uses CRLs and OCSP. 
 91 *
 92 * Once the caller has created the RevocationMethod object(s), the caller
 93 * then specifies the RevocationMethod object(s) in a RevocationCheck object
 94 * and sets it into a ProcessingParams.
 95 */
 96
 97/*
 98 * FUNCTION: PKIX_RevocationChecker_Create
 99 * DESCRIPTION:
100 *
101 * Creates revocation checker object with a given flags.
102 *
103 * PARAMETERS:
104 *  "revDate"
105 *      Revocation will be checked at this date. Current date is taken if the
106 *      parameter is not specified.
107 *  "leafMethodListFlags"
108 *      Defines a set of method independent flags that will be used to check
109 *      revocation of the leaf cert in the chain.
110 *  "chainMethodListFlags"
111 *      Defines a set of method independent flags that will be used to check
112 *      revocation of the remaining certs in the chain.
113 *  "pChecker"
114 *      The return address of created checker.
115 *  "plContext"
116 *      Platform-specific context pointer.
117 * THREAD SAFETY:
118 *  Thread Safe
119 *
120 *  Multiple threads must be able to safely call this function without
121 *  worrying about conflicts, even if they're operating on the same objects.
122 * RETURNS:
123 *  Returns NULL if the function succeeds.
124 *  Returns a RevocationChecker Error if the function fails in a non-fatal way.
125 *  Returns a Fatal Error if the function fails in an unrecoverable way.
126 */
127PKIX_Error *
128PKIX_RevocationChecker_Create(
129    PKIX_UInt32 leafMethodListFlags,
130    PKIX_UInt32 chainMethodListFlags,
131    PKIX_RevocationChecker **pChecker,
132    void *plContext);
133
134/*
135 * FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
136 * DESCRIPTION:
137 *
138 * Creates revocation method object with given parameters and adds it
139 * to revocation checker method list.
140 *
141 * PARAMETERS:
142 *  "revChecker"
143 *      Address of revocation checker structure.
144 *  "procParams"
145 *      Address of ProcessingParams used to initialize the checker.
146 *      Must be non-NULL.
147 *  "methodType"
148 *      Type of the method. Currently only two types are
149 *      supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
150 *  "methodFlags"
151 *      Set of flags for the method.
152 *  "methodPriority"
153 *      Method priority. (0 corresponds to a highest priority)
154 *  "verificationFn"
155 *      User call back function that will perform validation of fetched
156 *      revocation information(new crl or ocsp response)
157 *  "isLeafMethod"
158 *      Boolean flag that if set to true indicates that the method should
159 *      should be used for leaf cert revocation test(false for chain set
160 *      methods).
161 *  "plContext"
162 *      Platform-specific context pointer.
163 * THREAD SAFETY:
164 *  Thread Safe
165 *
166 *  Multiple threads must be able to safely call this function without
167 *  worrying about conflicts, even if they're operating on the same objects.
168 * RETURNS:
169 *  Returns NULL if the function succeeds.
170 *  Returns a RevocationChecker Error if the function fails in a non-fatal way.
171 *  Returns a Fatal Error if the function fails in an unrecoverable way.
172 */
173PKIX_Error *
174PKIX_RevocationChecker_CreateAndAddMethod(
175    PKIX_RevocationChecker *revChecker,
176    PKIX_ProcessingParams *params,
177    PKIX_RevocationMethodType methodType,
178    PKIX_UInt32 methodFlags,
179    PKIX_UInt32 mathodPriority,
180    PKIX_PL_VerifyCallback verificationFn,
181    PKIX_Boolean isLeafMethod,
182    void *plContext);
183
184/*
185 * FUNCTION: PKIX_RevocationChecker_Check
186 * DESCRIPTION:
187 *
188 * Verifies revocation status of the certificate. Issuer cert is given to
189 * be used in verification of revocation information. Performed verification
190 * check depends on configured revocation methods(ocsp, crl. See
191 * PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
192 * building process at which PKIX_RevocationChecker_Check was invoked.
193 * For security reasons, the cert status is checked only against cached
194 * revocation information during chain building stage(no trust anchor yes has
195 * been found). The fresh revocation information fetching is done only at chain
196 * verification stage after trust anchor was identified.
197 * 
198 * PARAMETERS:
199 *  "cert"
200 *      Address of Cert whose revocation status is to be determined.
201 *      Must be non-NULL.
202 *  "issuer"
203 *      Issuer cert that potentially holds public key that will be used
204 *      to verify revocation info.
205 *  "revChecker"
206 *      Address of revocation checker structure.
207 *  "procParams"
208 *      Address of ProcessingParams used to initialize the checker.
209 *      Must be non-NULL.
210 *  "chainVerificationState"
211 *     Need to be set to true, if the check was called during chain verification
212 *     as an opposite to chain building.
213 *  "testingLeafCert"
214 *     Set to true if verifying revocation status of a leaf cert.
215 *  "revStatus"
216 *     Address of the returned revocation status of the cert.
217 *  "pResultCode"
218 *      Address where revocation status will be stored. Must be non-NULL.
219 *  "pNBIOContext"
220 *      Address at which platform-dependent non-blocking I/O context is stored.
221 *      Must be non-NULL.
222 *  "plContext"
223 *      Platform-specific context pointer.
224 * THREAD SAFETY:
225 *  Thread Safe
226 *
227 *  Multiple threads must be able to safely call this function without
228 *  worrying about conflicts, even if they're operating on the same objects.
229 * RETURNS:
230 *  Returns NULL if the function succeeds.
231 *  Returns a RevocationChecker Error if the function fails in a non-fatal way.
232 *  Returns a Fatal Error if the function fails in an unrecoverable way.
233 */
234PKIX_Error *
235PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
236                             PKIX_PL_Cert *issuer,
237                             PKIX_RevocationChecker *revChecker,
238                             PKIX_ProcessingParams *procParams,
239                             PKIX_Boolean chainVerificationState,
240                             PKIX_Boolean testingLeafCert,
241                             PKIX_RevocationStatus *revStatus,
242                             PKIX_UInt32 *pReasonCode,
243                             void **pNbioContext,
244                             void *plContext);
245    
246#ifdef __cplusplus
247}
248#endif
249
250#endif /* _PKIX_REVCHECKER_H */