PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET コールバック関数 (wincrypt.h)

[アーティクル]
08/27/2023

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GETコールバック関数はオブジェクトを取得します。この関数は、カスタムプロバイダーの一部として実装する必要があります。この関数は現在、Secure Channel (Schannel) セキュリティパッケージによってのみ呼び出されています。

構文

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

パラメーター

[in, optional] pPluginContext

このプロバイダーによって定義され、 PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE 関数によって返される省略可能なバッファーへのポインター。バッファーは呼び出し元によって変更されません。プロバイダーは、データを使用して、実行するアクションを決定したり、追加情報を維持したりするのに役立ちます。

[in, optional] pIdentifier

オブジェクト識別子を含む CRYPTOAPI_BLOB 構造体へのポインター。この関数の最初の呼び出しでは、この値は常に NULL である必要があります。

[in] dwNameType

pNameBlob パラメーターの名前形式。使用できる値を次に示します。この関数の実装では、Schannel によって渡される CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPEを処理できる必要があります。

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE (1 (0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE (32 (0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE (33 (0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE (0x0000FFFF)

[in] pNameBlob

呼び出し元アプリケーションがオブジェクトを一意に識別するために使用している名前を含むCRYPTOAPI_BLOB構造体へのポインター。プロバイダーはこの名前を使用して、要求されたオブジェクトを検索します。 Schannel は現在、UTF8 でエンコードされた DNS (ドメインネームシステム) ホスト名を送信し、IDN 名を punycode から変換します。

[out] ppbContent

返されるオブジェクトを含むバイト配列へのポインター。

[out] pcbContent

ppbContent パラメーターが指すオブジェクトのサイズ (バイト単位)。

[out] ppwszPassword

オブジェクトの暗号化に使用されるパスワード (存在する場合) を含む Null で終わる Unicode 文字列。オブジェクトが個人情報交換 (PFX) ファイルの場合、通常は暗号化を実行するためにパスワードが使用されます。パスワードが不要な場合、この値は NULL にすることができます。

[out] ppIdentifier

この関数の後続の呼び出し中および変更通知に使用できる省略可能な識別子へのポインターを受け取るアドレス。詳細については、「解説」を参照してください。プロバイダーがこの値を NULL に設定した場合、Schannel は pNameBlob パラメーター値を内部的に使用します。

戻り値

関数が成功した場合は、0 以外 (TRUE) を返します。

関数が失敗した場合は、0 (FALSE) を返し、 SetLastError 関数で適切なエラーを指定します。ほとんどのエラーは変更されずに Schannel 経由で渡されますが、この動作は保証されません。一部のエラーは、他のエラーにマップされる場合があります。

特定の DNS 名 (pNameBlob) または識別子 (pIdentifier) に対してオブジェクトを返すことができない場合は、FALSE を返し、SetLastError 関数でCRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUNDを指定します。

注釈

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET コールバック関数は現在、Secure Channel (Schannel) セキュリティパッケージによってのみ呼び出されています。次のいずれかをカプセル化するオブジェクトを返すことができます。

個人情報交換 (PFX) バイト配列
証明書ストア。
汎用 BLOB。これは現在、Schannel ではサポートされていません。

この関数が最初に呼び出されると、Schannel は pNameBlob 引数に DNS ホスト名を送信して、オブジェクトの対象となるホストを指定します。プロバイダーは、検索するオブジェクトを決定するために、名前を処理する (ワイルドカードに一致する、ファイルパスを作成するなど) 必要があります。

多くのホスト名を 1 つのオブジェクトにマップできるため、プロバイダーは ppIdentifier パラメーターを使用して、暗号化 API (CAPI) 関数によってプロバイダーへの後続の呼び出しで使用できる内部定義識別子を返すことができます。その後、プロバイダーは識別子を使用して、適切なオブジェクトを見つけるのに役立ちます。

要件

要件	値
サポートされている最小のクライアント	Windows 8 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2012 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wincrypt.h

こちらもご覧ください

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

次の方法で共有