Previous section.

CDSA/CSSM Authenticaton: Human Recognition Service (HRS) API
Copyright © 2000 The Open Group

API Definition

Data Structures

CSSM_MODULE_EVENT

The following two events are added for HRS 


 

#define CSSM_NOTIFY_SOURCE_PRESENT        (4)
#define CSSM_NOTIFY_SOURCE_REMOVED        (5)

CSSM_MODULE_EVENT_MASK

This enumeration defines a mask with bit positions for event type. The mask is used to enable/disable events, and to indicate what events are supported. 


 

typedef uint32 CSSM_MODULE_EVENT_MASK;
#define CSSM_NOTIFY_INSERT_BIT            (0x0001)
#define CSSM_NOTIFY_REMOVE_BIT            (0x0002)
#define CSSM_NOTIFY_FAULT_BIT             (0x0004)
#define CSSM_NOTIFY_SOURCE_PRESENT_BIT    (0x0008)
#define CSSM_NOTIFY_SOURCE_REMOVED_BIT    (0x0010)

CSSM_HRS_BIR

A container for biometric data. A BIR may contain raw sample data, partially processed (intermediate) data, or completely processed data. It may be used to enroll a user (thus being stored persistently), or may be used to verify or identify a user (thus being used transiently).

The opaque biometric data is of variable length, and may be followed by a signature. The signature itself may not be a fixed length, depending on which signature standard is employed. 



 

typedef struct cssm_hrs_bir {
    CSSM_HRS_BIR_HEADER  Header;
    CSSM_HRS_BIR_BIOMETRIC_DATA_PTR BiometricData;    
                                    /* length indicated in header */
    CSSM_DATA_PTR Signature;   
         /* NULL if no signature; length is inherent in this type */
} CSSM_HRS_BIR, *CSSM_HRS_BIR_PTR;

CSSM_HRS_BIR_ARRAY_POPULATION 



 

typedef struct cssm_hrs_bir_array_population {
    uint32 NumberOfMembers;
    CSSM_HRS_BIR_PTR *Members;    
                         /* A pointer to an array of BIR pointers */
} CSSM_HRS_BIR_ARRAY_POPULATION, *CSSM_HRS_BIR_ARRAY_POPULATION_PTR;

CSSM_HRS_BIR_AUTH_FACTORS

A mask that describes the set of authentication factors supported by an authentication service. 


 

typedef uint32 CSSM_HRS_BIR_AUTH_FACTORS;

#define CSSM_HRS_FACTOR_MULTIPLE              (0x00000001)
#define CSSM_HRS_FACTOR_FACIAL_FEATURES       (0x00000002)
#define CSSM_HRS_FACTOR_VOICE                 (0x00000004)
#define CSSM_HRS_FACTOR_FINGERPRINT           (0x00000008)
#define CSSM_HRS_FACTOR_IRIS                  (0x00000010)
#define CSSM_HRS_FACTOR_RETINA                (0x00000020)
#define CSSM_HRS_FACTOR_HAND_GEOMETRY         (0x00000040)
#define CSSM_HRS_FACTOR_SIGNATURE_DYNAMICS    (0x00000080)
#define CSSM_HRS_FACTOR_KEYSTOKE_DYNAMICS     (0x00000100)
#define CSSM_HRS_FACTOR_LIP_MOVEMENT          (0x00000200)
#define CSSM_HRS_FACTOR_THERMAL_FACE_IMAGE    (0x00000400)
#define CSSM_HRS_FACTOR_THERMAL_HAND_IMAGE    (0x00000800)
#define CSSM_HRS_FACTOR_GAIT                  (0x00001000)
#define CSSM_HRS_FACTOR_PASSWORD              (0x80000000)

CSSM_HRS_BIR_BIOMETRIC_DATA 



 

typedef uint8 CSSM_HRS_BIR_BIOMETRIC_DATA, \
                  *CSSM_HRS_BIR_BIOMETRIC_DATA_PTR;

CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT 



 

typedef struct cssm_hrs_bir_biometric_data_format {
    uint16 FormatOwner;
    uint16 FormatID;
} CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT, \
                  *CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT_PTR;

Note:
FormatOwner values are assigned and registered by the International Biometric Industry Association (IBIA). FormatType is assigned by the Format Owner and may optionally be registered by the IBIA. Contact information for the IBIA is located in IBIA Contact Information.

CSSM_HRS_BIR_DATA_TYPE

Mask bits that may be OR'd together to indicate the type of opaque data in the BIR. (Raw OR Intermediate OR Processed) OR Encrypted OR Signed. 


 

typedef uint8 CSSM_HRS_BIR_DATA_TYPE;  

#define CSSM_HRS_BIR_DATA_TYPE_RAW             (0x00)
#define CSSM_HRS_BIR_DATA_TYPE_INTERMEDIATE    (0x01)
#define CSSM_HRS_BIR_DATA_TYPE_PROCESSED       (0x02)
#define CSSM_HRS_BIR_DATA_TYPE_ENCRYPTED       (0x10)
#define CSSM_HRS_BIR_DATA_TYPE_SIGNED          (0x20)

CSSM_HRS_BIR_HANDLE

A handle to refer to BIR data that exists in the service provider. 


 

typedef  sint32 CSSM_HRS_BIR_HANDLE, *CSSM_HRS_BIR_HANDLE_PTR;

#define CSSM_HRS_INVALID_BIR_HANDLE        (-1)
#define CSSM_HRS_UNSUPPORTED_BIR_HANDLE    (-2)

CSSM_HRS_BIR_HEADER 



 

typedef struct cssm_hrs_bir_header {
    uint32 Length;    /* Length of Header + Opaque Data */
    CSSM_HRS_BIR_VERSION HeaderVersion;
    CSSM_HRS_BIR_DATA_TYPE Type;
    CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT Format;
    CSSM_HRS_QUALITY Quality;
    CSSM_HRS_BIR_PURPOSE PurposeMask;
    CSSM_HRS_BIR_AUTH_FACTORS FactorsMask;
} CSSM_HRS_BIR_HEADER, *CSSM_HRS_BIR_HEADER_PTR;

CSSM_HRS_BIR_PURPOSE 



 

typedef uint8 CSSM_HRS_BIR_PURPOSE;

#define CSSM_HRS_PURPOSE_VERIFY                            (1)
#define CSSM_HRS_PURPOSE_IDENTIFY                          (2)
#define CSSM_HRS_PURPOSE_ENROLL                            (3)
#define CSSM_HRS_PURPOSE_ENROLL_FOR_VERIFICATION_ONLY      (4)
#define CSSM_HRS_PURPOSE_ENROLL_FOR_IDENTIFICATION_ONLY    (5)
#define CSSM_HRS_PURPOSE_AUDIT                             (6)

CSSM_HRS_BIR_VERSION

This data type is used to represent the version of a BIR header. The first version has a value of 1. 


 

typedef  uint8  CSSM_HRS_BIR_VERSION, *CSSM_HRS_BIR_VERSION_PTR;

CSSM_HRS_CANDIDATE

One of a set of candidates returned by Identify or IdentifyMatch, indicating a successful match. 


 

typedef struct cssm_hrs_candidate {
    CSSM_HRS_IDENTIFY_POPULATION_TYPE Type;
    union {
        CSSM_GUID_PTR BIRInDataBase;
        uint32 *BIRInArray;
    } BIR;
    CSSM_HRS_FAR  FARAchieved;
    CSSM_HRS_FRR  FRRAchieved;
} CSSM_HRS_CANDIDATE, *CSSM_HRS_CANDIDATE_PTR;

CSSM_HRS_CANDIDATE_ARRAY

An array of candidates returned by Identify or IdentifyMatch. 


 

typedef CSSM_HRS_CANDIDATE_PTR CSSM_HRS_CANDIDATE_ARRAY, \
    *CSSM_HRS_CANDIDATE_ARRAY_PTR;

CSSM_HRS_DB_ACCESS_TYPE

This bitmask describes a user's desired level of access to a database. The BSP may use the mask to determine what lock to obtain on a database. 


 

typedef uint32 CSSM_HRS_DB_ACCESS_TYPE, *CSSM_HRS_DB_ACCESS_TYPE_PTR;

#define CSSM_HRS_DB_ACCESS_READ    (0x1)
#define CSSM_HRS_DB_ACCESS_WRITE   (0x2)

CSSM_HRS_DB_CURSOR

A handle to a record in an open BIR database. The internal state for the handle includes the open database handle and also the position of a record in that open data base. All cursors to an open database are freed when the database is closed. 


 

typedef uint32 CSSM_HRS_DB_CURSOR, *CSSM_HRS_DB_CURSOR_PTR;

CSSM_HRS_DB_HANDLE

A handle to an open BIR database. 


 

typedef sint32 CSSM_HRS_DB_HANDLE, *CSSM_HRS_DB_HANDLE_PTR;
#define CSSM_HRS_DB_DEFAULT_DB_HANDLE    (-1)
#define CSSM_HRS_DB_INVALID_HANDLE       (-2)

CSSM_HRS_DBBIR_ID

A structure providing the handle to a database managed by the BSP, and the ID of a BIR in that database. 


 

typedef struct cssm_hrs_dbbir_id {
    CSSM_HRS_DB_HANDLE DbHandle;
    CSSM_GUID KeyValue;
} CSSM_HRS_DBBIR_ID, *CSSM_HRS_DBBIR_ID_PTR;

CSSM_HRS_FAR

A 32-bit integer value (N) that indicates a probable False Accept Rate of N/(231-1). The larger the value, the worse the result. 


 

typedef sint32 CSSM_HRS_FAR, *CSSM_HRS_FAR_PTR;
#define CSSM_HRS_FAR_NOT_SET    (-1)

CSSM_HRS_FRR

A 32-bit integer value (N) that indicates a probable False Reject Rate of N/(231-1). The larger the value, the worse the result. 


 

typedef sint32  CSSM_HRS_FRR, *CSSM_HRS_FRR_PTR;
#define CSSM_HRS_FRR_NOT_SET          (-1)
#define CSSM_HRS_FRR_NOT_SUPPORTED    (-2)

CSSM_HRS_GUI_BITMAP 



 

typedef struct cssm_hrs_gui_bitmap {
    uint32 Width;
    uint32 Height;
    CSSM_DATA_PTR Bitmap;
} CSSM_HRS_GUI_BITMAP, *CSSM_HRS_GUI_BITMAP_PTR;

CSSM_HRS_GUI_MESSAGE 



 

typedef uint32 CSSM_HRS_GUI_MESSAGE, *CSSM_HRS_GUI_MESSAGE_PTR;

CSSM_HRS_GUI_PROGRESS 



 

typedef uint8 CSSM_HRS_GUI_PROGRESS, *CSSM_HRS_GUI_PROGRESS_PTR;

CSSM_HRS_GUI_RESPONSE 



 

typedef uint8 CSSM_HRS_GUI_RESPONSE;

#define CSSM_HRS_CAPTURE_SAMPLE    (1)
#define CSSM_HRS_CANCEL            (2)
#define CSSM_HRS_CONTINUE          (3)
#define CSSM_HRS_VALID_SAMPLE      (4)
#define CSSM_HRS_INVALID_SAMPLE    (5)

CSSM_HRS_GUI_STATE

A mask that indicates GUI state, and also what other parameter values are provided in the GUI State Callback. 


 

typedef uint32 CSSM_HRS_GUI_STATE;

#define CSSM_HRS_SAMPLE_AVAILABLE     (0x0001)
#define CSSM_HRS_MESSAGE_PROVIDED     (0x0002)
#define CSSM_HRS_PROGRESS_PROVIDED    (0x0004)

CSSM_HRS_GUI_STATE_CALLBACK

A Callback function that an application supplies to allow the service provider to indicate GUI state information to the application, and to receive responses back. 


 

typedef CSSM_RETURN (CSSMAPI *CSSM_HRS_GUI_STATE_CALLBACK)
    (void *GuiStateCallbackCtx,
    CSSM_HRS_GUI_STATE GuiState,
    CSSM_HRS_GUI_RESPONSE Response,
    CSSM_HRS_GUI_MESSAGE Message,
    CSSM_HRS_GUI_PROGRESS Progress,
    CSSM_HRS_GUI_BITMAP_PTR SampleBuffer);

Parameters

GuiStateCallbackCtx (input)

A generic pointer to context information that was provided by the original requester and is being returned to its originator.

GuiState (input)

An indication of the current state of the service provider with respect to the GUI, plus an indication of what others parameters are available.

Response (output)

The response from the application back to the service provider on return from the Callback.

Message (input/optional)

The number of a message to display to the user. Message numbers are service-provider dependent. GuiState indicates if a Message is provided; if not the parameter is NULL.

Progress (input/optional)

A value that indicates (as a percentage) the amount of progress in the development of a Sample/BIR. The value may be used to display a progress bar. Not all service providers support a progress indication. GuiState indicates if a sample Progress value is provided in the call; if not, the parameter is NULL.

SampleBuffer (input/optional)

The current sample buffer for the application to display. GuiState indicates if a sample Buffer is provided; if not, the parameter is NULL.

CSSM_HRS_GUI_STREAMING_CALLBACK

A Callback function that an application supplies to allow the service provider to stream data in the form of a sequence of bitmaps. 


 

typedef CSSM_RETURN (CSSMAPI *CSSM_HRS_GUI_STREAMING_CALLBACK)
    (void *GuiStreamingCallbackCtx,
    CSSM_HRS_GUI_BITMAP_PTR Bitmap);

Parameters

GuiStreamingCallbackCtx (input)

A generic pointer to context information that was provided by the original requester and is being returned to its originator.

Bitmap (input)

A pointer to the bitmap to be displayed.

CSSM_HRS_HANDLE 



 

typedef CSSM_MODULE_HANDLE CSSM_HRS_HANDLE;  /* HRS Module Handle */

This data structure represents the HRS module handle. The handle value is a unique pairing between a HRS module and an application that has attached that module. HRS handles can be returned to an application as a result of the CSSM_ModuleAttach() function.

CSSM_HRS_IDENTIFY_POPULATION 



 

typedef struct cssm_hrs_identify_population {
    CSSM_HRS_IDENTIFY_POPULATION_TYPE Type;
    union {
        CSSM_HRS_DB_HANDLE_PTR  BIRDataBase;
        CSSM_HRS_BIR_ARRAY_POPULATION_PTR  BIRArray;
    } BIRs;
} CSSM_HRS_IDENTIFY_POPULATION, *CSSM_HRS_IDENTIFY_POPULATION_PTR;

CSSM_HRS_IDENTIFY_POPULATION_TYPE 



 

typedef uint8 CSSM_HRS_IDENTIFY_POPULATION_TYPE;

#define CSSM_HRS_DB_TYPE       (1)
#define CSSM_HRS_ARRAY_TYPE    (2)

CSSM_HRS_INPUT_BIR

A structure used to input a BIR to the API. Such input can be in one of three forms:

  1. A BIR Handle

  2. A key to a BIR in a database managed by the BSP. If the DbHandle is zero, the default database is assumed. (A DbHandle is returned when a database is opened).

  3. An actual BIR 



 

typedef struct cssm_hrs_input_bir {
    CSSM_HRS_INPUT_BIR_FORM Form;
    union {
        CSSM_HRS_DBBIR_ID_PTR  BIRinDb;
        CSSM_HRS_BIR_HANDLE_PTR  BIRinBSP;
        CSSM_HRS_BIR_PTR  BIR;
    } InputBIR;
} CSSM_HRS_INPUT_BIR, *CSSM_HRS_INPUT_BIR_PTR;

CSSM_HRS_INPUT_BIR_FORM 



 

typedef uint8 CSSM_HRS_INPUT_BIR_FORM;

#define CSSM_HRS_DATABASE_ID_INPUT    (1)
#define CSSM_HRS_BIR_HANDLE_INPUT     (2)
#define CSSM_HRS_FULLBIR_INPUT        (3)

CSSM_HRS_POWER_MODE

An enumeration that specifies the types of power modes the system will try to use. 


 

typedef uint32 CSSM_HRS_POWER_MODE;

/* All functions available           */
#define CSSM_HRS_POWER_NORMAL    (1)

/* Able to detect (for example)      */
/* insertion/fingeron/person present */
/* type of events                    */
#define CSSM_HRS_POWER_DETECT    (2)

/* minimum mode. all functions off   */
#define CSSM_HRS_POWER_SLEEP     (3)

CSSM_HRS_QUALITY

A value indicating the quality of the biometric data in a BIR. 


 

typedef sint8 CSSM_HRS_QUALITY;

The performance of biometrics varies with the quality of the biometric data. Since a universally accepted definition for this quality does not exist, HRS has elected to provide the following structure with the goal of framing the effect of quality on usage of the BSP (as envisioned by the BSP vendor). The scores as reported by the BSP are based on the purpose (BIR_PURPOSE) indicted by the application (for example, capture for enrollment/verify; capture for enrollment/identify; capture for verify; etc.). Additionally, the demands upon the biometric vary based on the actual customer application and/or environment (that is, a particular application usage may require higher quality samples than would normally be required by less demanding applications).

Quality measurements are reported as an integral value in the range 0-100 except as follows:

There are two objectives in providing CSSM_HRS_QUALITY feedback to the application:

  1. The primary objective is to have the BSP inform the application how suitable the biometric sample is for the purpose (CSSM_HRS_PURPOSE) specified by the application (as framed by the BSP vendor based on the use scenario intended by the BSP vendor).

  2. The secondary objective is to provide the application with relative results (for example, current sample is better/worse than previous sample).

Quality scores in the range 0-100 have the following interpretation:

0-25:
UNACCEPTABLE: The biometric data cannot be used for the purpose specified by the application (CSSM_HRS_PURPOSE). The biometric data must be replaced with a new sample.

26-50:
MARGINAL: The biometric data will provide poor performance for the purpose specified by the application (CSSM_HRS_PURPOSE) and in most application environments will compromise the intent of the application. The biometric data should be replaced with a new sample.

51-75:
ADEQUATE: The biometric data will provide good performance in most application environments based on the purpose specified by the application (CSSM_HRS_PURPOSE). The application should attempt to obtain higher quality data if the application developer anticipates demanding usage.

76-100:
EXCELLENT: The biometric data will provide good performance for the purpose specified by the application (CSSM_HRS_BIR_PURPOSE). The application may want to attempt to obtain better samples if the sample quality (CSSM_HRS_QUALITY) is in the lower portion of the range (e.g. 76, 77, ....) when convenient (for example during enrollment).

CSSM_HRS_STREAM_CALLBACK 



 

typedef CSSM_RETURN (CSSMAPI *CSSM_HRS_STREAM_CALLBACK)
    (void *StreamCallbackCtx,
    CSSM_DATA_PTR OutMessage,
    CSSM_DATA_PTR InMessage);

A callback function that an application supplies to allow the service provider to stream data in the form of a sequence of protocol data units (messages).

Parameters

StreamCallbackCtx (input)

A generic pointer to context information that was provided by the original requester and is being returned to its originator.

OutMessage (input)

A pointer to a protocol data unit to be sent to the communication partner.

InMessage (output/optional)

A pointer to a protocol data unit to be received back from the communicating partner.

CDSA/HRS Registry Schema

The various components of the CDSA/HRS implementation are represented by records in MDS.

The following section defines the information that should be kept for each component type.

Data Definitions

CSSM_HRS_OPERATIONS_MASK
A mask that indicates what operations are supported by the HRS service provider. 


 

typedef uint32 CSSM_HRS_OPERATIONS_MASK;

#define CSSM_HRS_CAPTURE               (0x0001)
#define CSSM_HRS_CREATETEMPLATE        (0x0002)
#define CSSM_HRS_PROCESS               (0x0004)
#define CSSM_HRS_VERIFYMATCH           (0x0008)
#define CSSM_HRS_IDENTIFYMATCH         (0x0010)
#define CSSM_HRS_ENROLL                (0x0020)
#define CSSM_HRS_VERIFY                (0x0040)
#define CSSM_HRS_IDENTIFY              (0x0080)
#define CSSM_HRS_IMPORT                (0x0100)
#define CSSM_HRS_SETPOWERMODE          (0x0200)
#define CSSM_HRS_DATABASEOPERATIONS    (0x0400)
CSSM_HRS_OPTIONS_MASK
A mask that indicates what options are supported by the HRS Service Provider. Note that optional functions are identified within the CSSM_HRS_OPERATIONS_MASK and not repeated here.

typedef uint32 CSSM_HRS_OPTIONS_MASK;    
     
#define CSSM_HRS_RAW (0x00000001) /* If set, indicates that the BSP supports the return of raw/audit data. */
#define CSSM_HRS_QUALITY_RAW (0x00000002) /* If set, BSP supports the return of a quality value (in the BIR header) for raw biometric data. */
#define CSSM_HRS_QUALITY_INTERMEDIATE (0x00000004) /* If set, BSP supports the return of a quality value (in the BIR header) for intermediate biometric data. */
#define CSSM_HRS_QUALITY_PROCESSED (0x00000008) /* If set, BSP supports the return of quality value (in the BIR header) for processed biometric data. */
#define CSSM_HRS_APP_GUI (0x00000010) /* If set, indicates that the BSP supports application control of the GUI. */
#define CSSM_HRS_STREAMINGDATA (0x00000020) /* If set, indicates that the BSP provides GUI streaming data. */
#define CSSM_HRS_USERVALIDATESSAMPLES (0x00000040) /* If set, User must validate each sample. */
#define CSSM_HRS_VERIFYSAMPLES (0x00000080) /* If set, BSP verifies each sample. */
#define CSSM_HRS_SOURCEPRESENT (0x00000100) /* If set, BSP supports detection of source presence. */
#define CSSM_HRS_PAYLOAD (0x00001000) /* If set, indicates that the BSP supports payload carry (accepts payload during enroll/process and returns payroll upon successful verify). */
#define CSSM_HRS_BIR_SIGN (0x00002000) /* If set, BSP returns signed BIRs. */
#define CSSM_HRS_BIR_ENCRYPT (0x00004000) /* If set, BSP returns encrypted BIRs. */
#define CSSM_HRS_FRR_SUPPORTED (0x00010000) /* If set, indicates BSP supports the return of actual FRR during matching operations (Verify, VerifyMatch, Identify, IdentifyMatch). */
#define CSSM_HRS_ADAPTATION (0x00020000) /* If set, BSP supports BIR adaptation (return of Verify or VerifyMatch operation). */
#define CSSM_HRS_BINNING (0x00040000) /* If set, BSP supports binning (parameter used in Identify and IdentifyMatch operations). */
#define CSSM_HRS_DEFAULTDATABASE (0x00080000) /* If set, BSP supports a default database. */
#define CSSM_HRS_LOCAL_BSP (0x01000000) /* If set, BSP can operate in standalone mode. */
#define CSSM_HRS_CLIENT_BSP (0x02000000) /* If set, BSP can operate as a Client (that is, can Capture). */
#define CSSM_HRS_SERVER_BSP (0x04000000) /* If set, BSP can operate as a Server. */
#define CSSM_HRS_STREAMINGCALLBACK (0x08000000) /* If set, BSP supports streaming callbacks and StreamInputOutput */
#define CSSM_HRS_PROGRESS (0x10000000) /* If set, BSP supports the return of progress. */
#define CSSM_HRS_SELFCONTAINEDDEVICE (0x20000000) /* If set, BSP is supporting a self-contained device. */

Component Schema

Primary HRS Service Provider Relation
The service provider schema describes capabilities of an HRS service provider module.

Field Name Field Data Type Comment
ModuleID STRING GUID uniquely identifying HRS SP
SSID UINT32 4 byte Subservice ID of attached sensor device
ModuleName STRING Filename of HRS Module
ProductVersion STRING HRS SP product version string
(in dotted high/low format - e.g. 2.0).
Vendor STRING Service provider vendor name in ASCII text.
HRSSpecVersion STRING Highest compatible HRS Spec Version (in dotted high/low format - e.g. 2.0)
SupportedFormats MULTIUINT32 An array of 2-byte integer pairs. Each pair specifying a supported biometric data format. See CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT
FactorsMask UINT32 A mask which indicates what forms of authentication are supported (CSSM_HRS_BIR_AUTH_FACTORS)
Operations UINT32 Operations supported by service provider (CSSM_HRS_OPERATIONS_MASK)
Options UINT32 Options supported by the BSP CSSM_HRS_OPTIONS_MASK
PayloadPolicy UINT32 Threshold setting (minimum FAR value) used to determine when to release a payload. CSSM_HRS_FAR
MaxPayloadSize UINT32 Maximum size in bytes of a payload.
DefaultVerifyTimeout SINT32 Default timeout value (in milliseconds) used by a BSP for verify operations when no timeout is set by the application
DefaultIdentifyTimeout SINT32 Default timeout value (in milliseconds) used by a BSP for identify operations when no timeout is set by the application.
DefaultCaptureTimeout SINT32 Default timeout value (in milliseconds) used by a BSP for capture operations when no timeout is set by the application.
DefaultEnrollTimeout SINT32 Default timeout value (in milliseconds) used by a BSP for enroll operations when no timeout is set by the application.
MAXBSPDBsize UINT32 Maximum size of a BSP owned (internal) database. If NULL, no BSP database exists.
MaxIdentify UINT32 Largest population supported by Identify function
Unlimited = FFFFFFFF.

Biometric Device Relation
The information in the biometric device registry entry is updated each time a biometric device is attached to or removed from the service provider.

Field Name Field Data Type Comment
ModuleID STRING GUID (in string format) uniquely identifying service provider module
SSID UINT32 4 byte device ID
SupportedFormats MULTIUINT32 BIR Formats supported by BSP+device
See CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT
SupportedEvents UINT32 A CSSM_HRS_MODULE_EVENT_MASK indicating which types of events are supported
DeviceVendor STRING Unicode text name of device Vendor.
DeviceDescription STRING Unicode text description of the biometric device.
DeviceSerialNumber STRING Serial Number of biometric device
DeviceHardwareVersion STRING Device hardware version string
(in dotted high/low format - for example 2.0).
DeviceFirmwareVersion STRING Device Firmware version string
(in dotted high/low format - for example 2.0).
AuthenticatedDevice BOOL An indication of whether the device has been authenticated.

HRS Error Codes

Configurable HRS Error Code Constants

The following constant can be configured on a per platform basis. 

#define CSSM_HRS_BASE_ERROR \
    (CSSM_AC_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 
#define CSSM_HRS_PRIVATE_ERROR \
    (CSSM_HRS_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET)

HRS Error Values Derived from Common Error Codes 


#define CSSMERR_HRS_INTERNAL_ERROR \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)        

#define CSSMERR_HRS_MEMORY_ERROR \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)            

#define CSSMERR_HRS_INVALID_POINTER \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)

#define CSSMERR_HRS_INVALID_INPUT_POINTER \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)

#define CSSMERR_HRS_INVALID_OUTPUT_POINTER \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)

#define CSSMERR_HRS_FUNCTION_NOT_IMPLEMENTED \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)

#define CSSMERR_HRS_OS_ACCESS_DENIED \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)

#define CSSMERR_HRS_FUNCTION_FAILED \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)    

#define CSSMERR_HRS_INVALID_DATA \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INVALID_DATA)

#define CSSMERR_HRS_INVALID_DB_HANDLE \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_HANDLE)

HRS-Specific Error Values 


#define CSSM_HRS_BASE_HRS_ERROR \
    (CSSM_HRS_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)


#define CSSMERR_HRS_UNABLE_TO_CAPTURE (CSSM_HRS_BASE_HRS_ERROR+1)
The BSP is unable to capture raw samples from the device.


#define CSSMERR_HRS_TOO_MANY_HANDLES (CSSM_HRS_BASE_HRS_ERROR+2)
The BSP has no more space to allocate BIR handles.


#define CSSMERR_HRS_TIMEOUT_EXPIRED (CSSM_HRS_BASE_HRS_ERROR+3)
The Function has been terminated because the timeout value has expired.


#define CSSMERR_HRS_INVALID_BIR (CSSM_HRS_BASE_HRS_ERROR+4)
The input BIR is invalid for the purpose required.


#define CSSMERR_HRS_BIR_SIGNATURE_FAILURE (CSSM_HRS_BASE_HRS_ERROR+5)
The BSP could not validate the signature on the BIR.


#define CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD (CSSM_HRS_BASE_HRS_ERROR+6)
The BSP is unable to include the payload in the new BIR.


#define CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED \
    (CSSM_HRS_BASE_HRS_ERROR+7)
The BSP does not support the requested adaptation of a BIR.


#define CSSMERR_HRS_NO_INPUT_BIRS (CSSM_HRS_BASE_HRS_ERROR+8)
The identify population is NULL.


#define CSSMERR_HRS_UNSUPPORTED_FORMAT (CSSM_HRS_BASE_HRS_ERROR+9)
The BSP does not support the data form for the Import function.


#define CSSMERR_HRS_UNABLE_TO_IMPORT (CSSM_HRS_BASE_HRS_ERROR+10)
The BSP was unable to construct a BIR from the input data.


#define CSSMERR_HRS_AUDITDATA_NOT_SUPPORTED \
    (CSSM_HRS_BASE_HRS_ERROR+11)
The BSP does not support the return of audit data.


#define CSSMERR_HRS_FUNCTION_NOT_SUPPORTED \
    (CSSM_HRS_BASE_HRS_ERROR+12)
The BSP does not support this operation.


#define CSSMERR_HRS_INCONSISTENT_PURPOSE (CSSM_HRS_BASE_HRS_ERROR+13)
The purpose recorded in the BIR, and the requested purpose, are inconsistent
with the function being performed.






#define CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED \


    (CSSM_HRS_BASE_HRS_ERROR+14)


The function requires a fully-processed BIR.






#define CSSMERR_HRS_PURPOSE_NOT_SUPPORTED (CSSM_HRS_BASE_HRS_ERROR+15)


The BSP does not support the requested purpose.






#define CSSMERR_HRS_INVALID_HANDLE (CSSM_HRS_BASE_HRS_ERROR+16)


No BIR exists with the requested handle.






#define CSSMERR_HRS_UNABLE_TO_OPEN_DATABASE \


    (CSSM_HRS_BASE_HRS_ERROR+256)


BSP is unable to open the specified database.






#define CSSMERR_HRS_DATABASE_IS_LOCKED (CSSM_HRS_BASE_HRS_ERROR+257)


The database cannot be opened for the access requested 


because it is locked.






#define CSSMERR_HRS_DATABASE_DOES_NOT_EXIST \


    (CSSM_HRS_BASE_HRS_ERROR+258)


The specified database name does not exist.








#define CSSMERR_HRS_DATABASE_ALREADY_EXISTS \


    (CSSM_HRS_BASE_HRS_ERROR+259)


Create failed because the database already exists.






#define CSSMERR_HRS_INVALID_DATABASE_NAME (CSSM_HRS_BASE_HRS_ERROR+260)


The database name is invalid.






#define CSSMERR_HRS_RECORD_NOT_FOUND (CSSM_HRS_BASE_HRS_ERROR+261)


No record exists with the requested key.






#define CSSMERR_HRS_CURSOR_IS_INVALID (CSSM_HRS_BASE_HRS_ERROR+262)


The specified cursor is invalid.






#define CSSMERR_HRS_DATABASE_IS_OPEN (CSSM_HRS_BASE_HRS_ERROR+263)


The database is already open.






#define CSSMERR_HRS_INVALID_ACCESS_REQUEST \


    (CSSM_HRS_BASE_HRS_ERROR+264)


The access type is unrecognized.






#define CSSMERR_HRS_END_OF_DATABASE (CSSM_HRS_BASE_HRS_ERROR+265)


End of database has been reached.

BSP Operations


Handle Operations




This section gives the definitions for the
BSP Handle
operations.
Previous section.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

NAME


CSSM_HRS_FreeBIRHandle,
HRS_FreeBIRHandle

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_FreeBIRHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle); 





SPI:


CSSM_RETURN CSSMHRI HRS_FreeBIRHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle);

DESCRIPTION


Frees the memory and resources associated with the specified BIR Handle. The associated BIR is no longer referenceable
through that handle. If necessary, the application must make the BIR persistent either in a HRS-managed database or an
application-managed database before freeing the handle.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

Handle (input)



The BIR Handle to be freed.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_GetBIRFromHandle,
HRS_GetBIRFromHandle

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_GetBIRFromHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle,


    CSSM_HRS_BIR_PTR *BIR);





SPI:


CSSM_RETURN CSSMHRI HRS_GetBIRFromHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle,


    CSSM_HRS_BIR_PTR *BIR);

DESCRIPTION


Retrieves the BIR associated with a BIR handle.
The handle is invalidated. The HRS service provider allocates the storage
for both the retrieved BIR structure and its data members,
using the application's memory allocation callback function.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

Handle (input)



The handle of the BIR to be retrieved.

BIR (output)



The retrieved BIR.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_GetHeaderFromHandle,
HRS_GetHeaderFromHandle

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_GetHeaderFromHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle,


    CSSM_HRS_BIR_HEADER_PTR  Header);





SPI:


CSSM_RETURN CSSMHRI HRS_GetHeaderFromHandle 


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_HANDLE  Handle,


    CSSM_HRS_BIR_HEADER_PTR  Header);

DESCRIPTION


Retrieves the BIR header identified by
Handle.
The BIR Handle is not freed by the HRS service provider.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

Handle (input)



The handle of the BIR whose header is to be retrieved.

Header (output)



The header of the specified BIR.


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


See the HRS Error Codes section
HRS Error Codes.


Callback and Event Operations


This section gives the definitions for the
BSP Callback and Event
operations.
Previous section.


NAME


CSSM_HRS_EnableEvents,
HRS_EnableEvents

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_EnableEvents


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_MODULE_EVENT_MASK *Events);





SPI:


CSSM_RETURN CSSMHRI HRS_EnableEvents


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_MODULE_EVENT_MASK *Events);

DESCRIPTION


This function enables the events (indicated by the Events mask) from the attached HRS service provider in the current
process. All other events from this HRS service provider are disabled for this process.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

Events (input)



A pointer to a mask indicating which events to enable.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_SetGUICallbacks,
HRS_SetGUICallbacks

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_SetGUICallbacks


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_GUI_STREAMING_CALLBACK  GuiStreamingCallback,


    void *GuiStreamingCallbackCtx,


    CSSM_HRS_GUI_STATE_CALLBACK  GuiStateCallback,


    void *GuiStateCallbackCtx);





SPI:


CSSM_RETURN CSSMHRI HRS_SetGUICallbacks


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_GUI_STREAMING_CALLBACK  GuiStreamingCallback,


    void *GuiStreamingCallbackCtx,


    CSSM_HRS_GUI_STATE_CALLBACK  GuiStateCallback,


    void *GuiStateCallbackCtx);

DESCRIPTION


This function allows the application to establish callbacks so that the application may control the "look-and-feel" of the
biometric user interface.


Note that not all HRS service providers provide streaming data.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

GuiStreamingCallback (input)



A pointer to an application callback to deal with the presentation of biometric
streaming data.

GuiStreamingCallbackCtx (input)



A generic pointer to context information provided by the application that will
be presented on the callback.

GuiStateCallback (input)



A pointer to an application callback to deal with GUI state changes.

GuiStateCallbackCtx (input)



A generic pointer to context information provided by the application that will be
presented on the callback.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_CancelGUICallbacks,
HRS_CancelGUICallbacks

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_CancelGUICallbacks


    (CSSM_HRS_HANDLE  ModuleHandle);





SPI:


CSSM_RETURN CSSMHRI HRS_CancelGUICallbacks


    (CSSM_HRS_HANDLE  ModuleHandle);

DESCRIPTION


This function cancels
GUICallbacks
if they have been set. A
GUICallback
should be cancelled before the service provider is detached.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_SetStreamCallback,
HRS_SetStreamCallback

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_SetStreamCallback


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_STREAM_CALLBACK  StreamCallback,


    void *StreamCallbackCtx);





SPI:


CSSM_RETURN CSSMHRI HRS_SetStreamCallback


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_STREAM_CALLBACK  StreamCallback,


    void *StreamCallbackCtx);

DESCRIPTION


This function allows the application to establish a callback for client/server communication. The callback allows the HRS
service provider to send a protocol message to its partner service provider, and to receive a protocol message in exchange.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

StreamCallback (input)



A pointer to an application callback to deal with the Client/Server transmission of
protocol data units between HRS service providers

StreamCallbackCtx (input)



A generic pointer to context information provided by the application that will be
presented on the callback.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_CancelStreamCallbacks,
HRS_CancelStreamCallbacks

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_CancelStreamCallbacks


    (CSSM_HRS_HANDLE  ModuleHandle);





SPI:


CSSM_RETURN CSSMHRI HRS_CancelStreamCallbacks


    (CSSM_HRS_HANDLE  ModuleHandle);

DESCRIPTION


This function cancels the
StreamCallback
if it has been set. A
StreamCallback
should be cancelled before the service provider is detached.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.


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


See the HRS Error Codes section
HRS Error Codes.

Previous section.


NAME


CSSM_HRS_StreamInputOutput,
HRS_StreamInputOutput

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_StreamInputOutput


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_DATA_PTR  InMessage,


    CSSM_DATA_PTR  OutMessage);





SPI:


CSSM_RETURN CSSMHRI HRS_StreamInputOutput


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_DATA_PTR  InMessage,


    CSSM_DATA_PTR  OutMessage);

DESCRIPTION


This function allows the application to pass a protocol data unit into the HRS service provider from the partner HRS service
provider, and to obtain a response message to return to the partner - see
API Model.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

InMessage (input)



InMessage
contains a protocol data unit from the partner HRS service provider.

OutMessage (output)



OutMessage
contains a protocol data unit to be sent back to the partner HRS service
provider. If the parameter is NULL, there is no message to return.


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


See the HRS Error Codes section
HRS Error Codes.


Biometric Operations


This section gives the definitions for the
BSP Biometric
operations.
Previous section.


NAME


CSSM_HRS_Capture,
HRS_Capture

SYNOPSIS





API:


CSSM_RETURN CSSMAPI CSSM_HRS_Capture


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_PURPOSE  Purpose,


    CSSM_HRS_BIR_HANDLE_PTR  CapturedBIR,


    sint32  Timeout,


    CSSM_HRS_BIR_HANDLE_PTR  AuditData);





SPI:


CSSM_RETURN CSSMHRI HRS_Capture


    (CSSM_HRS_HANDLE  ModuleHandle,


    CSSM_HRS_BIR_PURPOSE  Purpose,


    CSSM_HRS_BIR_HANDLE_PTR  CapturedBIR,


    sint32  Timeout,


    CSSM_HRS_BIR_HANDLE_PTR  AuditData);

DESCRIPTION


This function captures samples for the purpose specified, and returns either an "intermediate" type BIR (if the
Process
function needs to be called), or a "processed" BIR (if not). The
Purpose
is recorded in the header of the
CapturedBIR.
If
AuditData
is non-NULL, a BIR of type "raw" may be returned. The function returns handles to whatever data is collected,
and all local operations can be completed through use of the handles.


If the application needs to acquire the data either to
store it in a database or to send it to a server, the application can retrieve the data with the
HRS_GetBIRFromHandle()
function.


The application may request control of the GUI "look-and-feel" by providing a
GUI callback pointer in
HRS_SetGUICallbacks().


Capture
serializes use of the device. If two or more applications
are racing for the device, the losers will wait until the timeout expires. This serialization takes place in all functions that
capture data.

PARAMETERS


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

ModuleHandle (input)



The handle of the attached HRS service provider.

Purpose (input)



A value indicating the purpose of the biometric data capture.

CapturedBIR (output)



A handle to a BIR containing captured data.
This data is either an "intermediate" type BIR,
(which can only be used by either the
Process
or
CreateTemplate
functions, depending on the purpose), or a "processed" BIR,
(which can be used directly by
VerifyMatch
or
IdentifyMatch,
depending on the purpose).

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)



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
BSPs support the collection of audit data. A service provider may return a handle value of
CSSM_HRS_UNSUPPORTED_BIR_HANDLE
indicating not
supported, or a value of
CSSM_HRS_INVALID_BIR_HANDLE
indicating no audit data is available.


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



CSSMERR_HRS_UNABLE_TO_CAPTURE
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_PURPOSE_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_CreateTemplate, HRS_CreateTemplate

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_CreateTemplate
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *CapturedBIR,
    const CSSM_HRS_INPUT_BIR *StoredTemplate,
    CSSM_HRS_BIR_HANDLE_PTR  NewTemplate,
    const CSSM_DATA *Payload);

SPI:
CSSM_RETURN CSSMHRI HRS_CreateTemplate
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *CapturedBIR,
    const CSSM_HRS_INPUT_BIR *StoredTemplate,
    CSSM_HRS_BIR_HANDLE_PTR  NewTemplate,
    const CSSM_DATA *Payload);

DESCRIPTION

This function takes a BIR containing raw biometric data for the purpose of creating a new enrollment template. A new BIR is constructed from the CapturedBIR, and (optionally) it may perform an adaptation based on an existing StoredTemplate. The old StoredTemplate remains unchanged. If the StoredTemplate contains a payload, the payload is not copied into the NewTemplate. If the NewTemplate needs a payload, then that Payload must be presented as an argument to the function.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

CapturedBIR (input)

The captured BIR or its handle.

StoredTemplate (input/optional)

Optionally, the template to be adapted, or its key in a database, or its handle.

NewTemplate (output)

A handle to a newly created template that is derived from the CapturedBIR and (optionally) the StoredTemplate.

Payload (input/optional)

A pointer to data that will be wrapped inside the newly created template. This parameter is ignored, if NULL.

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


CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_PURPOSE_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_Process, HRS_Process

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_Process
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *CapturedBIR,
    CSSM_HRS_BIR_HANDLE_PTR  ProcessedBIR);

SPI:
CSSM_RETURN CSSMHRI HRS_Process
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *CapturedBIR,
    CSSM_HRS_BIR_HANDLE_PTR  ProcessedBIR);

DESCRIPTION

This function processes the intermediate data captured via a call to HRS_Capture() for the purpose of either verification or identification. If the processing capability is in the attached service provider, a "processed" BIR is returned, otherwise, ProcessedBIR is set to NULL.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

CapturedBIR (input)

The captured BIR or its handle.

ProcessedBIR (output)

A handle for the newly constructed "processed" BIR, NULL.

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


CSSMERR_HRS_INVALID_BIR
CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_PURPOSE_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_VerifyMatch, HRS_VerifyMatch

SYNOPSIS


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);

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.

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 -1 to indicate that adaptation is not supported. A handle value of -2 indicates that it was not possible to adapt.

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.

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


CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_IdentifyMatch, HRS_IdentifyMatch

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_IdentifyMatch
    (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_IDENTIFY_POPULATION *Population,
    CSSM_BOOL  Binning,
    uint32  MaxNumberOfResults,
    uint32 *NumberOfResults,
    CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
    sint32  Timeout);

SPI:
CSSM_RETURN CSSMHRI HRS_IdentifyMatch
    (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_IDENTIFY_POPULATION *Population,
    CSSM_BOOL  Binning,
    uint32  MaxNumberOfResults,
    uint32 *NumberOfResults,
    CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates,
    sint32  Timeout);

DESCRIPTION

This function performs an identification (1-to-many) match between a ProcessedBIR and a set of stored BIRs. The ProcessedBIR is the "processed" BIR captured specifically for this identification. The population that the match takes place against can be presented in one of three ways:

  1. In a database identified by an open database handle

  2. Input in an array of BIRs

  3. In the "default" database of the BSP (possibly stored in the biometric device)

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 FARAchieved and, optionally, the FRRAchieved are returned for each result in the Candidate array.

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 identified.

Population (input)

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

Binning (input)

A Boolean indicating whether Binning is on or off. Binning is a search-optimization technique that the service provider 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 increases 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 candidate list. This value can be any positive number. A -1 value means the service provider's default timeout value will be 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


CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_NO_INPUT_BIRS
CSSMERR_HRS_FUNCTION_NOT_SUPPORTED
CSSMERR_HRS_INCONSISTENT_PURPOSE
CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED

See also the HRS Error Codes section HRS Error Codes.

REMARKS

Not all service providers support 1:N identification.

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

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

Previous section.

NAME

CSSM_HRS_Enroll, HRS_Enroll

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_Enroll
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_BIR_PURPOSE  Purpose,
    const CSSM_HRS_INPUT_BIR *StoredTemplate,
    CSSM_HRS_BIR_HANDLE_PTR  NewTemplate,
    const CSSM_DATA *Payload,
    sint32  Timeout
    CSSM_HRS_BIR_HANDLE_PTR  AuditData);

SPI:
CSSM_RETURN CSSMHRI HRS_Enroll
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_BIR_PURPOSE  Purpose,
    const CSSM_HRS_INPUT_BIR *StoredTemplate,
    CSSM_HRS_BIR_HANDLE_PTR  NewTemplate,
    const CSSM_DATA *Payload,
    sint32  Timeout
    CSSM_HRS_BIR_HANDLE_PTR  AuditData);

DESCRIPTION

This function captures biometric data from the attached device for the purpose of creating a ProcessedBIR for the purpose of enrollment. The Enroll 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.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

Purpose (input)

A value indicating the desired purpose of Enrollment.

StoredTemplate (input/optional)

Optionally, the BIR to be adapted, or its key in a database, or its handle.

NewTemplate (output)

A handle to a newly created template that is derived from the new raw samples and (optionally) the StoredTemplate.

Payload (input/optional)

A pointer to data that will be wrapped inside the newly created template. This parameter is ignored, if NULL.

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 BSP's default timeout value will be used.

AuditData (output/optional)

A handle to a BIR containing biometric audit data. This data may be used to provide a human-identifiable data of the person at the device.

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


CSSMERR_HRS_UNABLE_TO_CAPTURE
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_PURPOSE_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_Verify, HRS_Verify

SYNOPSIS


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);

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 AdaptedBIRmaybeconstructed.

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.

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 BSPs support the adaptation of BIRs. The function may return a handle value of -1 to indicate that adaptation is not supported. A handle value of -2 indicates that it was not possible to adapt.

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)

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. A service provider may return a handle value of -1 indicating not supported, or a value of -2 indicating no audit data is available.

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


CSSMERR_HRS_UNABLE_TO_CAPTURE
CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_INCONSISTENT_PURPOSE

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_Identify, HRS_Identify

SYNOPSIS


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_INPUT_BIR *ProcessedBIR,
    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_INPUT_BIR *ProcessedBIR,
    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);

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.

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 identified.

Population (input)

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

Binning (input)

A Boolean 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 increases 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)

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.

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


CSSMERR_HRS_UNABLE_TO_CAPTURE
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_BIR_SIGNATURE_FAILURE
CSSMERR_HRS_TIMEOUT_EXPIRED
CSSMERR_HRS_NO_INPUT_BIRS
CSSMERR_HRS_FUNCTION_NOT_SUPPORTED
CSSMERR_HRS_INCONSISTENT_PURPOSE

See also the HRS Error Codes section HRS Error Codes.

REMARKS

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.

Previous section.

NAME

CSSM_HRS_Import, HRS_Import

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_Import
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_DATA *InputData,
    CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT  InputFormat,
    CSSM_HRS_BIR_PURPOSE  Purpose,
    CSSM_HRS_BIR_HANDLE_PTR  ConstructedBIR);

SPI:
CSSM_RETURN CSSMHRI HRS_Import
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_DATA *InputData,
    CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT  InputFormat,
    CSSM_HRS_BIR_PURPOSE  Purpose,
    CSSM_HRS_BIR_HANDLE_PTR  ConstructedBIR);

DESCRIPTION

This function imports non-real-time raw biometric data to construct a BIR for the purpose specified. InputData identifies the memory buffer containing the raw biometric data, while InputFormat identifies the form of the raw biometric data.

The function returns a handle to the ConstructedBIR.

If the application needs to acquire the BIR either to store it in a database or to send it to a server, the application can retrieve the data with the HRS_GetBIRFromHandle() function, or store it directly using HRS_DbStoreBIR().

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

InputData (input)

A pointer to image/stream data to import into a Processed BIR. The image/stream conforms to the standard identified by InputFormat.

InputFormat (input)

The format of the InputData.

Purpose (input)

A value indicating the Enroll purpose.

ConstructedBIR (output)

A handle to a BIR constructed from the imported biometric data. This BIR may be either an Intermediate or Processed BIR (as indicated in the header).

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


CSSMERR_HRS_UNSUPPORTED_FORMAT
CSSMERR_HRS_UNABLE_TO_IMPORT
CSSMERR_HRS_TOO_MANY_HANDLES
CSSMERR_HRS_FUNCTION_NOT_SUPPORTED
CSSMERR_HRS_PURPOSE_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_SetPowerMode, HRS_SetPowerMode

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_SetPowerMode
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_POWER_MODE  PowerMode);

SPI:
CSSM_RETURN CSSMHRI HRS_SetPowerMode
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_POWER_MODE  PowerMode);

DESCRIPTION

This function sets the device to the requested power mode if the device supports it.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

PowerMode (input)

A 32-bit value indicting the power mode to set the device to.

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


CSSMERR_HRS_FUNCTION_NOT_SUPPORTED

See also the HRS Error Codes section HRS Error Codes.

Database Operations

This section gives the definitions for the BSP Database operations.
Previous section.

NAME

CSSM_HRS_DbOpen, HRS_DbOpen

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbOpen
    (CSSM_HRS_HANDLE  ModuleHandle, 
    const uint8 *DbName,
    CSSM_HRS_DB_ACCESS_TYPE  AccessRequest,
    CSSM_HRS_DB_HANDLE_PTR  DbHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

SPI:
CSSM_RETURN CSSMHRI HRS_DbOpen
    (CSSM_HRS_HANDLE  ModuleHandle, 
    const uint8 *DbName,
    CSSM_HRS_DB_ACCESS_TYPE  AccessRequest,
    CSSM_HRS_DB_HANDLE_PTR  DbHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

DESCRIPTION

This function opens the data store with the specified name under the specified access mode. A database Cursor is set to point to the first record in the database.

Note that the default database (if any) is always open.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbName (input)
A pointer to the null-terminated string containing the name of the database.

AccessRequest (input)

An indicator of the requested access mode for the database, such as read or write.

DbHandle (output)

The handle to the opened data store. The value will be set to CSSM_HRS_DB_INVALID_HANDLE if the function fails.

Cursor (output)

A handle that can be used to iterate through the database.

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


CSSMERR_HRS_UNABLE_TO_OPEN_DATABASE
CSSMERR_HRS_DATABASE_IS_LOCKED
CSSMERR_HRS_DATABASE_DOES_NOT_EXIST
CSSMERR_HRS_INVALID_DATABASE_NAME
CSSMERR_HRS_INVALID_ACCESS_REQUEST

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbClose, HRS_DbClose

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbClose
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle);  

SPI:
CSSM_RETURN CSSMHRI HRS_DbClose
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle);

DESCRIPTION

This function closes an open database. All cursors currently set to the database are freed. The default database cannot be closed.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbHandle (input)

The DB handle for an open database managed by the service provider. This specifies the open database to be closed.

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

See the HRS Error Codes section HRS Error Codes.
Previous section.

NAME

CSSM_HRS_DbCreate, HRS_DbCreate

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbCreate
    (CSSM_HRS_HANDLE  ModuleHandle,
    const uint8 *DbName,
    CSSM_HRS_DB_ACCESS_TYPE  AccessRequest,
    CSSM_HRS_DB_HANDLE_PTR  DbHandle);

SPI:
CSSM_RETURN CSSMHRI HRS_DbCreate
    (CSSM_HRS_HANDLE  ModuleHandle,
    const uint8 *DbName,
    CSSM_HRS_DB_ACCESS_TYPE  AccessRequest,
    CSSM_HRS_DB_HANDLE_PTR  DbHandle);

DESCRIPTION

This function creates and opens a new database. The name of the new database is specified by the input parameter DbName. The newly created database is opened under the specified access mode.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbName (input)

A pointer to the null-terminated string containing the name of the new database.

AccessRequest (input)

An indicator of the requested access mode for the database, such as read or write.

DbHandle (output)

The handle to the newly created and open data store. The value will be set to CSSM_HRS_DB_INVALID_HANDLE if the function fails.

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


CSSMERR_HRS_DATABASE_ALREADY_EXISTS
CSSMERR_HRS_INVALID_DATABASE_NAME
CSSMERR_HRS_INVALID_ACCESS_REQUEST

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbDelete, HRS_DbDelete

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbDelete
    (CSSM_HRS_HANDLE  ModuleHandle, 
    const uint8 *DbName);

SPI:
CSSM_RETURN CSSMHRI HRS_DbDelete
    (CSSM_HRS_HANDLE  ModuleHandle, 
    const uint8 *DbName);

DESCRIPTION

This function deletes all records from the specified database and removes all state information associated with that database.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbName (input)

A pointer to the null-terminated string containing the name of the database to be deleted.

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


CSSMERR_HRS_DATABASE_IS_OPEN
CSSMERR_HRS_INVALID_DATABASE_NAME

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbSetCursor, HRS_DbSetCursor

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbSetCursor
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

SPI:
CSSM_RETURN CSSMHRI HRS_DbSetCursor
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

DESCRIPTION

The Cursor is set to point to the record indicated by the KeyValue in the database identified by the DbHandle. A NULL value will set the cursor to the first record in the database.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbHandle (input)

A handle to the open database.

KeyValue (input)

The key into the database of the BIR to which the Cursor is to be set.

Cursor (output)

A handle that can be used to iterate through the database from the retrieved record.

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


CSSMERR_HRS_RECORD_NOT_FOUND

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbFreeCursor, HRS_DbFreeCursor

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbFreeCursor 
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor); 

SPI:
CSSM_RETURN CSSMHRI HRS_DbFreeCursor 
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

DESCRIPTION

Frees memory and resources associated with the specified Cursor.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

Cursor (input)

The database Cursor to be freed.

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


CSSMERR_HRS_CURSOR_IS_INVALID

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbStoreBIR, HRS_DbStoreBIR

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbStoreBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *BIRToStore,
    CSSM_HRS_DB_HANDLE  DbHandle,
    CSSM_GUID_PTR  Guid);

SPI:
CSSM_RETURN CSSMHRI HRS_DbStoreBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    const CSSM_HRS_INPUT_BIR *BIRToStore,
    CSSM_HRS_DB_HANDLE  DbHandle,
    CSSM_GUID_PTR  Guid);

DESCRIPTION

The BIR identified by the BIRToStore parameter is stored in the open database identified by the DbHandle parameter. If the BIRToStore is identified by a BIR Handle, the input BIR Handle is freed. If the BIRToStore is identified by a database key value, the BIR is copied to the open database.

A new GUID is assigned to the new BIR in the database, and this GUID can be used as a key value to access the BIR later.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

BIRToStore (input)

The BIR to be stored in the open database (either the BIR, or its handle, or the index to it in another open database).

DbHandle (input)

The handle to the open database.

Guid (output)

A GUID that uniquely identifies the new BIR in the database. This GUID cannot be changed. To associate a different BIR with the user, it is necessary to delete the old one, store a new one in the database, and then replace the old GUID with the new one in the application account database.

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

See the HRS Error Codes section HRS Error Codes.
Previous section.

NAME

CSSM_HRS_DbGetBIR, HRS_DbGetBIR

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbGetBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue,
    CSSM_HRS_BIR_HANDLE_PTR  RetrievedBIR,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

SPI:
CSSM_RETURN CSSMHRI HRS_DbGetBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue,
    CSSM_HRS_BIR_HANDLE_PTR  RetrievedBIR,
    CSSM_HRS_DB_CURSOR_PTR  Cursor);

DESCRIPTION

The BIR identified by the KeyValue parameter in the open database identified by the DbHandle parameter is retrieved.

The BIR is copied into the service provider's storage and a handle to it is returned. The Cursor is set to point to the next record, or the first record in the database if the retrieved BIR is the last.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbHandle (input)

The handle to the open database.

KeyValue (input)

The key into the database of the BIR to retrieve.

RetievedBIR (output)

A handle to the retrieved BIR.

Cursor (output)

A handle that can be used to iterate through the database from the retrieved record.

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


CSSMERR_HRS_RECORD_NOT_FOUND

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbGetNextBIR, HRS_DbGetNextBIR

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbGetNextBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor,
    CSSM_HRS_BIR_HANDLE_PTR  RetievedBIR,
    CSSM_GUID_PTR  Guid);

SPI:
CSSM_RETURN CSSMHRI HRS_DbGetNextBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_CURSOR_PTR  Cursor,
    CSSM_HRS_BIR_HANDLE_PTR  RetievedBIR,
    CSSM_GUID_PTR  Guid);

DESCRIPTION

The BIR identified by the Cursor parameter is retrieved. The BIR is copied into the service provider's storage and a handle to it is returned, and a pointer to the GUID that uniquely identifies the BIR in the database is returned.. The Cursor is updated to the next record in the database, or to the first when the end of the database is reached.

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

Cursor (input/output)

A handle indicating which record to retrieve.

RetrievedBIR (output)

A handle to the retrieved BIR.

Guid (output)

The GUID that uniquely identifies the retrieved BIR in the database.

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


CSSMERR_HRS_END_OF_DATABASE
CSSMERR_HRS_CURSOR_IS_INVALID

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbQueryBIR, HRS_DbQueryBIR

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbQueryBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_HRS_INPUT_BIR *BIRToQuery,
    CSSM_GUID_PTR  Guid);

SPI:
CSSM_RETURN CSSMHRI HRS_DbQueryBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_HRS_INPUT_BIR *BIRToQuery,
    CSSM_GUID_PTR  Guid);

DESCRIPTION

If the BIR identified by the BIRToQuery parameter is in the open database identified by the DbHandle parameter, a pointer to its GUID is returned. Otherwise, CSSMERR_HRS_RECORD_NOT_FOUND is returned..

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbHandle (input)

The handle to the open database.

BIRToQuery (input)

The BIR to be queried in the open database (either the BIR, or its handle, or the key to it in another open database).

Guid (output)

The GUID that uniquely identifies the BIR in the database.

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


CSSMERR_HRS_RECORD_NOT_FOUND

See also the HRS Error Codes section HRS Error Codes.

Previous section.

NAME

CSSM_HRS_DbDeleteBIR, HRS_DbDeleteBIR

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_HRS_DbDeleteBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue);

SPI:
CSSM_RETURN CSSMHRI HRS_DbDeleteBIR
    (CSSM_HRS_HANDLE  ModuleHandle,
    CSSM_HRS_DB_HANDLE  DbHandle,
    const CSSM_GUID *KeyValue);

DESCRIPTION

The BIR identified by the KeyValue parameter in the open database identified by the DbHandle parameter is deleted from the database.

If there is a cursor set to the deleted BIR, then the cursor is moved to the next sequential BIR (or set to the start of the database if there are no more records).

PARAMETERS

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

ModuleHandle (input)

The handle of the attached HRS service provider.

DbHandle (input)

The handle to the open database.

KeyValue (input)

The GUID of the BIR to be deleted.

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


CSSMERR_HRS_RECORD_NOT_FOUND
CSSMERR_HRS_END_OF_DATABASE

See also the HRS Error Codes section HRS Error Codes.

Contents Next section Index