PIBIO_ENGINE_SET_HASH_ALGORITHM_FN fonction de rappel (winbio_adapter.h)

Article
03/03/2024

Appelé par l’infrastructure biométrique Windows pour sélectionner un algorithme de hachage à utiliser dans les opérations suivantes.

Syntaxe

PIBIO_ENGINE_SET_HASH_ALGORITHM_FN PibioEngineSetHashAlgorithmFn;

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

Paramètres

[in, out] Pipeline

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

[in] AlgorithmBufferSize

Taille, en octets, de la mémoire tampon spécifiée par le paramètre AlgorithmBuffer .

[in] AlgorithmBuffer

Pointeur vers une chaîne ANSI terminée par NULL qui contient l’identificateur d’objet de l’algorithme de hachage à sélectionner. Appelez la fonction EngineAdapterQueryHashAlgorithms pour récupérer un tableau des identificateurs d’objets d’algorithme (OID) pris en charge.

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 le hachage de modèle.
E_INVALIDARG	L’adaptateur moteur ne prend pas en charge l’algorithme de hachage spécifié par le paramètre AlgorithmBuffer .

Remarques

Windows Biometric Framework appelle cette fonction pour configurer une unité biométrique chaque fois que l’unité est ajoutée à un pool de capteurs.

Étant donné qu’un algorithme de hachage est sélectionné par pipeline, l’adaptateur moteur doit stocker l’algorithme sélectionné dans un contexte de pipeline privé.

L’adaptateur moteur doit effectuer le suivi de l’algorithme le plus récent sélectionné et utiliser cet algorithme lors du traitement des appels aux fonctions suivantes :

L’algorithme choisi par cette fonction doit rester sélectionné jusqu’à l’appel suivant de EngineAdapterSetHashAlgorithm , ou jusqu’à ce que la méthode EngineAdapterDetach soit appelée. En particulier, les appels à la fonction EngineAdapterClearContext ne doivent pas affecter l’algorithme sélectionné.

Seul l’algorithme de hachage SHA1 est utilisé par l’infrastructure biométrique Windows. La valeur de chaîne OID de cet algorithme est « 1.3.14.3.2.26 ». Pour plus d’informations, consultez EngineAdapterQueryHashAlgorithms.

Exemples

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

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

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

EngineAdapterQueryHashAlgorithms

Fonctions de plug-in

Partager via