Fungsi NCryptDeriveKey (ncrypt.h)

Fungsi NCryptDeriveKey memperoleh kunci dari NCRYPT_SECRET_HANDLE. Fungsi ini dimaksudkan untuk digunakan sebagai bagian dari prosedur perjanjian rahasia menggunakan kunci perjanjian rahasia yang dipertahankan.

Untuk mendapatkan materi kunci dengan menggunakan rahasia yang bertahan, gunakan fungsi NCryptKeyDerivation .

Syntax

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

[in] hSharedSecret

Handel rahasia untuk membuat kunci dari. Handel ini saat ini diperoleh dari fungsi NCryptSecretAgreement .

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

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

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

Pengaturan	Description	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 (bagian 4.1) menggunakan fungsi hash yang disetujui yang memiliki kekuatan yang sesuai dengan algoritma yang digunakan untuk menghasilkan handel rahasia.

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.

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

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.

Pengaturan	Description	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 NCryptBufferDesc 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 DWORD yang ditunjukkan oleh parameter pcbResult .

[in] cbDerivedKey

Ukurannya, 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	Meaning
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	Description
ERROR_SUCCESS	Fungsi berhasil.
NTE_INVALID_HANDLE	Handel dalam parameter hSharedSecret tidak valid.
NTE_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.

Komentar

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

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
Library	Ncrypt.lib
DLL	Ncrypt.dll

Lihat juga

NCryptBufferDesc

NCryptSecretAgreement

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-08-16

Bagikan melalui

Fungsi NCryptDeriveKey (ncrypt.h)

Syntax

Parameter-parameternya

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: