Fungsi BCryptDeriveKey (bcrypt.h)

Artikel
07/16/2024

Fungsi BCryptDeriveKey memperoleh kunci dari nilai perjanjian rahasia.

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 kurang dari ukuran kunci turunan, fungsi ini hanya akan menyalin jumlah byte yang ditentukan ke pbDerivedKey buffer. Jika parameter cbDerivedKey lebih besar dari ukuran kunci turunan, fungsi ini akan menyalin kunci ke pbDerivedKey buffer dan mengatur variabel yang ditunjukkan 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-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 Hash-Based (HMAC).

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-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 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.

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 dalam fungsi derivasi kunci SP800-56A. Menunjukkan tujuan yang dimaksudkan dari kunci turunan.	Diperlukan
KDF_PARTYUINFO	Menentukan subbidang PartyUInfo 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 dalam fungsi derivasi kunci SP800-56A. Bidang berisi informasi publik yang diketahui oleh inisiator dan responden.	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.

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

[in, optional] pParameterList

Alamat struktur BCryptBufferDesc yang berisi parameter KDF. Parameter ini bersifat opsional dan dapat null jika tidak diperlukan.

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

Ukurannya, dalam byte, dari pbDerivedKey buffer.

[out] pcbResult

Pointer ke ULONG yang menerima jumlah byte yang disalin ke pbDerivedKey buffer. Jika parameter pbDerivedKey NULL, fungsi ini akan menempatkan ukuran yang diperlukan, dalam byte, dalam ULONG 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 perjanjian rahasia 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 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 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.

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

Lihat juga

BCryptSecretAgreement

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")

Mengembalikan nilai

Komentar

Persyaratan

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: