Fungsi CertNameToStrA (wincrypt.h)

  • Artikel

Fungsi CertNameToStr mengonversi nama yang dikodekan dalam struktur CERT_NAME_BLOB menjadi string karakter yang dihentikan null.

Representasi string mengikuti spesifikasi nama khusus di RFC 1779. Pengecualian untuk aturan ini tercantum di bagian Keterangan, di bawah ini.

Sintaks

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Parameter

[in] dwCertEncodingType

Jenis pengodean sertifikat yang digunakan untuk mengodekan nama. Pengidentifikasi jenis pengodean pesan, yang terkandung dalam WORD tinggi dari nilai ini, diabaikan oleh fungsi ini.

Parameter ini bisa menjadi jenis pengodean sertifikat yang saat ini ditentukan berikut.

Nilai Makna
X509_ASN_ENCODING
1 (0x1)
 Menentukan pengodean sertifikat X.509.

[in] pName

Penunjuk ke struktur CERT_NAME_BLOB yang akan dikonversi.

[in] dwStrType

Parameter ini menentukan format string output. Parameter ini juga menentukan opsi lain untuk konten string.

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai Makna
CERT_SIMPLE_NAME_STR
1
 Semua pengidentifikasi objek (OID) dibuang. CERT_RDN entri dipisahkan oleh koma diikuti dengan spasi (, ). Beberapa atribut dalam CERT_RDN dipisahkan oleh tanda plus yang diapit dalam spasi ( + ), misalnya, Microsoft, Kim Abercrombie + Programmer.
CERT_OID_NAME_STR
2
 OID disertakan dengan pemisah tanda sama dengan (=) dari nilai atributnya. CERT_RDN entri dipisahkan oleh koma diikuti dengan spasi (, ). Beberapa atribut dalam CERT_RDN dipisahkan oleh tanda plus diikuti dengan spasi (+ ).
CERT_X500_NAME_STR
3
 OID dikonversi ke nama kunci X.500 mereka; jika tidak, mereka sama dengan CERT_OID_NAME_STR. Jika OID tidak memiliki nama X.500 yang sesuai, OID digunakan dengan awalan OID.

Nilai RDN dikutip jika berisi spasi kosong di awal atau akhir atau salah satu karakter berikut:

  • Koma (,)
  • Tanda plus (+)
  • Tanda sama dengan (=)
  • Tanda inci (")
  • Garis miring terbelakang diikuti oleh huruf n (\n)
  • Kurang dari tanda (<)
  • Lebih besar dari tanda (>)
  • Tanda nomor (#)
  • Titik koma (;)
Karakter kutipan adalah tanda inci ("). Jika nilai RDN berisi tanda inci, nilai tersebut diapit dalam tanda kutip ("").
 

Opsi berikut juga dapat dikombinasikan dengan nilai di atas untuk menentukan opsi tambahan untuk string.

Nilai Makna
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Ganti koma diikuti dengan pemisah spasi (, ) dengan titik koma diikuti dengan pemisah spasi (; ) .
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Ganti koma diikuti dengan pemisah spasi (, ) dengan garis miring terbelakang diikuti dengan huruf r diikuti dengan garis miring terbelakang diikuti dengan pemisah huruf n (\r\n).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Ganti tanda plus yang diapit dalam pemisah spasi ( + ) dengan pemisah spasi tunggal.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Nonaktifkan kutipan.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 Urutan RDN dalam string nama yang dibedakan dibalik setelah pendekodean. Bendera ini tidak diatur secara default.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 Secara default, string kunci CERT_RDN_T61_STRING X.500 didekodekan sebagai UTF8. Jika pendekodean UTF8 gagal, kunci X.500 didekodekan sebagai karakter 8 bit. Gunakan CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG untuk melewati upaya awal untuk mendekode sebagai UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Jika nama yang diarahkan oleh parameter pName berisi RDN email, dan bagian nama host alamat email berisi IA5String yang dikodekan Punycode, nama tersebut dikonversi ke unicode yang setara.

Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.

[out] psz

Penunjuk ke buffer karakter yang menerima string yang dikembalikan. Ukuran buffer ini ditentukan dalam parameter csz .

[in] csz

Ukuran, dalam karakter, dari penyangga psz . Ukuran harus menyertakan karakter null yang mengakhiri.

Nilai kembali

Mengembalikan jumlah karakter yang dikonversi, termasuk karakter null yang dihentikan.

Jika psz adalah NULL atau csz adalah nol, mengembalikan ukuran string tujuan yang diperlukan.

Keterangan

Jika psz bukan NULL dan csz bukan nol, psz yang dikembalikan selalu merupakan string yang dihentikan null.

Sebaiknya jangan gunakan RDN multikomponen (misalnya, CN=James+O=Microsoft) untuk menghindari kemungkinan masalah pemesanan saat pendekodean terjadi. Sebagai gantinya, pertimbangkan untuk menggunakan RDN bernilai tunggal (misalnya, CN=James, O=Microsoft).

Representasi string mengikuti spesifikasi nama khusus di RFC 1779 kecuali untuk penyimpangan yang dijelaskan dalam daftar berikut.

  • Nama yang berisi tanda kutip diapit dalam tanda kutip ganda.
  • String kosong diapit dalam tanda kutip ganda.
  • String yang berisi spasi berturut-turut tidak diapit dalam tanda kutip.
  • Nilai Relative Distinguished Name (RDN) jenis CERT_RDN_ENCODED_BLOB atau CERT_RDN_OCTET_STRING diformat dalam heksadesimal.
  • Jika OID tidak memiliki nama X.500 yang sesuai, awalan "OID" digunakan sebelum OID.
  • Nilai RDN diapit dengan tanda kutip ganda (bukan "\") jika berisi spasi kosong di depan, spasi kosong di belakang, atau salah satu karakter berikut:
    • Koma (,)
    • Tanda plus (+)
    • Tanda sama dengan (=)
    • Tanda inci (")
    • Garis miring terbelakang (/)
    • Kurang dari tanda (<)
    • Lebih besar dari tanda (>)
    • Tanda angka (#)
    • Titik koma (;)
  • Nama kunci X.500 untuk stateOrProvinceName (2.5.4.8) OID adalah "S". Nilai ini berbeda dari nama kunci RFC 1779 X.500 ("ST").
Selain itu, nama kunci X.500 berikut tidak disebutkan dalam RFC 1779, tetapi dapat dikembalikan oleh API ini:
Kunci String pengidentifikasi objek
E 1.2.840.113549.1.9.1
T 2.5.4.12
G 2.5.4.42
I 2.5.4.43
SN 2.5.4.4
 

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 CertNameToStr 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

   
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

CertRDNValueToStr

CertStrToName

Fungsi Konversi Data