Bagikan melalui

Fungsi NCryptDeriveKey (ncrypt.h)

  • Artikel

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

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