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

  • Artigo

Chamado pela Estrutura Biométrica do Windows para recuperar uma matriz de identificadores de objeto (OIDs) que representam os algoritmos de hash compatíveis com o adaptador do mecanismo.

Sintaxe

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

Parâmetros

[in, out] Pipeline

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

[out] AlgorithmCount

Ponteiro para um valor que recebe o número de cadeias de caracteres OID do algoritmo no buffer especificado pelo parâmetro AlgorithmBuffer .

[out] AlgorithmBufferSize

Ponteiro para um valor que contém o tamanho, em bytes, do buffer especificado pelo parâmetro AlgorithmBuffer . O tamanho inclui os dois valores NULL que encerram o buffer.

[out] AlgorithmBuffer

Endereço de uma variável que recebe um ponteiro para um buffer que contém cadeias de caracteres ANSI empacotadas e terminadas em NULL. Cada cadeia de caracteres representa um OID para um algoritmo de hash. A cadeia de caracteres final no buffer deve ser encerrada por dois valores NULL sucessivos.

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 à geração de hash de modelo.

Comentários

Somente o algoritmo de hash SHA1 é usado pela Estrutura Biométrica do Windows. Portanto, esse OID deve ser incluído no buffer. Outras cadeias de caracteres OID são opcionais e podem ser incluídas para versões futuras do Windows. No Wincrypt.h, incluído no SDK do Windows, o símbolo do algoritmo SHA1 é szOID_OIWSEC_sha1 e o valor da cadeia de caracteres associada é "1.3.14.3.2.26". Esse valor de cadeia de caracteres deve estar no buffer. Consulte Wincrypt.h para obter outros valores de OID.

O exemplo a seguir mostra como criar um buffer OID. O algoritmo SHA1 ("1.3.14.3.2.26") é incluído primeiro, embora a ordem de inclusão não seja importante. Outro algoritmo, szOID_OIWSEC_shaRSA com um valor de "1.3.14.3.2.15" também está incluído. Observe que um único valor NULL identifica o final de cada cadeia de caracteres OID e que um valor NULL adicional após o final da última cadeia de caracteres identifica o final do buffer.

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

Se essa função for bem-sucedida, retorne o endereço do início desse buffer no argumento AlgorithmBuffer . O adaptador do mecanismo é o proprietário do buffer. Como a Estrutura Biométrica do Windows lê o buffer, o endereço deve permanecer válido enquanto o adaptador do mecanismo estiver anexado à unidade biométrica.

Normalmente, você compila a tabela de cadeias de caracteres OID no adaptador do mecanismo como um bloco de dados estático.

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.

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

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

EngineAdapterSetHashAlgorithm

Funções de plug-in