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 中包含的訊息編碼類型標識碼。
此參數可以是下列目前定義的憑證編碼類型。
值 | 意義 |
---|---|
|
指定 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 相同。
忽略括住索引鍵、物件標識碼和值的空格符。
此參數可以是下列其中一個值。
值 | 意義 |
---|---|
|
不支援此字串類型。 |
|
驗證是否支援字串類型。 字串可以是 (OID) 或 X.500 名稱 的物件識別碼 。 |
|
與CERT_OID_NAME_STR相同。 驗證是否支援字串類型。 字串可以是 (OID) 或 X.500 名稱 的物件識別碼 。 |
下列選項也可以與上述值結合,以指定字串的其他選項。
值 | 意義 |
---|---|
|
RDN 分隔符僅支援逗號 (,) 。 |
|
只有分號 (;) 支援為 RDN 分隔符。 |
|
RDN 分隔符僅支援反斜杠 r (\r) 或反斜杠 n (\n) 。 |
|
加號 (+) 會忽略為分隔符,且不支援每個 RDN 的多個值。 |
|
不支援引號。 |
|
在編碼之前,會反轉辨別名稱中的 RDN 順序。 此旗標預設不會設定。 |
|
會使用 CERT_RDN_T61_STRING 編碼實值類型,而不是 CERT_RDN_UNICODE_STRING。 如果所有 Unicode 字元小於或等於0xFF,則可以使用此旗標。 |
|
會使用 CERT_RDN_UTF8_STRING 編碼實值類型,而不是 CERT_RDN_UNICODE_STRING。 |
|
強制 X.500 機碼編碼為 UTF-8 (CERT_RDN_UTF8_STRING) 字串,而不是可列印的 Unicode (CERT_RDN_PRINTABLE_STRING) 字串串。 這是從 Windows Server 2003 開始的 Microsoft 證書頒發機構單位預設值。 |
|
防止強制使用UTF-8 (CERT_RDN_UTF8_STRING) 來編碼可列印的 Unicode (CERT_RDN_PRINTABLE_STRING) X.500 金鑰。 當設定CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG時,使用 來啟用 X.500 索引鍵編碼為 Unicode 值。 |
|
如果字串包含電子郵件 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 |