HRS_Verify

NAME

CSSM_HRS_Verify, HRS_Verify — Captures biometric data from the attached device and compares it against the StoredTemplate

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, its key in a database, or its handle.
`AdaptedBIR` (output/optional)		A pointer to the handle of the adapted BIR (Biometric Identification Record). 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.

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