Fungsi CryptDecodeObjectEx (wincrypt.h)
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
[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 |
---|---|
|
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. |
|
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. |
|
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 . |
|
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. |
|
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. |
|
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. |
|
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.
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 |
---|---|
|
Terjadi kesalahan saat mendekode. |
|
Fungsi decoding tidak dapat ditemukan untuk dwCertEncodingType dan lpszStructType yang ditentukan. |
|
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
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
Setiap konstanta X509_UNICODE_NAME dalam daftar di bawah ini memiliki jenis struktur terkait yang diacu oleh parameter pvStructInfo .
- X509_UNICODE_NAME
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 |