Fungsi CryptDecodeObjectEx (wincrypt.h)

  • Artikel

Fungsi CryptDecodeObjectEx mendekode struktur jenis yang ditunjukkan oleh parameter lpszStructType . CryptDecodeObjectEx menawarkan peningkatan performa yang signifikan atas CryptDecodeObject dengan mendukung alokasi memori dengan nilai CRYPT_DECODE_ALLOC_FLAG.

Sintaks

BOOL CryptDecodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const BYTE         *pbEncoded,
  [in]      DWORD              cbEncoded,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_DECODE_PARA pDecodePara,
  [out]     void               *pvStructInfo,
  [in, out] DWORD              *pcbStructInfo
);

Parameter

[in] dwCertEncodingType

Jenis pengodean yang digunakan. Selalu dapat diterima untuk menentukan jenispengodean 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
Catatan Diperlukan jenis pengodean sertifikat atau pesan. X509_ASN_ENCODING adalah defaultnya. Jika jenis tersebut ditunjukkan, jenis tersebut digunakan. Jika tidak, jika jenis PKCS7_ASN_ENCODING ditunjukkan, jenis tersebut digunakan.
 

[in] lpszStructType

Penunjuk ke pengidentifikasi objek (OID) yang menentukan jenis struktur. Jika kata urutan tinggi dari parameter lpszStructType adalah nol, kata berurutan rendah menentukan pengidentifikasi bilangan bulat untuk jenis struktur yang ditentukan. Jika tidak, parameter ini adalah penunjuk panjang ke string yang dihentikan null.

Untuk informasi selengkapnya tentang string pengidentifikasi objek, konstanta yang telah ditentukan sebelumnya, dan struktur yang sesuai, lihat Konstanta untuk CryptEncodeObject dan CryptDecodeObject.

[in] pbEncoded

Penunjuk ke data yang akan didekodekan. Struktur harus dari jenis yang ditentukan oleh lpszStructType.

[in] cbEncoded

Jumlah byte yang diacu oleh pbEncoded. Ini adalah jumlah byte yang akan didekodekan.

[in] dwFlags

Parameter ini bisa menjadi satu atau beberapa bendera berikut. Bendera dapat digabungkan dengan menggunakan operasi bitwise-OR.

Nilai Makna
CRYPT_DECODE_ALLOC_FLAG
 Fungsi decoding yang disebut mengalokasikan memori untuk struktur yang didekodekan. Penunjuk ke struktur yang dialokasikan dikembalikan dalam pvStructInfo.

Jika pDecodePara atau anggota pfnAlloc dari pDecodePara adalah NULL, maka LocalAlloc dipanggil untuk alokasi dan LocalFree harus dipanggil untuk membebaskan memori.

Jika pDecodePara dan anggota pfnAllocdari pDecodePara bukan NULL, maka fungsi yang ditunjukkan oleh pfnAlloc dipanggil untuk alokasi dan fungsi yang ditunjukkan oleh anggota pfnFreedari pDecodePara harus dipanggil untuk membebaskan memori.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
 Bendera ini berlaku untuk mengaktifkan pendekodean Punycode dari nilai string Unicode. Untuk informasi selengkapnya, lihat Keterangan.

Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Bendera ini tidak didukung.
CRYPT_DECODE_NOCOPY_FLAG
 Bendera ini dapat diatur untuk mengaktifkan pengoptimalan "tanpa salinan". Pengoptimalan ini memperbarui anggota pvStructInfo untuk mengarahkan ke konten yang berada dalam pbEncoded alih-alih membuat salinan konten dan menambahkannya ke pvStructInfo. Aplikasi panggilan perlu mengalokasikan lebih sedikit memori dan eksekusi lebih cepat karena salinan tidak dibuat. Perhatikan bahwa saat melakukan decoding "no copy", pbEncoded tidak dapat dikodekan sampai pvStructInfo dikosongkan .
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG
 Bendera ini berlaku saat mendekode X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE, atau X509_UNICODE_ANY_STRING. Secara default, CERT_RDN_T61_STRING nilai yang dikodekan awalnya didekodekan sebagai UTF8. Jika pendekodean UTF8 gagal, maka nilai didekodekan sebagai karakter delapan-bit. Jika bendera ini diatur, bendera ini melewati upaya awal untuk mendekode nilai sebagai UTF8 dan mendekode nilai sebagai karakter delapan-bit.
CRYPT_DECODE_TO_BE_SIGNED_FLAG
 Secara default, konten buffer yang ditujukkan oleh pbEncoded menyertakan konten yang ditandatangani dan tanda tangan. Jika bendera ini diatur, buffer hanya menyertakan konten "yang akan ditandatangani". Bendera ini berlaku untuk objek X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED, dan X509_KEYGEN_REQUEST_TO_BE_SIGNED.
CRYPT_DECODE_SHARE_OID_STRING_FLAG
 Ketika bendera ini diatur, string OID dialokasikan di Crypt32.dll dan dibagikan alih-alih disalin ke dalam struktur data yang dikembalikan. Bendera ini dapat diatur jika Crypt32.dll tidak dibongkar sebelum pemanggil dibongkar.
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG
 Secara default, byte tanda tangan dibalik. Jika bendera ini diatur, pembalikan byte ini dihambat.

[in] pDecodePara

Penunjuk ke struktur CRYPT_DECODE_PARA yang berisi informasi paragraf pendekodean. Jika pDecodePara diatur ke NULL, maka LocalAlloc dan LocalFree digunakan untuk mengalokasikan dan membebaskan memori. Jika pDecodePara menunjuk ke struktur CRYPT_DECODE_PARA , struktur tersebut melewati fungsi panggilan balik untuk mengalokasikan dan membebaskan memori. Fungsi panggilan balik ini mengambil alih alokasi memori default LocalAlloc dan LocalFree.

[out] pvStructInfo

Jika CRYPT_ENCODE_ALLOC_FLAG dwFlags diatur, pvStructInfo bukan penunjuk ke buffer tetapi merupakan alamat pointer ke buffer. Karena memori dialokasikan di dalam fungsi dan pointer disimpan di *pvStructInfo, pvStructInfo tidak boleh NULL.

Jika CRYPT_ENCODE_ALLOC_FLAG tidak diatur, pvStructInfo adalah penunjuk ke buffer yang menerima struktur yang didekodekan. Ketika buffer yang ditentukan tidak cukup besar untuk menerima struktur yang didekodekan, fungsi mengatur kode ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan, dalam byte, dalam variabel yang ditunjukkan oleh pcbStructInfo.

Parameter ini dapat berupa NULL untuk mengambil ukuran informasi ini untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.

[in, out] pcbStructInfo

Penunjuk ke variabel DWORD yang berisi ukuran, dalam byte, dari buffer yang diacu oleh parameter pvStructInfo . Saat fungsi kembali, nilai DWORD berisi jumlah byte yang disimpan dalam buffer. Ukuran yang terkandung dalam variabel yang diacu oleh pcbStructInfo dapat menunjukkan ukuran yang lebih besar dari struktur yang didekodekan karena struktur yang didekodekan dapat mencakup pointer ke data tambahan. Ukuran ini adalah jumlah ukuran yang diperlukan oleh struktur yang didekodekan dan data tambahan.

Ketika CRYPT_DECODE_ALLOC_FLAG diatur, nilai awal *pcbStructInfo tidak digunakan oleh fungsi, dan saat kembali, *pcbStructInfo berisi jumlah byte yang dialokasikan untuk pvStructInfo.

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 cocok dalam buffer.) Pada output, variabel yang diacu oleh parameter ini diperbarui untuk mencerminkan ukuran aktual data yang disalin ke buffer.
 

Nilai kembali

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

Jika fungsi gagal, fungsi akan mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Tabel berikut ini memperlihatkan beberapa kemungkinan kode kesalahan.

Menampilkan kode Deskripsi
CRYPT_E_BAD_ENCODE
 Terjadi kesalahan saat mendekode.
ERROR_FILE_NOT_FOUND
 Fungsi decoding tidak dapat ditemukan untuk dwCertEncodingType dan lpszStructType yang ditentukan.
ERROR_MORE_DATA
 Jika buffer yang ditentukan oleh parameter pvStructInfo 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 pcbStructInfo.
 

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

Keterangan

Saat mengodekan objek kriptografi menggunakan fungsi CryptEncodeObjectEx pilihan, karakter NULL yang mengakhiri disertakan. Saat mendekode, menggunakan fungsi CryptDecodeObjectEx pilihan, karakter NULL yang mengakhiri tidak dipertahankan.

Setiap konstanta dalam daftar di bawah ini memiliki jenis struktur terkait yang diacu oleh parameter pvStructInfo . Struktur yang menunjuk ke, secara langsung atau tidak langsung, memiliki referensi ke struktur CERT_ALT_NAME_ENTRY .

  • X509_ALTERNATE_NAME
  • szOID_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_INFO_ACCESS
  • X509_AUTHORITY_KEY_ID2
  • szOID_AUTHORITY_KEY_IDENTIFIER2
  • szOID_CRL_DIST_POINTS
  • X509_CRL_DIST_POINTS
  • szOID_CROSS_CERT_DIST_POINTS
  • X509_CROSS_CERT_DIST_POINTS
  • szOID_ISSUER_ALT_NAME
  • szOID_ISSUER_ALT_NAME2
  • szOID_ISSUING_DIST_POINT
  • X509_ISSUING_DIST_POINT
  • X509_NAME_CONSTRAINTS
  • szOID_NAME_CONSTRAINTS
  • szOID_NEXT_UPDATE_LOCATION
  • OCSP_REQUEST
  • zOID_SUBJECT_ALT_NAME
  • szOID_SUBJECT_ALT_NAME2
Bendera CRYPT_DECODE_ENABLE_PUNYCODE_FLAG , bersama dengan nilai anggota dwAltNameChoice dari struktur CERT_ALT_NAME_ENTRY , menentukan cara string dikodekan.
dwAltNameChoice Efek
CERT_ALT_NAME_DNS_NAME Jika nama host berisi string IA5String yang dikodekan Punycode, itu dikonversi ke Unicode yang setara.
CERT_ALT_NAME_RFC822_NAME Jika bagian nama host dari alamat email berisi string IA5String yang dikodekan Punycode, itu dikonversi ke unicode yang setara.
CERT_ALT_NAME_URL URI didekodekan. Jika nama host server URI berisi string IA5String yang dikodekan Punycode, string nama host didekodekan ke Unicode yang setara.
 

Setiap konstanta dalam daftar di bawah ini memiliki jenis struktur terkait yang diacu oleh parameter pvStructInfo . Struktur yang diarahkan ke, secara langsung atau tidak langsung, memiliki referensi ke struktur CERT_HASHED_URL .

  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
Saat mendekode nilai struktur CERT_HASHED_URL , URI didekodekan. Jika nama host berisi nama host yang dikodekan Punycode, nama tersebut akan dikonversi ke unicode yang setara.

Setiap konstanta X509_UNICODE_NAME dalam daftar di bawah ini memiliki jenis struktur terkait yang diacu oleh parameter pvStructInfo .

  • X509_UNICODE_NAME
Jika anggota pszObjId dari struktur CERT_RDN_ATTR diatur ke szOID_RSA_emailAddr dan alamat email di anggota Nilai berisi string yang dikodekan Punycode, maka akan dikonversi ke ekuivalen Unicode.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Pengodean dan Pendekodean ASN.1.

Persyaratan

   
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

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

Fungsi Pengodean dan Pendekodean Objek