CertNameToStrA 函式 (wincrypt.h)

  • 發行項

CertNameToStr函式會將CERT_NAME_BLOB結構中的編碼名稱轉換為以 Null 結尾的字元字串。

字串表示遵循 RFC 1779中的辨別名稱規格。 下列一節會列出此規則的例外狀況。

語法

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

參數

[in] dwCertEncodingType

用來編碼名稱的 憑證編碼類型 。 此函式會忽略這個值高WORD中包含的訊息編碼類型識別碼。

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

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

[in] pName

要轉換 之CERT_NAME_BLOB 結構的指標。

[in] dwStrType

此參數會指定輸出字串的格式。 此參數也會指定字串內容的其他選項。

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

值 意義
CERT_SIMPLE_NAME_STR
1
 捨棄所有 物件識別碼 (OID) 。 CERT_RDN 專案會以逗號分隔，後面接著空格 (，) 。 CERT_RDN中的多個屬性會以空格括住的加號分隔， ( + ) ，例如 Microsoft、Kim Abercrombie + 程式設計人員。
CERT_OID_NAME_STR
2
 OID 隨附于等號 (= 從其屬性值) 分隔符號。 CERT_RDN 專案會以逗號分隔，後面接著空格 (，) 。 CERT_RDN中的多個屬性會以加號分隔，後面接著空格 (+ ) 。
CERT_X500_NAME_STR
3
 OID 會轉換成其 X.500 索引鍵名稱;否則，它們與 CERT_OID_NAME_STR相同。 如果 OID 沒有對應的 X.500 名稱，OID 會搭配 OID 前置詞使用。

如果 RDN 值包含開頭或尾端空白字元或下列其中一個字元，則會加上引號：

  • 逗號 (,)
  • 加號 (+)
  • 等號 (=)
  • 英吋標記 (「)
  • 反斜線後面接著字母 n (\n)
  • 小於符號 () <
  • 大於符號 (>)
  • 數位記號 (#)
  • 分號 (;)
引號字元是英吋標記 (「) 。 如果 RDN 值包含英吋標記，則會以引號括住 (「」) 。
 

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

值 意義
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 以分號取代後面加上空格 ( 的逗號，) 分隔符號後面接著空格 (;) 分隔符號。
CERT_NAME_STR_CRLF_FLAG
0x08000000
 將後面接著空格 ( 的逗號取代 ) 為反斜線，並將分隔符號取代為反斜線，後面接著反斜線，後面接著字母 n (\r\n) 分隔符號。
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 以單一空格分隔符號取代以空格括住的加號 ( + ) 分隔符號。
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 停用引號。
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 辨別名稱字串中的 RDN 順序會在解碼之後反轉。 預設不會設定此旗標。
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 根據預設，CERT_RDN_T61_STRING X.500 金鑰字串會解碼為 UTF8。 如果 UTF8 解碼失敗，X.500 索引鍵會解碼為 8 位字元。 使用CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG略過將初始嘗試解碼為 UTF8。
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 如果 pName 參數所指向的名稱包含電子郵件 RDN，而電子郵件地址的主機名稱部分包含 Punycode 編碼 的 IA5String，則名稱會轉換成 Unicode 對等專案。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援此值。

[out] psz

接收傳回字串之字元緩衝區的指標。 這個緩衝區的大小是在 csz 參數中指定。

[in] csz

psz緩衝區的大小，以字元為單位。 大小必須包含終止 Null 字元。

傳回值

傳回已轉換的字元數，包括終止的 Null 字元。

如果 psz 為 Null 或 csz 為零，則傳回目的地字串的必要大小。

備註

如果 psz 不是 Null ， 而 csz 不是零，則傳回的 psz 一律是 Null 終止的字串。

建議您不要使用多元件 RDN (，例如 CN=James+O=Microsoft) ，以避免解碼發生時可能發生的排序問題。 相反地，請考慮使用單一值 RDN (，例如 CN=James、O=Microsoft) 。

字串標記法遵循 RFC 1779 中的辨別名稱規格，但下列清單所述的偏差除外。

  • 包含引號的名稱會以雙引號括住。
  • 空字串會以雙引號括住。
  • 包含連續空格的字串不會以引號括住。
  • CERT_RDN_ENCODED_BLOB或CERT_RDN_OCTET_STRING類型的相對辨別名稱 (RDN) 值會以十六進位格式格式化。
  • 如果 OID 沒有對應的 X.500 名稱，則會在 OID 之前使用 「OID」 前置詞。
  • 如果 RDN 值包含前置空白字元、尾端空白字元或下列其中一個字元，則以雙引號括住 (，而不是 「\」) ：
    • 逗號 (,)
    • 加號 (+)
    • 等號 (=)
    • 英吋標記 (「)
    • 反斜線 (/)
    • 小於符號 () <
    • 大於符號 (>)
    • 數位記號 (#)
    • 分號 (;)
  • stateOrProvinceName (2.5.4.8) OID 的 X.500 機碼名稱為 「S」。 此值與 RFC 1779 X.500 機碼名稱 (「ST」) 不同。
此外，RFC 1779 中未提及下列 X.500 金鑰名稱，但此 API 可能會傳回：
答案 物件識別碼字串
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
 

範例

如需使用此函式的範例，請參閱

範例 C 程式：將名稱從憑證轉換為 ASN.1 和 Back。

注意

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

規格需求

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

另請參閱

CertRDNValueToStr

CertStrToName

資料轉換函式