NAME
   CSSM_HRS_VerifyMatch, HRS_VerifyMatch

 SYNOPSIS

 #include <hrs.h>

 API
   CSSM_RETURN CSSMAPI CSSM_HRS_VerifyMatch(
                              CSSM_HRS_HANDLE ModuleHandle,
                              const CSSM_HRS_FAR *MaxFARRequested,
                              const CSSM_HRS_FRR *MaxFRRRequested,
                              const CSSM_BOOL *FARPrecedence,
                              const CSSM_HRS_INPUT_BIR *ProcessedBIR,
                              const CSSM_HRS_INPUT_BIR *StoredTemplate,
                              CSSM_HRS_BIR_HANDLE *AdaptedBIR,
                              CSSM_BOOL *Result,
                              CSSM_HRS_FAR_PTR FARAchieved,
                              CSSM_HRS_FRR_PTR FRRAchieved,
                              CSSM_DATA_PTR *Payload);
 SPI
   CSSM_RETURN CSSMHRI HRS_VerifyMatch(
                              CSSM_HRS_HANDLE ModuleHandle,
                              const CSSM_HRS_FAR *MaxFARRequested,
                              const CSSM_HRS_FRR *MaxFRRRequested,
                              const CSSM_BOOL *FARPrecedence,
                              const CSSM_HRS_INPUT_BIR *ProcessedBIR,
                              const CSSM_HRS_INPUT_BIR *StoredTemplate,
                              CSSM_HRS_BIR_HANDLE *AdaptedBIR,
                              CSSM_BOOL *Result,
                              CSSM_HRS_FAR_PTR FARAchieved,
                              CSSM_HRS_FRR_PTR FRRAchieved,
                              CSSM_DATA_PTR *Payload);

 LIBRARY
   HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE)

 PARAMETERS
   The parameter definitions are the same for the API and the SPI.

   ModuleHandle (input)             The handle of the attached HRS
                                    service provider.
   MaxFARRequested (input)          The requested FAR criterion for
                                    successful verification.
   MaxFRRRequested (input/optional) The requested FRR criterion for
                                    successful verification. A NULL
                                    pointer indicates that this
                                    criterion is not provided.
   FARPrecedence (input)            If both criteria are provided,
                                    this parameter indicates which
                                    takes precedence: CSSM_TRUE for
                                    FAR, CSSM_FALSE for FRR.
   ProcessedBIR (input)             The BIR to be verified, or its handle.
   StoredTemplate (input)           The BIR to be verified against,
                                    or its key in a database, or its
                                    handle.
   AdaptedBIR (output/optional)     A pointer to the handle of the
                                    adapted BIR. This parameter can be
                                    NULL if an Adapted BIR is not
                                    desired. Not all service providers
                                    support the adaptation of BIRs. The
                                    function may return a handle value
                                    of CSSM_HRS_UNSUPPORTED_BIR_HANDLE
                                    to indicate that adaptation is not
                                    supported, or a value of
                                    CSSM_HRS_INVALID_BIR_HANDLE to
                                    indicate that adaptation was not
                                    possible.
   Result (output)                  A pointer to a Boolean value indicating
                                    (CSSM_TRUE/CSSM_FALSE) whether the
                                    BIRs matched or not according to the
                                    specified criteria.
   FARAchieved (output)            A pointer to an FAR value indicating
                                   the closeness of the match.
   FRRAchieved (output/optional)   A pointer to an FRR value indicating
                                   the closeness of the match.
   Payload (output/optional)       If the StoredTemplate contains a
                                   payload, it is returned in an
                                   allocated CSSM_DATA structure if the
                                   FARAchieved satisfies the policy of
                                   the service provider.

 DESCRIPTION
   This function performs a verification (1-to-1) match between two
   BIRs - the ProcessedBIR and the StoredTemplate. The ProcessedBIR
   is the "processed" BIR constructed specifically for this
   verification. The StoredTemplate was created at enrollment. The
   application must request a maximum FAR value for a successful
   match, and may also (optionally) request a maximum FRR for a
   successful match. If a maximum FRR value is provided, the
   application must also indicate (via the FARPrecedence parameter)
   which one takes precedence. The Boolean Result indicates whether
   verification was successful or not, and the FARAchieved is a FAR
   value indicating how closely the BIRs actually matched.

   The service provider may optionally return the corresponding FRR
   that was achieved, through the FRRAchieved return parameter.

   By setting the AdaptedBIR pointer to non-NULL, the application
   can request that a BIR be constructed by adapting the
   StoredTemplate using the ProcessedBIR. A new handle is
   returned to the AdaptedBIR. If the StoredTemplate contains a
   Payload, the Payload may be returned upon successful
   verification if the FARAchieved is sufficiently stringent.
   This is controlled by the policy of the service provider.

   If the match is successful, an attempt may be made to adapt
   the StoredTemplate with information taken from the ProcessedBIR.
   (Not all service providers perform adaptation.) The resulting
   AdaptedBIR should now be considered an optimal enrollment
   template, and be saved in the enrollment database. It is up to
   the application whether or not it uses or discards this data.
   It is important to note that adaptation may not occur in all cases.

   In the event of an adaptation, this function stores the handle to
   the new BIR in the memory pointed to by the AdaptedBIR parameter.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 ERRORS
   Errors are described in the CDSA Technical Standard.

   CSSMERR_CSSM_NOT_INITIALIZED
   CSSMERR_CSSM_FUNCTION_FAILED
   CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED
   CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL
   CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED
   CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED
   CSSMERR_HRS_BIR_SIGNATURE_FAILURE
   CSSMERR_HRS_INCONSISTENT_PURPOSE