共用方式為

CertStrToNameW 函式 （wincrypt.h）

  • 發行項

CertStrToName 函式會將以 Null 結尾 的 X.500 字串轉換成編碼的憑證名稱。

語法

BOOL CertStrToNameW(
  [in]            DWORD   dwCertEncodingType,
  [in]            LPCWSTR pszX500,
  [in]            DWORD   dwStrType,
  [in, optional]  void    *pvReserved,
  [out]           BYTE    *pbEncoded,
  [in, out]       DWORD   *pcbEncoded,
  [out, optional] LPCWSTR *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
 只有反斜杠 r （\r） 或反斜杠 n （\n） 支援為 RDN 分隔符。
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 實值類型
快遞 之 家 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

聖

 2.5.4.8 szOID_STATE_OR_PROVINCE_NAME 列印

T61
街 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
我

縮寫

 2.5.4.43 szOID_INITIALS 列印

T61
錫 2.5.4.4 szOID_SUR_NAME 列印

T61
直流 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 應用程式]
目標平臺 窗戶
標頭 wincrypt.h
連結庫 Crypt32.lib
DLL Crypt32.dll

另請參閱

CertNameToStr

資料轉換函式

GetLastError

擷取未知長度的數據