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 値の区切り記号としてプラス記号 (+) を含めることができます。

引用符 ("") がサポートされています。 引用符は、引用符の 2 つのセット (CN="User ""one"" など) を使用して、引用符で囲まれた値に含めることができます。

数値記号 (#) で始まる値は ASCII 16 進数として扱われ、 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_UNICODE_STRINGの代わりに、CERT_RDN_T61_STRINGエンコードされた値型が使用されます。 このフラグは、すべての Unicode 文字が0xFF以下の場合に使用できます。
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
 CERT_RDN_UNICODE_STRINGの代わりに、CERT_RDN_UTF8_STRINGエンコードされた値型が使用されます。
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
 X.500 キーを、印刷可能な Unicode (CERT_RDN_PRINTABLE_STRING) 文字列としてではなく、UTF-8 (CERT_RDN_UTF8_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が設定されている場合に、Unicode 値として X.500 キーのエンコードを有効にするには、 を使用します。
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

エンコードされた構造体を受け取るバッファーへのポインター。

このバッファーのサイズは 、pcbEncoded パラメーターで指定します。

このパラメーターは、メモリ割り当てのためにバッファーの必要なサイズを取得するために NULL にすることができます 。 詳細については、「 不明な長さのデータの取得」を参照してください。

[in, out] pcbEncoded

関数を呼び出す前に、pbEncoded パラメーターが指すバッファーのサイズをバイト単位で格納する DWORD へのポインター。 関数が戻ると、 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

戻り値

成功した場合は 0 以外、それ以外の場合は 0 を返します。

拡張エラー情報については、 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

Initials

 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
 

キーの RDN 値型として Printable または T61 が許可されている場合、名前文字列コンポーネントが次の文字セットのメンバーである場合、Printable は自動的に選択されます。

  • A、B、...、Z
  • a、b、...、z
  • 0, 1, ..., 9
  • (スペース)' ( ) + , - . / : = ?

T61 型は UTF8 エンコードです。

例

この関数を使用する例については、「 サンプル C プログラム: 証明書から ASN.1 への名前の変換」および「Back」を参照してください。

注意

wincrypt.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CertStrToName を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー wincrypt.h
Library Crypt32.lib
[DLL] Crypt32.dll

こちらもご覧ください

CertNameToStr

データ変換関数

GetLastError

不明な長さのデータの取得