Fungsi CryptEncodeObjectEx (wincrypt.h)
Fungsi CryptEncodeObjectEx mengodekan struktur jenis yang ditunjukkan oleh nilai parameter lpszStructType . Fungsi ini menawarkan peningkatan performa yang signifikan atas CryptEncodeObject dengan mendukung alokasi memori dengan nilai CRYPT_ENCODE_ALLOC_FLAG .
Sintaks
BOOL CryptEncodeObjectEx(
[in] DWORD dwCertEncodingType,
[in] LPCSTR lpszStructType,
[in] const void *pvStructInfo,
[in] DWORD dwFlags,
[in] PCRYPT_ENCODE_PARA pEncodePara,
[out] void *pvEncoded,
[in, out] DWORD *pcbEncoded
);
Parameter
[in] dwCertEncodingType
Jenis pengodean sertifikat dan jenis pengodean pesan yang digunakan untuk mengodekan objek. Parameter ini bisa menjadi kombinasi dari satu atau beberapa nilai berikut.
| Nilai | Makna |
|---|---|
|
Menentukan pengodean pesan PKCS 7. |
|
Menentukan pengodean sertifikat X.509. |
[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 ke string yang dihentikan null yang berisi representasi string OID.
Untuk informasi selengkapnya tentang string pengidentifikasi objek, konstanta yang telah ditentukan sebelumnya dan struktur yang sesuai, lihat Konstanta untuk CryptEncodeObject dan CryptDecodeObject.
[in] pvStructInfo
Penunjuk ke struktur yang akan dikodekan. Struktur harus dari jenis yang ditentukan oleh lpszStructType.
[in] dwFlags
Menentukan opsi untuk pengodean. Parameter ini bisa nol atau kombinasi dari satu atau beberapa nilai berikut.
[in] pEncodePara
Penunjuk ke struktur CRYPT_ENCODE_PARA yang berisi informasi pengodean. Parameter ini bisa NULL.
Jika pEncodePara atau anggota pfnAlloc dari pEncodePara adalah NULL, maka LocalAlloc digunakan untuk alokasi dan LocalFree harus dipanggil untuk membebaskan memori.
Jika pEncodePara dan anggota pfnAlloc dari pEncodePara bukan NULL, maka fungsi yang ditunjukkan oleh anggota pfnAlloc dari struktur CRYPT_ENCODE_PARA yang ditunjukkan oleh pEncodePara dipanggil untuk alokasi. Fungsi yang ditujukkan oleh anggota pfnFree dari pEncodePara harus dipanggil untuk membebaskan memori.
[out] pvEncoded
Penunjuk ke buffer untuk menerima struktur yang dikodekan. Ukuran buffer ini ditentukan dalam parameter pcbEncoded . 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 pcbEncoded.
Parameter ini dapat berupa NULL untuk mengambil ukuran buffer untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.
Jika dwFlags berisi bendera CRYPT_ENCODE_ALLOC_FLAG , pvEncoded bukan penunjuk ke buffer tetapi merupakan alamat pointer ke buffer. Karena memori dialokasikan di dalam fungsi dan penunjuk disimpan dalam pvEncoded, pvEncoded tidak boleh NULL.
[in, out] pcbEncoded
Penunjuk ke variabel DWORD yang berisi ukuran, dalam byte, dari buffer yang diacu oleh parameter pvEncoded . Ketika fungsi kembali, variabel yang diacu oleh parameter pcbEncoded berisi jumlah byte yang dialokasikan dan dikodekan yang disimpan dalam buffer.
Ketika dwFlags berisi bendera CRYPT_ENCODE_ALLOC_FLAG , pcbEncoded adalah alamat penunjuk ke nilai DWORD yang diperbarui.
Mengembalikan nilai
Mengembalikan bukan nol jika berhasil atau nol sebaliknya.
Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Tabel berikut menunjukkan beberapa kemungkinan kode kesalahan yang dapat dikembalikan dari GetLastError saat CryptEncodeObjectEx gagal.
| Menampilkan kode | Deskripsi |
|---|---|
|
Terjadi kesalahan saat pengodean. |
|
Fungsi pengodean tidak dapat ditemukan untuk dwCertEncodingType dan lpszStructType yang ditentukan. |
|
Jika buffer yang ditentukan oleh parameter pvEncoded 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 pcbEncoded. |
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.
CryptEncodeObjectEx pertama-tama mencari fungsi pengodean yang diperluas yang dapat diinstal. Jika tidak ada fungsi pengodean yang diperluas yang ditemukan, fungsi lama yang tidak ada, dan dapat diinstal berada.
Ketika pengodean IA5String langsung objek tidak dimungkinkan, Anda dapat menentukan pengodean Punycode dengan mengatur parameter dwFlag ke nilai CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG . Mengatur bendera CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG memiliki efek yang berbeda berdasarkan jenis struktur yang dikodekan seperti yang ditentukan oleh nilai parameter lpszStructType .
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
- szOID_NAME_CONSTRAINTS
- X509_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 karakter Unicode di luar kumpulan karakter ASCII, nama host pertama kali dikodekan dalam Punycode dan kemudian dikodekan sebagai string IA5String . |
| CERT_ALT_NAME_RFC822_NAME | Jika bagian nama host alamat email berisi karakter Unicode di luar kumpulan karakter ASCII, bagian nama host alamat email dikodekan dalam Punycode. Alamat email yang dihasilkan kemudian dikodekan sebagai string IA5String . |
| CERT_ALT_NAME_URL | Jika nama host server URI berisi karakter Unicode di luar kumpulan karakter ASCII, maka bagian nama host URI dikodekan dalam Punycode. Kemudian URI yang dihasilkan lolos, dan URL kemudian dikodekan sebagai string IA5String . |
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_HASHED_URL .
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
- szOID_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
Setiap konstanta X509_UNICODE_NAME dalam daftar di bawah ini memiliki jenis struktur terkait yang diacu oleh parameter pvStructInfo .
- X509_UNICODE_NAME
Dalam semua kasus, pengodean Punycode dari nama host dilakukan berdasarkan label-demi-label.
Contoh
Contoh berikut menunjukkan inisialisasi dan pengodean struktur X509_NAME menggunakan CryptEncodeObjectEx. Untuk contoh yang menyertakan konteks lengkap untuk contoh ini, lihat Contoh Program C: Pengodean dan Pendekodean ASN.1.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")
#define MY_TYPE (X509_ASN_ENCODING)
void main()
{
//#define moved
//--------------------------------------------------------------------
// Declare and initialize local variables.
char *Cert_Sub_Name ="Test User Name";
//--------------------------------------------------------------------
// Initialize a single RDN structure.
CERT_RDN_ATTR rgNameAttr =
{
"2.5.4.3", // The OID
CERT_RDN_PRINTABLE_STRING, // Type of string
(DWORD)strlen(Cert_Sub_Name)+1, // String length including
// the terminating null character
(BYTE *)Cert_Sub_Name // Pointer to the string
};
//--------------------------------------------------------------------
// Declare and initialize a structure to include
// the array of RDN structures.
CERT_RDN rgRDN[] =
{
1, // The number of elements in the array
&rgNameAttr // Pointer to the array
};
//--------------------------------------------------------------------
// Declare and initialize a CERT_NAME_INFO
// structure that includes a CERT_RND.
CERT_NAME_INFO CertName =
{
1, // The number of elements in the CERT_RND's array
rgRDN
};
//--------------------------------------------------------------------
// Declare additional variables.
DWORD cbEncoded; // Variable to hold the
// length of the encoded string
BYTE *pbEncoded; // Variable to hold a pointer to the
// encoded buffer
//--------------------------------------------------------------------
// Call CrypteEncodeObjectEx to get
// length to allocate for pbEncoded.
if( CryptEncodeObjectEx(
MY_TYPE, // The encoding/decoding type
X509_NAME,
&CertName,
0,
NULL,
NULL,
&cbEncoded)) // Fill in the length needed for
// the encoded buffer.
{
printf("The number of bytes needed is %d \n",cbEncoded);
}
else
{
printf("The first call to the function failed.\n");
exit(1);
}
if( pbEncoded = (BYTE*)malloc(cbEncoded))
{
printf("Memory for pvEncoded has been allocated.\n");
}
else
{
printf("Memory allocation failed.\n");
exit(1);
}
if(CryptEncodeObjectEx(
MY_TYPE,
X509_NAME,
&CertName,
0,
NULL,
pbEncoded,
&cbEncoded))
{
printf("The structure has been encoded.\n");
}
else
{
printf("Encoding failed.");
exit(1);
}
// Free allocated memory when done.
// ...
if(pbEncoded)
{
free(pbEncoded);
}
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
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk