функция обратного вызова PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN (winbio_adapter.h)

Статья
08/27/2023

Вызывается биометрической платформой Windows для получения массива идентификаторов объектов (OID), представляющих хэш-алгоритмы, поддерживаемые адаптером подсистемы.

Синтаксис

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

Параметры

[in, out] Pipeline

Указатель на структуру WINBIO_PIPELINE , связанную с биометрической единицей, выполняющей операцию.

[out] AlgorithmCount

Указатель на значение, которое получает количество строк OID алгоритма в буфере, заданном параметром AlgorithmBuffer .

[out] AlgorithmBufferSize

Указатель на значение, содержащее размер (в байтах) буфера, заданного параметром AlgorithmBuffer . Размер включает два значения NULL , которые завершают буфер.

[out] AlgorithmBuffer

Адрес переменной, получающей указатель на буфер, содержащий упакованные строки ANSI, заканчивающиеся null. Каждая строка представляет OID для хэш-алгоритма. Последняя строка в буфере должна быть завершена двумя последовательными значениями NULL .

Возвращаемое значение

Если функция выполняется успешно, она возвращает S_OK. Если функция завершается сбоем, она должна вернуть одно из следующих значений HRESULT , чтобы указать на ошибку.

Код возврата	Описание
E_POINTER	Обязательный параметр указателя имеет значение NULL.
E_NOTIMPL	Адаптер обработчика не поддерживает создание хэша шаблона.

В Windows Biometric Framework используется только хэш-алгоритм SHA1. Таким образом, этот OID должен быть включен в буфер. Другие строки OID являются необязательными и могут быть включены для будущих версий Windows. В Wincrypt.h, включенном в Windows SDK, символ для алгоритма SHA1 szOID_OIWSEC_sha1, а связанное строковое значение — "1.3.14.3.2.26". Это строковое значение должно находиться в буфере. Другие значения OID см. в статье Wincrypt.h.

В следующем примере показано, как создать буфер OID. Алгоритм SHA1 ("1.3.14.3.2.26") включается первым, хотя порядок включения не важен. Также включен другой алгоритм, szOID_OIWSEC_shaRSA со значением "1.3.14.3.2.15". Обратите внимание, что одно значение NULL определяет конец каждой строки OID, а дополнительное значение NULL после конца последней строки определяет конец буфера.

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

Если эта функция выполнена успешно, верните адрес начала этого буфера в аргументе AlgorithmBuffer . Буфер принадлежит адаптеру подсистемы. Поскольку Биометрическая платформа Windows считывает буфер, адрес должен оставаться действительным до тех пор, пока адаптер подсистемы подключен к биометрической единице.

Как правило, таблица строк OID компилируется в адаптер подсистемы в виде статического блока данных.

Примеры

В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	winbio_adapter.h (включая Winbio_adapter.h)

См. также раздел

EngineAdapterSetHashAlgorithm

Функции подключаемых модулей

Поделиться через