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

http://github.com/zpao/v8monkey · C Header · 250 lines · 38 code · 10 blank · 202 comment · 0 complexity · d055d6a14ddd927347d46f75832d157d MD5 · raw file

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