PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN fungsi panggilan balik (winbio_adapter.h)

Artikel
03/08/2023

Dipanggil oleh Windows Biometric Framework untuk mengambil array pengidentifikasi objek (OID) yang mewakili algoritma hash yang didukung oleh adaptor mesin.

Sintaks

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

Parameter

[in, out] Pipeline

Penunjuk ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.

[out] AlgorithmCount

Penunjuk ke nilai yang menerima jumlah string OID algoritma dalam buffer yang ditentukan oleh parameter AlgoritmaBuffer .

[out] AlgorithmBufferSize

Penunjuk ke nilai yang berisi ukuran, dalam byte, dari buffer yang ditentukan oleh parameter AlgorithmBuffer . Ukurannya mencakup dua nilai NULL yang mengakhiri buffer.

[out] AlgorithmBuffer

Alamat variabel yang menerima penunjuk ke buffer yang berisi string ANSI yang dikemas dan dihentikan NULL. Setiap string mewakili OID untuk algoritma hash. String akhir dalam buffer harus dihentikan oleh dua nilai NULL berturut-turut.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.

Menampilkan kode	Deskripsi
E_POINTER	Parameter pointer wajib adalah NULL.
E_NOTIMPL	Adaptor mesin tidak mendukung pembuatan hash templat.

Keterangan

Hanya algoritma hash SHA1 yang digunakan oleh Windows Biometric Framework. Oleh karena itu, OID ini harus disertakan dalam buffer. String OID lainnya bersifat opsional dan dapat disertakan untuk versi Windows mendatang. Dalam Wincrypt.h, disertakan dengan Windows SDK, simbol untuk algoritma SHA1 szOID_OIWSEC_sha1 dan nilai string terkait adalah "1.3.14.3.2.26". Nilai string ini harus berada di buffer. Lihat Wincrypt.h untuk nilai OID lainnya.

Contoh berikut menunjukkan cara membuat buffer OID. Algoritma SHA1 ("1.3.14.3.2.26") disertakan terlebih dahulu meskipun urutan penyertaan tidak penting. Algoritma lain, szOID_OIWSEC_shaRSA dengan nilai "1.3.14.3.2.15" juga disertakan. Perhatikan bahwa satu nilai NULL mengidentifikasi akhir setiap string OID dan bahwa nilai NULL tambahan setelah akhir string terakhir mengidentifikasi akhir buffer.

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

Jika fungsi ini berhasil, kembalikan alamat awal buffer ini dalam argumen AlgorithmBuffer . Adaptor mesin memiliki buffer. Karena Windows Biometric Framework membaca buffer, alamat harus tetap valid selama adaptor mesin dilampirkan ke unit biometrik.

Biasanya, Anda mengkompilasi tabel string OID ke dalam adaptor mesin sebagai blok data statis.

Contoh

Pseudocode berikut menunjukkan salah satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Kau harus menyesuaikannya sesuai dengan tujuanmu.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbio_adapter.h (termasuk Winbio_adapter.h)

Lihat juga

EngineAdapterSetHashAlgorithm

Fungsi Plug-in

Bagikan melalui