Fungsi CryptDecodeMessage (wincrypt.h)

Artikel
03/15/2023

Fungsi CryptDecodeMessage mendekode, mendekripsi, dan memverifikasi pesan kriptografi.

Fungsi ini dapat digunakan ketika jenis pesan kriptografi tidak diketahui. Konstanta dwMsgTypeFlags dapat dikombinasikan dengan operasi bitwise-OR sehingga fungsi akan mencoba menemukan salah satu jenisnya. Ketika salah satu jenis ditemukan, fungsi melaporkan jenis yang ditemukan dan mengembalikan data yang sesuai dengan jenis tersebut.

Dalam setiap pass, fungsi hanya retak satu tingkat enkripsi atau pengodean. Untuk pemecahan tambahan, fungsi ini, atau salah satu Fungsi Pesan Sederhana lainnya, harus dipanggil lagi.

Sintaks

BOOL CryptDecodeMessage(
  [in]                DWORD                       dwMsgTypeFlags,
  [in]                PCRYPT_DECRYPT_MESSAGE_PARA pDecryptPara,
  [in]                PCRYPT_VERIFY_MESSAGE_PARA  pVerifyPara,
  [in]                DWORD                       dwSignerIndex,
  [in]                const BYTE                  *pbEncodedBlob,
  [in]                DWORD                       cbEncodedBlob,
  [in]                DWORD                       dwPrevInnerContentType,
  [out, optional]     DWORD                       *pdwMsgType,
  [out, optional]     DWORD                       *pdwInnerContentType,
  [out, optional]     BYTE                        *pbDecoded,
  [in, out, optional] DWORD                       *pcbDecoded,
  [out, optional]     PCCERT_CONTEXT              *ppXchgCert,
  [out, optional]     PCCERT_CONTEXT              *ppSignerCert
);

Parameter

[in] dwMsgTypeFlags

Menunjukkan jenis pesan. Jenis pesan dapat dikombinasikan dengan operator bitwise-OR. Parameter ini bisa menjadi salah satu jenis pesan berikut:

CMSG_DATA_FLAG
CMSG_SIGNED_FLAG
CMSG_ENVELOPED_FLAG
CMSG_SIGNED_AND_ENVELOPED_FLAG
CMSG_HASHED_FLAG

Catatan Setelah kembali, DWORD yang diarahkan oleh pdwMsgType diatur dengan jenis pesan.

[in] pDecryptPara

Penunjuk ke struktur CRYPT_DECRYPT_MESSAGE_PARA yang berisi parameter dekripsi.

[in] pVerifyPara

Penunjuk ke struktur CRYPT_VERIFY_MESSAGE_PARA yang berisi parameter verifikasi.

[in] dwSignerIndex

Menunjukkan penanda tangan mana, di antara kemungkinan banyak penanda tangan pesan, yang akan diverifikasi. Indeks ini dapat diubah dalam beberapa panggilan ke fungsi untuk memverifikasi penanda tangan tambahan.

dwSignerIndex diatur ke nol untuk penanda tangan pertama. Jika fungsi mengembalikan FALSE, dan GetLastError mengembalikan CRYPT_E_NO_SIGNER, panggilan sebelumnya mengembalikan penanda tangan terakhir pesan. Parameter ini hanya digunakan dengan pesan jenis CMSG_SIGNED_AND_ENVELOPED atau CMSG_SIGNED. Untuk semua jenis pesan lainnya, harus diatur ke nol.

[in] pbEncodedBlob

Penunjuk ke BLOB yang dikodekan yang akan didekodekan.

[in] cbEncodedBlob

Ukuran, dalam byte, dari BLOB yang dikodekan.

[in] dwPrevInnerContentType

Hanya berlaku saat memproses pesan kriptografi berlapis. Saat memproses pesan kriptografi luar, pesan harus diatur ke nol. Saat mendekode pesan kriptografi berlapis, pesan tersebut diatur ke nilai yang dikembalikan di pdwInnerContentType dengan panggilan CryptDecodeMessage sebelumnya untuk pesan luar. Ini bisa menjadi salah satu jenis CMSG yang tercantum dalam pdwMsgType. Untuk kompatibilitas mundur, atur dwPrevInnerContentType ke nol.

[out, optional] pdwMsgType

Penunjuk ke DWORD yang menentukan jenis pesan yang dikembalikan. Parameter ini bisa menjadi salah satu jenis pesan berikut:

CMSG_DATA
CMSG_SIGNED
CMSG_ENVELOPED
CMSG_SIGNED_AND_ENVELOPED
CMSG_HASHED

[out, optional] pdwInnerContentType

Penunjuk ke DWORD yang menentukan jenis pesan dalam. Kode jenis pesan yang digunakan untuk pdwMsgType juga digunakan di sini.

Jika tidak ada bersarang kriptografi, CMSG_DATA dikembalikan.

[out, optional] pbDecoded

Penunjuk ke buffer untuk menerima pesan yang didekodekan.

Parameter ini dapat berupa NULL jika pesan yang didekode tidak diperlukan atau untuk mengatur ukuran pesan yang didekodekan untuk tujuan alokasi memori. Pesan yang didekode tidak akan dikembalikan jika parameter ini NULL. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.

[in, out, optional] pcbDecoded

Penunjuk ke variabel yang menentukan ukuran, dalam byte, dari buffer yang diacu oleh parameter pbDecoded . Ketika fungsi kembali, variabel ini berisi ukuran pesan yang didekodekan.

Catatan Saat memproses data yang dikembalikan dalam buffer, aplikasi harus 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.

[out, optional] ppXchgCert

Penunjuk ke penunjuk ke struktur CERT_CONTEXT dengan sertifikat yang sesuai dengan kunci pertukaran privat yang diperlukan untuk mendekode pesan. Parameter ini hanya diatur untuk jenis pesan CMSG_ENVELOPED dan CMSG_SIGNED_AND_ENVELOPED.

[out, optional] ppSignerCert

Penunjuk ke penunjuk ke struktur CERT_CONTEXT konteks sertifikat penanda tangan. Parameter ini hanya diatur untuk jenis pesan CMSG_SIGNED dan CMSG_SIGNED_AND_ENVELOPED.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).

Jika fungsi gagal, fungsi akan mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Fungsi CryptDecryptMessage, CryptVerifyMessageSignature, atau CryptVerifyMessageHash dapat disebarluaskan ke fungsi ini.

Kode kesalahan berikut paling umum dikembalikan oleh fungsi GetLastError .

Menampilkan kode	Deskripsi
ERROR_MORE_DATA	Jika buffer yang ditentukan oleh parameter pbDecoded tidak cukup besar untuk menyimpan data yang dikembalikan, fungsi mengatur kode ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan, dalam byte, dalam variabel yang ditunjukkan oleh pcbDecoded.

Keterangan

Parameter dwMsgTypeFlags menentukan kumpulan pesan yang diizinkan. Misalnya, untuk mendekode pesan SIGNED atau ENVELOPED, atur dwMsgTypeFlags ke CMSG_SIGNED_FLAG | CMSG_ENVELOPED_FLAG. Baik atau kedua parameter pDecryptPara atau pVerifyPara harus ditentukan.

Untuk pesan yang berhasil didekodekan atau diverifikasi, penunjuk konteks sertifikat yang diarahkan oleh ppXchgCert dan ppSignerCert diperbarui. Mereka harus dikosongkan dengan memanggil CertFreeCertificateContext. Jika fungsi gagal, fungsi diatur ke NULL.

Parameter ppXchgCert atau ppSignerCert dapat diatur ke NULL sebelum fungsi dipanggil, yang menunjukkan bahwa pemanggil tidak tertarik untuk mendapatkan sertifikat pertukaran atau konteks sertifikat penanda tangan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincrypt.h
Pustaka	Crypt32.lib
DLL	Crypt32.dll

Lihat juga

CryptDecryptMessage

CryptVerifyMessageHash

CryptVerifyMessageSignature

Fungsi Pesan Yang Disederhanakan