Fungsi CryptMsgOpenToDecode (wincrypt.h)
Fungsi CryptMsgOpenToDecode membuka pesan kriptografi untuk pendekodean dan mengembalikan handel pesan yang dibuka. Pesan tetap terbuka sampai fungsi CryptMsgClose dipanggil.
Perubahan penting yang memengaruhi penanganan pesan yang diselimuti telah dilakukan pada CryptoAPI untuk mendukung interoperabilitas email Secure/Multipurpose Internet Mail Extensions (S/MIME). Untuk detailnya, lihat bagian Keterangan dari CryptMsgOpenToEncode.
Sintaks
HCRYPTMSG CryptMsgOpenToDecode(
[in] DWORD dwMsgEncodingType,
[in] DWORD dwFlags,
[in] DWORD dwMsgType,
[in] HCRYPTPROV_LEGACY hCryptProv,
[in] PCERT_INFO pRecipientInfo,
[in, optional] PCMSG_STREAM_INFO pStreamInfo
);
Parameter
[in] dwMsgEncodingType
Menentukan jenis pengodean yang digunakan. Selalu dapat diterima untuk menentukan jenis pengodean sertifikat dan pesan dengan menggabungkannya dengan operasi bitwise-OR seperti yang ditunjukkan dalam contoh berikut:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
Jenis pengodean yang saat ini ditentukan adalah:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] dwFlags
Parameter ini bisa menjadi salah satu bendera berikut.
| Nilai | Makna |
|---|---|
|
Menunjukkan bahwa pesan yang akan didekodekan dilepas. Jika bendera ini tidak diatur, pesan tidak dilepas. |
|
Jika diatur, hCryptProv yang diteruskan ke fungsi ini dirilis pada CryptMsgUpdate akhir. Handel tidak dirilis jika fungsi gagal. |
[in] dwMsgType
Menentukan jenis pesan yang akan didekode. Dalam kebanyakan kasus, jenis pesan ditentukan dari header pesan dan nol diteruskan untuk parameter ini. Dalam beberapa kasus, terutama dengan Internet Explorer 3.0, pesan tidak memiliki header dan jenis pesan yang akan didekodekan harus disediakan dalam panggilan fungsi ini. Jika header hilang dan nol diteruskan untuk parameter ini, fungsi gagal.
Parameter ini bisa menjadi salah satu jenis pesan yang telah ditentukan sebelumnya berikut.
[in] hCryptProv
Parameter ini tidak digunakan dan harus diatur ke NULL.
Windows Server 2003 dan Windows XP: Menentukan handel untuk penyedia kriptografi yang akan digunakan untuk hashing pesan. Untuk pesan yang ditandatangani, hCryptProv digunakan untuk verifikasi tanda tangan. Jenis data parameter ini adalah HCRYPTPROV.
Kecuali ada alasan kuat untuk meneruskan penyedia kriptografi tertentu di hCryptProv, atur parameter ini ke NULL. Meneruskan NULL menyebabkan penyedia RSA atau DSS default diperoleh sebelum melakukan operasi hash, verifikasi tanda tangan, atau enkripsi penerima.
[in] pRecipientInfo
Parameter ini dicadangkan untuk digunakan di masa mendatang dan harus NULL.
[in, optional] pStreamInfo
Ketika streaming tidak digunakan, parameter ini harus diatur ke NULL.
Saat streaming digunakan, parameter pStreamInfo adalah penunjuk ke struktur CMSG_STREAM_INFO yang berisi penunjuk ke panggilan balik untuk dipanggil ketika CryptMsgUpdate dijalankan atau ketika CryptMsgControl dijalankan saat mendekode pesan yang dialirkan.
Untuk pesan yang ditandatangani, panggilan balik diteruskan blok byte yang didekode dari konten dalam pesan.
Untuk pesan yang diselimuti, setelah setiap panggilan ke CryptMsgUpdate, Anda harus memeriksa untuk menentukan apakah properti CMSG_ENVELOPE_ALGORITHM_PARAM tersedia dengan memanggil fungsi CryptMsgGetParam . CryptMsgGetParam akan gagal dan GetLastError akan mengembalikan CRYPT_E_STREAM_MSG_NOT_READY sampai CryptMsgUpdate telah memproses cukup pesan untuk membuat properti CMSG_ENVELOPE_ALGORITHM_PARAM tersedia. Ketika properti CMSG_ENVELOPE_ALGORITHM_PARAM tersedia, Anda dapat melakukan iterasi melalui penerima, mengambil struktur CERT_INFO untuk setiap penerima dengan menggunakan fungsi CryptMsgGetParam untuk mengambil properti CMSG_RECIPIENT_INFO_PARAM. Untuk mencegah penolakan serangan layanan dari pesan yang diselimuti yang memiliki blok header besar buatan, Anda harus melacak jumlah memori yang telah diteruskan ke fungsi CryptMsgUpdate selama proses ini. Jika jumlah data melebihi batas yang ditentukan aplikasi sebelum properti CMSG_ENVELOPE_ALGORITHM_PARAM tersedia, Anda harus berhenti memproses pesan dan memanggil fungsi CryptMsgClose untuk menyebabkan sistem operasi merilis memori apa pun yang telah dialokasikan untuk pesan. Batas yang disarankan adalah ukuran maksimum pesan yang diizinkan. Misalnya, jika ukuran pesan maksimum adalah 10 MB, batas untuk pengujian ini harus 10 MB.
Struktur CERT_INFO digunakan untuk menemukan sertifikat yang cocok di penyimpanan sertifikat yang dibuka sebelumnya dengan menggunakan fungsi CertGetSubjectCertificateFromStore . Ketika sertifikat yang benar ditemukan, fungsi CertGetCertificateContextProperty dengan parameter CERT_KEY_PROV_INFO_PROP_ID dipanggil untuk mengambil struktur CRYPT_KEY_PROV_INFO . Struktur berisi informasi yang diperlukan untuk memperoleh kunci privat penerima dengan memanggil CryptAcquireContext, menggunakan pwszContainerName, pwszProvName, dwProvType, dan dwFlags anggota struktur CRYPT_KEY_PROV_INFO . hCryptProv yang diperoleh dan anggota dwKeySpec dari struktur CRYPT_KEY_PROV_INFO diteruskan ke struktur CryptMsgControl sebagai anggota struktur CMSG_CTRL_DECRYPT_PARA untuk mengizinkan awal dekripsi konten dalam. Kode streaming kemudian akan melakukan dekripsi saat data dimasukkan. Blok teks biasa yang dihasilkan diteruskan ke fungsi panggilan balik yang ditentukan oleh anggota pfnStreamOutput dari struktur CMSG_STREAM_INFO untuk menangani output pesan yang didekripsi.
Dalam kasus pesan bertanda tangan yang diapit dalam pesan yang diselimuti, output teks biasa dari dekode streaming pesan yang diselimuti dapat disalurkan ke dekode streaming lain untuk memproses pesan yang ditandatangani.
Nilai kembali
Jika fungsi berhasil, fungsi mengembalikan handel pesan yang dibuka.
Jika fungsi gagal, fungsi akan mengembalikan NULL. Untuk informasi kesalahan yang diperluas, hubungi GetLastError.
Tabel berikut mencantumkan kode kesalahan yang paling umum dikembalikan oleh fungsi GetLastError .
| Nilai | Deskripsi |
|---|---|
|
Satu atau beberapa argumen tidak valid. |
|
Terjadi kegagalan alokasi memori. |
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 |