PIBIO_ENGINE_SET_HASH_ALGORITHM_FN função de retorno de chamada (winbio_adapter.h)

  • Artigo

Chamado pela Estrutura Biométrica do Windows para selecionar um algoritmo de hash para uso em operações subsequentes.

Sintaxe

PIBIO_ENGINE_SET_HASH_ALGORITHM_FN PibioEngineSetHashAlgorithmFn;

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

Parâmetros

[in, out] Pipeline

Ponteiro para uma estrutura WINBIO_PIPELINE associada à unidade biométrica que executa a operação.

[in] AlgorithmBufferSize

O tamanho, em bytes, do buffer especificado pelo parâmetro AlgorithmBuffer .

[in] AlgorithmBuffer

Ponteiro para uma cadeia de caracteres ANSI terminada em NULL que contém o identificador de objeto do algoritmo de hash a ser selecionado. Chame a função EngineAdapterQueryHashAlgorithms para recuperar uma matriz dos OIDs (identificadores de objeto de algoritmo) com suporte.

Retornar valor

Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela deverá retornar um dos seguintes valores HRESULT para indicar o erro.

Código de retorno Descrição
E_POINTER
 Um parâmetro de ponteiro obrigatório é NULL.
E_NOTIMPL
 O adaptador de mecanismo não dá suporte ao hash de modelo.
E_INVALIDARG
 O adaptador do mecanismo não dá suporte ao algoritmo de hash especificado pelo parâmetro AlgorithmBuffer .

Comentários

A Estrutura Biométrica do Windows chama essa função para configurar uma unidade biométrica sempre que a unidade é adicionada a um pool de sensores.

Como um algoritmo de hash é selecionado por pipeline, o adaptador do mecanismo deve armazenar o algoritmo selecionado em um contexto de pipeline privado.

O adaptador de mecanismo deve acompanhar o algoritmo mais recente selecionado e usar esse algoritmo ao processar chamadas para as seguintes funções:

O algoritmo escolhido por essa função deve permanecer selecionado até a próxima vez que EngineAdapterSetHashAlgorithm for chamado ou até que o método EngineAdapterDetach seja chamado. Em particular, as chamadas para a função EngineAdapterClearContext não devem afetar o algoritmo selecionado.

Somente o algoritmo de hash SHA1 é usado pela Estrutura Biométrica do Windows. O valor da cadeia de caracteres OID para esse algoritmo é "1.3.14.3.2.26". Para obter mais informações, consulte EngineAdapterQueryHashAlgorithms.

Exemplos

O pseudocódigo a seguir mostra uma implementação possível dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar ao seu propósito.

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

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winbio_adapter.h (inclua Winbio_adapter.h)

Confira também

EngineAdapterQueryHashAlgorithms

Funções de plug-in