/* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the PKIX-C library. * * The Initial Developer of the Original Code is * Sun Microsystems, Inc. * Portions created by the Initial Developer are * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved. * * Contributor(s): * Sun Microsystems, Inc. * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ /* * This file defines functions associated with the PKIX_RevocationChecker * type. * */ #ifndef _PKIX_REVCHECKER_H #define _PKIX_REVCHECKER_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_RevocationChecker * * PKIX_RevocationCheckers provide a standard way for the caller to insert * their own custom revocation checks to verify the revocation status of * certificates. This may be useful in many scenarios, including when the * caller wishes to use their own revocation checking mechanism instead of (or * in addition to) the default revocation checking mechanism provided by * libpkix, which uses CRLs. The RevCallback allows custom revocation checking * to take place. Additionally, the RevocationChecker can be initialized with * a revCheckerContext, which is where the caller can specify configuration * data such as the IP address of a revocation server. Note that this * revCheckerContext must be a PKIX_PL_Object, allowing it to be * reference-counted and allowing it to provide the standard PKIX_PL_Object * functions (Equals, Hashcode, ToString, Compare, Duplicate). * * Once the caller has created the RevocationChecker object(s), the caller * then specifies the RevocationChecker object(s) in a ProcessingParams object * and passes that object to PKIX_ValidateChain or PKIX_BuildChain, which uses * the objects to call the user's callback functions as needed during the * validation or building process. * * Note that if multiple revocation checkers are added, the order is * important, in that each revocation checker will be called sequentially * until the revocation status can be determined or all the revocation checkers * have been called. Also note that the default CRL revocation checker will * always be called last after all the custom revocation checkers have been * called. This default CRL revocation checking can be disabled by calling * PKIX_ProcessingParams_SetRevocationEnabled with a Boolean parameter of * PKIX_FALSE. This will ONLY disable the CRL revocation checker, not the * custom RevocationCheckers specified by the caller. * * For example, assume the caller specifies an OCSP RevocationChecker in the * ProcessingParams object. Let's look at two scenarios: * * 1) SetRevocationEnabled(PKIX_FALSE) * * The OCSP RevocationChecker will be used. If it is unable to determine * whether the certificate has been revoked (perhaps the network is down), * the revocation check fails safe and the certificate is rejected * (assumed to be revoked). * * 2) SetRevocationEnabled(PKIX_TRUE) * [This doesn't need to be called, since this is the default behavior] * * The OCSP RevocationChecker will be used first. If it is unable to * determine whether the certificate has been revoked (perhaps the network * is down), the default CRL revocation checker is used next. If it is * also unable to determine whether the certificate has been revoked, the * revocation check fails safe. Note that this is a useful scenario where * the CRL check is only done if the OCSP check is unable to take place. */ /* * FUNCTION: PKIX_RevocationChecker_RevCallback * DESCRIPTION: * * This callback function determines the revocation status of the specified * Cert pointed to by "cert" and stores it at "pResultCode". If a checker * initiates non-blocking I/O, it stores a platform-dependent non-blocking * I/O context at "pNBIOContext". A subsequent call with that same value on * input allows the operation to continue. On completion, with no non-blocking * I/O pending, NULL is stored at "pNBIOContext". * * PARAMETERS: * "revCheckerContext" * Address of RevocationCheckerContext for the RevocationChecker whose * RevCallback logic is to be used. Must be non-NULL. * "cert" * Address of Cert whose revocation status is to be determined. * Must be non-NULL. * "procParams" * Address of ProcessingParams used to initialize the checker. * Must be non-NULL. * "pNBIOContext" * Address at which platform-dependent non-blocking I/O context is stored. * Must be non-NULL. * "pResultCode" * Address where revocation status will be stored. Must be non-NULL. * "plContext" * Platform-specific context pointer. * THREAD SAFETY: * Thread Safe * * Multiple threads must be able to safely call this function without * worrying about conflicts, even if they're operating on the same objects. * RETURNS: * Returns NULL if the function succeeds. * Returns a RevocationChecker Error if the function fails in a non-fatal way. * Returns a Fatal Error if the function fails in an unrecoverable way. */ typedef PKIX_Error * (*PKIX_RevocationChecker_RevCallback)( PKIX_PL_Object *revCheckerContext, PKIX_PL_Cert *cert, PKIX_ProcessingParams *procParams, void **pNBIOContext, PKIX_UInt32 *pResultCode, void *plContext); /* * FUNCTION: PKIX_RevocationChecker_Create * DESCRIPTION: * * Creates a new RevocationChecker using the Object pointed to by * "revCheckerContext" (if any) and stores it at "pRevChecker". The new * RevocationChecker uses the RevCallback pointed to by "callback". Once * created, a RevocationChecker is immutable. * PARAMETERS: * "callback" * The RevCallback function to be used. Must be non-NULL. * "revCheckerContext" * Address of Object representing the RevocationChecker's context. * "pRevChecker" * Address where object pointer will be stored. Must be non-NULL. * "plContext" * Platform-specific context pointer. * THREAD SAFETY: * Thread Safe (see THREAD SAFETY DEFINITIONS at top of file) * RETURNS: * Returns NULL if the function succeeds. * Returns a RevocationChecker 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_RevocationChecker_Create( PKIX_RevocationChecker_RevCallback callback, PKIX_PL_Object *revCheckerContext, PKIX_RevocationChecker **pRevChecker, void *plContext); /* * FUNCTION: PKIX_RevocationChecker_GetRevCallback * DESCRIPTION: * * Retrieves a pointer to "revChecker's" Rev callback function and puts it in * "pCallback". * * PARAMETERS: * "revChecker" * The RevocationChecker whose Rev callback is desired. Must be non-NULL. * "pCallback" * Address where Rev callback function pointer will be stored. * Must be non-NULL. * "plContext" * Platform-specific context pointer. * THREAD SAFETY: * Thread Safe (see THREAD SAFETY DEFINITIONS at top of file) * RETURNS: * Returns NULL if the function succeeds. * Returns a RevocationChecker 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_RevocationChecker_GetRevCallback( PKIX_RevocationChecker *revChecker, PKIX_RevocationChecker_RevCallback *pCallback, void *plContext); /* * FUNCTION: PKIX_RevocationChecker_GetRevCheckerContext * DESCRIPTION: * * Retrieves a pointer to a PKIX_PL_Object representing the context (if any) * of the RevocationChecker pointed to by "revChecker" and stores it at * "pRevCheckerContext". * * PARAMETERS: * "revChecker" * Address of RevocationChecker whose context is to be stored. * Must be non-NULL. * "pRevCheckerContext" * Address where object pointer will be stored. Must be non-NULL. * "plContext" * Platform-specific context pointer. * THREAD SAFETY: * Thread Safe (see THREAD SAFETY DEFINITIONS at top of file) * RETURNS: * Returns NULL if the function succeeds. * Returns a RevocationChecker 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_RevocationChecker_GetRevCheckerContext( PKIX_RevocationChecker *revChecker, PKIX_PL_Object **pRevCheckerContext, void *plContext); #ifdef __cplusplus } #endif #endif /* _PKIX_REVCHECKER_H */