コールバック関数PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN (winbio_adapter.h)

[アーティクル]
03/09/2024

エンジンアダプターでサポートされているハッシュアルゴリズムを表すオブジェクト識別子 (OID) の配列を取得するために、Windows 生体認証フレームワークによって呼び出されます。

構文

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

AlgorithmBuffer パラメーターで指定されたバッファー内のアルゴリズム OID 文字列の数を受け取る値へのポインター。

[out] AlgorithmBufferSize

AlgorithmBuffer パラメーターで指定されたバッファーのサイズ (バイト単位) を含む値へのポインター。サイズには、バッファーを終了する 2 つの NULL 値が含まれます。

[out] AlgorithmBuffer

パックされた NULL で終わる ANSI 文字列を含むバッファーへのポインターを受け取る変数のアドレス。各文字列は、ハッシュアルゴリズムの OID を表します。バッファー内の最後の文字列は、2 つの連続する NULL 値で終了する必要があります。

戻り値

関数が成功した場合は、S_OK を返します。関数が失敗した場合は、エラーを示すために次のいずれかの HRESULT 値を返す必要があります。

リターンコード	説明
E_POINTER	必須ポインターパラメーターは NULL です。
E_NOTIMPL	エンジンアダプターでは、テンプレートハッシュの生成はサポートされていません。

注釈

WINDOWS 生体認証フレームワークでは、SHA1 ハッシュアルゴリズムのみが使用されます。したがって、この OID はバッファーに含まれている必要があります。その他の OID 文字列は省略可能であり、将来の Windows バージョンに含めることができます。 Windows SDKに含まれる Wincrypt.h では、SHA1 アルゴリズムのシンボルがszOID_OIWSEC_sha1され、関連付けられている文字列値は "1.3.14.3.2.26" です。この文字列値はバッファー内にある必要があります。その他の OID 値については、「Wincrypt.h」を参照してください。

次の例は、OID バッファーを作成する方法を示しています。 SHA1 アルゴリズム ("1.3.14.3.2.26") は最初に含まれますが、包含の順序は重要ではありません。値が "1.3.14.3.2.15" のszOID_OIWSEC_shaRSA別のアルゴリズムも含まれています。 1 つの 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 文字列のテーブルを静的データブロックとしてエンジンアダプターにコンパイルします。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

//////////////////////////////////////////////////////////////////////////////////////////
//
// 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
ヘッダー	winbio_adapter.h (Winbio_adapter.h を含む)

こちらもご覧ください

EngineAdapterSetHashAlgorithm

プラグイン関数

次の方法で共有

コールバック関数PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN (winbio_adapter.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース