PIBIO_ENGINE_SET_HASH_ALGORITHM_FN callback function (winbio_adapter.h)

Article
10/13/2021

Called by the Windows Biometric Framework to select a hash algorithm for use in subsequent operations.

Syntax

PIBIO_ENGINE_SET_HASH_ALGORITHM_FN PibioEngineSetHashAlgorithmFn;

HRESULT PibioEngineSetHashAlgorithmFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      SIZE_T AlgorithmBufferSize,
  [in]      PUCHAR AlgorithmBuffer
)
{...}

Parameters

[in, out] Pipeline

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

[in] AlgorithmBufferSize

The size, in bytes, of the buffer specified by the AlgorithmBuffer parameter.

[in] AlgorithmBuffer

Pointer to a NULL-terminated ANSI string that contains the object identifier of the hash algorithm to select. Call the EngineAdapterQueryHashAlgorithms function to retrieve an array of the supported algorithm object identifiers (OIDs).

Return value

If the function succeeds, it returns S_OK. If the function fails, it must return one of the following HRESULT values to indicate the error.

Return code	Description
E_POINTER	A mandatory pointer parameter is NULL.
E_NOTIMPL	The engine adapter does not support template hashing.
E_INVALIDARG	The engine adapter does not support the hash algorithm specified by the AlgorithmBuffer parameter.

Remarks

The Windows Biometric Framework calls this function to configure a biometric unit every time the unit is added to a sensor pool.

Because a hash algorithm is selected on a per-pipeline basis, the engine adapter must store the selected algorithm in a private pipeline context.

The engine adapter must keep track of the most recent algorithm selected and use this algorithm when processing calls to the following functions:

The algorithm chosen by this function must remain selected until the next time EngineAdapterSetHashAlgorithm is called, or until the EngineAdapterDetach method is called. In particular, calls to the EngineAdapterClearContext function should not affect the selected algorithm.

Only the SHA1 hash algorithm is used by the Windows Biometric Framework. The OID string value for this algorithm is "1.3.14.3.2.26". For more information, see EngineAdapterQueryHashAlgorithms.

Examples

The following pseudocode shows one possible implementation of this function. The example does not compile. You must adapt it to suit your purpose.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterSetHashAlgorithm
//
// Purpose:
//      Selects a hash algorithm for use in subsequent operations.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation.   
//      AlgorithmBufferSize - Size, in bytes, of the buffer specified by the 
//                            AlgorithmBuffer parameter.
//      AlgorithmBuffer     - Pointer to a NULL-terminated ANSI string that 
//                            contains the object identifier of the hash algorithm
//                            to select.
//
static HRESULT
WINAPI
EngineAdapterSetHashAlgorithm(
    __inout PWINBIO_PIPELINE Pipeline,
    __in SIZE_T AlgorithmBufferSize,
    __in PUCHAR AlgorithmBuffer
    )
{
    ////////////////////////////////////////////////////////////////////////////
    // Return E_NOTIMPL here if your adapter does not support template hashing.
    ////////////////////////////////////////////////////////////////////////////

    HRESULT hr = S_OK;
    SIZE_T algorithmSize = (strlen(szOID_OIWSEC_sha1) + 1) * sizeof(CHAR);

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(AlgorithmBuffer))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Only the SHA1 hashing algorithm is supported.
    // Therefore, make certain that SHA1 is included in the algorithm
    // table.
    // The SHA1 object identifier, szOID_OIWSEC_sha1, is contained in the
    // Wincrypt.h header file.
    if (AlgorithmBufferSize != algorithmSize ||
        memcmp(AlgorithmBuffer, szOID_OIWSEC_sha1, algorithmSize) != 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Make any necessary changes to the adapter state to specify that
    // SHA1 hashing is enabled. If your adapter does not support template
    // hashing, return E_NOTIMPL.

cleanup:
    
    return hr;
}

Requirements

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