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 會包含儲存在緩衝區中的位元元組數目。

如果 pbEncoded 為 NULL，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

擷取未知長度的數據