PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN Rückruffunktion (winbio_adapter.h)

  • Artikel

Wird vom Windows Biometric Framework aufgerufen, um ein Array von Objektbezeichnern (OIDs) abzurufen, die die vom Moduladapter unterstützten Hashalgorithmen darstellen.

Syntax

PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN PibioEngineQueryHashAlgorithmsFn;

HRESULT PibioEngineQueryHashAlgorithmsFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PSIZE_T AlgorithmCount,
  [out]     PSIZE_T AlgorithmBufferSize,
  [out]     PUCHAR *AlgorithmBuffer
)
{...}

Parameter

[in, out] Pipeline

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

[out] AlgorithmCount

Zeiger auf einen Wert, der die Anzahl der Algorithmus-OID-Zeichenfolgen in dem puffer empfängt, der durch den AlgorithmBuffer-Parameter angegeben wird.

[out] AlgorithmBufferSize

Zeiger auf einen Wert, der die Größe des puffers in Bytes enthält, der durch den AlgorithmBuffer-Parameter angegeben wird. Die Größe enthält die zwei NULL-Werte , die den Puffer beenden.

[out] AlgorithmBuffer

Adresse einer Variablen, die einen Zeiger auf einen Puffer empfängt, der gepackte, NULL-beendete ANSI-Zeichenfolgen enthält. Jede Zeichenfolge stellt eine OID für einen Hashalgorithmus dar. Die letzte Zeichenfolge im Puffer muss durch zwei aufeinanderfolgende NULL-Werte beendet werden.

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 keine Vorlagenhashgenerierung.

Hinweise

Nur der SHA1-Hashalgorithmus wird vom Windows Biometric Framework verwendet. Daher muss diese OID im Puffer enthalten sein. Andere OID-Zeichenfolgen sind optional und können für zukünftige Windows-Versionen eingeschlossen werden. In Wincrypt.h, die im Windows SDK enthalten ist, ist das Symbol für den SHA1-Algorithmus szOID_OIWSEC_sha1 und der zugeordnete Zeichenfolgenwert ist "1.3.14.3.2.26". Dieser Zeichenfolgenwert muss sich im Puffer befinden. Weitere OID-Werte finden Sie unter Wincrypt.h.

Das folgende Beispiel zeigt, wie Sie einen OID-Puffer erstellen. Der SHA1-Algorithmus ("1.3.14.3.2.26") ist zuerst enthalten, obwohl die Reihenfolge der Aufnahme nicht wichtig ist. Ein anderer Algorithmus, szOID_OIWSEC_shaRSA mit dem Wert "1.3.14.3.2.15" ist ebenfalls enthalten. Beachten Sie, dass ein einzelner NULL-Wert das Ende jeder OID-Zeichenfolge identifiziert und dass ein zusätzlicher NULL-Wert nach dem Ende der letzten Zeichenfolge das Ende des Puffers identifiziert.

char OidBuffer[] = 
{
    '1','.','3','.','1','4','.','3','.','2','.','2','6','\0',
    '1','.','3','.','1','4','.','3','.','2','.','1','5','\0','\0'
};

Wenn diese Funktion erfolgreich ist, geben Sie die Adresse des Anfangs dieses Puffers im AlgorithmBuffer-Argument zurück. Der Moduladapter besitzt den Puffer. Da das biometrische Windows-Framework den Puffer liest, muss die Adresse gültig bleiben, solange der Moduladapter an die biometrische Einheit angefügt ist.

In der Regel kompilieren Sie die Tabelle der OID-Zeichenfolgen als statischen Datenblock in den Moduladapter.

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterQueryHashAlgorithms
// 
//      Retrieves an array of object identifiers (OIDs) that represent the 
//      hash algorithms supported by the engine adapter.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation.
//      AlgorithmCount      - Pointer to a value that receives the number of 
//                            algorithm OID strings specified by the 
//                            AlgorithmBuffer parameter.
//      AlgorithmBufferSize - Pointer to a value that contains the size, 
//                            in bytes, of the buffer specified by the 
//                            AlgorithmBuffer parameter.
//      AlgorithmBuffer     - Address of a variable that receives a pointer to 
//                            a buffer that contains packed, NULL-terminated ANSI 
//                            strings. Each string represents an OID for a hash 
//                            algorithm. The final string in the buffer must be 
//                            terminated by two successive NULL values.
//
// Note:
//      The following algorithm table contains the SHA1 OID. Only 
//      the SHA1 hash algorithm is supported by the Windows Biometric Framework.
//      The algorithm table must be defined in global scope for the engine adapter.
//

static char g_HashAlgorithmOidTable[] = 
{
    '1','.','3','.','1','4','.','3','.','2','.','2','6','\0','\0'
};

static HRESULT
WINAPI
EngineAdapterQueryHashAlgorithms(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PSIZE_T AlgorithmCount,
    __out PSIZE_T AlgorithmBufferSize,
    __out PUCHAR *AlgorithmBuffer
    )
{
    ////////////////////////////////////////////////////////////////////////////
    // Return E_NOTIMPL here if your adapter does not support template hashing.
    ////////////////////////////////////////////////////////////////////////////

    HRESULT hr = S_OK;

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

    // Pass the address and size of the static algorithm table and the number
    // of algorithms to the caller. If your adapter does not support template
    // hashing, return E_NOTIMPL.
    *AlgorithmCount = 1;
    *AlgorithmBufferSize = sizeof(g_HashAlgorithmOidTable);
    *AlgorithmBuffer = g_HashAlgorithmOidTable;

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

EngineAdapterSetHashAlgorithm

Plug-In-Funktionen