struktur BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO (bcrypt.h)

Artikel
08/22/2023

Struktur BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO digunakan dengan fungsi BCryptEncrypt dan BCryptDecrypt untuk berisi informasi tambahan yang terkait dengan mode sandi yang diautentikasi.

Sintaks

typedef struct _BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO {
  ULONG     cbSize;
  ULONG     dwInfoVersion;
  PUCHAR    pbNonce;
  ULONG     cbNonce;
  PUCHAR    pbAuthData;
  ULONG     cbAuthData;
  PUCHAR    pbTag;
  ULONG     cbTag;
  PUCHAR    pbMacContext;
  ULONG     cbMacContext;
  ULONG     cbAAD;
  ULONGLONG cbData;
  ULONG     dwFlags;
} BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO, *PBCRYPT_AUTHENTICATED_CIPHER_MODE_INFO;

Anggota

cbSize

Ukuran, dalam byte, dari struktur ini. Jangan atur bidang ini secara langsung. Gunakan makro BCRYPT_INIT_AUTH_MODE_INFO sebagai gantinya.

dwInfoVersion

Nomor versi struktur. Satu-satunya nilai yang didukung adalah BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO_VERSION. Jangan atur bidang ini secara langsung. Gunakan makro BCRYPT_INIT_AUTH_MODE_INFO sebagai gantinya.

pbNonce

Penunjuk ke buffer yang berisi nonce. Penyedia algoritma Microsoft untuk Standar Enkripsi Lanjutan (AES) memerlukan nonce untuk penghitung dengan mode penautan CBC-MAC (CCM) dan Galois/Counter Mode (GCM), dan akan mengembalikan kesalahan jika tidak ada. Jika nonce tidak digunakan, anggota ini harus diatur ke NULL.

cbNonce

Ukuran, dalam byte, dari buffer yang diacu oleh anggota pbNonce . Jika nonce tidak digunakan, anggota ini harus diatur ke nol.

pbAuthData

Penunjuk ke buffer yang berisi data yang diautentikasi. Ini adalah data yang akan disertakan dalam Kode Autentikasi Pesan (MAC) tetapi tidak dienkripsi. Jika tidak ada data terautentikasi, anggota ini harus diatur ke NULL.

cbAuthData

Ukuran, dalam byte, dari buffer yang diacu oleh anggota pbAuthData . Jika tidak ada data terautentikasi, anggota ini harus diatur ke nol.

pbTag

Penunjuk ke buffer.

Penggunaan anggota ini tergantung pada fungsi di mana struktur diteruskan.

Fungsi	Deskripsi
BCryptEncrypt	Buffer akan menerima tag autentikasi.
BCryptDecrypt	Buffer berisi tag autentikasi yang akan diperiksa.

Jika tidak ada tag, anggota ini harus diatur ke NULL.

cbTag

Ukuran, dalam byte, dari buffer pbTag . Buffer harus cukup lama untuk menyertakan seluruh tag autentikasi. Beberapa mode autentikasi, seperti CCM dan GCM, mendukung pemeriksaan terhadap tag dengan beberapa panjang. Untuk mendapatkan panjang tag autentikasi yang valid, gunakan BCryptGetProperty untuk mengkueri properti BCRYPT_AUTH_TAG_LENGTH . Jika tidak ada tag, anggota ini harus diatur ke nol.

pbMacContext

Pointer ke buffer yang menyimpan MAC yang dihitung sebagian antara panggilan ke BCryptEncrypt dan BCryptDecrypt saat menautkan enkripsi atau dekripsi.

Jika input ke enkripsi atau dekripsi tersebar di beberapa buffer, maka Anda harus menautkan panggilan ke fungsi BCryptEncrypt dan BCryptDecrypt . Penautan ditunjukkan dengan mengatur bendera BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG di anggota dwFlags .

Buffer ini harus disediakan oleh pemanggil dan harus setidaknya sebesar panjang maksimum tag autentikasi untuk cipher yang Anda gunakan. Untuk mendapatkan panjang tag autentikasi yang valid, gunakan BCryptGetProperty untuk mengkueri properti BCRYPT_AUTH_TAG_LENGTH .

Jika panggilan BCryptEncrypt dan BCryptDecrypt tidak dirangkai, anggota ini harus diatur ke NULL.

cbMacContext

Ukuran, dalam byte, dari buffer yang ditunjukkan oleh anggota pbMacContext . Jika panggilan BCryptEncrypt dan BCryptDecrypt tidak dirangkai, anggota ini harus diatur ke nol.

cbAAD

Panjangnya, dalam byte, dari data terautentikasi tambahan (AAD) yang akan digunakan oleh fungsi BCryptEncrypt dan BCryptDecrypt . Anggota ini hanya digunakan saat menautkan panggilan.

Anggota ini hanya digunakan ketika bendera BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG di anggota dwFlags ditetapkan.

Pada panggilan pertama ke BCryptEncrypt atau BCryptDecrypt , Anda harus mengatur bidang ini ke nol.

Catatan Selama urutan penautan, anggota ini dipertahankan secara internal dan tidak boleh diubah atau nilai MAC komputasi akan rusak.

cbData

Panjang, dalam byte, dari data payload yang dienkripsi atau didekripsi. Anggota ini hanya digunakan saat menautkan panggilan.

Anggota ini hanya digunakan ketika bendera BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG di anggota dwFlags ditetapkan.

Pada panggilan pertama ke BCryptEncrypt atau BCryptDecrypt, Anda harus mengatur bidang ini ke nol, , baik secara langsung atau dengan memanggil makro BCRYPT_INIT_AUTH_INFO

Catatan Selama urutan penautan, anggota ini dipertahankan secara internal dan tidak boleh diubah atau nilai MAC komputasi akan rusak.

dwFlags

Bendera ini digunakan saat menautkan panggilan fungsi BCryptEncrypt atau BCryptDecrypt . Jika panggilan tidak dirangkai, anggota ini harus diatur ke nol.

Nilai	Makna
0x00000000	Untuk BCryptEncrypt, hitung tag autentikasi dan letakkan di buffer yang diacu oleh anggota pbTag . Untuk BCryptDecrypt, hitung tag autentikasi dan bandingkan dengan tag yang diteruskan ke buffer yang diarahkan oleh anggota pbTag . Saat menautkan beberapa panggilan ke BCryptEncrypt atau BCryptDecrypt, nilai ini menandakan akhir rantai.
BCRYPT_AUTH_MODE_CHAIN_CALLS_FLAG 0x00000001	Menunjukkan bahwa panggilan fungsi BCryptEncrypt dan BCryptDecrypt sedang dirangkai dan bahwa nilai MAC tidak akan dihitung. Pada panggilan terakhir dalam rantai, hapus nilai ini untuk menghitung nilai MAC untuk seluruh rantai.
BCRYPT_AUTH_MODE_IN_PROGRESS_FLAG 0x00000002	Menunjukkan bahwa struktur BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO ini sedang digunakan dalam urutan panggilan fungsi BCryptEncrypt atau BCryptDecrypt berantai. Bendera ini diatur dan dipertahankan secara internal. Catatan Selama urutan penautan, nilai bendera ini dipertahankan secara internal dan tidak boleh diubah atau nilai MAC komputasi akan rusak.

Keterangan

Ukuran struktur ini berbeda antara sistem operasi 64-bit dan 32-bit. Pada sistem operasi 64-bit, ukurannya berbeda antara proses 64-bit dan 32-bit. Instans struktur ini tidak boleh dibagikan di seluruh utas atau diteruskan di antara proses.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista dengan SP1 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Header	bcrypt.h

Bagikan melalui