NAME
   CSSM_HRS_Verify, HRS_Verify

 SYNOPSIS

 #include <hrs.h>

 API
   CSSM_RETURN CSSMAPI CSSM_HRS_Verify(
                          CSSM_HRS_HANDLE ModuleHandle,
                          const CSSM_HRS_FAR *MaxFARRequested,
                          const CSSM_HRS_FRR *MaxFRRRequested,
                          const CSSM_BOOL *FARPrecedence,
                          const CSSM_HRS_INPUT_BIR *StoredTemplate,
                          CSSM_HRS_BIR_HANDLE_PTR AdaptedBIR,
                          CSSM_BOOL *Result,
                          CSSM_HRS_FAR_PTR FARAchieved,
                          CSSM_HRS_FRR_PTR FRRAchieved,
                          CSSM_DATA_PTR *Payload,
                          sint32 Timeout,
                          CSSM_HRS_BIR_HANDLE_PTR AuditData);
 SPI
   CSSM_RETURN CSSMHRI HRS_Verify(
                          CSSM_HRS_HANDLE ModuleHandle,
                          const CSSM_HRS_FAR *MaxFARRequested,
                          const CSSM_HRS_FRR *MaxFRRRequested,
                          const CSSM_BOOL *FARPrecedence,
                          const CSSM_HRS_INPUT_BIR *StoredTemplate,
                          CSSM_HRS_BIR_HANDLE_PTR AdaptedBIR,
                          CSSM_BOOL *Result,
                          CSSM_HRS_FAR_PTR FARAchieved,
                          CSSM_HRS_FRR_PTR FRRAchieved,
                          CSSM_DATA_PTR *Payload,
                          sint32 Timeout,
                          CSSM_HRS_BIR_HANDLE_PTR AuditData);

 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.
   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 HRS 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.
   Timeout (input)                  An integer specifying the timeout
                                    value (in milliseconds) for the
                                    operation. If this timeout is
                                    reached, the function returns an
                                    error, and no results. This value
                                    can be any positive number. A -1
                                    value means the service provider's
                                    default timeout value will be used.
   AuditData (output/optional)      A handle to a BIR containing raw
                                    biometric data. This data may be
                                    used to provide human-identifiable
                                    data of the person at the device.
                                    If the pointer is NULL on input,
                                    no audit data is collected. Not all
                                    service providers support the
                                    collection of audit data. An HRS
                                    service provider may return a
                                    handle value of
                                    CSSM_HRS_UNSUPPORTED_BIR_HANDLE
                                    to indicate AuditData is not
                                    supported, or a value of
                                    CSSM_HRS_INVALID_BIR_HANDLE to
                                    indicate that no audit data is
                                    available.

 DESCRIPTION
   This function captures biometric data from the attached device,
   and compares it against the StoredTemplate. The application must
   request a maximum FAR value criterion for a successful match, and
   may also (optionally) request a maximum FRR criterion for a
   successful match. If a maximum FRR value is provided, the
   application must also indicate via the FARPrecedence parameter,
   which criteria 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.

   If the StoredTemplate contains a payload, the Payload may be
   returned upon successful verification. Optionally, a new
   AdaptedBIR may be constructed.

   The Verify function may be split between client and server if
   a streaming callback has been set.  Either the client or the
   server can initiate the operation.

   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, 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.  See CDSA.

   CSSMERR_CSSM_NOT_INITIALIZED
   CSSMERR_CSSM_FUNCTION_FAILED
   CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED
   CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL
   CSSMERR_HRS_BIR_SIGNATURE_FAILURE
   CSSMERR_HRS_INCONSISTENT_PURPOSE
   CSSMERR_HRS_RECORD_NOT_FOUND
   CSSMERR_HRS_TIMEOUT_EXPIRED
   CSSMERR_HRS_TOO_MANY_HANDLES
   CSSMERR_HRS_UNABLE_TO_CAPTURE