PIBIO_ENGINE_IDENTIFY_FEATURE_SET_SECURE_FN callback function (winbio_adapter.h)

Article
10/05/2021

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.

Syntax

PIBIO_ENGINE_IDENTIFY_FEATURE_SET_SECURE_FN PibioEngineIdentifyFeatureSetSecureFn;

HRESULT PibioEngineIdentifyFeatureSetSecureFn(
  PWINBIO_PIPELINE Pipeline,
  const UCHAR *Nonce,
  SIZE_T NonceSize,
  const UCHAR *KeyIdentifier,
  SIZE_T KeyIdentifierSize,
  PWINBIO_IDENTITY Identity,
  PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
  PWINBIO_REJECT_DETAIL RejectDetail,
  PUCHAR *Authorization,
  PSIZE_T AuthorizationSize
)
{...}

Parameters

Pipeline

Pointer to a WINBIO_PIPELINE structure associated with the biometric unit performing the operation.

Nonce

Pointer to a buffer that contains a nonce.

NonceSize

Size, in bytes, of the buffer specified by the Nonce parameter.

KeyIdentifier

Pointer to a buffer that contains an identifier for the key from a previous call to EngineAdapterCreateKey

KeyIdentifierSize

Size, in bytes, of the buffer specified by the KeyIdentifier parameter.

Identity

Pointer to a WINBIO_IDENTITY structure that contains the SID of the template recovered from the database. This value is returned only if a match is found.

SubFactor

RejectDetail

Pointer to a variable that receives additional information if a capture failure prevents the engine from performing a matching operation. If the most recent capture succeeded, set this parameter to zero.

Authorization

An HMAC. See remarks section.

AuthorizationSize

Size, in bytes, of the buffer specified by the Authorization parameter.

Return value

WINBIO_E_INVALID_KEY_IDENTIFIER must be returned in the case where the key cannot be used for whatever reason. When WINBIO_E_INVALID_KEY_IDENTIFIER is returned, the sensor and TPM will be re-provisioned.

Remarks

The Authorization buffer contains the following SHA256_HMAC:

SHA256_HMAC(Key, SHA256(Nonce || 0xffffffe2 || SHA256(AccountSid)))

Key
Key is the HMAC key passed in by EngineAdapterCreateKey, and identified by the KeyIdentifier parameter.
Nonce
Nonce is the Nonce parameter.
0xffffffe2
A 32-bit unsigned integer in big-endian format.
AccountSid
The account SID of the user referenced by the Identity parameter. The SID bytes can be obtained from the WINBIO_IDENTITY structure.

Examples

Here is a pseudocode implementation of the SHA256 HMAC calculation:

// Hash the AccountSid.
    assert(Identity->Type == WINBIO_ID_TYPE_SID);
    hashHandle = CreateHash(SHA256_ALGORITHM);
    HashData(
        hashHandle, 
        Identity->Value.AccountSid.Data, 
        Identity->Value.AccountSid.Size);
    identityHash = FinishHash(hashHandle);

    // Hash the parameters.
    BYTE bytes[] = {0xff, 0xff, 0xff, 0xe2};
    hashHandle = CreateHash(SHA256_ALGORITHM);
    HashData(hashHandle, Nonce, NonceSize);
    HashData(hashHandle, bytes, sizeof(bytes));
    HashData(hashHandle, identityHash, SHA256_DIGEST_LENGTH);
    parameterHash = FinishHash(hashHandle);

    // Calculate the authorization HMAC
    key, keySize = GetKeyFromIdentifier(KeyIdentifier, KeyIdentifierSize);
    hashHandle = CreateHash(HMAC_SHA256_ALGORITHM, key, keySize);
    HashData(hashHandle, parameterHash, SHA256_DIGEST_LENGTH);
    authorization = FinishHash(hashHandle);

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Target Platform	Windows
Header	winbio_adapter.h (include Winbio_adapter.h)

Share via