CryptGetProvParam 関数 (wincrypt.h)
構文
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
パラメーター
[in] hProv
クエリの CSP ターゲットのハンドル。 このハンドルは、 CryptAcquireContext 関数を使用して作成されている必要があります。
[in] dwParam
クエリの性質。 次のクエリが定義されています。
| 値 | 意味 |
|---|---|
|
pbData パラメーターの管理者の個人識別番号 (PIN) を LPSTR として返します。 |
|
この定数は使用されません。 |
|
この定数は使用されません。 |
|
hProv ハンドルに関連付けられている証明書チェーンを返します。 返された証明書チェーンは X509_ASN_ENCODING エンコードされます。 |
|
null で終わる CHAR 文字列としての現在のキー コンテナーの名前。 この文字列は、使用するキー コンテナーを指定するために CryptAcquireContext 関数の pszContainer パラメーターで渡されたものとまったく同じです。 pszContainer パラメーターを読み取って、既定のキー コンテナーの名前を決定できます。 |
|
Microsoft CSP によって実装されていません。 この動作は、他の CSP によって実装される場合があります。
Windows XP: このパラメーターはサポートされていません。 |
|
クエリ対象の CSP でサポートされている 1 つのアルゴリズムに関する情報を含む PROV_ENUMALGS 構造。
この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。 この関数はスレッド セーフではありません。この関数がマルチスレッド コンテキストで使用されている場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。 |
|
クエリ対象の CSP でサポートされている 1 つのアルゴリズムに関する情報を含む PROV_ENUMALGS_EX 構造。 返される構造体には、PP_ENUMALGSに返される構造体よりもアルゴリズムに関する詳細情報が含まれています。
この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。 この関数はスレッド セーフではなく、マルチスレッド コンテキストでこの関数を使用する場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。 |
|
CSP によって null で終わる CHAR 文字列の形式で保持されるキー コンテナーの 1 つの名前。
この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。 コンピューターに関連付けられているキー コンテナーを列挙するには、まず CRYPT_MACHINE_KEYSET フラグを使用して CryptAcquireContext を呼び出し、次に CryptAcquireContext から返されたハンドルを CryptGetProvParam の呼び出しで hProv パラメーターとして使用します。 この関数はスレッド セーフではなく、マルチスレッド コンテキストでこの関数を使用する場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。 |
|
この定数は使用されません。 |
|
現在の CSP がPROV_ENUMALGS_EX構造体の dwProtocols メンバーをサポートしていることを示します。 この関数が成功した場合、CSP はPROV_ENUMALGS_EX構造体の dwProtocols メンバーをサポートします。 この関数が NTE_BAD_TYPE エラー コードで失敗した場合、CSP は dwProtocols メンバーを サポートしません。 |
|
この定数は使用されません。 |
|
CSP の実装方法を示す DWORD 値。 使用可能な値のテーブルについては、「解説」を参照してください。 |
|
このクエリは使用されません。 |
|
キー交換 PIN が pbData に含まれていることを指定します。 PIN は null で終わる ASCII 文字列として表されます。 |
|
キー ストレージ コンテナーの セキュリティ記述子 を取得します。 pbData パラメーターは、キー ストレージ コンテナーのセキュリティ記述子を受け取るSECURITY_DESCRIPTOR構造体のアドレスです。 セキュリティ記述子は自己相対形式で返されます。 |
|
hProv パラメーターがコンピューター キー セットであるかどうかを判断します。 pbData パラメーターは DWORD である必要があります。そのフラグが CryptAcquireContext 関数に渡された場合、DWORD は CRYPT_MACHINE_KEYSET フラグに設定されます。 |
|
CSP がサポートするキー指定子の値に関する情報を返します。 キー指定子の値は論理 OR に結合され、呼び出しの pbData パラメーターで DWORD として返されます。 たとえば、Microsoft Base Cryptographic Provider バージョン 1.0 では、 AT_SIGNATURE | の DWORD 値が返されます。AT_KEYEXCHANGE。 |
|
CRYPT_SEC_DESCRの DWORD 値を返します。 |
|
AT_KEYEXCHANGEのインクリメント長のビット数。 この情報は、PP_ENUMALGS_EX値で返される情報と共に使用されます。 PP_ENUMALGS_EXとPP_KEYX_KEYSIZE_INCを使用するときに返される情報を使用して、AT_KEYEXCHANGEの有効なキー長を決定できます。 これらのキーの長さは 、CryptGenKey と共に使用できます。 たとえば、CSP が最小キー長 512 ビット、最大 1024 ビットの CALG_RSA_KEYX (AT_KEYEXCHANGE) を列挙し、増分長を 64 ビットとして返す場合、有効なキー長は 512、576、640 になります,... 1024. |
|
NULL で終わる CHAR 文字列の形式の CSP の名前。 この文字列は、現在の CSP を使用するように指定するために CryptAcquireContext 関数の pszProvider パラメーターで渡されたものと同じです。 |
|
CSP のプロバイダーの種類を示す DWORD 値。 |
|
スマート カードのルート証明書ストアを取得します。 この証明書ストアには、スマート カードに格納されているすべてのルート証明書が含まれています。
pbData パラメーターは、証明書ストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このハンドルが不要になった場合、呼び出し元は CertCloseStore 関数を使用してハンドルを閉じる必要があります。 Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。 |
|
セッション キーのサイズ (ビット単位)。 |
|
サーバー ゲート暗号化で使用されます。 |
|
AT_SIGNATUREのインクリメント長のビット数。 この情報は、PP_ENUMALGS_EX値で返される情報と共に使用されます。 PP_ENUMALGS_EXおよびPP_SIG_KEYSIZE_INCを使用するときに返される情報を使用して、AT_SIGNATUREの有効な キー長 を決定できます。 これらのキーの長さは 、CryptGenKey と共に使用できます。
たとえば、CSP が最小キー長 512 ビットで最大 1024 ビットのCALG_RSA_SIGN (AT_SIGNATURE) を列挙し、増分長を 64 ビットとして返す場合、有効なキーの長さは 512、576、640 になります,... 1024. |
|
キー署名 PIN が pbData に含まれていることを指定します。 PIN は 、null で終わる ASCII 文字列として表されます。 |
|
スマート カードの識別子を取得します。 pbData パラメーターは、スマート カードの識別子を受け取る GUID 構造体のアドレスです。
Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。 |
|
スマート カード リーダーの名前を取得します。 pbData パラメーターは、スマート カード リーダーの名前を含む null で終わる ANSI 文字列を受け取る ANSI 文字配列のアドレスです。 pdwDataLen パラメーターが指す変数に含まれるこのバッファーのサイズには、NULL 終端記号を含める必要があります。
Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。 |
|
対称キーのサイズ。 |
|
このクエリは使用されません。 |
|
null で終わる CHAR 文字列の形式の現在のキー コンテナーの一意のコンテナー名。 多くの CSP では、この名前は、PP_CONTAINER値を使用するときに返される名前と同じです。 CryptAcquireContext 関数は、このコンテナー名で動作する必要があります。 |
|
ハードウェア乱数ジェネレーター (RNG) がサポートされているかどうかを示します。 PP_USE_HARDWARE_RNGを指定すると、関数は成功し、ハードウェア RNG がサポートされている場合は TRUE を返します。 関数は失敗し、ハードウェア RNG がサポートされていない場合は FALSE を 返します。 RNG がサポートされている場合は、CryptSetProvParam で PP_USE_HARDWARE_RNGを設定して、CSP がこのプロバイダー コンテキストに対してハードウェア RNG を排他的に使用する必要があることを示すことができます。 PP_USE_HARDWARE_RNGを使用する場合、pbData パラメーターは NULL、dwFlags は 0 である必要があります。
現在、ハードウェア RNG の使用をサポートしている Microsoft CSP はありません。 |
|
スマート カードのユーザー証明書ストアを取得します。 この証明書ストアには、スマート カードに格納されているすべてのユーザー証明書が含まれています。 このストア内の証明書は、PKCS_7_ASN_ENCODING または X509_ASN_ENCODING エンコードを使用してエンコードされ、 CERT_KEY_PROV_INFO_PROP_ID プロパティを含める必要があります。
pbData パラメーターは、メモリ内証明書ストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このハンドルが不要になった場合、呼び出し元は CertCloseStore 関数を使用してハンドルを閉じる必要があります。 Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。 |
|
CSP のバージョン番号。 最下位バイトにはマイナー バージョン番号とメジャー バージョン番号の次の最上位バイトが含まれます。 バージョン 2.0 は、0x00000200として表されます。 以前のバージョンの Microsoft Base Cryptographic Provider および Microsoft Enhanced Cryptographic Provider との下位互換性を維持するために、プロバイダー名は新しいバージョンでは "v1.0" の指定を保持します。 |
[out] pbData
データを受信するバッファーへのポインター。 このデータの形式は、 dwParam の値によって異なります。 dwParam が PP_USE_HARDWARE_RNG に設定されている場合は、pbData を NULL に設定する必要があります。
このパラメーターは、メモリ割り当て目的でこの情報のサイズを設定するために NULL にすることができます 。 詳細については、「不明な 長さのデータの取得」を参照してください。
[in, out] pdwDataLen
pbData パラメーターが指すバッファーのサイズをバイト単位で指定する DWORD 値へのポインター。 関数が戻るときに、 DWORD 値には、格納されているバイト数、またはバッファーに格納されるバイト数が含まれます。
PP_ENUMALGS、またはPP_ENUMALGS_EXが設定されている場合、 pdwDataLen パラメーターの動作は多少異なります。 pbData が NULL の場合、または pdwDataLen が指す値が小さすぎる場合、このパラメーターで返される値は、現在読み取られているアイテムのサイズではなく、列挙リスト内の最大の項目のサイズです。
PP_ENUMCONTAINERSが設定されている場合、関数の最初の呼び出しは、現在のプロバイダーによって許可されている最大キー コンテナーのサイズを返します。 これは、既存の最も長いコンテナーの長さや現在のコンテナーの長さを返すなど、他の考えられる動作とは対照的です。 後続の列挙呼び出しでは、 dwLen パラメーターは変更されません。 列挙されたコンテナーごとに、呼び出し元は 、必要に応じて、プログラムによって null で終わる文字列の長さを決定できます。 列挙値の 1 つが読み取られ、 pbData パラメーターが NULL の場合、サイズ情報を正しく取得するには、CRYPT_FIRST フラグを指定する必要があります。
[in] dwFlags
dwParam がPP_KEYSET_SEC_DESCRされている場合、キーが格納されているキー コンテナーのセキュリティ記述子が取得されます。 この場合、 dwFlags は、Platform SDK で定義されているように、要求されたセキュリティ情報を示す SECURITY_INFORMATION ビット フラグを渡すために使用されます。 SECURITY_INFORMATION ビット フラグは、ビットごとの OR 演算と組み合わせることができます。
次の値は、 PP_KEYSET_SEC_DESCRで使用するために定義されています。
次の値は、PP_ENUMALGS、PP_ENUMALGS_EX、およびPP_ENUMCONTAINERSで使用するために定義されています。
| 値 | 意味 |
|---|---|
|
列挙体の最初の要素を取得します。 これは、列挙子をリセットする場合と同じ効果があります。 |
|
列挙体の次の要素を取得します。 取得する要素がこれ以上ない場合、この関数は失敗し、最後のエラーを ERROR_NO_MORE_ITEMS に設定します。 |
|
サーバー ゲート暗号化 (SGC) が有効な証明書を取得します。 SGC が有効な証明書はサポートされなくなりました。 |
|
このフラグは使用されません。 |
|
このフラグは使用されません。 |
戻り値
関数が成功した場合、戻り値は 0 以外 (TRUE) になります。
関数が失敗した場合、戻り値は 0 (FALSE) になります。 拡張エラー情報については、 GetLastError を呼び出します。
NTE の前のエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。
| リターン コード | 説明 |
|---|---|
|
パラメーターの 1 つは、無効なハンドルを指定します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。 |
|
pbData パラメーターで指定されたバッファーが、返されたデータを保持するのに十分な大きさでない場合、関数はERROR_MORE_DATA コードを設定し、必要なバッファー サイズをバイト単位で pdwDataLen が指す変数に格納します。 |
|
列挙リストの末尾に達しました。 pbData バッファーに有効なデータが配置されていません。 このエラー コードは、 dwParam が PP_ENUMALGS または PP_ENUMCONTAINERS と等しい場合にのみ返されます。 |
|
dwFlags パラメーターは、無効なフラグを指定します。 |
|
dwParam パラメーターは、不明な値番号を指定します。 |
|
hProv で指定された CSP コンテキストが無効です。 |
注釈
この関数は、マルチスレッド プログラムのスレッドでは使用できません。
dwParam がPP_IMPTYPEの場合、pbData では次の値が返されます。
| 値 | 意味 |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
実装はハードウェアにあります。 |
| CRYPT_IMPL_SOFTWARE 0x02 |
実装はソフトウェアに含まれます。 |
| CRYPT_IMPL_MIXED 0x03 |
実装には、ハードウェアとソフトウェアの両方が含まれます。 |
| CRYPT_IMPL_UNKNOWN 0x04 |
実装の種類が不明です。 |
| CRYPT_IMPL_REMOVABLE 0x08 |
実装はリムーバブル メディアにあります。 |
dwFlags パラメーターは、要求されたセキュリティ情報を示すSECURITY_INFORMATION ビット フラグを渡すために使用されます。 セキュリティ記述子へのポインターは pbData パラメーターで返され、セキュリティ記述子の長さは pdwDataLen パラメーターで返されます。 キー コンテナーのセキュリティは、 SetFileSecurity と GetFileSecurity で処理されます。
dwParam を PP_ENUMALGS または PP_ENUMALGS_EX に設定して列挙されたアルゴリズムのクラスを決定できます。 これは、サポートされている暗号化アルゴリズムの一覧を表示し、残りの部分を無視するために行われる場合があります。 GET_ALG_CLASS(x) マクロは、アルゴリズム識別子を引数として受け取り、そのアルゴリズムの一般的なクラスを示すコードを返します。 可能な戻り値は次のとおりです。
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
次の表に、Microsoft 基本暗号化プロバイダーでサポートされているアルゴリズムと、各アルゴリズムのクラスを示します。
| 名前 | 識別子 | クラス |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
アプリケーションでは、認識されないアルゴリズム識別子を持つアルゴリズムを使用することはできません。 不明な暗号化アルゴリズムを使用すると、予期しない結果が生じる可能性があります。
例
次の例は、暗号化サービス プロバイダー ハンドルに関連付けられている CSP の名前と、ハンドルに関連付けられているキー コンテナーの名前を見つける方法を示しています。 この例の完全なコンテキストについては、「 サンプル C プログラム: CryptAcquireContext の使用」を参照してください。
この関数を使用する別の例については、「 サンプル C プログラム: CSP プロバイダーとプロバイダーの種類の列挙」を参照してください。
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |