Fungsi CryptMsgOpenToEncode (wincrypt.h)

Artikel
08/27/2023

Fungsi CryptMsgOpenToEncode membuka pesan kriptografi untuk pengodean dan mengembalikan handel pesan yang dibuka. Pesan tetap terbuka sampai CryptMsgClose dipanggil.

Sintaks

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           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

DwFlags yang ditentukan saat ini ditampilkan dalam tabel berikut.

Nilai	Makna
CMSG_BARE_CONTENT_FLAG	Output yang dialirkan tidak akan memiliki pembungkus ContentInfo luar (seperti yang didefinisikan oleh PKCS #7). Ini membuatnya cocok untuk dialirkan ke dalam pesan penutup.
CMSG_DETACHED_FLAG	Ada data yang dilepaskan yang disediakan untuk panggilan berikutnya ke CryptMsgUpdate.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Atribut terautentikasi dipaksa untuk disertakan dalam SignerInfo (seperti yang didefinisikan oleh PKCS #7) dalam kasus di mana mereka tidak akan diperlukan.
CMSG_CONTENTS_OCTETS_FLAG	Digunakan saat menghitung ukuran pesan yang telah dikodekan dengan menggunakan Distinguished Encoding Rules (DER) dan yang disarangkan di dalam pesan yang diselimuti. Ini sangat berguna saat melakukan streaming.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Saat diatur, konten non-data type-inner dienkapsulasi dalam STRING OCTET. Berlaku untuk pesan yang ditandatangani dan diselimuti.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Jika diatur, hCryptProv yang diteruskan ke fungsi ini dirilis pada CryptMsgUpdate akhir. Handel tidak dirilis jika fungsi gagal. CatatanhCryptProvdari penerima amplop tidak dirilis.

[in] dwMsgType

Menunjukkan jenis pesan. Ini harus menjadi salah satu nilai berikut.

Nilai	Makna
CMSG_DATA	Nilai ini tidak digunakan.
CMSG_SIGNED	Parameter pvMsgEncodeInfo adalah alamat struktur CMSG_SIGNED_ENCODE_INFO yang berisi informasi pengodean.
CMSG_ENVELOPED	Parameter pvMsgEncodeInfo adalah alamat struktur CMSG_ENVELOPED_ENCODE_INFO yang berisi informasi pengodean.
CMSG_SIGNED_AND_ENVELOPED	Nilai ini saat ini tidak diimplementasikan.
CMSG_HASHED	Parameter pvMsgEncodeInfo adalah alamat struktur CMSG_HASHED_ENCODE_INFO yang berisi informasi pengodean.

[in] pvMsgEncodeInfo

Alamat struktur yang berisi informasi pengodean. Jenis data tergantung pada nilai parameter dwMsgType . Untuk detailnya, lihat dwMsgType.

[in, optional] pszInnerContentObjID

Jika CryptMsgCalculateEncodedLength dipanggil dan data untuk CryptMsgUpdate telah dikodekan pesan, pengidentifikasi objek (OID) yang sesuai diteruskan dalam pszInnerContentObjID. Jika pszInnerContentObjID adalah NULL, maka jenis konten dalam diasumsikan belum dikodekan sebelumnya dan karenanya dikodekan sebagai string oktet dan diberi jenis CMSG_DATA.

Catatan Saat streaming sedang digunakan, pszInnerContentObjID harus NULL atau szOID_RSA_data.

OID algoritma berikut umumnya digunakan. Pengguna dapat menentukan penggunaan konten dalam baru dengan memastikan bahwa pengirim dan penerima pesan menyetujui semantik yang terkait dengan OID.

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

Saat streaming sedang digunakan, parameter ini adalah alamat struktur CMSG_STREAM_INFO . Fungsi panggilan balik yang ditentukan oleh anggota pfnStreamOutput dari struktur CMSG_STREAM_INFO dipanggil ketika CryptMsgUpdate dijalankan. Panggilan balik diteruskan byte yang dikodekan yang dihasilkan dari pengodean. Untuk informasi selengkapnya tentang cara menggunakan panggilan balik, lihat CMSG_STREAM_INFO.

Catatan Ketika streaming sedang digunakan, aplikasi tidak boleh merilis handel data apa pun yang diteruskan dalam parameter pvMsgEncodeInfo , seperti handel penyedia di anggota hCryptProv dari struktur CMSG_SIGNER_ENCODE_INFO , sampai setelah handel pesan yang dikembalikan oleh fungsi ini ditutup dengan menggunakan fungsi CryptMsgClose .

Ketika streaming tidak digunakan, parameter ini diatur ke NULL.

Streaming tidak digunakan dengan jenis pesan CMSG_HASHED . Saat berhadapan dengan data yang di-hash, parameter ini harus diatur ke NULL.

Pertimbangkan kasus pesan yang ditandatangani yang diapit dalam pesan yang diselimuti. Output yang dikodekan dari pengodean streaming umpan pesan yang ditandatangani ke pengodean streaming lain dari pesan yang diselimuti. Panggilan balik untuk pengodean streaming memanggil CryptMsgUpdate untuk mengodekan pesan yang diselimuti. Panggilan balik untuk pesan yang diselimuti menerima byte yang dikodekan dari pesan bertanda tangan berlapis.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan handel ke pesan yang dibuka. Handel ini harus ditutup ketika tidak lagi diperlukan dengan meneruskannya ke fungsi CryptMsgClose .

Jika fungsi ini gagal, NULL dikembalikan.

Untuk mengambil informasi kesalahan yang diperluas, gunakan fungsi GetLastError .

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

Menampilkan kode	Deskripsi
CRYPT_E_INVALID_MSG_TYPE	Tipe pesan tidak valid.
CRYPT_E_OID_FORMAT	OID diformat dengan buruk.
CRYPT_E_UNKNOWN_ALGO	Algoritma kriptografi tidak diketahui.
E_INVALIDARG	Satu atau beberapa argumen tidak valid.
E_OUTOFMEMORY	Memori tidak cukup.

Selain itu, jika dwMsgType CMSG_SIGNED, kesalahan dapat disebarluaskan dari CryptCreateHash.

Jika dwMsgType CMSG_ENVELOPED, kesalahan dapat disebarluaskan dari CryptGenKey, CryptImportKey, dan CryptExportKey.

Jika dwMsgType CMSG_HASHED, kesalahan dapat disebarluaskan dari CryptCreateHash.

Keterangan

Untuk fungsi yang melakukan enkripsi, kunci konten terenkripsi dibalik dari format little-endian ke format big-endian setelah CryptExportKey dipanggil secara internal. Untuk fungsi yang melakukan dekripsi, kunci konten terenkripsi dibalik dari format big-endian ke format little-endian sebelum CryptImportKey dipanggil.

CRYPT_NO_SALT ditentukan ketika kunci konten dihasilkan dan diimpor dengan CryptGenKey dan CryptImportKey.

Pesan yang dienkripsi dengan algoritma enkripsi RC2 menggunakan KP_EFFECTIVE_KEYLEN dengan CryptGetKeyParam untuk menentukan panjang kunci efektif dari kunci RC2 yang mengimpor atau mengekspor kunci.

Untuk pesan yang dienkripsi dengan algoritma enkripsi RC2, operasi pengodean dan dekode telah diperbarui untuk menangani parameter ASN RC2 untuk anggota ContentEncryptionAlgorithm dari struktur CMSG_ENVELOPED_ENCODE_INFO .

Untuk pesan yang dienkripsi dengan algoritma enkripsi RC4, DES, dan 3DES, operasi pengodean dan dekode sekarang menangani parameter string oktet ASN IV untuk anggota ContentEncryptionAlgorithm dari struktur CMSG_ENVELOPED_ENCODE_INFO .

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 Enveloped, Pesan Bertanda tangan, dan Contoh Program C: Pengodean dan Pendekodean Pesan Hash.

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