Fungsi CertStrToNameA (wincrypt.h)
Fungsi CertStrToName mengonversi string X.500 yang dihentikan null menjadi nama sertifikat yang dikodekan.
Sintaks
BOOL CertStrToNameA(
[in] DWORD dwCertEncodingType,
[in] LPCSTR pszX500,
[in] DWORD dwStrType,
[in, optional] void *pvReserved,
[out] BYTE *pbEncoded,
[in, out] DWORD *pcbEncoded,
[out, optional] LPCSTR *ppszError
);
Parameter
[in] dwCertEncodingType
Jenis pengodean sertifikat yang digunakan untuk mengodekan string. Pengidentifikasi jenis pengodean pesan, yang terkandung dalam WORD tinggi dari nilai ini, diabaikan oleh fungsi ini.
Parameter ini dapat menjadi jenis pengodean sertifikat yang saat ini ditentukan berikut.
| Nilai | Makna |
|---|---|
|
Menentukan pengodean sertifikat X.509 . |
[in] pszX500
Penunjuk ke string X.500 yang dihentikan null untuk dikonversi. Format string ini ditentukan oleh parameter dwStrType .
String ini diharapkan diformat sama dengan output dari fungsi CertNameToStr .
[in] dwStrType
Parameter ini menentukan jenis string. Parameter ini juga menentukan opsi lain untuk konten string.
Jika tidak ada bendera yang dikombinasikan dengan penentu jenis string, string dapat berisi koma (,) atau titik koma (;) sebagai pemisah dalam nama khusus relatif (RDN) dan tanda plus (+) sebagai pemisah dalam beberapa nilai RDN.
Tanda kutip ("") didukung. Kutipan dapat disertakan dalam nilai yang dikutip dengan menggunakan dua set tanda kutip, misalnya, CN="Pengguna ""satu""".
Nilai yang dimulai dengan tanda angka (#) diperlakukan sebagai heksadesimal ASCII dan dikonversi menjadi CERT_RDN_OCTET_STRING. Ruang putih yang disematkan diabaikan. Misalnya, 1.2.3 = # AB CD 01 sama dengan 1.2.3=#ABCD01.
Spasi kosong yang mengelilingi kunci, pengidentifikasi objek, dan nilai diabaikan.
Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Jenis string ini tidak didukung. |
|
Memvalidasi bahwa jenis string didukung. String dapat berupa pengidentifikasi objek (OID) atau nama X.500. |
|
Identik dengan CERT_OID_NAME_STR. Memvalidasi bahwa jenis string didukung. String dapat berupa pengidentifikasi objek (OID) atau nama X.500. |
Opsi berikut juga dapat dikombinasikan dengan nilai di atas untuk menentukan opsi tambahan untuk string.
| Nilai | Makna |
|---|---|
|
Hanya koma (,) yang didukung sebagai pemisah RDN. |
|
Hanya titik koma (;) yang didukung sebagai pemisah RDN. |
|
Hanya r garis miring terbalik (\r) atau garis miring terbalik n (\n) yang didukung sebagai pemisah RDN. |
|
Tanda plus (+) diabaikan sebagai pemisah, dan beberapa nilai per RDN tidak didukung. |
|
Kutipan tidak didukung. |
|
Urutan RDN dalam nama yang dibedakan dibalik sebelum pengodean. Bendera ini tidak diatur secara default. |
|
Jenis nilai yang dikodekan CERT_RDN_T61_STRING digunakan alih-alih CERT_RDN_UNICODE_STRING. Bendera ini dapat digunakan jika semua karakter Unicode kurang dari atau sama dengan 0xFF. |
|
Jenis nilai yang dikodekan CERT_RDN_UTF8_STRING digunakan alih-alih CERT_RDN_UNICODE_STRING. |
|
Memaksa kunci X.500 dikodekan sebagai string UTF-8 (CERT_RDN_UTF8_STRING) daripada sebagai string Unicode (CERT_RDN_PRINTABLE_STRING) yang dapat dicetak. Ini adalah nilai default untuk otoritas sertifikasi Microsoft yang dimulai dengan Windows Server 2003. |
|
Mencegah memaksa kunci Unicode (CERT_RDN_PRINTABLE_STRING) X.500 yang dapat dicetak untuk dikodekan dengan menggunakan UTF-8 (CERT_RDN_UTF8_STRING). Gunakan untuk mengaktifkan pengodean kunci X.500 sebagai nilai Unicode saat CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG diatur. |
|
Jika string berisi nilai RDN email, dan 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 . Pengodean Punycode dari nama host dilakukan berdasarkan label demi label.
Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
[in, optional] pvReserved
Dicadangkan untuk penggunaan di masa mendatang dan harus NULL.
[out] pbEncoded
Penunjuk ke buffer yang menerima struktur yang dikodekan.
Ukuran buffer ini ditentukan dalam parameter pcbEncoded .
Parameter ini dapat berupa NULL untuk mendapatkan ukuran buffer yang diperlukan untuk tujuan alokasi memori. Untuk informasi selengkapnya, lihat Mengambil Data Dengan Panjang Tidak Diketahui.
[in, out] pcbEncoded
Penunjuk ke DWORD yang, sebelum memanggil fungsi, berisi ukuran, dalam byte, dari buffer yang diacu oleh parameter pbEncoded . Saat fungsi kembali, DWORD berisi jumlah byte yang disimpan dalam buffer.
Jika pbEncodedadalah NULL, DWORD menerima ukuran, dalam byte, yang diperlukan untuk buffer.
[out, optional] ppszError
Penunjuk ke penunjuk string yang menerima informasi kesalahan tambahan tentang string input yang tidak valid.
Jika string pszX500 tidak valid, ppszError diperbarui oleh fungsi ini untuk menunjuk ke awal urutan karakter yang tidak valid. Jika tidak ada kesalahan yang terdeteksi dalam string input, ppszError diatur ke NULL.
Jika informasi ini tidak diperlukan, teruskan NULL untuk parameter ini.
Parameter ini diperbarui untuk kode kesalahan berikut yang dikembalikan dari GetLastError.
CRYPT_E_INVALID_X500_STRING
CRYPT_E_INVALID_NUMERIC_STRING
CRYPT_E_INVALID_PRINTABLE_STRING
CRYPT_E_INVALID_IA5_STRING
Mengembalikan nilai
Mengembalikan bukan nol jika berhasil atau nol sebaliknya.
Untuk informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Tabel berikut berisi kunci X.500 yang didukung, string pengidentifikasi objek, pengidentifikasi string yang sesuai (dari Wincrypt.h), dan jenis nilai.
| Kunci | String pengidentifikasi objek | Pengidentifikasi string | Jenis nilai RDN |
|---|---|---|---|
| CN | 2.5.4.3 | szOID_COMMON_NAME |
Dicetak T61 |
| L | 2.5.4.7 | szOID_LOCALITY_NAME |
Dicetak T61 |
| O | 2.5.4.10 | szOID_ORGANIZATION_NAME |
Dicetak T61 |
| OU | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
Dicetak T61 |
|
E |
1.2.840.113549.1.9.1 | szOID_RSA_emailAddr | IA5 |
| C | 2.5.4.6 | szOID_COUNTRY_NAME | Dicetak |
|
S ST |
2.5.4.8 | szOID_STATE_OR_PROVINCE_NAME |
Dicetak T61 |
| STREET | 2.5.4.9 | szOID_STREET_ADDRESS |
Dicetak T61 |
|
T Judul |
2.5.4.12 | szOID_TITLE |
Dicetak T61 |
|
G GivenName |
2.5.4.42 | szOID_GIVEN_NAME |
Dicetak T61 |
|
I Initials |
2.5.4.43 | szOID_INITIALS |
Dicetak T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
Dicetak T61 |
| DC | 0.9.2342.19200300.100.1.25 | szOID_DOMAIN_COMPONENT |
IA5 UTF8 |
Jika Dapat dicetak atau T61 diizinkan sebagai jenis nilai RDN untuk kunci, Cetak dipilih secara otomatis jika komponen string nama adalah anggota dari kumpulan karakter berikut:
- A, B, ..., Z
- a, b, ..., z
- 0, 1, ..., 9
- (spasi) ' ( ) + , - . / : = ?
Jenis T61 dikodekan UTF8.
Contoh
Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Mengonversi Nama dari Sertifikat ke ASN.1 dan Kembali.
Catatan
Header wincrypt.h mendefinisikan CertStrToName sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
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