Fungsi BCryptDeriveKey (bcrypt.h)

Fungsi BCryptDeriveKey memperoleh kunci dari BCRYPT_SECRET_HANDLE. Ini biasanya dilakukan sebagai bagian dari prosedur perjanjian rahasia.

Untuk derivasi kunci dari rahasia yang langsung disediakan oleh pemanggil, 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

Handel rahasia 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 mendapatkan kunci. Ini bisa menjadi salah satu string berikut.

BCRYPT_KDF_HASH (L"HASH")

Gunakan fungsi derivasi kunci hash.

Jika parameter cbDerivedKey kurang dari ukuran kunci turunan, fungsi ini hanya akan menyalin jumlah byte yang ditentukan ke buffer pbDerivedKey . Ini biasanya merupakan praktik buruk karena dapat secara signifikan mengurangi kekuatan keamanan kunci yang dihasilkan.

Jika parameter cbDerivedKey lebih besar dari ukuran kunci turunan, fungsi ini akan menyalin kunci ke buffer pbDerivedKey dan mengatur variabel yang diarahkan oleh pcbResult ke jumlah byte aktual yang disalin.

Parameter yang diidentifikasi oleh parameter pParameterList dapat atau harus berisi parameter berikut, seperti yang ditunjukkan oleh kolom Wajib atau opsional.

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-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")

Gunakan fungsi derivasi kunci kode autentikasi pesan ( HMAC)Hash-Based.

Parameter yang diidentifikasi oleh parameter pParameterList dapat atau harus berisi parameter berikut, seperti yang ditunjukkan oleh kolom Wajib atau opsional.

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-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

Gunakan fungsi derivasi kunci fungsi pseudo-random (PRF) keamanan lapisan transportasi (TLS). Ukuran kunci turunan selalu 48 byte, sehingga parameter cbDerivedKey harus 48.

Parameter yang diidentifikasi oleh parameter pParameterList dapat atau harus berisi parameter berikut, seperti yang ditunjukkan oleh kolom Wajib atau opsional.

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 yang menentukan versi protokol TLS yang algoritma PRF-nya akan digunakan. Nilai yang valid adalah: SSL2_PROTOCOL_VERSION (0x0002) SSL3_PROTOCOL_VERSION (0x0300) TLS1_PROTOCOL_VERSION (0x0301) TLS1_0_PROTOCOL_VERSION (0x0301) TLS1_1_PROTOCOL_VERSION (0x0302) TLS1_2_PROTOCOL_VERSION (0x0303) DTLS1_0_PROTOCOL_VERSION (0xfeff) 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. Ini juga dikenal sebagai KDF satu langkah SP800-56C rev2.

KDF mengambil fungsi hash yang disetujui sebagai parameter, tetapi API ini memilih fungsi hash secara internal, mencocokkan kekuatan keamanan algoritma hash dengan algoritma yang digunakan untuk menghasilkan handel rahasia. (yaitu ECDH P-256 menggunakan SHA256, ECDH P-384 menggunakan SHA384)

Parameter yang diidentifikasi oleh parameter pParameterList dapat atau harus berisi parameter berikut, seperti yang ditunjukkan oleh kolom Wajib atau opsional. Semua nilai parameter diperlakukan sebagai array byte buram.

Parameter	Deskripsi	Diperlukan atau opsional
KDF_ALGORITHMID	Menentukan subbidang AlgoritmaID dari bidang OtherInfo di fungsi derivasi kunci SP800-56A. Menunjukkan tujuan yang dimaksudkan dari kunci turunan.	Diperlukan
KDF_PARTYUINFO	Menentukan subbidang PartyUInfo dari bidang OtherInfo dalam fungsi derivasi kunci SP800-56A. Bidang berisi informasi publik yang dikontribusikan oleh inisiator.	Diperlukan
KDF_PARTYVINFO	Menentukan subbidang PartyVInfo dari bidang OtherInfo dalam fungsi derivasi kunci SP800-56A. Bidang berisi informasi publik yang disumbangkan oleh responden.	Diperlukan
KDF_SUPPPUBINFO	Menentukan subbidang SuppPubInfo dari bidang OtherInfo di fungsi derivasi kunci SP800-56A. Bidang berisi informasi publik yang diketahui oleh inisiator dan responden.	Fakultatif
KDF_SUPPPRIVINFO	Menentukan subbidang SuppPrivInfo dari 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. Penggunaan opsi ini biasanya merupakan praktik yang buruk, tetapi mungkin diperlukan jika Anda perlu beroperasi dengan KDF yang tidak didukung.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.

BCRYPT_KDF_HKDF (L"HKDF")

Gunakan fungsi HKDF (KDF Extract-and-Expand berbasis HMAC) dari RFC 5869.

Dalam HKDF, perbedaan dibuat antara mendapatkan kunci dari:

Output fungsi perjanjian rahasia, yang tidak acak secara seragam, dan dianggap sebagai bahan kunci input (IKM). Hampir semua pengguna BCryptDeriveKey akan memiliki handel rahasia dari formulir ini.
Nilai rahasia acak yang seragam.

Langkah pertama adalah "Mengekstrak" kunci pseudorandom (PRK) dari handel rahasia.

Langkah ini dilakukan dengan memanggil BCryptSetProperty pada handel rahasia dengan BCRYPT_HKDF_HASH_ALGORITHM untuk mengatur algoritma hash yang akan digunakan dalam komputasi HMAC di HKDF. Ini diikuti dengan panggilan kedua ke BCryptSetProperty dengan salah satu dari:

Jika handel rahasia mewakili IKM, gunakan BCRYPT_HKDF_SALT_AND_FINALIZE untuk memberikan nilai garam opsional dan mengekstrak PRK dari IKM dan menyelesaikan handel rahasia.
Jika tidak, gunakan BCRYPT_HKDF_PRK_AND_FINALIZE untuk secara langsung mengubah nilai rahasia menjadi HKDF PRK dan menyelesaikan handel rahasia.

Langkah kedua adalah "Perluas" PRK ke dalam kunci turunan output.

Langkah ini dilakukan dengan memanggil BCryptDeriveKey pada handel rahasia yang diselesaikan.

Parameter	Deskripsi	Diperlukan atau opsional
KDF_HKDF_INFO	Menentukan bidang info di Langkah Perluas HKDF. Menunjukkan konteks opsional dan informasi spesifik aplikasi.	Fakultatif

Panggilan ke KDF dibuat seperti yang ditunjukkan dalam pseudocode berikut.

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10: Dukungan untuk HKDF dimulai.

[in, optional] pParameterList

Alamat struktur BCryptBufferDesc yang berisi parameter KDF. Parameter ini bersifat opsional dan bisa jadi NULL jika tidak diperlukan.

[out, optional] pbDerivedKey

Alamat buffer yang menerima kunci. Parameter cbDerivedKey berisi ukuran buffer ini. Jika parameter ini adalah NULL, fungsi ini akan menempatkan ukuran yang diperlukan, dalam byte, di ULONG yang ditunjukkan oleh parameter pcbResult .

[in] cbDerivedKey

Ukurannya, dalam byte, dari buffer pbDerivedKey .

[out] pcbResult

Pointer ke ULONG yang menerima jumlah byte yang disalin ke buffer pbDerivedKey . Jika parameter pbDerivedKey adalah NULL, fungsi ini akan menempatkan ukuran yang diperlukan, dalam byte, di ULONG yang ditunjukkan oleh parameter ini.

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini.

Ini bisa nol atau nilai berikut:

Nilai	Arti
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	Nilai dalam hSharedSecret juga akan berfungsi sebagai kunci HMAC. Jika bendera ini ditentukan, parameter KDF_HMAC_KEY tidak boleh disertakan dalam kumpulan parameter dalam parameter pParameterList . Bendera ini hanya digunakan oleh fungsi derivasi kunci BCRYPT_KDF_HMAC .

Mengembalikan nilai

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini:

Mengembalikan kode	Deskripsi
STATUS_SUCCESS	Fungsi berhasil.
STATUS_INTERNAL_ERROR	Terjadi kesalahan internal.
STATUS_INVALID_HANDLE	Handel dalam parameter hSharedSecret tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.

Komentar

Struktur BCryptBufferDesc dalam parameter pParameterList dapat berisi lebih dari salah satu parameter KDF_SECRET_PREPEND dan KDF_SECRET_APPEND . Jika lebih dari salah satu parameter ini ditentukan, nilai parameter digabungkan dalam urutan di mana parameter tersebut terkandung dalam array sebelum KDF dipanggil. Misalnya, asumsikan nilai parameter berikut ditentukan.

BYTE abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

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 diatur ke BCRYPT_KDF_RAW_SECRET, rahasia yang dikembalikan (tidak seperti nilai pwszKDF lainnya) akan dikodekan dalam format little-endian. Penting untuk dicatat ini saat menggunakan rahasia mentah dalam fungsi CNG lainnya, karena sebagian besar dari mereka mengambil input yang dikodekan big-endian.

Saat menggunakan penyedia algoritma yang didukung, BCryptDeriveKey dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel dapat menjalankan baik di IRQL PASSIVE_LEVEL atau IRQLDISPATCH_LEVEL. Jika tingkat IRQL saat ini DISPATCH_LEVEL, handel yang disediakan dalam parameter hSharedSecret harus terletak di memori yang tidak dipagasi (atau dikunci) dan harus berasal dari handel algoritma yang dikembalikan oleh penyedia yang dibuka dengan menggunakan bendera BCRYPT_PROV_DISPATCH .

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]
Target Platform	Windows
Header	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll

Lihat juga

BCryptBufferDesc

BCryptSecretAgreement

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-08-16

Bagikan melalui

Fungsi BCryptDeriveKey (bcrypt.h)

Sintaksis

Parameter

BCRYPT_KDF_HASH (L"HASH")

BCRYPT_KDF_HMAC (L"HMAC")

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

BCRYPT_KDF_HKDF (L"HKDF")

Langkah pertama adalah "Mengekstrak" kunci pseudorandom (PRK) dari handel rahasia.

Langkah kedua adalah "Perluas" PRK ke dalam kunci turunan output.

Mengembalikan nilai

Komentar

Persyaratan

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: