Fungsi BCryptDeriveKey (bcrypt.h)
Fungsi BCryptDeriveKey
Untuk derivasi kunci dari rahasia tertentu, lihat BCryptKeyDerivation.
Sintaksis
NTSTATUS BCryptDeriveKey(
[in] BCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] BCryptBufferDesc *pParameterList,
[out, optional] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);
Parameter
[in] hSharedSecret
Perjanjian rahasia menangani untuk membuat kunci dari. Handel ini diperoleh dari fungsi BCryptSecretAgreement
[in] pwszKDF
Penunjuk ke string Unicode yang dihentikan null yang mengidentifikasi fungsi derivasi kunci (KDF) untuk digunakan untuk memperoleh kunci. Ini bisa menjadi salah satu string berikut.
BCRYPT_KDF_HASH (L"HASH")
Gunakan fungsi derivasi kunci hash.
Jika parameter cbDerivedKey
Parameter yang diidentifikasi oleh parameter pParameterList
Parameter | Deskripsi | Diperlukan atau opsional |
---|---|---|
KDF_HASH_ALGORITHM |
String Unicode null-terminated yang mengidentifikasi algoritma hash yang akan digunakan. Ini bisa menjadi salah satu pengidentifikasi algoritma hash standar dari Pengidentifikasi Algoritma CNG atau pengidentifikasi untuk algoritma hash terdaftar lainnya.
Jika parameter ini tidak ditentukan, algoritma hash SHA1 digunakan. |
Fakultatif |
KDF_SECRET_PREPEND | Nilai yang akan ditambahkan ke awal input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan. | Fakultatif |
KDF_SECRET_APPEND | Nilai yang akan ditambahkan ke akhir input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan. | Fakultatif |
Panggilan ke KDF dibuat seperti yang ditunjukkan dalam pseudocode berikut.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
KDF-Output = Hash(
KDF-Prepend +
hSharedSecret +
KDF-Append)
BCRYPT_KDF_HMAC (L"HMAC")
Gunakan fungsi derivasi kunci Kode Autentikasi Pesan
Jika parameter cbDerivedKey
Parameter yang diidentifikasi oleh parameter pParameterList
Parameter | Deskripsi | Diperlukan atau opsional |
---|---|---|
KDF_HASH_ALGORITHM |
String Unicode null-terminated yang mengidentifikasi algoritma hash yang akan digunakan. Ini bisa menjadi salah satu pengidentifikasi algoritma hash standar dari Pengidentifikasi Algoritma CNG atau pengidentifikasi untuk algoritma hash terdaftar lainnya.
Jika parameter ini tidak ditentukan, algoritma hash SHA1 digunakan. |
Fakultatif |
KDF_HMAC_KEY |
Kunci yang digunakan untuk fungsi pseudo-random (PRF) |
Fakultatif |
KDF_SECRET_PREPEND | Nilai yang akan ditambahkan ke awal input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan. | Fakultatif |
KDF_SECRET_APPEND | Nilai yang akan ditambahkan ke akhir input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan. | Fakultatif |
Panggilan ke KDF dibuat seperti yang ditunjukkan dalam pseudocode berikut.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
KDF-Output = HMAC-Hash(
KDF_HMAC_KEY,
KDF-Prepend +
hSharedSecret +
KDF-Append)
BCRYPT_KDF_TLS_PRF (L"TLS_PRF")
Gunakan fungsi derivasi kunci keamanan lapisan transportasi (TLS) fungsi pseudo-random (PRF). Ukuran kunci turunan selalu 48 byte, sehingga parameter
Parameter yang diidentifikasi oleh parameter pParameterList
Parameter | Deskripsi | Diperlukan atau opsional |
---|---|---|
KDF_TLS_PRF_LABEL | String ANSI yang berisi label PRF. | Diperlukan |
KDF_TLS_PRF_SEED | Benih PRF. Benih harus panjangnya 64 byte. | Diperlukan |
KDF_TLS_PRF_PROTOCOL |
Nilai DWORD Nilai yang valid adalah:
Windows Server 2008 dan Windows Vista: TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION, dan DTLS1_0_PROTOCOL_VERSION tidak didukung. Windows Server 2008 R2, Windows 7, Windows Server 2008 dan Windows Vista: DTLS1_0_PROTOCOL_VERSION tidak didukung. |
Fakultatif |
KDF_HASH_ALGORITHM | ID algoritma CNG dari hash yang akan digunakan dengan HMAC di PRF, untuk versi protokol TLS 1.2. Pilihan yang valid adalah SHA-256 dan SHA-384. Jika tidak ditentukan, SHA-256 digunakan. | Fakultatif |
Panggilan ke KDF dibuat seperti yang ditunjukkan dalam pseudocode berikut.
KDF-Output = PRF(
hSharedSecret,
KDF_TLS_PRF_LABEL,
KDF_TLS_PRF_SEED)
BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")
Gunakan fungsi derivasi kunci SP800-56A.
Parameter yang diidentifikasi oleh parameter pParameterList
Parameter | Deskripsi | Diperlukan atau opsional |
---|---|---|
KDF_ALGORITHMID |
Menentukan subbidang |
Diperlukan |
KDF_PARTYUINFO |
Menentukan subbidang |
Diperlukan |
KDF_PARTYVINFO |
Menentukan subbidang |
Diperlukan |
KDF_SUPPPUBINFO |
Menentukan subbidang |
Fakultatif |
KDF_SUPPPRIVINFO | Menentukan subbidang SuppPrivInfo bidang OtherInfo dalam fungsi derivasi kunci SP800-56A. Ini berisi informasi privat yang diketahui oleh inisiator dan responden, seperti rahasia bersama. | Fakultatif |
Panggilan ke KDF dibuat seperti yang ditunjukkan dalam pseudocode berikut.
KDF-Output = SP_800-56A_KDF(
hSharedSecret,
KDF_ALGORITHMID,
KDF_PARTYUINFO,
KDF_PARTYVINFO,
KDF_SUPPPUBINFO,
KDF_SUPPPRIVINFO)
Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")
Mengembalikan representasi little-endian dari rahasia mentah tanpa modifikasi apa pun.
Jika parameter cbDerivedKey
Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
[in, optional] pParameterList
Alamat struktur BCryptBufferDesc
[out, optional] pbDerivedKey
Alamat buffer yang menerima kunci. Parameter cbDerivedKey berisi ukuran buffer ini. Jika parameter ini
[in] cbDerivedKey
Ukurannya, dalam byte, dari pbDerivedKey buffer.
[out] pcbResult
Pointer ke ULONG
[in] dwFlags
Sekumpulan bendera yang mengubah perilaku fungsi ini. Ini bisa nol atau nilai berikut.
Mengembalikan nilai
Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.
Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini.
Mengembalikan kode | Deskripsi |
---|---|
|
Fungsi berhasil. |
|
Terjadi kesalahan internal. |
|
Handel dalam parameter |
|
Satu atau beberapa parameter tidak valid. |
Komentar
Struktur
BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};
Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);
Jika nilai parameter di atas ditentukan, nilai yang digabungkan ke KDF aktual adalah sebagai berikut.
Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6
Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4
Jika parameter pwszKDF
Bergantung pada mode prosesor apa yang didukung penyedia, BCryptDeriveKey dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel dapat menjalankan baik di PASSIVE_LEVELIRQL atau IRQL DISPATCH_LEVEL. Jika tingkat IRQL saat ini
Untuk memanggil fungsi ini dalam mode kernel, gunakan Cng.lib, yang merupakan bagian dari Driver Development Kit (DDK). Windows Server 2008 dan Windows Vista: Untuk memanggil fungsi ini dalam mode kernel, gunakan Ksecdd.lib.
Persyaratan
Syarat | Nilai |
---|---|
klien minimum yang didukung | Windows Vista [aplikasi desktop | Aplikasi UWP] |
server minimum yang didukung |
Windows Server 2008 [aplikasi desktop | Aplikasi UWP] |
Platform Target |
Windows |
Header |
bcrypt.h |
Pustaka |
Bcrypt.lib |
DLL |
Bcrypt.dll |