CryptSetProvParam 関数 (wincrypt.h)

大事な この API は非推奨です。 新規および既存のソフトウェアでは 、暗号化次世代 API の 使用を開始する必要があります。Microsoft は、今後のリリースでこの API を削除する可能性があります。
 
CryptSetProvParam 関数は、暗号化サービス プロバイダー (CSP) の操作をカスタマイズします。 この関数は、CSP に関連付けられているキー コンテナーに セキュリティ記述子 を設定し、その キー コンテナー 内の 秘密キー へのアクセスを制御するために一般的に使用されます。

構文

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

パラメーター

[in] hProv

値を設定する CSP のハンドル。 このハンドルは、 CryptAcquireContext 関数を使用して既に作成されている必要があります。

[in] dwParam

設定するパラメーターを指定します。 これには、次のいずれかの値を指定できます。

意味
PP_CLIENT_HWND
1 (0x1)
プロバイダーが作成するダイアログ ボックスの親として使用するウィンドウ ハンドルを設定します。 pbData には、親ウィンドウ ハンドルを含む HWND へのポインターが含まれています。

CryptAcquireContext を呼び出すと、多くの CSP にユーザー インターフェイスが表示されるため、このパラメーターは CryptAcquireContext を呼び出す前に設定する必要があります。 hProv パラメーターに NULL を渡して、このプロセス内で後で取得されたすべての暗号化コンテキストに対してこのウィンドウ ハンドルを設定できます。

PP_DELETEKEY
24 (0x18)
ハッシュ暗号化、または検証コンテキストに関連付けられているエフェメラル キーを削除します。 これにより、メモリが解放され、キーに関連付けられているレジストリ設定がクリアされます。
PP_KEYEXCHANGE_ALG
この定数は使用されません。
PP_KEYEXCHANGE_PIN
32 (0x20)
キー交換 PIN が pbData に含まれていることを指定します。 PIN は null で終わる ASCII 文字列として表されます。
PP_KEYEXCHANGE_KEYSIZE
この定数は使用されません。
PP_KEYSET_SEC_DESCR
8 (0x8)
キー ストレージ コンテナーの セキュリティ記述子 を設定します。 pbData パラメーターは、キー ストレージ コンテナーの新しいセキュリティ記述子を含むSECURITY_DESCRIPTOR構造体のアドレスです。
PP_PIN_PROMPT_STRING
44 (0x2C)
ユーザーの PIN が要求されたときにユーザーに表示する代替プロンプト文字列を設定します。 pbData パラメーターは、null で終わる Unicode 文字列へのポインターです。
PP_ROOT_CERTSTORE
46 (0x2E)
スマート カードのルート証明書ストアを設定します。 プロバイダーは、このストアからスマート カードにルート証明書をコピーします。

pbData パラメーターは、新しい証明書ストアのハンドルを含む HCERTSTORE 変数です。 プロバイダーは、この呼び出し中にストアから証明書をコピーするため、この関数が呼び出された後にこのストアを閉じても安全です。

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

PP_SIGNATURE_ALG
この定数は使用されません。
PP_SIGNATURE_PIN
33 (0x21)
署名 PIN を指定します。 pbData パラメーターは、PIN を表す null で終わる ASCII 文字列です。
PP_SIGNATURE_KEYSIZE
この定数は使用されません。
PP_UI_PROMPT
21 (0x15)
スマート カード プロバイダーの場合は、スマート カードを挿入するためのプロンプトとしてユーザーに表示される検索文字列を設定します。 この文字列は、SCardUIDlgSelectCard 関数に渡されるOPENCARDNAME_EX構造体の lpstrSearchDesc メンバーとして渡されます。 この文字列は、呼び出し元プロセスの有効期間に使用されます。

pbData パラメーターは、null で終わる Unicode 文字列へのポインターです。

PP_USE_HARDWARE_RNG
38 (0x26)
CSP がハードウェア乱数ジェネレーター (RNG) を排他的に使用する必要があることを指定します。 PP_USE_HARDWARE_RNGが設定されている場合、ランダムな値はハードウェア RNG から排他的に取得され、他のソースは使用されません。 ハードウェア RNG が CSP でサポートされており、排他的に使用できる場合、関数は成功し 、TRUE を返します。それ以外の場合、関数は失敗し、 FALSE を返します。 この値を使用する場合、 pbData パラメーターは NULL で、 dwFlags は 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_SECURE_KEYEXCHANGE_PIN
47 (0x2F)
暗号化されたキー交換 PIN が pbData に含まれていることを指定します。 pbData パラメーターには、DATA_BLOBが含まれています。
PP_SECURE_SIGNATURE_PIN
48 (0x30)
暗号化された署名 PIN が pbData に含まれていることを指定します。 pbData パラメーターには、DATA_BLOBが含まれています。
PP_SMARTCARD_READER
43 (0x2B)
スマート カード リーダーの名前を指定します。 pbData パラメーターは、スマート カード リーダーの名前を含む null で終わる ANSI 文字列を含む ANSI 文字配列のアドレスです。

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

PP_SMARTCARD_GUID
45 (0x2D)
スマート カードの識別子を指定します。 pbData パラメーターは、スマート カードの識別子を含む GUID 構造体のアドレスです。

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

[in] pbData

プロバイダー パラメーターとして設定する値を含むデータ バッファーへのポインター。 このデータの形式は dwParam 値によって異なります。 dwParam にPP_USE_HARDWARE_RNGが含まれている場合、このパラメーターは NULL である必要があります。

[in] dwFlags

dwParamPP_KEYSET_SEC_DESCRが含まれている場合、dwFlags には、プラットフォーム SDK で定義されているSECURITY_INFORMATION適用可能なビット フラグが含まれます。 キー コンテナーのセキュリティは、 SetFileSecurityGetFileSecurity を使用して処理されます。

これらのビット フラグは、ビットごとの OR 演算を使用して組み合わせることができます。 詳細については、「 CryptGetProvParam」を参照してください。

dwParamPP_USE_HARDWARE_RNGまたはPP_DELETEKEYの場合は、dwFlags を 0 に設定する必要があります。

戻り値

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

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

"NTE" の前に表示されるエラー コードは、使用されている特定の CSP によって生成されます。 エラー コードには、次のようなものがあります。

リターン コード 説明
ERROR_BUSY
現在、CSP コンテキストは別の プロセスで使用されています。
ERROR_INVALID_HANDLE
パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。
NTE_BAD_FLAGS
dwFlags パラメーターが 0 以外であるか、pbData バッファーに無効な値が含まれています。
NTE_BAD_TYPE
dwParam パラメーターは、不明なパラメーターを指定します。
NTE_BAD_UID
hKey キーの作成時に指定された CSP コンテキストが見つかりません。
NTE_FAIL
関数が予期しない方法で失敗しました。

要件

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

こちらもご覧ください

CryptAcquireContext

CryptGetProvParam

CryptSetKeyParam

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