Fungsi CryptMsgGetParam (wincrypt.h)

Artikel
08/27/2023

Fungsi CryptMsgGetParam memperoleh parameter pesan setelah pesan kriptografi dikodekan atau didekodekan. Fungsi ini dipanggil setelah panggilan CryptMsgUpdate akhir.

Sintaks

BOOL CryptMsgGetParam(
  [in]      HCRYPTMSG hCryptMsg,
  [in]      DWORD     dwParamType,
  [in]      DWORD     dwIndex,
  [out]     void      *pvData,
  [in, out] DWORD     *pcbData
);

Parameter

[in] hCryptMsg

Menangani pesan kriptografi.

[in] dwParamType

Menunjukkan jenis parameter data yang akan diambil. Jenis data yang akan diambil menentukan jenis struktur yang akan digunakan untuk pvData.

Untuk pesan yang dikodekan, hanya CMSG_BARE_CONTENT, CMSG_ENCODE_SIGNER, CMSG_CONTENT_PARAM, dan CMSG_COMPUTED_HASH_PARAM dwParamTypes yang valid.

Nilai	Makna
CMSG_ATTR_CERT_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah sertifikat atribut dalam pesan SIGNED atau ENVELOPED.
CMSG_ATTR_CERT_PARAM	jenis data pvData: penunjuk ke array BYTE Mengambil sertifikat atribut. Untuk mendapatkan semua sertifikat atribut, panggil CryptMsgGetParam dengan berbagai dwIndex yang diatur ke 0 jumlah atribut dikurangi satu.
CMSG_BARE_CONTENT_PARAM	jenis data pvData: penunjuk ke array BYTE Mengambil konten yang dikodekan dari pesan kriptografi yang dikodekan, tanpa lapisan luar struktur CONTENT_INFO. Artinya, hanya pengodean bidang ContentInfo.content yang ditentukan PKCS #7 yang dikembalikan.
CMSG_CERT_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah sertifikat dalam pesan SIGNED atau ENVELOPED yang diterima.
CMSG_CERT_PARAM	jenis data pvData: penunjuk ke array BYTE Mengembalikan sertifikat penanda tangan. Untuk mendapatkan semua sertifikat penanda tangan, panggil CryptMsgGetParam, bervariasi dwIndex dari 0 hingga jumlah sertifikat yang tersedia dikurangi satu.
CMSG_COMPUTED_HASH_PARAM	jenis data pvData: penunjuk ke array BYTE Mengembalikan hash yang dihitung dari data dalam pesan. Jenis ini berlaku untuk pengodean dan dekode.
CMSG_CONTENT_PARAM	jenis data pvData: penunjuk ke array BYTE Mengembalikan seluruh pesan PKCS #7 dari pesan yang dibuka untuk dikodekan. Mengambil konten dalam pesan yang dibuka untuk didekode. Jika pesan diselimuti, jenis dalam adalah data, dan CryptMsgControl telah dipanggil untuk mendekripsi pesan, konten yang didekripsi dikembalikan. Jika jenis dalam bukan data, BLOB yang dikodekan yang memerlukan pendekodean lebih lanjut dikembalikan. Jika pesan tidak diselimuti dan konten dalam adalah DATA, data yang dikembalikan adalah oktet dari konten dalam. Jenis ini berlaku untuk pengodean dan dekode. Untuk pendekodean, jika jenisnya CMSG_DATA, oktet konten dikembalikan; jika tidak, konten dalam yang dikodekan dikembalikan.
CMSG_CRL_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah CRL dalam pesan yang diterima, DITANDATANGANI, atau DISELIMUTI.
CMSG_CRL_PARAM	jenis data pvData: penunjuk ke array BYTE Mengembalikan CRL. Untuk mendapatkan semua CRL, panggil CryptMsgGetParam, bervariasi dwIndex dari 0 hingga jumlah CRL yang tersedia dikurangi satu.
CMSG_ENCODED_MESSAGE	jenis data pvData: penunjuk ke array BYTE Mengubah isi pesan yang sudah dikodekan. Pesan harus didekode terlebih dahulu dengan panggilan ke CryptMsgOpenToDecode. Kemudian perubahan pada pesan dilakukan melalui panggilan ke CryptMsgControl, CryptMsgCountersign, atau CryptMsgCountersignEncoded. Pesan kemudian dikodekan lagi dengan panggilan ke CryptMsgGetParam, menentukan CMSG_ENCODED_MESSAGE untuk mendapatkan pengodean baru yang mencerminkan perubahan yang dibuat. Ini dapat digunakan, misalnya, untuk menambahkan atribut stempel waktu ke pesan.
CMSG_ENCODED_SIGNER	jenis data pvData: penunjuk ke array BYTE Mengembalikan informasi penanda tangan CMSG_SIGNER_INFO yang dikodekan untuk penanda tangan pesan.
CMSG_ENCRYPTED_DIGEST	jenis data pvData: penunjuk ke array BYTE Mengembalikan hash terenkripsi tanda tangan. Biasanya digunakan untuk melakukan stempel waktu.
CMSG_ENCRYPT_PARAM	jenis data pvData: penunjuk ke array BYTE untuk struktur CRYPT_ALGORITHM_IDENTIFIER. Mengembalikan algoritma enkripsi yang digunakan untuk mengenkripsi pesan.
CMSG_ENVELOPE_ALGORITHM_PARAM	jenis data pvData: penunjuk ke array BYTE untuk struktur CRYPT_ALGORITHM_IDENTIFIER. Mengembalikan algoritma enkripsi yang digunakan untuk mengenkripsi pesan ENVELOPED.
CMSG_HASH_ALGORITHM_PARAM	jenis data pvData: penunjuk ke array BYTE untuk struktur CRYPT_ALGORITHM_IDENTIFIER. Mengembalikan algoritma hash yang digunakan untuk hash pesan saat dibuat.
CMSG_HASH_DATA_PARAM	jenis data pvData: penunjuk ke array BYTE Mengembalikan nilai hash yang disimpan dalam pesan saat dibuat.
CMSG_INNER_CONTENT_TYPE_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima string pengidentifikasi objek (OID) yang dihentikan null. Mengembalikan tipe isi dalam pesan yang diterima. Jenis ini tidak berlaku untuk pesan jenis DATA.
CMSG_RECIPIENT_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah penerima transportasi utama dari pesan yang diterima ENVELOPED.
CMSG_CMS_RECIPIENT_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah total semua penerima pesan termasuk perjanjian kunci dan penerima daftar email.
CMSG_RECIPIENT_INDEX_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan indeks penerima transportasi kunci yang digunakan untuk mendekripsi pesan ENVELOPED. Nilai ini hanya tersedia setelah pesan didekripsi.
CMSG_CMS_RECIPIENT_INDEX_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan indeks pengangkutan kunci, perjanjian kunci, atau penerima daftar email yang digunakan untuk mendekripsi pesan ENVELOPED.
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan indeks kunci terenkripsi penerima perjanjian kunci yang digunakan untuk mendekripsi pesan ENVELOPED.
CMSG_RECIPIENT_INFO_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CERT_INFO. Mengembalikan informasi sertifikat tentang penerima pesan transportasi utama. Untuk mendapatkan informasi sertifikat tentang semua penerima pesan transportasi utama, berulang kali panggil CryptMsgGetParam, bervariasi dwIndex dari 0 hingga jumlah penerima dikurangi satu. Hanya anggota Penerbit, SerialNumber, dan PublicKeyAlgorithm dari struktur CERT_INFO yang dikembalikan yang tersedia dan valid.
CMSG_CMS_RECIPIENT_INFO_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CMSG_CMS_RECIPIENT_INFO. Mengembalikan informasi tentang transportasi kunci, perjanjian kunci, atau penerima daftar email. Ini tidak terbatas pada penerima pesan transportasi utama. Untuk mendapatkan informasi tentang semua penerima pesan, berulang kali panggil CryptMsgGetParam, bervariasi dwIndex dari 0 hingga jumlah penerima dikurangi satu.
CMSG_SIGNER_AUTH_ATTR_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CRYPT_ATTRIBUTES. Mengembalikan atribut terautentikasi dari penanda tangan pesan. Untuk mengambil atribut terautentikasi untuk penanda tangan tertentu, panggil CryptMsgGetParam dengan dwIndex yang sama dengan indeks penanda tangan tersebut.
CMSG_SIGNER_CERT_INFO_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CERT_INFO. Mengembalikan informasi tentang penanda tangan pesan yang diperlukan untuk mengidentifikasi sertifikat penanda tangan. Pengeluar sertifikat dan SerialNumber dapat digunakan untuk mengidentifikasi sertifikat untuk pengambilan secara unik. Untuk mengambil informasi untuk semua penanda tangan, secara berulang-ulang panggil CryptMsgGetParam berbagai dwIndex dari 0 hingga jumlah penanda tangan dikurangi satu. Hanya bidang Penerbit dan SerialNumber dalam struktur CERT_INFO yang dikembalikan yang berisi data yang tersedia dan valid.
CMSG_SIGNER_CERT_ID_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CERT_ID. Mengembalikan informasi tentang penanda tangan pesan yang diperlukan untuk mengidentifikasi kunci umum penanda tangan. Ini bisa menjadi Penerbit sertifikat dan SerialNumber, KeyID, atau HashId. Untuk mengambil informasi untuk semua penanda tangan, panggil CryptMsgGetParam bervariasi dwIndex dari 0 hingga jumlah penanda tangan dikurangi satu.
CMSG_SIGNER_COUNT_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan jumlah penanda tangan pesan BERTANDA TANGAN yang diterima.
CMSG_SIGNER_HASH_ALGORITHM_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CRYPT_ALGORITHM_IDENTIFIER. Mengembalikan algoritma hash yang digunakan oleh penanda tangan pesan. Untuk mendapatkan algoritma hash untuk penanda tangan tertentu, panggil CryptMsgGetParam dengan dwIndex sama dengan indeks penanda tangan tersebut.
CMSG_SIGNER_INFO_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CMSG_SIGNER_INFO. Mengembalikan informasi pada penanda tangan pesan. Ini termasuk penerbit dan nomor seri sertifikat penanda tangan dan atribut sertifikat penanda tangan yang diautentikasi dan tidak diautentikasi. Untuk mengambil informasi penanda tangan tentang semua penanda tangan pesan, panggil CryptMsgGetParam berbagai dwIndex dari 0 hingga jumlah penanda tangan dikurangi satu.
CMSG_CMS_SIGNER_INFO_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CMSG_CMS_SIGNER_INFO. Mengembalikan informasi pada penanda tangan pesan. Ini termasuk signerId dan atribut yang diautentikasi dan tidak diautentikasi. Untuk mengambil informasi penanda tangan tentang semua penanda tangan pesan, panggil CryptMsgGetParam berbagai dwIndex dari 0 hingga jumlah penanda tangan dikurangi satu.
CMSG_SIGNER_UNAUTH_ATTR_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CRYPT_ATTRIBUTES. Mengembalikan atribut penanda tangan pesan yang tidak diautentikasi. Untuk mengambil atribut yang tidak terauthentikasi untuk penanda tangan tertentu, panggil CryptMsgGetParam dengan dwIndex sama dengan indeks penanda tangan tersebut.
CMSG_TYPE_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan tipe pesan dari pesan yang didekodekan dari tipe yang tidak diketahui. Jenis pesan yang diambil dapat dibandingkan dengan jenis yang didukung untuk menentukan apakah pemrosesan dapat dilanjutkan. Untuk jenis pesan yang didukung, lihat parameter dwMessageType dari CryptMsgOpenToDecode.
CMSG_UNPROTECTED_ATTR_PARAM	jenis data pvData: penunjuk ke array BYTE untuk menerima struktur CMSG_ATTR. Mengembalikan atribut yang tidak terlindungi dalam pesan yang diselimuti.
CMSG_VERSION_PARAM	jenis data pvData: penunjuk ke DWORD Mengembalikan versi pesan yang didekodekan. Untuk mendapatkan informasi selengkapnya, lihat tabel di bagian Keterangan.

[in] dwIndex

Indeks untuk parameter yang diambil, jika berlaku. Ketika parameter tidak diambil, parameter ini diabaikan dan diatur ke nol.

[out] pvData

Penunjuk ke buffer yang menerima data yang diambil. Bentuk data ini akan bervariasi tergantung pada nilai parameter dwParamType .

Parameter ini dapat berupa NULL untuk mengatur ukuran informasi ini untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.

Saat memproses data yang dikembalikan dalam buffer ini, aplikasi perlu menggunakan ukuran aktual data yang dikembalikan. Ukuran aktual bisa sedikit lebih kecil dari ukuran buffer yang ditentukan pada input. (Pada input, ukuran buffer biasanya ditentukan cukup besar untuk memastikan bahwa data output terbesar yang mungkin akan pas di buffer.) Pada output, variabel yang diacu oleh parameter ini diperbarui untuk mencerminkan ukuran aktual data yang disalin ke buffer.

[in, out] pcbData

Penunjuk ke variabel yang menentukan ukuran, dalam byte, dari buffer yang diacu oleh parameter pvData . Ketika fungsi kembali, variabel yang diacu oleh parameter pcbData berisi jumlah byte yang disimpan dalam buffer.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Tabel berikut mencantumkan kode kesalahan yang paling umum dikembalikan oleh fungsi GetLastError .

Menampilkan kode	Deskripsi
CRYPT_E_ATTRIBUTES_MISSING	Pesan tidak berisi atribut yang diminta.
CRYPT_E_INVALID_INDEX	Nilai indeks tidak valid.
CRYPT_E_INVALID_MSG_TYPE	Tipe pesan tidak valid.
CRYPT_E_NOT_DECRYPTED	Isi pesan belum didekripsi.
CRYPT_E_OID_FORMAT	Pengidentifikasi objek diformat dengan buruk.
CRYPT_E_UNEXPECTED_ENCODING	Pesan tidak dikodekan seperti yang diharapkan.
E_INVALIDARG	Satu atau beberapa argumen tidak valid.
ERROR_MORE_DATA	Buffer yang ditentukan tidak cukup besar untuk menyimpan data yang dikembalikan.

Untuk dwParamType CMSG_COMPUTED_HASH_PARAM, kesalahan dapat disebarluaskan dari CryptGetHashParam.

Jika fungsi gagal, GetLastError dapat mengembalikan kesalahan pengodean/pendekodean Abstract Syntax Notation One (ASN.1). Untuk informasi tentang kesalahan ini, lihat Nilai Pengembalian Pengodean/Pendekodean ASN.1.

Keterangan

Nomor versi berikut dikembalikan oleh panggilan ke CryptMsgGetParam dengan dwParamType diatur ke CMSG_VERSION_PARAM ditentukan:

CMSG_SIGNED_DATA_V1
CMSG_SIGNED_DATA_V3
CMSG_SIGNED_DATA_PKCS_1_5_VERSION
CMSG_SIGNED_DATA_CMS_VERSION
CMSG_SIGNER_INFO_V1
CMSG_SIGNER_INFO_V3
CMSG_SIGNER_INFO_PKCS_1_5_VERSION
CMSG_SIGNER_INFO_CMS_VERSION
CMSG_HASHED_DATA_V0
CMSG_HASHED_DATA_V2
CMSG_HASHED_DATA_PKCS_1_5_VERSION
CMSG_HASHED_DATA_CMS_VERSION
CMSG_ENVELOPED_DATA_V0
CMSG_ENVELOPED_DATA_V2
CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
CMSG_ENVELOPED_DATA_CMS_VERSION

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Penandatanganan, Pengodean, Pendekodean, dan Verifikasi Pesan, Kode Alternatif untuk Pengodean Pesan Yang Diselimuti, Contoh Program C: Mengodekan Pesan yang Diselimuti, Ditandatangani, dan Program Contoh C: Pengodean dan Pendekodean Pesan Hash.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	wincrypt.h
Pustaka	Crypt32.lib
DLL	Crypt32.dll