Win32 API 日本語リファレンス
ホーム › Security.Cryptography.Certificates › IX509PrivateKey

IX509PrivateKey

COMIDispatch (デュアル)
📘 Microsoft Learn (日本語) · English
✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IID728ab30c-217d-11da-b2a4-000e7bbb2b09継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

暗号化、署名、およびキー合意に使用できる非対称秘密キーを表します。

メソッド 58

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT Open()

既存の秘密キーを開きます。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

解説(Remarks)

成功した場合、このメソッドは Opened プロパティを設定します。Export メソッドまたは ExportPublicKey メソッドを呼び出す前に、Open メソッドまたは Create メソッドのいずれかを呼び出す必要があります。

Open メソッドまたは Create メソッドを呼び出した後は、次のプロパティを設定できません。これらを指定したい場合は、いずれかのメソッドを呼び出す前に行う必要があります。

次のプロパティは、キーが開いているかどうかに関係なく設定できます。

vtbl 8 HRESULT Create()

非対称秘密キーを作成します。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値には次の表の値が含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻りコード/値 説明
HRESULT_FROM_WIN32(ERROR_BUSY)
 CSP ハンドルが NULL ではありません。
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)
 キーが既に存在します。

解説(Remarks)

CspStatus、ProviderName、または ProviderType プロパティを設定しない場合、このメソッドはキーの作成時に既定のプロバイダー、キーサイズ、および KeySpec 値を使用します。たとえば、新規にオペレーティングシステムをインストールした環境では、Microsoft Enhanced Cryptographic Provider v1.0 が既定のプロバイダーです。

ContainerName プロパティを設定しない場合、このメソッドは名前を自動的に生成します。生成される名前には GUID が含まれ、ContainerNamePrefix プロパティが設定されていない場合は接頭辞 "lp-" が付きます。プロバイダーがスマートカードプロバイダーの場合、生成される名前はプロバイダーが指定する MaxKeyContainerNameLength 値を超えません。生成された名前が最初にこの値を超える場合は、40 文字に切り詰められます。

Create メソッドまたは Open メソッドを呼び出した後は、次のプロパティを設定できません。これらを指定したい場合は、いずれかのメソッドを呼び出す前に行う必要があります。

vtbl 9 HRESULT Close()

暗号化サービスプロバイダー (CSP) のハンドル、または Cryptography API: Next Generation (CNG) キーストレージプロバイダー (KSP) のハンドルを解放します。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

解説(Remarks)

このメソッドは、ストレージからキーを削除したり、IX509PrivateKey インスタンスを削除したりしません。詳細については、Delete メソッドを参照してください。

vtbl 10 HRESULT Delete()

暗号化サービスプロバイダー (CSP) のハンドル、または Cryptography API: Next Generation (CNG) キーストレージプロバイダー (KSP) のハンドルを解放し、ディスクまたはスマートカードからキーを削除します。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値には次の表の値が含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻りコード/値 説明
CERTSRV_E_PROPERTY_EMPTY
 CSP が見つかりませんでした。

解説(Remarks)

プロバイダーのハンドルを閉じるだけの場合は、Close メソッドを呼び出してください。Delete メソッドは IX509PrivateKey インスタンスを削除しません。

vtbl 11 HRESULT Verify(X509PrivateKeyVerify VerifyType)

秘密キーが存在し、クライアントが使用できることを検証しますが、キーを開くことはしません。

VerifyTypeX509PrivateKeyVerifyin

メソッドの実行オプションを指定する X509PrivateKeyVerify 列挙値です。次のいずれかの値を指定できます。

値 意味
VerifyNone
 検証しません。
VerifySilent
 秘密キーを開くのにユーザーインターフェイスが必要な場合は検証しません。それ以外の場合は検証が行われます。詳細については、「解説」を参照してください。
VerifySmartCardNone
 キーがスマートカードに格納されている場合は検証しません。それ以外の場合、この値は VerifyAllowUI と同等です。
VerifySmartCardSilent
 秘密キーを開くのにユーザーインターフェイスが必要で、かつキーがスマートカードに格納されている場合は検証しません。それ以外の場合、この値は VerifyAllowUI と同等です。詳細については、「解説」を参照してください。
VerifyAllowUI
 メソッドはユーザーインターフェイスの表示を許可します。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値には次の表の値が含まれますが、これらに限定されません。また、このメソッドは CryptoAPI の CryptGetUserKey 関数および CryptAcquireContext 関数を呼び出すため、そのドキュメントで示されているエラーを返す場合があります。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻りコード 説明
CERTSRV_E_PROPERTY_EMPTY
 CSP または KSP に関連するプロパティが見つかりませんでした。

解説(Remarks)

VerifySilent または VerifySmartCardSilent の値が設定されていて、暗号化プロバイダーがユーザーインターフェイスが必要であると指定している場合、キーは開かれませんが、メソッドは S_OK を返します。

vtbl 12 HRESULT Import(LPWSTR strExportType, LPWSTR strEncodedKey, EncodingType Encoding)

既存の秘密キーを、暗号化プロバイダー内のキーコンテナーにインポートします。

strExportTypeLPWSTRin

キーが CNG KSP (キーストレージプロバイダー) を使用して作成された場合、Import メソッドはこの引数を NCryptSetProperty 関数の pszProperty パラメーターに渡します。つまり、指定した値は、インポートされたキーに設定するプロパティの名前として使用されます。

キーが CryptoAPI CSP (暗号化サービスプロバイダー) を使用して作成された場合、この引数は秘密キーをどのようにインポートするかを指定します。次の値を指定できます。

値 意味
BCRYPT_PRIVATE_KEY_BLOB
 秘密キー全体をインポートします。
strEncodedKeyLPWSTRinインポートするキーを格納する BSTR 変数です。
EncodingEncodingTypeinstrEncodedKey パラメーターに格納された文字列に適用する Unicode エンコードの種類を指定する EncodingType 列挙値です。既定値は XCN_CRYPT_STRING_BASE64 です。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値には次の表の値が含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻りコード 説明
HRESULT_FROM_WIN32(ERROR_FILE_READ_ONLY)
 キーコンテナーが既に開いています。既に Open または Create を呼び出している場合、このエラーが返されることがあります。
HRESULT_FROM_WIN32(ERROR_CALL_NOT_IMPLEMENTED)
 キーが CryptoAPI CSP によって作成されており、strExportType パラメーターに BCRYPT_PRIVATE_KEY_BLOB 以外の値を指定しました。

解説(Remarks)

Import 関数は、strExportType パラメーターに BCRYPT_PRIVATE_KEY_BLOB 以外の値を指定し、かつ次のいずれのプロパティも設定していない場合、CNG KSP キーをインポートしようとしていると自動的に見なします。

vtbl 13 HRESULT Export(LPWSTR strExportType, EncodingType Encoding, LPWSTR* pstrEncodedKey)

秘密キーをバイト配列にコピーします。

strExportTypeLPWSTRin

秘密キーをどのようにエクスポートするかを指定する BSTR 値です。

キーが CNG KSP (キーストレージプロバイダー) を使用して作成された場合は、NCryptExportKey 関数の pszBlobType パラメーターで許可されている値のいずれかを指定できます。

キーが CryptoAPI CSP (暗号化サービスプロバイダー) を使用して作成された場合は、Wincrypt.h に含まれる Bcrypt.h ヘッダーファイルの次のいずれかの値を指定できます。

値 意味
BCRYPT_PUBLIC_KEY_BLOB
 秘密キーの公開部分のみをエクスポートします。
BCRYPT_PRIVATE_KEY_BLOB
 秘密キー全体をエクスポートします。
EncodingEncodingTypeinpstrEncodedKey パラメーターに格納された文字列に適用する Unicode エンコードの種類を指定する EncodingType 列挙値です。既定値は XCN_CRYPT_STRING_BASE64 です。
pstrEncodedKeyLPWSTR*out秘密キーを格納する BSTR 変数へのポインターです。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値には次の表の値が含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

戻りコード 説明
HRESULT_FROM_WIN32(ERROR_CALL_NOT_IMPLEMENTED)
 キーが CryptoAPI CSP によって作成されており、strExportType パラメーターに BCRYPT_PRIVATE_KEY_BLOB または BCRYPT_PUBLIC_KEY_BLOB 以外の値を指定しました。
vtbl 14 HRESULT ExportPublicKey(IX509PublicKey** ppPublicKey)

非対称キーペアの公開キー部分をエクスポートします。

ppPublicKeyIX509PublicKey**outキーを表す IX509PublicKey インターフェイスへのポインターを受け取る変数のアドレスです。

戻り値

関数が成功した場合、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

解説(Remarks)

このメソッドを呼び出す前に、Open または Create を呼び出して秘密キーを開いておく必要があります。

vtbl 15 HRESULT get_ContainerName(LPWSTR* pValue)

キーコンテナーの名前を指定または取得します。(Get)

pValueLPWSTR*out鍵コンテナー名を受け取る文字列ポインタである。

解説(Remarks)

名前を指定しない場合は、Create メソッドが呼び出されたときに名前が作成されます。

vtbl 16 HRESULT put_ContainerName(LPWSTR Value)

キーコンテナーの名前を指定または取得します。(Put)

ValueLPWSTRin設定する鍵コンテナー名を指定する。

解説(Remarks)

名前を指定しない場合は、Create メソッドが呼び出されたときに名前が作成されます。

vtbl 17 HRESULT get_ContainerNamePrefix(LPWSTR* pValue)

キーコンテナーの名前に追加する接頭辞を指定または取得します。(Get)

pValueLPWSTR*out鍵コンテナー名のプレフィックスを受け取る文字列ポインタである。

解説(Remarks)

接頭辞には、キーコンテナー名の最大長と、コンテナー名として有効な文字の範囲内で、任意の文字列を指定できます。たとえば、ContainerName プロパティを呼び出してキーコンテナー名を指定しない場合、Create メソッドが呼び出されたときに名前が自動的に作成され、コンテナー名の接頭辞は文字列 "lp" になります。別の例として、テストハーネスを作成していて、生成元のプログラムごとにキーコンテナーを区別したい場合は、実行可能ファイルの名前を接頭辞として使用できます。

vtbl 18 HRESULT put_ContainerNamePrefix(LPWSTR Value)

キーコンテナーの名前に追加する接頭辞を指定または取得します。(Put)

ValueLPWSTRin設定する鍵コンテナー名のプレフィックスを指定する。

解説(Remarks)

接頭辞には、キーコンテナー名の最大長と、コンテナー名として有効な文字の範囲内で、任意の文字列を指定できます。たとえば、ContainerName プロパティを呼び出してキーコンテナー名を指定しない場合、Create メソッドが呼び出されたときに名前が自動的に作成され、コンテナー名の接頭辞は文字列 "lp" になります。別の例として、テストハーネスを作成していて、生成元のプログラムごとにキーコンテナーを区別したい場合は、実行可能ファイルの名前を接頭辞として使用できます。

vtbl 19 HRESULT get_ReaderName(LPWSTR* pValue)

スマートカードリーダーの名前を指定または取得します。(Get)

pValueLPWSTR*outスマートカードリーダーの名前を受け取る文字列ポインタである。

解説(Remarks)

キーを開く前にこのプロパティを設定すると、リーダー名がキーコンテナーの名前に連結されます。形式は \.\Reader_Name\Container_Name です。リーダー名をキーコンテナー名の前に付加することで、以降の暗号化プロバイダーへの呼び出しで名前を一意に識別できるようになります。スマートカードを使用する場合、秘密キーは通常、スマートカードのキーコンテナーに格納されます。

vtbl 20 HRESULT put_ReaderName(LPWSTR Value)

スマートカードリーダーの名前を指定または取得します。(Put)

ValueLPWSTRin設定するスマートカードリーダーの名前を指定する。

解説(Remarks)

キーを開く前にこのプロパティを設定すると、リーダー名がキーコンテナーの名前に連結されます。形式は \.\Reader_Name\Container_Name です。リーダー名をキーコンテナー名の前に付加することで、以降の暗号化プロバイダーへの呼び出しで名前を一意に識別できるようになります。スマートカードを使用する場合、秘密キーは通常、スマートカードのキーコンテナーに格納されます。

vtbl 21 HRESULT get_CspInformations(ICspInformations** ppValue)

秘密キーに関連付けられた公開キーアルゴリズムをサポートする、利用可能な暗号化プロバイダーに関する情報を格納した ICspInformation オブジェクトのコレクションを指定または取得します。(Get)

ppValueICspInformations**out利用可能な CSP 情報のコレクションを受け取るインターフェイスポインタへのポインタである。

解説(Remarks)

登録 (エンロール) プロセスでは、ICspInformations コレクションにクライアントコンピューターにインストールされているすべてのプロバイダーが含まれていることが前提となります。そのため、このプロパティにインストール済みプロバイダーの一部だけを設定しようとしないでください。空のコレクションを作成し、AddAvailableCsps を呼び出して設定することをお勧めします。複数のコレクションを作成するコストを避けるため、このコレクションは一度だけ構築し、すべての最上位の要求オブジェクト (IX509PrivateKey オブジェクトを直接使用している場合は秘密キー) に設定してください。ICspInformations コレクションは大きなものです。

vtbl 22 HRESULT put_CspInformations(ICspInformations* pValue)

秘密キーに関連付けられた公開キーアルゴリズムをサポートする、利用可能な暗号化プロバイダーに関する情報を格納した ICspInformation オブジェクトのコレクションを指定または取得します。(Put)

pValueICspInformations*inoptional設定する CSP 情報のコレクションを表す ICspInformations へのポインタである。

解説(Remarks)

登録 (エンロール) プロセスでは、ICspInformations コレクションにクライアントコンピューターにインストールされているすべてのプロバイダーが含まれていることが前提となります。そのため、このプロパティにインストール済みプロバイダーの一部だけを設定しようとしないでください。空のコレクションを作成し、AddAvailableCsps を呼び出して設定することをお勧めします。複数のコレクションを作成するコストを避けるため、このコレクションは一度だけ構築し、すべての最上位の要求オブジェクト (IX509PrivateKey オブジェクトを直接使用している場合は秘密キー) に設定してください。ICspInformations コレクションは大きなものです。

vtbl 23 HRESULT get_CspStatus(ICspStatus** ppValue)

秘密キーに関連付けられた暗号化プロバイダーとアルゴリズムのペアに関する情報を格納した ICspStatus オブジェクトを指定または取得します。(Get)

ppValueICspStatus**out現在の CSP 状態を表す ICspStatus オブジェクトを受け取るインターフェイスポインタへのポインタである。

解説(Remarks)

CspStatus プロパティを呼び出すと、Algorithm プロパティと ProviderName プロパティが自動的に設定されます。CspStatus プロパティは通常、登録 (エンロール) プロセス中に設定されます。つまり、要求テンプレートが複数のプロバイダー/アルゴリズムのペアを指定している場合、登録コードは CspStatus プロパティを最初に有効な ICspStatus オブジェクトに設定して秘密キーの作成を試みます。キーを作成できない場合、登録コードはこのプロパティを次に有効な ICspStatus オブジェクトに設定して再試行します。

vtbl 24 HRESULT put_CspStatus(ICspStatus* pValue)

秘密キーに関連付けられた暗号化プロバイダーとアルゴリズムのペアに関する情報を格納した ICspStatus オブジェクトを指定または取得します。(Put)

pValueICspStatus*inoptional設定する CSP 状態を表す ICspStatus へのポインタである。

解説(Remarks)

CspStatus プロパティを呼び出すと、Algorithm プロパティと ProviderName プロパティが自動的に設定されます。CspStatus プロパティは通常、登録 (エンロール) プロセス中に設定されます。つまり、要求テンプレートが複数のプロバイダー/アルゴリズムのペアを指定している場合、登録コードは CspStatus プロパティを最初に有効な ICspStatus オブジェクトに設定して秘密キーの作成を試みます。キーを作成できない場合、登録コードはこのプロパティを次に有効な ICspStatus オブジェクトに設定して再試行します。

vtbl 25 HRESULT get_ProviderName(LPWSTR* pValue)

暗号化プロバイダーの名前を指定または取得します。(Get)

pValueLPWSTR*out使用するプロバイダー名を受け取る文字列ポインタである。

解説(Remarks)

このプロパティを設定すると、指定した ProviderName 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 ProviderName プロパティを設定する場合は、LegacyCsp または ProviderType プロパティを設定しないことをお勧めします。
vtbl 26 HRESULT put_ProviderName(LPWSTR Value)

暗号化プロバイダーの名前を指定または取得します。(Put)

ValueLPWSTRin設定するプロバイダー名を指定する。

解説(Remarks)

このプロパティを設定すると、指定した ProviderName 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 ProviderName プロパティを設定する場合は、LegacyCsp または ProviderType プロパティを設定しないことをお勧めします。
vtbl 27 HRESULT get_ProviderType(X509ProviderType* pValue)

秘密キーに関連付けられた暗号化プロバイダーの種類を指定または取得します。(Get)

pValueX509ProviderType*outプロバイダーの種類を受け取る X509ProviderType へのポインタである。

解説(Remarks)

このプロパティを使用すると、指定したプロバイダーの種類に対して既定のプロバイダーの使用を強制できます。たとえば、PROV_RSA_SCHANNEL プロバイダーを使用するには、このプロパティを XCN_PROV_RSA_SCHANNEL X509ProviderType 列挙値に設定し、ProviderName プロパティには値を指定しません。

このプロパティを設定すると、指定した ProviderType 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 以前に指定した ProviderName は ProviderType プロパティの設定による影響を受けないため、ProviderName プロパティと矛盾する ProviderType を設定すると、未定義の動作となり、秘密キーの作成時または開くときに失敗する可能性があります。上記のとおり、指定した種類の既定プロバイダーの使用を強制する場合にのみ、ProviderType プロパティを設定することをお勧めします。
vtbl 28 HRESULT put_ProviderType(X509ProviderType Value)

秘密キーに関連付けられた暗号化プロバイダーの種類を指定または取得します。(Put)

ValueX509ProviderTypein設定するプロバイダーの種類を表す X509ProviderType である。

解説(Remarks)

このプロパティを使用すると、指定したプロバイダーの種類に対して既定のプロバイダーの使用を強制できます。たとえば、PROV_RSA_SCHANNEL プロバイダーを使用するには、このプロパティを XCN_PROV_RSA_SCHANNEL X509ProviderType 列挙値に設定し、ProviderName プロパティには値を指定しません。

このプロパティを設定すると、指定した ProviderType 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 以前に指定した ProviderName は ProviderType プロパティの設定による影響を受けないため、ProviderName プロパティと矛盾する ProviderType を設定すると、未定義の動作となり、秘密キーの作成時または開くときに失敗する可能性があります。上記のとおり、指定した種類の既定プロバイダーの使用を強制する場合にのみ、ProviderType プロパティを設定することをお勧めします。
vtbl 29 HRESULT get_LegacyCsp(VARIANT_BOOL* pValue)

プロバイダーが CryptoAPI (レガシー) 暗号化サービスプロバイダー (CSP) であるかどうかを示すブール値を指定または取得します。(Get)

pValueVARIANT_BOOL*outレガシー CSP (CAPI) を使用するかどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

このプロパティを設定すると、指定した LegacyCsp 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 以前に指定した ProviderName は LegacyCsp プロパティの設定による影響を受けないため、ProviderName プロパティと矛盾する LegacyCsp を設定すると、未定義の動作となり、秘密キーの作成時または開くときに失敗する可能性があります。
vtbl 30 HRESULT put_LegacyCsp(VARIANT_BOOL Value)

プロバイダーが CryptoAPI (レガシー) 暗号化サービスプロバイダー (CSP) であるかどうかを示すブール値を指定または取得します。(Put)

ValueVARIANT_BOOLinレガシー CSP (CAPI) を使用するかどうかを指定する VARIANT_BOOL である。

解説(Remarks)

このプロパティを設定すると、指定した LegacyCsp 値と整合するように次のプロパティが自動的に設定されます。

これらのプロパティは次のように設定されます。 以前に指定した ProviderName は LegacyCsp プロパティの設定による影響を受けないため、ProviderName プロパティと矛盾する LegacyCsp を設定すると、未定義の動作となり、秘密キーの作成時または開くときに失敗する可能性があります。
vtbl 31 HRESULT get_Algorithm(IObjectId** ppValue)

公開キーアルゴリズムのオブジェクト識別子 (OID) を指定または取得します。(Get)

ppValueIObjectId**out鍵アルゴリズムの OID を表す IObjectId オブジェクトを受け取るインターフェイスポインタへのポインタである。

解説(Remarks)

このプロパティは、CspStatus プロパティが呼び出されたときに自動的に設定されます。

vtbl 32 HRESULT put_Algorithm(IObjectId* pValue)

公開キーアルゴリズムのオブジェクト識別子 (OID) を指定または取得します。(Put)

pValueIObjectId*inoptional設定する鍵アルゴリズムの OID を表す IObjectId へのポインタである。

解説(Remarks)

このプロパティは、CspStatus プロパティが呼び出されたときに自動的に設定されます。

vtbl 33 HRESULT get_KeySpec(X509KeySpec* pValue)

秘密キーを署名、暗号化、またはその両方のいずれに使用できるかを示す値を指定または取得します。(Get)

pValueX509KeySpec*out鍵指定 (KeySpec) を受け取る X509KeySpec へのポインタである。

解説(Remarks)

XCN_AT_SIGNATURE の値を指定すると、KeySpec プロパティは KeyUsage プロパティを XCN_NCRYPT_ALLOW_SIGNING_FLAG に自動的に設定します。XCN_AT_KEYEXCHANGE を指定すると、KeyUsage プロパティは XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG に設定されます。KeySpec プロパティは、CryptoAPI を使用して作成された [レガシー] プロバイダーにのみ適用されます。

vtbl 34 HRESULT put_KeySpec(X509KeySpec Value)

秘密キーを署名、暗号化、またはその両方のいずれに使用できるかを示す値を指定または取得します。(Put)

ValueX509KeySpecin設定する鍵指定 (KeySpec) を表す X509KeySpec である。

解説(Remarks)

XCN_AT_SIGNATURE の値を指定すると、KeySpec プロパティは KeyUsage プロパティを XCN_NCRYPT_ALLOW_SIGNING_FLAG に自動的に設定します。XCN_AT_KEYEXCHANGE を指定すると、KeyUsage プロパティは XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG に設定されます。KeySpec プロパティは、CryptoAPI を使用して作成された [レガシー] プロバイダーにのみ適用されます。

vtbl 35 HRESULT get_Length(INT* pValue)

秘密キーの長さをビット単位で指定または取得します。(Get)

pValueINT*out鍵長 (ビット数) を受け取る INT へのポインタである。
vtbl 36 HRESULT put_Length(INT Value)

秘密キーの長さをビット単位で指定または取得します。(Put)

ValueINTin設定する鍵長 (ビット数) を指定する。
vtbl 37 HRESULT get_ExportPolicy(X509PrivateKeyExportFlags* pValue)

秘密キーのエクスポート制約を指定または取得します。(Get)

pValueX509PrivateKeyExportFlags*out鍵のエクスポートポリシーを受け取る X509PrivateKeyExportFlags へのポインタである。
vtbl 38 HRESULT put_ExportPolicy(X509PrivateKeyExportFlags Value)

秘密キーのエクスポート制約を指定または取得します。(Put)

ValueX509PrivateKeyExportFlagsin設定する鍵のエクスポートポリシーを表す X509PrivateKeyExportFlags である。
vtbl 39 HRESULT get_KeyUsage(X509PrivateKeyUsageFlags* pValue)

秘密キーを使用できる特定の目的を示す値を指定または取得します。(Get)

pValueX509PrivateKeyUsageFlags*out鍵の用途を受け取る X509PrivateKeyUsageFlags へのポインタである。

解説(Remarks)

レガシー CSP の KeySpec プロパティを XCN_NCRYPT_ALLOW_SIGNING_FLAG に設定すると、KeyUsage プロパティは XCN_NCRYPT_ALLOW_SIGNING_FLAG に設定されます。XCN_AT_KEYEXCHANGE を指定すると、KeyUsage プロパティは自動的に XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG に設定されます。

vtbl 40 HRESULT put_KeyUsage(X509PrivateKeyUsageFlags Value)

秘密キーを使用できる特定の目的を示す値を指定または取得します。(Put)

ValueX509PrivateKeyUsageFlagsin設定する鍵の用途を表す X509PrivateKeyUsageFlags である。

解説(Remarks)

レガシー CSP の KeySpec プロパティを XCN_NCRYPT_ALLOW_SIGNING_FLAG に設定すると、KeyUsage プロパティは XCN_NCRYPT_ALLOW_SIGNING_FLAG に設定されます。XCN_AT_KEYEXCHANGE を指定すると、KeyUsage プロパティは自動的に XCN_NCRYPT_ALLOW_DECRYPT_FLAG | XCN_NCRYPT_ALLOW_KEY_AGREEMENT_FLAG に設定されます。

vtbl 41 HRESULT get_KeyProtection(X509PrivateKeyProtection* pValue)

秘密キーが使用前にどのように保護されるかを示す値を指定または取得します。(Get)

pValueX509PrivateKeyProtection*out鍵の保護レベルを受け取る X509PrivateKeyProtection へのポインタである。
vtbl 42 HRESULT put_KeyProtection(X509PrivateKeyProtection Value)

秘密キーが使用前にどのように保護されるかを示す値を指定または取得します。(Put)

ValueX509PrivateKeyProtectionin設定する鍵の保護レベルを表す X509PrivateKeyProtection である。
vtbl 43 HRESULT get_MachineContext(VARIANT_BOOL* pValue)

ローカル証明書ストアのコンテキストを示すブール値を指定または取得します。(Get)

pValueVARIANT_BOOL*outマシンコンテキストを使用するかどうかを受け取る VARIANT_BOOL へのポインタである。
vtbl 44 HRESULT put_MachineContext(VARIANT_BOOL Value)

ローカル証明書ストアのコンテキストを示すブール値を指定または取得します。(Put)

ValueVARIANT_BOOLinマシンコンテキストを使用するかどうかを指定する VARIANT_BOOL である。
vtbl 45 HRESULT get_SecurityDescriptor(LPWSTR* pValue)

秘密キーのセキュリティ記述子を指定または取得します。(Get)

pValueLPWSTR*out鍵に設定されているセキュリティ記述子 (SDDL 形式) を受け取る文字列ポインタである。

解説(Remarks)

セキュリティ記述子を使用するには、Microsoft Authorization API に含まれる ConvertStringSecurityDescriptorToSecurityDescriptor 関数を呼び出し、GetDefaultSecurityDescriptor メソッドが返す文字列を指定する必要があります。

セキュリティ記述子は、コンピューターおよびユーザーの秘密キーへのアクセスを次のように定義するために使用されます。

キーが開かれていないときに記述子を指定した場合、プロパティ値はキーが開かれたときに設定されます。

vtbl 46 HRESULT put_SecurityDescriptor(LPWSTR Value)

秘密キーのセキュリティ記述子を指定または取得します。(Put)

ValueLPWSTRin設定するセキュリティ記述子 (SDDL 形式) を指定する。

解説(Remarks)

セキュリティ記述子を使用するには、Microsoft Authorization API に含まれる ConvertStringSecurityDescriptorToSecurityDescriptor 関数を呼び出し、GetDefaultSecurityDescriptor メソッドが返す文字列を指定する必要があります。

セキュリティ記述子は、コンピューターおよびユーザーの秘密キーへのアクセスを次のように定義するために使用されます。

キーが開かれていないときに記述子を指定した場合、プロパティ値はキーが開かれたときに設定されます。

vtbl 47 HRESULT get_Certificate(EncodingType Encoding, LPWSTR* pValue)

秘密キーに関連付けられた証明書を格納するバイト配列を指定または取得します。(Get)

EncodingEncodingTypein出力データのエンコード形式を指定する EncodingType である。
pValueLPWSTR*out鍵に関連付けられた証明書 (エンコード済み) を受け取る文字列ポインタである。

解説(Remarks)

キーが開かれていないときに証明書を指定した場合、証明書はキーが開かれたときに設定されます。詳細については、Open メソッドを参照してください。

Certificate プロパティは、IX509PrivateKey オブジェクトに関連付けられた公開キーと、証明書に含まれる公開キーを比較します。2 つのキーは一致している必要があります。

vtbl 48 HRESULT put_Certificate(EncodingType Encoding, LPWSTR Value)

秘密キーに関連付けられた証明書を格納するバイト配列を指定または取得します。(Put)

EncodingEncodingTypein入力データのエンコード形式を指定する EncodingType である。
ValueLPWSTRin鍵に関連付ける証明書 (エンコード済み) を指定する。

解説(Remarks)

キーが開かれていないときに証明書を指定した場合、証明書はキーが開かれたときに設定されます。詳細については、Open メソッドを参照してください。

Certificate プロパティは、IX509PrivateKey オブジェクトに関連付けられた公開キーと、証明書に含まれる公開キーを比較します。2 つのキーは一致している必要があります。

vtbl 49 HRESULT get_UniqueContainerName(LPWSTR* pValue)

キーコンテナーの一意の名前を取得します。

pValueLPWSTR*out鍵の一意な (内部的な) コンテナー名を受け取る文字列ポインタである。

解説(Remarks)

このプロパティは、ContainerName プロパティ値では十分な識別ができるほど一意でないと考えられる場合に、キーへのアクセス時に使用できる代替名を取得します。通常、この名前はキーコンテナーによって作成されます。たとえば、Cryptography API: Next Generation (CNG) キーストレージプロバイダー (KSP) は、キーを格納する暗号化ファイルの名前を返します。

vtbl 50 HRESULT get_Opened(VARIANT_BOOL* pValue)

秘密キーが開いているかどうかを示すブール値を取得します。

pValueVARIANT_BOOL*out鍵が開かれているかどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

Create メソッドを呼び出して秘密キーを作成し、Open メソッドを呼び出して秘密キーを開くことができます。

vtbl 51 HRESULT get_DefaultContainer(VARIANT_BOOL* pValue)

秘密キーが既定のキーコンテナーを表すかどうかを示すブール値を取得します。

pValueVARIANT_BOOL*out既定のコンテナーを使用するかどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

キーコンテナーは名前によって識別されます。名前はクライアントが指定することも、CSP または KSP がサポートする既定値にすることもできます。たとえば、一部の CSP は現在のユーザーのログオン名を既定のコンテナー名として使用します。

このプロパティ値は、Open または Create メソッドが呼び出されたときに設定されます。

vtbl 52 HRESULT get_Existing(VARIANT_BOOL* pValue)

秘密キーが作成済みまたはインポート済みかどうかを示すブール値を指定または取得します。(Get)

pValueVARIANT_BOOL*out既存の鍵を使用するかどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

新しい秘密キーを作成するには、Create メソッドを呼び出します。既存のキーを開くには、Open メソッドを呼び出します。

vtbl 53 HRESULT put_Existing(VARIANT_BOOL Value)

秘密キーが作成済みまたはインポート済みかどうかを示すブール値を指定または取得します。(Put)

ValueVARIANT_BOOLin既存の鍵を使用するかどうかを指定する VARIANT_BOOL である。

解説(Remarks)

新しい秘密キーを作成するには、Create メソッドを呼び出します。既存のキーを開くには、Open メソッドを呼び出します。

vtbl 54 HRESULT get_Silent(VARIANT_BOOL* pValue)

秘密キーへのアクセス時に証明書登録コントロール (Certificate Enrollment Control) がダイアログボックスを表示することを許可するかどうかを示すブール値を指定または取得します。(Get)

pValueVARIANT_BOOL*outUI を表示せずに処理する (サイレントモード) かどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

ユーザーインターフェイスが許可されていないものの、秘密キーへのアクセスに必要な場合、ユーザーインターフェイスを必要とする操作は失敗します。

vtbl 55 HRESULT put_Silent(VARIANT_BOOL Value)

秘密キーへのアクセス時に証明書登録コントロール (Certificate Enrollment Control) がダイアログボックスを表示することを許可するかどうかを示すブール値を指定または取得します。(Put)

ValueVARIANT_BOOLinUI を表示せずに処理する (サイレントモード) かどうかを指定する VARIANT_BOOL である。

解説(Remarks)

ユーザーインターフェイスが許可されていないものの、秘密キーへのアクセスに必要な場合、ユーザーインターフェイスを必要とする操作は失敗します。

vtbl 56 HRESULT get_ParentWindow(INT* pValue)

キー情報の表示に使用するウィンドウの ID を指定または取得します。(Get)

pValueINT*outUI 表示時の親ウィンドウハンドル (値) を受け取る INT へのポインタである。
vtbl 57 HRESULT put_ParentWindow(INT Value)

キー情報の表示に使用するウィンドウの ID を指定または取得します。(Put)

ValueINTinUI 表示時の親ウィンドウハンドル (値) を指定する。
vtbl 58 HRESULT get_UIContextMessage(LPWSTR* pValue)

秘密キーに関連付けられたユーザーインターフェイステキストを含む文字列を指定または取得します。(Get)

pValueLPWSTR*outUI に表示するコンテキストメッセージを受け取る文字列ポインタである。
vtbl 59 HRESULT put_UIContextMessage(LPWSTR Value)

秘密キーに関連付けられたユーザーインターフェイステキストを含む文字列を指定または取得します。(Put)

ValueLPWSTRinUI に表示するコンテキストメッセージを指定する。
vtbl 60 HRESULT put_Pin(LPWSTR Value)

スマートカード上の秘密キーコンテナーにアクセスする前にユーザーを認証するために使用される個人識別番号 (PIN) を指定します。

ValueLPWSTRinスマートカードなどの鍵にアクセスするための PIN を指定する。
vtbl 61 HRESULT get_FriendlyName(LPWSTR* pValue)

秘密キーの表示名を指定または取得します。(Get)

pValueLPWSTR*out鍵の表示名 (フレンドリ名) を受け取る文字列ポインタである。

解説(Remarks)

このプロパティには任意のテキストを指定でき、秘密キーを識別するためにユーザーインターフェイスに表示されることを目的としています。

vtbl 62 HRESULT put_FriendlyName(LPWSTR Value)

秘密キーの表示名を指定または取得します。(Put)

ValueLPWSTRin設定する鍵の表示名 (フレンドリ名) を指定する。

解説(Remarks)

このプロパティには任意のテキストを指定でき、秘密キーを識別するためにユーザーインターフェイスに表示されることを目的としています。

vtbl 63 HRESULT get_Description(LPWSTR* pValue)

秘密キーの説明を含む文字列を指定または取得します。(Get)

pValueLPWSTR*out鍵の説明を受け取る文字列ポインタである。

解説(Remarks)

このプロパティには任意のテキストを指定でき、秘密キーの性質と用途を識別するためにユーザーインターフェイスに表示されることを目的としています。

vtbl 64 HRESULT put_Description(LPWSTR Value)

秘密キーの説明を含む文字列を指定または取得します。(Put)

ValueLPWSTRin設定する鍵の説明を指定する。

解説(Remarks)

このプロパティには任意のテキストを指定でき、秘密キーの性質と用途を識別するためにユーザーインターフェイスに表示されることを目的としています。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IX509PrivateKey "{728AB30C-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IX509PrivateKey IID_IX509PrivateKey "{}"
#comfunc global IX509PrivateKey_Open                     7
#comfunc global IX509PrivateKey_Create                   8
#comfunc global IX509PrivateKey_Close                    9
#comfunc global IX509PrivateKey_Delete                   10
#comfunc global IX509PrivateKey_Verify                   11 int
#comfunc global IX509PrivateKey_Import                   12 wstr,wstr,int
#comfunc global IX509PrivateKey_Export                   13 wstr,int,var
#comfunc global IX509PrivateKey_ExportPublicKey          14 sptr
#comfunc global IX509PrivateKey_get_ContainerName        15 var
#comfunc global IX509PrivateKey_put_ContainerName        16 wstr
#comfunc global IX509PrivateKey_get_ContainerNamePrefix  17 var
#comfunc global IX509PrivateKey_put_ContainerNamePrefix  18 wstr
#comfunc global IX509PrivateKey_get_ReaderName           19 var
#comfunc global IX509PrivateKey_put_ReaderName           20 wstr
#comfunc global IX509PrivateKey_get_CspInformations      21 sptr
#comfunc global IX509PrivateKey_put_CspInformations      22 sptr
#comfunc global IX509PrivateKey_get_CspStatus            23 sptr
#comfunc global IX509PrivateKey_put_CspStatus            24 sptr
#comfunc global IX509PrivateKey_get_ProviderName         25 var
#comfunc global IX509PrivateKey_put_ProviderName         26 wstr
#comfunc global IX509PrivateKey_get_ProviderType         27 var
#comfunc global IX509PrivateKey_put_ProviderType         28 int
#comfunc global IX509PrivateKey_get_LegacyCsp            29 var
#comfunc global IX509PrivateKey_put_LegacyCsp            30 int
#comfunc global IX509PrivateKey_get_Algorithm            31 sptr
#comfunc global IX509PrivateKey_put_Algorithm            32 sptr
#comfunc global IX509PrivateKey_get_KeySpec              33 var
#comfunc global IX509PrivateKey_put_KeySpec              34 int
#comfunc global IX509PrivateKey_get_Length               35 var
#comfunc global IX509PrivateKey_put_Length               36 int
#comfunc global IX509PrivateKey_get_ExportPolicy         37 var
#comfunc global IX509PrivateKey_put_ExportPolicy         38 int
#comfunc global IX509PrivateKey_get_KeyUsage             39 var
#comfunc global IX509PrivateKey_put_KeyUsage             40 int
#comfunc global IX509PrivateKey_get_KeyProtection        41 var
#comfunc global IX509PrivateKey_put_KeyProtection        42 int
#comfunc global IX509PrivateKey_get_MachineContext       43 var
#comfunc global IX509PrivateKey_put_MachineContext       44 int
#comfunc global IX509PrivateKey_get_SecurityDescriptor   45 var
#comfunc global IX509PrivateKey_put_SecurityDescriptor   46 wstr
#comfunc global IX509PrivateKey_get_Certificate          47 int,var
#comfunc global IX509PrivateKey_put_Certificate          48 int,wstr
#comfunc global IX509PrivateKey_get_UniqueContainerName  49 var
#comfunc global IX509PrivateKey_get_Opened               50 var
#comfunc global IX509PrivateKey_get_DefaultContainer     51 var
#comfunc global IX509PrivateKey_get_Existing             52 var
#comfunc global IX509PrivateKey_put_Existing             53 int
#comfunc global IX509PrivateKey_get_Silent               54 var
#comfunc global IX509PrivateKey_put_Silent               55 int
#comfunc global IX509PrivateKey_get_ParentWindow         56 var
#comfunc global IX509PrivateKey_put_ParentWindow         57 int
#comfunc global IX509PrivateKey_get_UIContextMessage     58 var
#comfunc global IX509PrivateKey_put_UIContextMessage     59 wstr
#comfunc global IX509PrivateKey_put_Pin                  60 wstr
#comfunc global IX509PrivateKey_get_FriendlyName         61 var
#comfunc global IX509PrivateKey_put_FriendlyName         62 wstr
#comfunc global IX509PrivateKey_get_Description          63 var
#comfunc global IX509PrivateKey_put_Description          64 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。