PIBIO_ENGINE_SET_HASH_ALGORITHM_FN Rückruffunktion (winbio_adapter.h)

Artikel
08/27/2023

Wird vom Windows Biometric Framework aufgerufen, um einen Hashalgorithmus für nachfolgende Vorgänge auszuwählen.

Syntax

PIBIO_ENGINE_SET_HASH_ALGORITHM_FN PibioEngineSetHashAlgorithmFn;

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

Parameter

[in, out] Pipeline

Zeiger auf eine WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.

[in] AlgorithmBufferSize

Die Größe des Puffers in Bytes, der durch den AlgorithmBuffer-Parameter angegeben wird.

[in] AlgorithmBuffer

Zeiger auf eine NULL-beendete ANSI-Zeichenfolge, die den Objektbezeichner des auszuwählenden Hashalgorithmus enthält. Rufen Sie die EngineAdapterQueryHashAlgorithms-Funktion auf, um ein Array der unterstützten Algorithmusobjektbezeichner (OIDs) abzurufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Rückgabecode	Beschreibung
E_POINTER	Ein obligatorischer Zeigerparameter ist NULL.
E_NOTIMPL	Der Moduladapter unterstützt kein Vorlagenhashing.
E_INVALIDARG	Der Engineadapter unterstützt den durch den AlgorithmBuffer-Parameter angegebenen Hashalgorithmus nicht.

Hinweise

Das Windows Biometric Framework ruft diese Funktion auf, um jedes Mal eine biometrische Einheit zu konfigurieren, wenn die Einheit einem Sensorpool hinzugefügt wird.

Da ein Hashalgorithmus auf Pipelinebasis ausgewählt wird, muss der Engineadapter den ausgewählten Algorithmus in einem privaten Pipelinekontext speichern.

Der Moduladapter muss den zuletzt ausgewählten Algorithmus nachverfolgen und diesen Algorithmus bei der Verarbeitung von Aufrufen der folgenden Funktionen verwenden:

Der von dieser Funktion ausgewählte Algorithmus muss bis zum nächsten Aufruf von EngineAdapterSetHashAlgorithm oder bis die EngineAdapterDetach-Methode aufgerufen wird, ausgewählt bleiben. Insbesondere sollten Aufrufe der EngineAdapterClearContext-Funktion keinen Einfluss auf den ausgewählten Algorithmus haben.

Nur der SHA1-Hashalgorithmus wird vom Windows Biometric Framework verwendet. Der OID-Zeichenfolgenwert für diesen Algorithmus ist "1.3.14.3.2.26". Weitere Informationen finden Sie unter EngineAdapterQueryHashAlgorithms.

Beispiele

Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.

//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio_adapter.h (einschließlich Winbio_adapter.h)

Weitere Informationen

EngineAdapterQueryHashAlgorithms

Plug-In-Funktionen