次の方法で共有


CryptGetProvParam 関数 (wincrypt.h)

大事な この API は非推奨です。 新規および既存のソフトウェアでは 、暗号化次世代 API の 使用を開始する必要があります。Microsoft は、今後のリリースでこの API を削除する可能性があります。
 
CryptGetProvParam 関数は、暗号化サービス プロバイダー (CSP) の操作を制御するパラメーターを取得します。

構文

BOOL CryptGetProvParam(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

パラメーター

[in] hProv

クエリの CSP ターゲットのハンドル。 このハンドルは、 CryptAcquireContext 関数を使用して作成されている必要があります。

[in] dwParam

クエリの性質。 次のクエリが定義されています。

意味
PP_ADMIN_PIN
31 (0x1F)
pbData パラメーターの管理者の個人識別番号 (PIN) を LPSTR として返します。
PP_APPLI_CERT
18 (0x12)
この定数は使用されません。
PP_CHANGE_PASSWORD
7 (0x7)
この定数は使用されません。
PP_CERTCHAIN
9 (0x9)
hProv ハンドルに関連付けられている証明書チェーンを返します。 返された証明書チェーンは X509_ASN_ENCODING エンコードされます。
PP_CONTAINER
6 (0x6)
null で終わる CHAR 文字列としての現在のキー コンテナーの名前。 この文字列は、使用するキー コンテナーを指定するために CryptAcquireContext 関数の pszContainer パラメーターで渡されたものとまったく同じです。 pszContainer パラメーターを読み取って、既定のキー コンテナーの名前を決定できます。
PP_CRYPT_COUNT_KEY_USE
41 (0x29)
Microsoft CSP によって実装されていません。 この動作は、他の CSP によって実装される場合があります。

Windows XP: このパラメーターはサポートされていません。

PP_ENUMALGS
1 (0x1)
クエリ対象の CSP でサポートされている 1 つのアルゴリズムに関する情報を含む PROV_ENUMALGS 構造。

この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。

この関数はスレッド セーフではありません。この関数がマルチスレッド コンテキストで使用されている場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。

PP_ENUMALGS_EX
22 (0x16)
クエリ対象の CSP でサポートされている 1 つのアルゴリズムに関する情報を含む PROV_ENUMALGS_EX 構造。 返される構造体には、PP_ENUMALGSに返される構造体よりもアルゴリズムに関する詳細情報が含まれています。

この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。

この関数はスレッド セーフではなく、マルチスレッド コンテキストでこの関数を使用する場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。

PP_ENUMCONTAINERS
2 (0x2)
CSP によって null で終わる CHAR 文字列の形式で保持されるキー コンテナーの 1 つの名前。

この値を初めて読み取る場合は、 dwFlags パラメーターに CRYPT_FIRST フラグが含まれている必要があります。 これにより、この関数は列挙体の最初の要素を取得します。 その後、dwFlags パラメーターで CRYPT_NEXT フラグを設定することで、後続の要素を取得できます。 この関数が ERROR_NO_MORE_ITEMS エラー コードで失敗すると、列挙体の末尾に達しました。

コンピューターに関連付けられているキー コンテナーを列挙するには、まず CRYPT_MACHINE_KEYSET フラグを使用して CryptAcquireContext を呼び出し、次に CryptAcquireContext から返されたハンドルを CryptGetProvParam の呼び出しで hProv パラメーターとして使用します。

この関数はスレッド セーフではなく、マルチスレッド コンテキストでこの関数を使用する場合は、使用可能なすべてのアルゴリズムが列挙されない可能性があります。

PP_ENUMELECTROOTS
26 (0x1A)
この定数は使用されません。
PP_ENUMEX_SIGNING_PROT
40 (0x28)
現在の CSP がPROV_ENUMALGS_EX構造体の dwProtocols メンバーをサポートしていることを示します。 この関数が成功した場合、CSP はPROV_ENUMALGS_EX構造体の dwProtocols メンバーをサポートします。 この関数が NTE_BAD_TYPE エラー コードで失敗した場合、CSP は dwProtocols メンバーを サポートしません。
PP_ENUMMANDROOTS
25 (0x19)
この定数は使用されません。
PP_IMPTYPE
3 (0x3)
CSP の実装方法を示す DWORD 値。 使用可能な値のテーブルについては、「解説」を参照してください。
PP_KEY_TYPE_SUBTYPE
10 (0xA)
このクエリは使用されません。
PP_KEYEXCHANGE_PIN
32 (0x20)
キー交換 PIN が pbData に含まれていることを指定します。 PIN は null で終わる ASCII 文字列として表されます。
PP_KEYSET_SEC_DESCR
8 (0x8)
キー ストレージ コンテナーの セキュリティ記述子 を取得します。 pbData パラメーターは、キー ストレージ コンテナーのセキュリティ記述子を受け取るSECURITY_DESCRIPTOR構造体のアドレスです。 セキュリティ記述子は自己相対形式で返されます。
PP_KEYSET_TYPE
27 (0x1B)
hProv パラメーターがコンピューター キー セットであるかどうかを判断します。 pbData パラメーターは DWORD である必要があります。そのフラグが CryptAcquireContext 関数に渡された場合、DWORD は CRYPT_MACHINE_KEYSET フラグに設定されます。
PP_KEYSPEC
39 (0x27)
CSP がサポートするキー指定子の値に関する情報を返します。 キー指定子の値は論理 OR に結合され、呼び出しの pbData パラメーターで DWORD として返されます。 たとえば、Microsoft Base Cryptographic Provider バージョン 1.0 では、 AT_SIGNATURE | の DWORD 値が返されます。AT_KEYEXCHANGE。
PP_KEYSTORAGE
17 (0x11)
CRYPT_SEC_DESCRの DWORD 値を返します。
PP_KEYX_KEYSIZE_INC
35 (0x23)
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.
PP_NAME
4 (0x4)
NULL で終わる CHAR 文字列の形式の CSP の名前。 この文字列は、現在の CSP を使用するように指定するために CryptAcquireContext 関数の pszProvider パラメーターで渡されたものと同じです。
PP_PROVTYPE
16 (0x10)
CSP のプロバイダーの種類を示す DWORD 値。
PP_ROOT_CERTSTORE
46 (0x2E)
スマート カードのルート証明書ストアを取得します。 この証明書ストアには、スマート カードに格納されているすべてのルート証明書が含まれています。

pbData パラメーターは、証明書ストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このハンドルが不要になった場合、呼び出し元は CertCloseStore 関数を使用してハンドルを閉じる必要があります。

Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。

PP_SESSION_KEYSIZE
20 (0x14)
セッション キーのサイズ (ビット単位)。
PP_SGC_INFO
37 (0x25)
サーバー ゲート暗号化で使用されます。
PP_SIG_KEYSIZE_INC
34 (0x22)
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.

PP_SIGNATURE_PIN
33 (0x21)
キー署名 PIN が pbData に含まれていることを指定します。 PIN は 、null で終わる ASCII 文字列として表されます。
PP_SMARTCARD_GUID
45 (0x2D)
スマート カードの識別子を取得します。 pbData パラメーターは、スマート カードの識別子を受け取る GUID 構造体のアドレスです。

Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。

PP_SMARTCARD_READER
43 (0x2B)
スマート カード リーダーの名前を取得します。 pbData パラメーターは、スマート カード リーダーの名前を含む null で終わる ANSI 文字列を受け取る ANSI 文字配列のアドレスです。 pdwDataLen パラメーターが指す変数に含まれるこのバッファーのサイズには、NULL 終端記号を含める必要があります。

Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。

PP_SYM_KEYSIZE
19 (0x13)
対称キーのサイズ。
PP_UI_PROMPT
21 (0x15)
このクエリは使用されません。
PP_UNIQUE_CONTAINER
36 (0x24)
null で終わる CHAR 文字列の形式の現在のキー コンテナーの一意のコンテナー名。 多くの CSP では、この名前は、PP_CONTAINER値を使用するときに返される名前と同じです。 CryptAcquireContext 関数は、このコンテナー名で動作する必要があります。
PP_USE_HARDWARE_RNG
38 (0x26)
ハードウェア乱数ジェネレーター (RNG) がサポートされているかどうかを示します。 PP_USE_HARDWARE_RNGを指定すると、関数は成功し、ハードウェア RNG がサポートされている場合は TRUE を返します。 関数は失敗し、ハードウェア RNG がサポートされていない場合は FALSE を 返します。 RNG がサポートされている場合は、CryptSetProvParamPP_USE_HARDWARE_RNGを設定して、CSP がこのプロバイダー コンテキストに対してハードウェア RNG を排他的に使用する必要があることを示すことができます。 PP_USE_HARDWARE_RNGを使用する場合、pbData パラメーターは NULLdwFlags は 0 である必要があります。

現在、ハードウェア RNG の使用をサポートしている Microsoft CSP はありません。

PP_USER_CERTSTORE
42 (0x2A)
スマート カードのユーザー証明書ストアを取得します。 この証明書ストアには、スマート カードに格納されているすべてのユーザー証明書が含まれています。 このストア内の証明書は、PKCS_7_ASN_ENCODING または X509_ASN_ENCODING エンコードを使用してエンコードされ、 CERT_KEY_PROV_INFO_PROP_ID プロパティを含める必要があります。

pbData パラメーターは、メモリ内証明書ストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このハンドルが不要になった場合、呼び出し元は CertCloseStore 関数を使用してハンドルを閉じる必要があります。

Windows Server 2003 および Windows XP: このパラメーターはサポートされていません。

PP_VERSION
5 (0x5)
CSP のバージョン番号。 最下位バイトにはマイナー バージョン番号とメジャー バージョン番号の次の最上位バイトが含まれます。 バージョン 2.0 は、0x00000200として表されます。 以前のバージョンの Microsoft Base Cryptographic Provider および Microsoft Enhanced Cryptographic Provider との下位互換性を維持するために、プロバイダー名は新しいバージョンでは "v1.0" の指定を保持します。

[out] pbData

データを受信するバッファーへのポインター。 このデータの形式は、 dwParam の値によって異なります。 dwParam が PP_USE_HARDWARE_RNG に設定されている場合は、pbDataNULL に設定する必要があります。

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

[in, out] pdwDataLen

pbData パラメーターが指すバッファーのサイズをバイト単位で指定する DWORD 値へのポインター。 関数が戻るときに、 DWORD 値には、格納されているバイト数、またはバッファーに格納されるバイト数が含まれます。

メモ バッファーで返されるデータを処理する場合、アプリケーションは返されるデータの実際のサイズを使用する必要があります。 実際のサイズは、入力時に指定されたバッファーのサイズよりも若干小さくすることができます。 (入力では、バッファー サイズは通常、可能な最大の出力データがバッファーに収まるように十分な大きさで指定されます)。出力時に、このパラメーターが指す変数は、バッファーにコピーされたデータの実際のサイズを反映するように更新されます。

PP_ENUMALGS、またはPP_ENUMALGS_EXが設定されている場合、 pdwDataLen パラメーターの動作は多少異なります。 pbDataNULL の場合、または pdwDataLen が指す値が小さすぎる場合、このパラメーターで返される値は、現在読み取られているアイテムのサイズではなく、列挙リスト内の最大の項目のサイズです。

PP_ENUMCONTAINERSが設定されている場合、関数の最初の呼び出しは、現在のプロバイダーによって許可されている最大キー コンテナーのサイズを返します。 これは、既存の最も長いコンテナーの長さや現在のコンテナーの長さを返すなど、他の考えられる動作とは対照的です。 後続の列挙呼び出しでは、 dwLen パラメーターは変更されません。 列挙されたコンテナーごとに、呼び出し元は 、必要に応じて、プログラムによって null で終わる文字列の長さを決定できます。 列挙値の 1 つが読み取られ、 pbData パラメーターが NULL の場合、サイズ情報を正しく取得するには、CRYPT_FIRST フラグを指定する必要があります。

 

[in] dwFlags

dwParamPP_KEYSET_SEC_DESCRされている場合、キーが格納されているキー コンテナーセキュリティ記述子が取得されます。 この場合、 dwFlags は、Platform SDK で定義されているように、要求されたセキュリティ情報を示す SECURITY_INFORMATION ビット フラグを渡すために使用されます。 SECURITY_INFORMATION ビット フラグは、ビットごとの OR 演算と組み合わせることができます。

次の値は、 PP_KEYSET_SEC_DESCRで使用するために定義されています。

意味
OWNER_SECURITY_INFORMATION
オブジェクトの所有者識別子が参照されています。
GROUP_SECURITY_INFORMATION
オブジェクトのプライマリ グループ識別子が参照されています。
DACL_SECURITY_INFORMATION
オブジェクトの随意 ACL が参照されています。
SACL_SECURITY_INFORMATION
オブジェクトのシステム ACL が参照されています。
 

次の値は、PP_ENUMALGS、PP_ENUMALGS_EXおよびPP_ENUMCONTAINERSで使用するために定義されています。

意味
CRYPT_FIRST
1 (0x1)
列挙体の最初の要素を取得します。 これは、列挙子をリセットする場合と同じ効果があります。
CRYPT_NEXT
2 (0x2)
列挙体の次の要素を取得します。 取得する要素がこれ以上ない場合、この関数は失敗し、最後のエラーを ERROR_NO_MORE_ITEMS に設定します。
CRYPT_SGC_ENUM
4 (0x4)
サーバー ゲート暗号化 (SGC) が有効な証明書を取得します。 SGC が有効な証明書はサポートされなくなりました。
CRYPT_SGC
このフラグは使用されません。
CRYPT_FASTSGC
このフラグは使用されません。

戻り値

関数が成功した場合、戻り値は 0 以外 (TRUE) になります

関数が失敗した場合、戻り値は 0 (FALSE) になります。 拡張エラー情報については、 GetLastError を呼び出します。

NTE の前のエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。

リターン コード 説明
ERROR_INVALID_HANDLE
パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。
ERROR_MORE_DATA
pbData パラメーターで指定されたバッファーが、返されたデータを保持するのに十分な大きさでない場合、関数はERROR_MORE_DATA コードを設定し、必要なバッファー サイズをバイト単位で pdwDataLen が指す変数に格納します。
ERROR_NO_MORE_ITEMS
列挙リストの末尾に達しました。 pbData バッファーに有効なデータが配置されていません。 このエラー コードは、 dwParam が PP_ENUMALGS または PP_ENUMCONTAINERS と等しい場合にのみ返されます。
NTE_BAD_FLAGS
dwFlags パラメーターは、無効なフラグを指定します。
NTE_BAD_TYPE
dwParam パラメーターは、不明な値番号を指定します。
NTE_BAD_UID
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 パラメーターで返されます。 キー コンテナーのセキュリティは、 SetFileSecurityGetFileSecurity で処理されます。

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

こちらもご覧ください

絶対セキュリティ記述子と Self-Relative セキュリティ記述子

CryptAcquireContext

CryptCreateHash

CryptDeriveKey

CryptGenKey

CryptGetKeyParam

CryptSetProvParam

サービス プロバイダー関数