NAME
CSSM_HRS_VerifyMatch, HRS_VerifyMatch — Performs a verification (1-to-1) match between two BIRs - the
ProcessedBIR and the StoredTemplate
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,
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
