/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/*
 * This file defines functions associated with the PKIX_RevocationChecker
 * type.
 *
 */

#ifndef _PKIX_REVCHECKER_H
#define _PKIX_REVCHECKER_H

#include "pkixt.h"
#include "pkix_pl_pki.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_RevocationChecker provides a standard way of revocation checking.
 * Caller should configure two set of tests(represented at lists of
 * RevocationMethod objects) to be performed on the leaf and on the rest of
 * the chain certificates.
 *
 * PKIX_RevocationMethods 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 and OCSP. 
 *
 * Once the caller has created the RevocationMethod object(s), the caller
 * then specifies the RevocationMethod object(s) in a RevocationCheck object
 * and sets it into a ProcessingParams.
 */

/*
 * FUNCTION: PKIX_RevocationChecker_Create
 * DESCRIPTION:
 *
 * Creates a revocation checker object with the given flags. Revocation will
 * be checked at the current date.
 *
 * PARAMETERS:
 *  "leafMethodListFlags"
 *      Defines a set of method independent flags that will be used to check
 *      revocation of the leaf cert in the chain.
 *  "chainMethodListFlags"
 *      Defines a set of method independent flags that will be used to check
 *      revocation of the remaining certs in the chain.
 *  "pChecker"
 *      The return address of created checker.
 *  "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.
 */
PKIX_Error *
PKIX_RevocationChecker_Create(
    PKIX_UInt32 leafMethodListFlags,
    PKIX_UInt32 chainMethodListFlags,
    PKIX_RevocationChecker **pChecker,
    void *plContext);

/*
 * FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
 * DESCRIPTION:
 *
 * Creates revocation method object with given parameters and adds it
 * to revocation checker method list.
 *
 * PARAMETERS:
 *  "revChecker"
 *      Address of revocation checker structure.
 *  "procParams"
 *      Address of ProcessingParams used to initialize the checker.
 *      Must be non-NULL.
 *  "methodType"
 *      Type of the method. Currently only two types are
 *      supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
 *  "methodFlags"
 *      Set of flags for the method.
 *  "methodPriority"
 *      Method priority. (0 corresponds to the highest priority)
 *  "verificationFn"
 *      User call back function that will perform validation of fetched
 *      revocation information(new crl or ocsp response)
 *  "isLeafMethod"
 *      Boolean flag that if set to true indicates that the method should
 *      should be used for leaf cert revocation test(false for chain set
 *      methods).
 *  "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.
 */
PKIX_Error *
PKIX_RevocationChecker_CreateAndAddMethod(
    PKIX_RevocationChecker *revChecker,
    PKIX_ProcessingParams *params,
    PKIX_RevocationMethodType methodType,
    PKIX_UInt32 methodFlags,
    PKIX_UInt32 methodPriority,
    PKIX_PL_VerifyCallback verificationFn,
    PKIX_Boolean isLeafMethod,
    void *plContext);

/*
 * FUNCTION: PKIX_RevocationChecker_Check
 * DESCRIPTION:
 *
 * Verifies revocation status of the certificate. Issuer cert is given to
 * be used in verification of revocation information. Performed verification
 * check depends on configured revocation methods(ocsp, crl. See
 * PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
 * building process at which PKIX_RevocationChecker_Check was invoked.
 * For security reasons, the cert status is checked only against cached
 * revocation information during chain building stage(no trust anchor yes has
 * been found). The fresh revocation information fetching is done only at chain
 * verification stage after trust anchor was identified.
 * 
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose revocation status is to be determined.
 *      Must be non-NULL.
 *  "issuer"
 *      Issuer cert that potentially holds public key that will be used
 *      to verify revocation info.
 *  "revChecker"
 *      Address of revocation checker structure.
 *  "procParams"
 *      Address of ProcessingParams used to initialize the checker.
 *      Must be non-NULL.
 *  "chainVerificationState"
 *     Need to be set to true, if the check was called during chain verification
 *     as an opposite to chain building.
 *  "testingLeafCert"
 *     Set to true if verifying revocation status of a leaf cert.
 *  "revStatus"
 *     Address of the returned revocation status of the cert.
 *  "pResultCode"
 *      Address where revocation status will be stored. Must be non-NULL.
 *  "pNBIOContext"
 *      Address at which platform-dependent non-blocking I/O context is 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.
 */
PKIX_Error *
PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
                             PKIX_PL_Cert *issuer,
                             PKIX_RevocationChecker *revChecker,
                             PKIX_ProcessingParams *procParams,
                             PKIX_Boolean chainVerificationState,
                             PKIX_Boolean testingLeafCert,
                             PKIX_RevocationStatus *revStatus,
                             PKIX_UInt32 *pReasonCode,
                             void **pNbioContext,
                             void *plContext);
    
#ifdef __cplusplus
}
#endif

#endif /* _PKIX_REVCHECKER_H */