共用方式為


CertStrToNameA 函式 (wincrypt.h)

CertStrToName 函式會將以 Null 終止的 X.500 字串轉換為編碼的憑證名稱。

語法

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
);

參數

[in] dwCertEncodingType

用來編碼字串的 憑證編碼類型 。 這個函式會忽略這個值之高 WORD 中包含的訊息編碼類型標識碼。

此參數可以是下列目前定義的憑證編碼類型。

意義
X509_ASN_ENCODING
1 (0x1)
指定 X.509 憑證編碼。

[in] pszX500

要轉換之 Null 終止之 X.500 字串的指標。 此字串的格式是由 dwStrType 參數所指定。

此字串的格式應該與 CertNameToStr 函式的輸出相同。

[in] dwStrType

此參數會指定字串的類型。 此參數也會指定字串內容的其他選項。

如果未將旗標與字串類型規範結合,則字串可以包含逗號 (、) 或分號 (;) 做為相對 辨別名稱 中的分隔符, (RDN) 和加號 (+) 做為多個 RDN 值的分隔符。

支援引號 (“”) 。 引號可以使用兩組引號來包含在引號值中,例如 CN=“User ”“one”“。

以數位符號開頭 (#) 的值會被視為 ASCII 十六進位,並轉換成 CERT_RDN_OCTET_STRING。 會忽略內嵌空格符。 例如,1.2.3 = # AB CD 01 與 1.2.3=#ABCD01 相同。

忽略括住索引鍵、物件標識碼和值的空格符。

此參數可以是下列其中一個值。

意義
CERT_SIMPLE_NAME_STR
1
不支援此字串類型。
CERT_OID_NAME_STR
2
驗證是否支援字串類型。 字串可以是 (OID) 或 X.500 名稱 的物件識別碼
CERT_X500_NAME_STR
3
與CERT_OID_NAME_STR相同。 驗證是否支援字串類型。 字串可以是 (OID) 或 X.500 名稱 的物件識別碼
 

下列選項也可以與上述值結合,以指定字串的其他選項。

意義
CERT_NAME_STR_COMMA_FLAG
0x04000000
RDN 分隔符僅支援逗號 (,) 。
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
只有分號 (;) 支援為 RDN 分隔符。
CERT_NAME_STR_CRLF_FLAG
0x08000000
RDN 分隔符僅支援反斜杠 r (\r) 或反斜杠 n (\n) 。
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
加號 (+) 會忽略為分隔符,且不支援每個 RDN 的多個值。
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
不支援引號。
CERT_NAME_STR_REVERSE_FLAG
0x02000000
在編碼之前,會反轉辨別名稱中的 RDN 順序。 此旗標預設不會設定。
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
會使用 CERT_RDN_T61_STRING 編碼實值類型,而不是 CERT_RDN_UNICODE_STRING。 如果所有 Unicode 字元小於或等於0xFF,則可以使用此旗標。
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
會使用 CERT_RDN_UTF8_STRING 編碼實值類型,而不是 CERT_RDN_UNICODE_STRING
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
強制 X.500 機碼編碼為 UTF-8 (CERT_RDN_UTF8_STRING) 字串,而不是可列印的 Unicode (CERT_RDN_PRINTABLE_STRING) 字串串。 這是從 Windows Server 2003 開始的 Microsoft 證書頒發機構單位預設值。
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
防止強制使用UTF-8 (CERT_RDN_UTF8_STRING) 來編碼可列印的 Unicode (CERT_RDN_PRINTABLE_STRING) X.500 金鑰。 當設定CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG時,使用 來啟用 X.500 索引鍵編碼為 Unicode 值。
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
如果字串包含電子郵件 RDN 值,且電子郵件位址包含 ASCII 字元集外的 Unicode 字元,則電子郵件位址的主機名部分會以 Punycode 編碼。 然後,產生的電子郵件地址會編碼為 IA5String 字串串。 主機名的 Punycode 編碼是以標籤為基礎執行。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP: 不支援這個值。

[in, optional] pvReserved

保留供日後使用,且必須為 NULL

[out] pbEncoded

接收編碼結構的緩衝區指標。

這個緩衝區的大小是在 參數 中指定。

此參數可以是 NULL ,以取得記憶體配置所需的緩衝區大小。 如需詳細資訊,請參閱 擷取未知長度的數據

[in, out] pcbEncoded

在呼叫函式之前, DWORD 的指標包含 pbEncoded 參數所指向緩衝區的大小,以位元組為單位。 當函式傳回時, DWORD 會包含儲存在緩衝區中的位元元組數目。

如果 pbEncodedNULL,DWORD 會接收緩衝區所需的大小,以位元組為單位。

[out, optional] ppszError

字串指標的指標,可接收無效之輸入字串的其他錯誤資訊。

如果 pszX500 字串無效,則這個函式會更新 ppszError ,以指向無效字元序列的開頭。 如果在輸入字串中未偵測到任何錯誤, ppszError 會設定為 NULL

如果不需要此資訊,請傳遞此參數的 NULL

此參數會針對從 GetLastError 傳回的下列錯誤碼進行更新。

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

傳回值

如果成功或零,則傳回非零。

如需擴充的錯誤資訊,請呼叫 GetLastError

備註

下表包含支援的 X.500 索引鍵、其對應的物件標識符字串、來自 Wincrypt.h) 的字串標識碼 (,以及實值類型。

答案 物件識別符字串 字串標識碼 RDN 實值類型
CN 2.5.4.3 szOID_COMMON_NAME 可列印

T61

L 2.5.4.7 szOID_LOCALITY_NAME 可列印

T61

O 2.5.4.10 szOID_ORGANIZATION_NAME 可列印

T61

OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME 可列印

T61

E

電子郵件

1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME 可列印
S

ST

2.5.4.8 szOID_STATE_OR_PROVINCE_NAME 可列印

T61

STREET 2.5.4.9 szOID_STREET_ADDRESS 可列印

T61

T

標題

2.5.4.12 szOID_TITLE 可列印

T61

G

GivenName

2.5.4.42 szOID_GIVEN_NAME 可列印

T61

I

縮寫

2.5.4.43 szOID_INITIALS 可列印

T61

SN 2.5.4.4 szOID_SUR_NAME 可列印

T61

DC 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8

 

如果允許 Printable 或 T61 做為索引鍵的 RDN 值類型,如果名稱字串元件是下列字元集的成員,則會自動選取 Printable:

  • A、B、...、Z
  • a, b, ..., z
  • 0, 1, ..., 9
  • (空間) ' ( ) + , - 。 / : = ?

T61 類型會以UTF8編碼。

範例

如需使用此函式的範例,請參閱 範例 C 程式:將名稱從憑證轉換為 ASN.1 和 Back

注意

wincrypt.h 標頭會將 CertStrToName 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例

規格需求

需求
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 wincrypt.h
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

CertNameToStr

數據轉換函式

GetLastError

擷取未知長度的數據