Bagikan melalui


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
CMSG_DETACHED_FLAG
Menunjukkan bahwa pesan yang akan didekodekan dilepas. Jika bendera ini tidak diatur, pesan tidak dilepas.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
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.

Nilai Makna
CMSG_DATA
Pesan adalah data yang dikodekan.
CMSG_ENVELOPED
Pesan adalah pesan yang diselimuti.
CMSG_HASHED
Pesan adalah pesan yang di-hash.
CMSG_SIGNED
Pesan adalah pesan yang ditandatangani.
CMSG_SIGNED_AND_ENVELOPED
Pesan adalah pesan yang ditandatangani dan diselimuti.

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

Catatan Streaming tidak digunakan dengan pesan CMSG_HASHED. Saat berhadapan dengan data yang di-hash, 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.

Catatan Dekode aliran pesan yang diselimuti mengantrekan ciphertext dalam memori hingga CryptMsgControl dipanggil untuk memulai dekripsi. Aplikasi harus memulai dekripsi secara tepat waktu sehingga data dapat disimpan ke disk atau dirutekan di tempat lain sebelum akumulasi ciphertext menjadi terlalu besar dan sistem kehabisan memori.
 

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
E_INVALIDARG
Satu atau beberapa argumen tidak valid.
E_OUTOFMEMORY
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

Lihat juga

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToEncode

CryptMsgUpdate

Fungsi Pesan tingkat rendah

Fungsi Pesan yang Disederhanakan