HP Open Source Security for OpenVMS Volume 1: Common Data Security Architecture > Human Recognition Service (HRS) API Functions

HRS_Identify

 » Table of Contents

 » Glossary

 » Index

NAME

CSSM_HRS_Identify, HRS_Identify — Captures biometric data from the attached device and compares it against the Population

SYNOPSIS

#include <hrs.h>

API

CSSM_RETURN CSSMAPI CSSM_HRS_Identify
(CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
sint32 Timeout,
CSSM_HRS_BIR_HANDLE_PTR AuditData);

SPI

CSSM_RETURN CSSMHRI HRS_Identify
(CSSM_HRS_HANDLE ModuleHandle,
const CSSM_HRS_FAR *MaxFARRequested,
const CSSM_HRS_FRR *MaxFRRRequested,
const CSSM_BOOL *FARPrecedence,
const CSSM_HRS_IDENTIFY_POPULATION *Population,
CSSM_BOOL Binning,
uint32 MaxNumberOfResults,
uint32 *NumberOfResults,
CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
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.

Population (input) 

The population of Templates against which the Identify match is performed.

Binning (input)  

A Boolean value indicating whether Binning is on or off. Binning is a search optimization technique that the BSP may employ. It is based on searching the population according to the intrinsic characteristics of the biometric data. While it may improve the speed of the Match operation, it may also increase the probability of missing a candidate.

MaxNumberOfResults (input)  

Specifies the maximum number of match candidates to be returned as a result of the 1:N match. A value of zero is a request for all candidates.

NumberOfResults (output)  

Specifies the number of candidates returned in the Candidates array as a result of the 1:N match.

Candidates (output) 

A pointer to an array of CSSM_HRS_CANDIDATE_PTRs corresponding to the BIRs identified as a result of the match process (that is, indices associated with BIRs found to exceed the match threshold). This list is in rank order, with the highest scoring record being first. If no matches are found, this pointer will be set to NULL. If the Population was presented in a database, the IDs are database IDs; if the set was presented in an in-memory array, the IDs are indexes into the array.

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 HRS service providers support the collection of audit data. A BSP 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 Population. 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 function returns a number of candidates from the population that match according to the specified criteria, and the FARAchieved and, optionally, the FRRAchieved are returned for each result in the Candidate array.

The Identify 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.

NOTE: Not all service providers support 1:N identification. See your service provider’s programming manual for more details.

Depending on the service provider and the location and size of the database to be searched, this operation can take a significant amount of time to perform. Check your service provider’s manual for recommended Timeout values.

The number of match candidates found by the service provider is dependent on the actual FAR used.

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_FUNCTION_NOT_SUPPORTED
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_NO_INPUT_BIRS
CSSMERR_HRS_RECORD_NOT_FOUND
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_UNABLE_TO_CAPTURE