Fungsi CryptMsgControl (wincrypt.h)

Artikel
03/15/2023

Fungsi CryptMsgControl melakukan operasi kontrol setelah pesan didekodekan oleh panggilan akhir ke fungsi CryptMsgUpdate . Operasi kontrol yang disediakan oleh fungsi ini digunakan untuk dekripsi, verifikasi tanda tangan dan hash, serta penambahan dan penghapusan sertifikat, daftar pencabutan sertifikat (CRL), penanda tangan, dan atribut yang tidak diautentikasi.

Perubahan penting yang memengaruhi penanganan pesan yang diselimuti telah dilakukan pada CryptoAPI untuk mendukung interoperabilitas email Secure/Multipurpose Internet Mail Extensions (S/MIME). Untuk informasi selengkapnya, lihat Keterangan untuk fungsi CryptMsgOpenToEncode .

Sintaks

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Parameter

[in] hCryptMsg

Handel pesan kriptografi yang kontrolnya akan diterapkan.

[in] dwFlags

Nilai berikut didefinisikan ketika parameter dwCtrlType adalah salah satu dari berikut ini:

CMSG_CTRL_DECRYPT
CMSG_CTRL_KEY_TRANS_DECRYPT
CMSG_CTRL_KEY_AGREE_DECRYPT
CMSG_CTRL_MAIL_LIST_DECRYPT

Nilai	Makna
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Handel ke penyedia kriptografi dirilis pada panggilan akhir ke fungsi CryptMsgClose . Handel ini tidak dirilis jika fungsi CryptMsgControl gagal.

Jika parameter dwCtrlType tidak menentukan operasi dekripsi, atur nilai ini ke nol.

[in] dwCtrlType

Jenis operasi yang akan dilakukan. Jenis kontrol pesan yang ditentukan saat ini dan jenis struktur yang harus diteruskan ke parameter pvCtrlPara diperlihatkan dalam tabel berikut.

Nilai	Makna
CMSG_CTRL_ADD_ATTR_CERT 14 (0xE)	BLOB yang berisi byte sertifikat atribut yang dikodekan.
CMSG_CTRL_ADD_CERT 10 (0xA)	Struktur CRYPT_INTEGER_BLOB yang berisi byte sertifikat yang dikodekan untuk ditambahkan ke pesan.
CMSG_CTRL_ADD_CMS_SIGNER_INFO 20 (0x14)	Struktur CMSG_CMS_SIGNER_INFO yang berisi informasi penanda tangan. Operasi ini berbeda dari CMSG_CTRL_ADD_SIGNER karena informasi penanda tangan berisi tanda tangan.
CMSG_CTRL_ADD_CRL 12 (0xC)	BLOB yang berisi byte yang dikodekan dari CRL untuk ditambahkan ke pesan.
CMSG_CTRL_ADD_SIGNER 6 (0x6)	Struktur CMSG_SIGNER_ENCODE_INFO yang berisi informasi penanda tangan yang akan ditambahkan ke pesan.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR 8 (0x8)	Struktur CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA yang berisi indeks penanda tangan dan BLOB yang berisi informasi atribut yang tidak diautentikasi untuk ditambahkan ke pesan.
CMSG_CTRL_DECRYPT 2 (0x2)	Struktur CMSG_CTRL_DECRYPT_PARA digunakan untuk mendekripsi pesan untuk penerima transportasi kunci yang ditentukan. Nilai ini berlaku untuk penerima RSA. Operasi ini menentukan bahwa fungsi CryptMsgControl mencari indeks penerima untuk mendapatkan informasi penerima transportasi utama. Jika fungsi gagal, GetLastError akan mengembalikan CRYPT_E_INVALID_INDEX jika tidak ada penerima transportasi kunci yang ditemukan.
CMSG_CTRL_DEL_ATTR_CERT 15 (0xF)	Indeks sertifikat atribut yang akan dihapus.
CMSG_CTRL_DEL_CERT 11 (0xB)	Indeks sertifikat yang akan dihapus dari pesan.
CMSG_CTRL_DEL_CRL 13 (0xD)	Indeks CRL yang akan dihapus dari pesan.
CMSG_CTRL_DEL_SIGNER 7 (0x7)	Indeks penanda tangan yang akan dihapus.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR 9 (0x9)	Struktur CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA yang berisi indeks yang menentukan penanda tangan dan indeks yang menentukan atribut penanda tangan yang tidak diatomatiskan untuk dihapus.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE 21 (0x15)	Struktur CERT_STRONG_SIGN_PARA digunakan untuk melakukan pemeriksaan tanda tangan yang kuat. Untuk memeriksa tanda tangan yang kuat, tentukan jenis kontrol ini sebelum memanggil CryptMsgGetAndVerifySigner atau sebelum memanggil CryptMsgControl dengan jenis kontrol berikut diatur: CMSG_CTRL_VERIFY_SIGNATURE CMSG_CTRL_VERIFY_SIGNATURE_EX Setelah tanda tangan berhasil diverifikasi, fungsi ini memeriksa tanda tangan yang kuat. Jika tanda tangan tidak kuat, operasi akan gagal dan nilai GetLastError akan diatur ke NTE_BAD_ALGID.
CMSG_CTRL_KEY_AGREE_DECRYPT 17 (0x11)	Struktur CMSG_CTRL_KEY_AGREE_DECRYPT_PARA digunakan untuk mendekripsi pesan untuk kunci sesi perjanjian kunci yang ditentukan. Perjanjian kunci digunakan dengan enkripsi/dekripsi Diffie-Hellman.
CMSG_CTRL_KEY_TRANS_DECRYPT 16 (0x10)	Struktur CMSG_CTRL_KEY_TRANS_DECRYPT_PARA digunakan untuk mendekripsi pesan untuk penerima transportasi kunci yang ditentukan. Transportasi kunci digunakan dengan enkripsi/dekripsi RSA.
CMSG_CTRL_MAIL_LIST_DECRYPT 18 (0x12)	Struktur CMSG_CTRL_MAIL_LIST_DECRYPT_PARA digunakan untuk mendekripsi pesan untuk penerima yang ditentukan menggunakan kunci enkripsi kunci (KEK) yang didistribusikan sebelumnya.
CMSG_CTRL_VERIFY_HASH 5 (0x5)	Nilai ini tidak digunakan.
CMSG_CTRL_VERIFY_SIGNATURE 1 (0x1)	Struktur CERT_INFO yang mengidentifikasi penanda tangan pesan yang tanda tangannya akan diverifikasi.
CMSG_CTRL_VERIFY_SIGNATURE_EX 19 (0x13)	Struktur CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA yang menentukan indeks penanda tangan dan kunci umum untuk memverifikasi tanda tangan pesan. Kunci umum penanda tangan dapat berupa struktur CERT_PUBLIC_KEY_INFO , konteks sertifikat, atau konteks rantai sertifikat.

[in] pvCtrlPara

Penunjuk ke struktur yang ditentukan oleh nilai dwCtrlType.

nilai dwCtrlType	Makna
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT, atau CMSG_CTRL_MAIL_LIST_DECRYPT, dan pesan amplop yang dialirkan sedang didekode	Pendekodean akan dilakukan seolah-olah konten yang dialirkan sedang didekripsi. Jika ada konten streaming terenkripsi yang telah terakumulasi sebelum panggilan ini, beberapa atau semua teks biasa yang dihasilkan dari dekripsi teks sandi diteruskan kembali ke aplikasi melalui fungsi panggilan balik yang ditentukan dalam panggilan ke fungsi CryptMsgOpenToDecode . Catatan Saat mengalirkan pesan yang diselimuti, fungsi CryptMsgControl tidak dipanggil sampai polling untuk ketersediaan CMSG_ENVELOPE_ALGORITHM_PARAM berhasil. Jika polling tidak berhasil, hasil kesalahan. Untuk deskripsi polling tersebut, lihat fungsi CryptMsgOpenToDecode .
CMSG_CTRL_VERIFY_HASH	Hash yang dihitung dari konten pesan dibandingkan dengan hash yang terkandung dalam pesan.
CMSG_CTRL_ADD_SIGNER	pvCtrlPara menunjuk ke struktur CMSG_SIGNER_ENCODE_INFO yang berisi informasi penanda tangan yang akan ditambahkan ke pesan.
CMSG_CTRL_DEL_SIGNER	Setelah penghapusan dilakukan, indeks penanda tangan lain yang digunakan untuk pesan ini tidak lagi valid dan harus diperoleh kembali dengan memanggil fungsi CryptMsgGetParam .
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	Setelah penghapusan dilakukan, indeks atribut lain yang tidak terautentikasi yang digunakan untuk penanda tangan ini tidak lagi valid dan harus diperoleh kembali dengan memanggil fungsi CryptMsgGetParam .
CMSG_CTRL_DEL_CERT	Setelah penghapusan dilakukan, indeks sertifikat lain yang digunakan untuk pesan ini tidak lagi valid dan harus diperoleh kembali dengan memanggil fungsi CryptMsgGetParam .
CMSG_CTRL_DEL_CRL	Setelah penghapusan dilakukan, indeks CRL lain yang digunakan untuk pesan ini tidak lagi valid dan perlu diperoleh kembali dengan memanggil fungsi CryptMsgGetParam .

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Ketika pesan yang dialirkan, pesan yang diselimuti sedang didekodekan, kesalahan yang ditemui dalam fungsi panggilan balik yang ditentukan aplikasi yang ditentukan oleh parameter pStreamInfo dari
Fungsi CryptMsgOpenToDecode mungkin disebarluaskan ke fungsi CryptMsgControl . Jika ini terjadi, fungsi SetLastError tidak dipanggil oleh fungsi CryptMsgControl setelah fungsi panggilan balik kembali. Ini mempertahankan kesalahan apa pun yang ditemui di bawah kendali aplikasi. Ini adalah tanggung jawab fungsi panggilan balik (atau salah satu API yang dipanggilnya) untuk memanggil fungsi SetLastError jika terjadi kesalahan saat aplikasi memproses data yang dialirkan.

Kesalahan yang disebarkan mungkin ditemui dari fungsi berikut:

Kode kesalahan berikut paling sering dikembalikan.

Menampilkan kode	Deskripsi
CRYPT_E_ALREADY_DECRYPTED	Isi pesan telah didekripsi. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_DECRYPT.
CRYPT_E_AUTH_ATTR_MISSING	Pesan tidak berisi atribut terautentikasi yang diharapkan. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_BAD_ENCODE	Terjadi kesalahan saat pengodean atau pendekodean. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_CONTROL_TYPE	Tipe kontrol tidak valid.
CRYPT_E_HASH_VALUE	Nilai hash salah.
CRYPT_E_INVALID_INDEX	Nilai indeks tidak valid.
CRYPT_E_INVALID_MSG_TYPE	Tipe pesan tidak valid.
CRYPT_E_OID_FORMAT	Pengidentifikasi objek diformat dengan buruk. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_ADD_SIGNER.
CRYPT_E_RECIPIENT_NOT_FOUND	Pesan data yang diselimuti tidak berisi penerima yang ditentukan. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_DECRYPT.
CRYPT_E_SIGNER_NOT_FOUND	Penanda tangan yang ditentukan untuk pesan tidak ditemukan. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_UNKNOWN_ALGO	Algoritma kriptografi tidak diketahui.
CRYPT_E_UNEXPECTED_ENCODING	Pesan tidak dikodekan seperti yang diharapkan. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_VERIFY_SIGNATURE.
E_INVALIDARG	Satu atau beberapa argumen tidak valid. Kesalahan ini dapat dikembalikan jika parameter dwCtrlType diatur ke CMSG_CTRL_DECRYPT.
E_OUTOFMEMORY	Tidak tersedia cukup memori untuk menyelesaikan operasi.

Persyaratan

Persyaratan	Nilai
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

Lihat juga

Fungsi Pesan tingkat rendah

Fungsi Pesan yang Disederhanakan

Bagikan melalui