Fungsi NCryptDeriveKey (ncrypt.h)

Artikel
03/05/2024

Fungsi NCryptDeriveKey memperoleh kunci dari nilai perjanjian rahasia. Fungsi ini dimaksudkan untuk digunakan sebagai bagian dari prosedur perjanjian rahasia menggunakan kunci perjanjian rahasia yang bertahan. Untuk mendapatkan materi kunci dengan menggunakan rahasia yang bertahan sebagai gantinya, gunakan fungsi NCryptKeyDerivation .

Sintaks

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

Parameter

[in] hSharedSecret

Perjanjian rahasia menangani untuk membuat kunci dari. Handel ini diperoleh dari fungsi NCryptSecretAgreement .

[in] pwszKDF

Penunjuk ke string Unicode yang dihentikan null yang mengidentifikasi fungsi derivasi kunci (KDF) yang akan 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 buffer pbDerivedKey . 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 yang dihentikan null yang mengidentifikasi algoritma hash untuk 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.	Opsional
KDF_SECRET_PREPEND	Nilai yang akan ditambahkan ke awal input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan.	Opsional
KDF_SECRET_APPEND	Nilai yang akan ditambahkan ke akhir input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan.	Opsional

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 Berbasis Hash (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 yang dihentikan null yang mengidentifikasi algoritma hash untuk 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.	Opsional
KDF_HMAC_KEY	Kunci yang digunakan untuk fungsi pseudo-random (PRF).	Opsional
KDF_SECRET_PREPEND	Nilai yang akan ditambahkan ke awal input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan.	Opsional
KDF_SECRET_APPEND	Nilai yang akan ditambahkan ke akhir input pesan ke fungsi hash. Untuk informasi selengkapnya, lihat Keterangan.	Opsional

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) pseudo-random function (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

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 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 dikontribusikan oleh responden.	Diperlukan
KDF_SUPPPUBINFO	Menentukan subbidang SuppPubInfo dari bidang OtherInfo dalam fungsi derivasi kunci SP800-56A. Bidang ini berisi informasi publik yang diketahui oleh inisiator dan responden.	Opsional
KDF_SUPPPRIVINFO	Menentukan subbidang SuppPrivInfo dari bidang OtherInfo dalam fungsi derivasi kunci SP800-56A. Ini berisi informasi privat yang diketahui oleh inisiator dan penanggap, seperti rahasia bersama.	Opsional

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.

[in, optional] pParameterList

Alamat struktur NCryptBufferDesc yang berisi parameter KDF. Parameter ini bersifat opsional dan dapat berupa 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 DWORD yang ditunjukkan oleh parameter pcbResult .

[in] cbDerivedKey

Ukuran, dalam byte, dari buffer pbDerivedKey .

[out] pcbResult

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

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Ini bisa nol atau nilai berikut.

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

Menampilkan kode	Deskripsi
ERROR_SUCCESS	Fungsi berhasil.
NTE_INVALID_HANDLE	Parameter hSharedSecret tidak valid.
NTE_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.

Keterangan

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

Layanan tidak boleh memanggil fungsi ini dari Fungsi StartService-nya. Jika layanan memanggil fungsi ini dari fungsi StartService-nya, kebuntuan dapat terjadi, dan layanan mungkin berhenti merespons.

Persyaratan

Persyaratan	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	ncrypt.h
Pustaka	Ncrypt.lib
DLL	Ncrypt.dll

Lihat juga

NCryptBufferDesc

Bagikan melalui

Fungsi NCryptDeriveKey (ncrypt.h)

Sintaks

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

Mengembalikan nilai

Keterangan

Persyaratan

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: