Fungsi NCryptKeyDerivation (ncrypt.h)

Fungsi NCryptKeyDerivation membuat kunci dari kunci lain dengan menggunakan fungsi derivasi kunci yang ditentukan. Fungsi mengembalikan kunci dalam array byte.

Sintaks

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Parameter

[in] hKey

Handel kunci fungsi derivasi kunci (KDF).

[in] pParameterList

Alamat struktur NCryptBufferDesc yang berisi parameter KDF. Parameter dapat spesifik untuk KDF atau generik. Tabel berikut menunjukkan parameter yang diperlukan dan opsional untuk KDF tertentu yang diterapkan oleh penyedia penyimpanan kunci perangkat lunak Microsoft.

KDF	Parameter	Diperlukan
SP800-108 HMAC dalam mode penghitung	KDF_LABEL	ya
	KDF_CONTEXT	ya
	KDF_HASH_ALGORITHM	ya
SP800-56A	KDF_ALGORITHMID	ya
	KDF_PARTYUINFO	ya
	KDF_PARTYVINFO	ya
	KDF_HASH_ALGORITHM	ya
	KDF_SUPPPUBINFO	tidak
	KDF_SUPPPRIVINFO	tidak
PBKDF2	KDF_HASH_ALGORITHM	ya
	KDF_SALT	ya
	KDF_ITERATION_COUNT	tidak
CAPI_KDF	KDF_HASH_ALGORITHM	ya

 

Parameter generik berikut dapat digunakan:

• KDF_GENERIC_PARAMETER

Parameter generik memetakan ke parameter khusus KDF dengan cara berikut:

SP800-108 HMAC dalam mode penghitung:

• KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

• KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

• KDF_GENERIC_PARAMETER = KDF_SALT
• KDF_ITERATION_COUNT – default ke 10000

CAPI_KDF

• KDF_GENERIC_PARAMETER = Tidak Digunakan

[out] pbDerivedKey

Alamat buffer yang menerima kunci. Parameter cbDerivedKey berisi ukuran, dalam byte, dari buffer kunci.

[in] cbDerivedKey

Ukuran, dalam byte, dari buffer yang diacu oleh parameter pbDerivedKey .

[out] pcbResult

Penunjuk ke DWORD yang menerima jumlah byte yang disalin ke buffer yang ditujukkan oleh parameter pbDerivedKey .

[in] dwFlags

Bendera yang mengubah perilaku fungsi. Nilai berikut dapat digunakan dengan penyedia penyimpanan kunci perangkat lunak Microsoft.

Nilai	Makna
BCRYPT_CAPI_AES_FLAG	Menentukan bahwa algoritma target adalah AES dan oleh karena itu kunci harus diperluas dua kali lipat. Bendera ini hanya valid dengan algoritma CAPI_KDF.
NCRYPT_SILENT_FLAG	Meminta agar penyedia layanan utama (KSP) tidak menampilkan antarmuka pengguna apa pun. Jika penyedia harus menampilkan UI untuk beroperasi, panggilan gagal dan KSP harus mengatur kode kesalahan NTE_SILENT_CONTEXT sebagai kesalahan terakhir.

Mengembalikan nilai

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

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

Menampilkan kode	Deskripsi
ERROR_SUCCESS	Fungsi berhasil.
NTE_INVALID_HANDLE	Handel hProvider atau hKey tidak valid.
NTE_INVALID_PARAMETER	Parameter pwszDerivedKeyAlg dan pParameterList tidak boleh NULL.
NTE_NO_MEMORY	Memori tidak cukup untuk membuat kunci.
NTE_NOT_SUPPORTED	Fungsi ini tidak didukung oleh penyedia penyimpanan utama.

Keterangan

Anda dapat menggunakan pengidentifikasi algoritma berikut dalam fungsi NCryptCreatePersistedKey sebelum memanggil NCryptKeyDerivation:

• BCRYPT_CAPI_KDF_ALGORITHM
• BCRYPT_SP800108_CTR_HMAC_ALGORITHM
• BCRYPT_SP80056A_CONCAT_ALGORITHM
• BCRYPT_PBKDF2_ALGORITHM

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	ncrypt.h
Pustaka	Ncrypt.lib
DLL	Ncrypt.dll

Lihat juga

BCryptKeyDerivation

NCryptDeriveKey