PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN fonction de rappel (winbio_adapter.h)

Article
03/03/2024

Appelé par l’infrastructure biométrique Windows pour récupérer un tableau d’identificateurs d’objets (OID) qui représentent les algorithmes de hachage pris en charge par l’adaptateur du moteur.

Syntaxe

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
)
{...}

Paramètres

[in, out] Pipeline

Pointeur vers une structure WINBIO_PIPELINE associée à l’unité biométrique qui effectue l’opération.

[out] AlgorithmCount

Pointeur vers une valeur qui reçoit le nombre de chaînes OID d’algorithme dans la mémoire tampon spécifiée par le paramètre AlgorithmBuffer .

[out] AlgorithmBufferSize

Pointeur vers une valeur qui contient la taille, en octets, de la mémoire tampon spécifiée par le paramètre AlgorithmBuffer . La taille inclut les deux valeurs NULL qui mettent fin à la mémoire tampon.

[out] AlgorithmBuffer

Adresse d’une variable qui reçoit un pointeur vers une mémoire tampon qui contient des chaînes ANSI remplies et terminées par NULL. Chaque chaîne représente un OID pour un algorithme de hachage. La chaîne finale de la mémoire tampon doit être terminée par deux valeurs NULL successives.

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle doit retourner l’une des valeurs HRESULT suivantes pour indiquer l’erreur.

Code de retour	Description
E_POINTER	Un paramètre de pointeur obligatoire est NULL.
E_NOTIMPL	L’adaptateur moteur ne prend pas en charge la génération de hachage de modèle.

Remarques

Seul l’algorithme de hachage SHA1 est utilisé par l’infrastructure biométrique Windows. Par conséquent, cet OID doit être inclus dans la mémoire tampon. D’autres chaînes OID sont facultatives et peuvent être incluses pour les futures versions de Windows. Dans Wincrypt.h, inclus avec le SDK Windows, le symbole de l’algorithme SHA1 est szOID_OIWSEC_sha1 et la valeur de chaîne associée est « 1.3.14.3.2.26 ». Cette valeur de chaîne doit se trouver dans la mémoire tampon. Pour d’autres valeurs OID, consultez Wincrypt.h.

L’exemple suivant montre comment créer une mémoire tampon OID. L’algorithme SHA1 (« 1.3.14.3.2.26 ») est inclus en premier, bien que l’ordre d’inclusion ne soit pas important. Un autre algorithme, szOID_OIWSEC_shaRSA avec la valeur « 1.3.14.3.2.15 » est également inclus. Notez qu’une seule valeur NULL identifie la fin de chaque chaîne OID et qu’une valeur NULL supplémentaire après la fin de la dernière chaîne identifie la fin de la mémoire tampon.

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

Si cette fonction réussit, retournez l’adresse du début de cette mémoire tampon dans l’argument AlgorithmBuffer . L’adaptateur moteur est propriétaire de la mémoire tampon. Étant donné que l’infrastructure biométrique Windows lit la mémoire tampon, l’adresse doit rester valide tant que l’adaptateur moteur est attaché à l’unité biométrique.

En règle générale, vous compilez la table des chaînes OID dans l’adaptateur du moteur en tant que bloc de données statique.

Exemples

Le pseudocode suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbio_adapter.h (include Winbio_adapter.h)

Voir aussi

EngineAdapterSetHashAlgorithm

Fonctions de plug-in

Partager via