POST
Fingerprint driver development in Windows(2)
Continue…
3. Biometric Unit
Biometric devices are manufactured in a wide variety of types and configurations. The Windows Biometric Framework (WBF) addresses this variety by providing an extensible architecture that enables third-party developers to create custom plug-in components. A primary component is a software object called a biometric unit. Biometric units expose the capabilities of a device to the framework through a standard interface that consists of sensor, engine, and storage adapters
A single physical sensor is associated with each biometric unit. The sensor captures biometric data and may also, depending on its hardware capabilities, perform other biometric operations such as template matching and storage. Sensors that do not support onboard matching or storage require additional software modules to perform these functions.
The above diagram shows how data flows through a biometric unit. Essentially, the data flow forms a type of pipeline. The initial input to the pipeline is a biometric sample captured by a physical sensor. The engine attempts to match the sample to templates that already exist in the template store or, if no match is found, builds a new template from repeated physical samples and saves the template in the store.
4. Biometric Unit Life Cycle
4.1 Creation
When the Windows Biometric Service starts or when it receives a hardware notification from the Plug and Play manager, it scans for any hardware that supports the well-known interface
GUID_DEVINTERFACE_BIOMETRIC_READER (E2B5183A-99EA-4cc3-AD6B-80CA8D715B80)For each biometric device discovered it then:
- Opens a handle to the device.
- Queries the device capabilities by using a Windows Biometric Driver control interface.
- Opens the device registry key and attempts to locate information about any associated adapter plug-ins.
- Opens the Windows Biometric Service registry key and searches for information about any global plug-ins that should override the device-specific values found in the preceding step.
- Builds a biometric unit to represent the device and passes the unit to a biometric service provider.
4.2 Configuration
After a biometric service provider (BSP) accepts a biometric unit, it configures the unit and assigns it to a sensor pool. The unit is configured by loading the appropriate adapters, connecting to a template store, and possibly changing the operating mode. A biometric unit can be configured to operate in one of two modes:
- In the basic mode, the unit acts as a simple capture device. It does not use onboard processing or storage but relies entirely on software adapters for additional support. It should be able to generate samples in a standard format. For example, fingerprint readers should generate samples that comply with
ANSI INCITS 381-2004. The purpose of the basic mode is to support interoperability among components from different vendors. - In the advanced mode, the biometric unit uses onboard processing and storage functions. It must expose the standard interfaces but can generate and process samples in any format desired.
4.3 Shut Down
When the Windows Biometric Service shuts down or when the Plug and Play manager notifies it that a unit has been removed, the service deletes all biometric units.
5. Adapters
Plug-in software components called adapters connect a biometric unit to its underlying hardware and supply any functionality that may be missing from the sensor hardware. There are three types of adapters that you can create:
- A sensor adapter wraps a biometric device and provides a standard interface for configuring the sensor, capturing samples, and controlling the flow of biometric data to the processing engine.
- An engine adapter generates biometric templates from captured samples, matches samples to existing templates, and indexes templates.
- A storage adapter manages template databases. Adapters can be loaded and unloaded at runtime. This enables the Windows Biometric Service to dynamically reconfigure a biometric unit by connecting it to a different set of adapters.
Finally, each of the sensor, engine and storage adapter interfaces expose two methods, ControlUnit and ControlUnitPrivileged, that enable client applications to access custom adapter capabilities defined by the vendor. This allows the vendor to define an almost unlimited set of control operations for a device. Further, by choosing which function to implement, a vendor can choose to make some control operations available to non-privileged users while restricting other operations to privileged users.
5.1 Sensor Adapter Function
A sensor adapter wraps a biometric device and provides a standard interface that enables the Windows Biometric service to configure the sensor, capture samples, and control the flow of biometric data to the processing engine. The following functions must be implemented by the developer of the adapter. They are called by the Windows Biometric service.
| Interface | Description |
|---|---|
| SensorAdapterAcceptCalibrationData | Passes calibration data from the engine adapter to the sensor adapter. |
| SensorAdapterActivate | Gives the Sensor Adapter the chance to perform any work needed to bring the sensor component out of an idle state. |
| SensorAdapterAttach | Adds a sensor adapter to the processing pipeline of the biometric unit. |
| SensorAdapterCancel | Cancels all pending sensor operations. |
| SensorAdapterClearContext | Prepares the processing pipeline of the biometric unit for a new operation. |
| SensorAdapterControlUnit | Performs a vendor-defined control operation that does not require elevated privilege. |
| SensorAdapterControlUnitPrivileged | Performs a vendor-defined control operation that requires elevated privilege. |
| SensorAdapterDeactivate | Gives the Sensor Adapter the chance to perform any work needed to put the sensor component into an idle state. |
| SensorAdapterDetach | Releases adapter specific resources attached to the pipeline. |
| SensorAdapterExportSensorData | Retrieves the most recently captured biometric sample formatted as a standard WINBIO_BIR structure. |
| SensorAdapterFinishCapture | Called by the Windows Biometric Framework to wait for the completion of a capture operation initiated by the SensorAdapterStartCapture function. |
| SensorAdapterGetIndicatorStatus |
Retrieves a value that indicates whether the sensor indicator is on or off. |
| SensorAdapterNotifyPowerChange |
Receives notification about a change in the computer power state and prepares the sensor adapter accordingly. |
| SensorAdapterPipelineCleanup |
Gives the Sensor Adapter the chance to perform any cleanup in that requires help from the Engine or Storage adapter components. |
| SensorAdapterPipelineInit |
Gives the Sensor Adapter the chance to perform any initialization that remains incomplete, and which requires help from the Engine or Storage adapter components. |
| SensorAdapterPushDataToEngine |
Makes the current contents of the sample buffer available to the engine adapter. |
| SensorAdapterQueryCalibrationFormats |
Determines the set of calibration formats supported by the Sensor Adapter. |
| SensorAdapterQueryExtendedInfo |
Determines the capabilities and limitations of the biometric sensor component. |
| SensorAdapterQueryStatus |
Retrieves information about the current status of the sensor device. |
| SensorAdapterReset |
Reinitializes the sensor. |
| SensorAdapterSetCalibrationFormat |
Notifies the sensor adapter that a particular calibration data format has been selected by the engine adapter. |
| SensorAdapterSetIndicatorStatus |
Toggles the sensor indicator on or off. |
| SensorAdapterSetMode |
Sets the sensor adapter mode. |
| SensorAdapterStartCapture |
Begins an asynchronous biometric capture. |
| WbioQuerySensorInterface |
Retrieves a pointer to the WINBIO_SENSOR_INTERFACE structure for the sensor adapter. |
5.2 Engine Adapter Function
An engine adapter generates biometric templates from captured samples, matches samples to existing templates, and indexes templates. The following functions must be implemented by the adapter developer. They are called by the Windows Biometric service.
| Interface | Description |
|---|---|
| EngineAdapterCreateKey |
Called by the Windows Biometric Framework to push an HMAC key to the sensor. The returned key identifier will be passed back to the biometric unit when the framework calls EngineAdapterIdentifyFeatureSetSecure. |
| EngineAdapterAcceptSampleData |
Accepts a raw biometric sample and extracts a feature set. |
| EngineAdapterActivate |
Gives the Engine Adapter the chance to perform any work needed to bring the sensor component out of an idle state. |
| EngineAdapterAttach |
Adds an engine adapter to the processing pipeline of the biometric unit. |
| EngineAdapterCheckForDuplicate |
Determines whether a new template in the pipeline duplicates any template already saved in the database regardless of the identity associated with the templates. |
| EngineAdapterClearContext |
Prepares the processing pipeline of the biometric unit for a new operation. |
| EngineAdapterCommitEnrollment |
Finalizes the enrollment object, converts it to a template, and saves the template in the database. |
| EngineAdapterControlUnit |
Performs a vendor-defined control operation that does not require elevated privilege. |
| EngineAdapterControlUnitPrivileged |
Performs a vendor-defined control operation that requires elevated privilege. |
| EngineAdapterCreateEnrollment |
Initializes the enrollment object in the biometric unit pipeline. |
| EngineAdapterDeactivate |
Gives the Engine Adapter the chance to perform any work needed to put the sensor component into an idle state. |
| EngineAdapterDetach |
Releases adapter-specific resources attached to the pipeline. |
| EngineAdapterDiscardEnrollment |
Deletes intermediate enrollment state information from the pipeline. |
| EngineAdapterExportEngineData |
Retrieves a copy of the most recently processed feature set or template from the engine in a standard biometric information record. |
| EngineAdapterGetEnrollmentHash |
Retrieves the hash of the completed enrollment template in the pipeline. |
| EngineAdapterGetEnrollmentStatus |
Determines whether the enrollment object is ready to be committed to the pipeline. |
| EngineAdapterIdentifyAll |
Determines the identities of any people who are currently in camera frame. |
| EngineAdapterIdentifyFeatureSet |
Builds a template from the current feature set and locates a matching template in the database. |
| EngineAdapterIdentifyFeatureSetSecure |
Called by the Windows Biometric Framework to build a template from the current feature set and locate a matching template in the database. If a match can be found, the engine adapter must fill the Identity, SubFactor, Authorization, and AuthorizationSize fields. |
| EngineAdapterNotifyPowerChange |
Receives notification about a change in the computer power state and prepares the engine adapter accordingly. |
| EngineAdapterPipelineCleanup |
Gives the Engine Adapter the chance to perform any cleanup that requires help from the Storage Adapter. |
| EngineAdapterPipelineInit |
Gives the Engine Adapter the chance to perform any initialization that remains incomplete. |
| EngineAdapterQueryCalibrationData |
Gets a set of post-capture calibration data from the engine adapter. |
| EngineAdapterQueryExtendedInfo |
Determines the capabilities and limitations of the biometric engine component. |
| EngineAdapterQueryHashAlgorithms |
Retrieves an array of object identifiers that represent the hash algorithms supported by the engine adapter. |
| EngineAdapterQueryIndexVectorSize |
Retrieves the size of the index vector used by the engine adapter. |
| EngineAdapterQueryPreferredFormat |
Determines the input data format preferred by the engine adapter. |
| EngineAdapterQuerySampleHint |
Retrieves the number of correct samples required by the engine adapter to construct an enrollment template. |
| EngineAdapterRefreshCache |
Notifies the Engine Adapter that it should discard any cached templates that it may be keeping in memory. |
| EngineAdapterSelectCalibrationFormat |
Called by the Windows Biometric Framework to determine which of the Sensor Adapter s calibration formats the Engine Adapter wants to use. |
| EngineAdapterSetAccountPolicy |
Sets the extended default and per-user antispoofing policies used by the engine adapter. |
| EngineAdapterSetEnrollmentParameters |
Gives the engine adapter additional information about an enrollment operation. |
| EngineAdapterSetEnrollmentSelector |
Tells the Engine Adapter which person to track for the current enrollment operation. |
| EngineAdapterSetHashAlgorithm |
Selects a hash algorithm for use in subsequent operations. |
| EngineAdapterUpdateEnrollment |
Adds the current feature set to the enrollment object. |
| EngineAdapterVerifyFeatureSet |
Compares the template in the current feature set with a specific template in the database. |
| WbioQueryEngineInterface |
Retrieves a pointer to the WINBIO_ENGINE_INTERFACE structure for the engine adapter. |
5.3 Storage Adapter Functions
A storage adapter manages template databases. The following functions must be implemented by the adapter developer. They are called by the Windows Biometric service.
| Interface | Description |
|---|---|
| StorageAdapterActivate |
Gives the Storage Adapter the chance to perform any work needed to bring the storage component out of an idle state. |
| StorageAdapterAddRecord |
Adds a template to the database. |
| StorageAdapterAttach |
Adds a storage adapter to the processing pipeline of the biometric unit. |
| StorageAdapterClearContext |
Prepares the processing pipeline of the biometric unit for a new operation. |
| StorageAdapterCloseDatabase |
Closes the database associated with the pipeline and frees all related resources. |
| StorageAdapterControlUnit |
Performs a vendor-defined control operation that does not require elevated privilege. |
| StorageAdapterControlUnitPrivileged |
Performs a vendor-defined control operation that requires elevated privilege. |
| StorageAdapterCreateDatabase |
Creates and configures a new database. |
| StorageAdapterDeactivate |
Gives the Storage Adapter the chance to perform any work needed to put the storage component into an idle state. |
| StorageAdapterDeleteRecord |
Deletes one or more templates from the database. |
| StorageAdapterDetach |
Releases adapter-specific resources attached to the pipeline. |
| StorageAdapterEraseDatabase |
Erases the database and marks it for deletion. |
| StorageAdapterFirstRecord |
Positions the result set cursor on the first record in the set. |
| StorageAdapterGetCurrentRecord |
Retrieves the contents of the current record in the pipeline result set. |
| StorageAdapterGetDatabaseSize |
Retrieves the database size and available space. |
| StorageAdapterGetDataFormat |
Retrieves format and version information used by the current database associated with the pipeline. |
| StorageAdapterGetRecordCount |
Retrieves the number of template records in the pipeline result set. |
| StorageAdapterNextRecord |
Advances the result set cursor by one record. |
| StorageAdapterNotifyPowerChange |
Receives notification about a change in the computer power state and prepares the storage adapter accordingly. |
| StorageAdapterOpenDatabase |
Opens a database for use by the storage adapter. |
| StorageAdapterPipelineCleanup |
Gives the Storage Adapter the chance to perform any cleanup in preparation for closing the template database. |
| StorageAdapterPipelineInit |
Gives the Storage Adapter the chance to perform any initialization that remains incomplete. |
| StorageAdapterQueryByContent |
Queries the database that is currently open for templates associated with a specified index vector. |
| StorageAdapterQueryBySubject |
Queries the database that is currently open for templates associated with a specified identity and sub-factor. |
| StorageAdapterQueryExtendedInfo |
Determines the capabilities and limitations of the biometric storage component. |
| WbioQueryStorageInterface |
Retrieves a pointer to the WINBIO_STORAGE_INTERFACE structure for the storage adapter. |
6. IOCTLs Interface of Biometric
WBDI is a Windows standard IOCTL-based interface. When you write a WBDI driver, you must support a set of mandatory IOCTLs. You may additionally choose to support optional IOCTLs.
- Biometric winbio_ioctl.h contains the following programming IOCTLs interfaces:
6.1 IOCTLs
| Interface | Description |
|---|---|
| IOCTL_BIOMETRIC_CALIBRATE |
The IOCTL_BIOMETRIC_CALIBRATE IOCTL directs the driver to perform any necessary steps to calibrate the device for use. |
| IOCTL_BIOMETRIC_CAPTURE_DATA |
The IOCTL_BIOMETRIC_CAPTURE_DATA IOCTL directs the driver to retrieve the next scan of biometric data. This call should put the device into capture mode.Vendor-supplied WBDI drivers must support IOCTL_BIOMETRIC_CAPTURE_DATA. |
| IOCTL_BIOMETRIC_GET_ATTRIBUTES |
The IOCTL_BIOMETRIC_GET_ATTRIBUTES IOCTL returns a structure that contains a set of attributes for the sensor. Vendor-supplied WBDI drivers must support this IOCTL. |
| IOCTL_BIOMETRIC_GET_INDICATOR |
The IOCTL_BIOMETRIC_GET_INDICATOR IOCTL directs the driver to retrieve the status of the indicator light. This IOCTL is optional. |
| IOCTL_BIOMETRIC_GET_SENSOR_STATUS |
The IOCTL_BIOMETRIC_GET_SENSOR_STATUS IOCTL tells the driver to perform any necessary steps to collect the current operating status of the device. Vendor-supplied WBDI drivers must support this IOCTL. |
| IOCTL_BIOMETRIC_RESET |
The IOCTL_BIOMETRIC_RESET IOCTL resets the device to a known or idle state, according to the current power state. Vendor-supplied WBDI drivers must support this IOCTL. |
| IOCTL_BIOMETRIC_SET_INDICATOR |
The IOCTL_BIOMETRIC_SET_INDICATOR IOCTL directs the driver to update the status of the indicator light. |
| IOCTL_BIOMETRIC_UPDATE_FIRMWARE |
The IOCTL_BIOMETRIC_UPDATE_FIRMWARE IOCTL tells the driver to update the firmware for the device with the given firmware image. This IOCTL is optional. |
6.2 Biometric IOCTLs Calling Sequence
A vendor-supplied WBDI driver should be prepared to receive IOCTL requests in the following order from the Windows Biometric Service (WBS). You can review examples of handlers for these IOCTLs in Device.cpp in WudfBioUsbSample.
-
The Windows Biometric Service or the sensor adapter initializes the biometric device and verifies that it is ready for use. The service or adapter sends an IOCTL_BIOMETRIC_GET_ATTRIBUTES request.
The driver receives a pointer to a WINBIO_SENSOR_ATTRIBUTES structure. In the handler for this IOCTL, the driver should fill in the relevant members of this structure and complete the request by calling IWDFIoRequest::Complete. -
Next, the driver receives IOCTL_BIOMETRIC_GET_SENSOR_STATUS. The driver should fill in the relevant members of the WINBIO_DIAGNOSTICS structure and complete the request.
-
If the driver indicates that calibration is necessary in the SensorStatus member of the WINBIO_DIAGNOSTICS structure that was returned from the IOCTL_BIOMETRIC_GET_SENSOR_STATUS request, the driver next receives an IOCTL_BIOMETRIC_CALIBRATE request. The driver must provide a handler for this IOCTL. After calibrating the device, the callback should return a WINBIO_CALIBRATION_INFO structure.
-
The driver can now expect to receive IOCTL_BIOMETRIC_CAPTURE_DATA requests. Because only one capture can be pending at any time, the handler for this request should first confirm that no request is pending. If a request is pending, complete the request with WINBIO_E_DATA_COLLECTION_IN_PROGRESS.
The WinBio service or an application can request cancellation of an outstanding capture request at any time by calling Win32 cancellation routines such as CancelIo, CancelIoEx, or CancelSynchronousIo. As such, WBDI drivers must also support cancellation.
The driver handles cancellation by calling IWDFIoRequest::MarkCancelable to register an IRequestCallbackCancel interface.
The handler then programs the device for capture mode and returns from the callback. The request should remain pending until canceled or the driver detects that the capture is complete. After this I/O request is completed, the device can return to an idle state. A client may make an initial call to IOCTL_BIOMETRIC_CAPTURE_DATA to determine the correct buffer size for an actual capture. -
The handler for IOCTL_BIOMETRIC_RESET should physically reset the device to a known or idle state. The handler for this request must also cancel any pending data collection I/O and fill out the WINBIO_BLANK_PAYLOAD structure. The handler then completes the request. Clients do not need to call reset between calls to IOCTL_BIOMETRIC_CAPTURE_DATA.