EngineAdapterSetHashAlgorithm function

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

Syntax


HRESULT WINAPI EngineAdapterSetHashAlgorithm(
  _Inout_  PWINBIO_PIPELINE Pipeline,
  _In_     SIZE_T AlgorithmBufferSize,
  _In_     PUCHAR AlgorithmBuffer
);

Parameters

Pipeline [in, out]

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

AlgorithmBufferSize [in]

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

AlgorithmBuffer [in]

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 codeDescription
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

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio_adapter.h (include Winbio_adapter.h)

See also

Plug-in Functions
EngineAdapterQueryHashAlgorithms

 

 

Community Additions

ADD
Show:
© 2015 Microsoft