AcquireCredentialsHandle (General) 関数

AcquireCredentialsHandle (General) 関数は、セキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。 このハンドルは、 InitializeSecurityContext (General) 関数と AcceptSecurityContext (General) 関数で必要です。 これらは、ここでは説明されていないシステム ログオンによって確立される既存の資格情報か、呼び出し元が代替資格情報を提供できます。

特定の セキュリティ サポート プロバイダー (SSP) でこの関数を使用する方法については、次のトピックを参照してください。

構文

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

パラメーター

pszPrincipal [in]

ハンドルが参照する資格情報を持つプリンシパルの名前を指定する null で終わる文字列へのポインター。

Digest SSP を使用する場合、このパラメーターは省略可能です。

Schannel SSP を使用する場合、このパラメーターは使用されず、 NULL に設定する必要があります。

注

ハンドルを要求するプロセスが資格情報にアクセスできない場合、関数はエラーを返します。 null 文字列は、プロセスで実行されている セキュリティ コンテキスト のユーザーの資格情報へのハンドルが必要であることを示します。

 

pszPackage [in]

これらの資格情報を使用する セキュリティ パッケージ の名前を指定する null で終わる文字列へのポインター。 これは、EnumerateSecurityPackages 関数によって返される SecPkgInfo 構造体の Name メンバーで返されるセキュリティ パッケージ名です。 コンテキストが確立されると、 queryContextAttributes (General) を ulAttribute を SECPKG_ATTR_PACKAGE_INFO に設定して呼び出し、使用中の セキュリティ パッケージ に関する情報を返すことができます。

Digest SSP を使用する場合は、このパラメーターを WDIGEST_SP_NAME に設定します。

Schannel SSP を使用する場合は、このパラメーターを UNISP_NAME に設定します。

fCredentialUse [in]

これらの資格情報の使用方法を示すフラグ。 このパラメーターには、次のいずれかの値を指定できます。

価値	意味
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	セキュリティでは、既定のログオン資格情報や 資格情報マネージャーからの資格情報は使用されません。 この値は、ネゴシエート の制約付き委任でのみサポートされます。 Windows Server 2008、Windows Vista、Windows Server 2003、および Windows XP: この値はサポートされていません。
SECPKG_CRED_BOTH	受信資格情報を検証するか、ローカル資格情報を使用して送信トークンを準備します。 このフラグにより、他のフラグの両方が有効になります。 このフラグは、Digest および Schannel SP では無効です。
SECPKG_CRED_INBOUND	受信サーバーの資格情報を検証します。 InitializeSecurityContext (General) または AcceptSecurityContext (General) が呼び出されると、認証機関を使用して受信資格情報が検証される場合があります。 このような権限を使用できない場合、関数は失敗し、SEC_E_NO_AUTHENTICATING_AUTHORITYを返します。 検証はパッケージ固有です。
SECPKG_CRED_OUTBOUND	ローカル クライアントの資格情報で送信トークンを準備できるようにします。
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	関数はサーバー ポリシーを処理し、 SEC_E_NO_CREDENTIALSを返し、アプリケーションで資格情報の入力を求めるメッセージを表示します。 この値は、ネゴシエート の制約付き委任でのみサポートされます。 Windows Server 2008、Windows Vista、Windows Server 2003、および Windows XP: この値はサポートされていません。

 

pvLogonID [in]

ユーザーを識別する ローカル一意識別子 (LUID) へのポインター。 このパラメーターは、ネットワーク リダイレクターなどのファイル システム プロセスに対して提供されます。 このパラメーターは NULL できます。

Schannel SSP を使用する場合、このパラメーターは使用されず、 NULL に設定する必要があります。

pAuthData [in]

パッケージ固有のデータへのポインター。 このパラメーターには NULL を指定できます。これは、その セキュリティ パッケージ の既定の資格情報を使用する必要があることを示します。 指定された資格情報を使用するには、このパラメーターにこれらの資格情報を含む SEC_WINNT_AUTH_IDENTITY 構造体を渡します。 RPC ランタイムは、 RpcBindingSetAuthInfo で指定されたものを渡します。

Digest SSP を使用する場合、このパラメーターは資格情報の検索に使用する認証情報を含む SEC_WINNT_AUTH_IDENTITY 構造体へのポインターです。

Schannel SSP を使用する場合は、使用するプロトコルと、さまざまなカスタマイズ可能なチャネル機能の設定を示す SCHANNEL_CRED 構造を指定します。

NTLM またはネゴシエート パッケージを使用する場合、ユーザー名、パスワード、ドメインの最大文字数はそれぞれ 256、256、および 15 です。

pGetKeyFn [in]

このパラメーターは使用されず、 NULL に設定する必要があります。

pvGetKeyArgument [in]

このパラメーターは使用されず、 NULL に設定する必要があります。

phCredential [out]

資格情報ハンドルを受け取る CredHandle 構造体へのポインター。

ptsExpiry [out]

返された資格情報の有効期限が切れる時刻を受け取る TimeStamp 構造体へのポインター。 この TimeStamp 構造体で返される値は、 制約付き委任によって異なります。 セキュリティ パッケージは、ローカル時刻でこの値を返す必要があります。

このパラメータは一定の最大時間に設定されます。 ダイジェスト セキュリティ コンテキストまたは資格情報、またはダイジェスト SSP を使用する場合、有効期限はありません。

Schannel SSP を使用する場合、このパラメーターは省略可能です。 認証に使用する資格情報が証明書の場合、このパラメーターはその証明書の有効期限を受け取ります。 証明書が指定されていない場合は、最大時間値が返されます。

戻り値

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

関数が失敗すると、次のいずれかのエラー コードが返されます。

注釈

AcquireCredentialsHandle (General) 関数は、特定の制約付き委任で使用されるプリンシパル (ユーザーやクライアントなど) の資格情報へのハンドルを返します。 これは、既存の資格情報のハンドルであるか、関数が新しい資格情報のセットを作成して返すことができます。 このハンドルは、AcceptSecurityContext (General) 関数と InitializeSecurityContext (General) 関数の後続の呼び出しで使用できます。

一般 に、AcquireCredentialsHandle (General) では、プロセスが同じコンピューターにログオンしている他のユーザーの資格情報のハンドルを取得することはできません。 ただし、SE_TCB_NAME 特権 を持つ呼び出し元には、既存のログオン セッション トークンの ログオン識別子 (LUID) を指定して、そのセッションの資格情報へのハンドルを取得するオプションがあります。 通常、これは、ログオンしているユーザーの代わりに動作する必要があるカーネル モード モジュールによって使用されます。

パッケージは、RPC ランタイム トランスポートによって提供される pGetKeyFn 内の関数を呼び出す場合があります。 トランスポートが資格情報を取得するためのコールバックの概念をサポートしていない場合、このパラメーターは NULL である必要があります。

カーネル モードの呼び出し元の場合は、次の相違点に注意する必要があります。

• 2 つの文字列パラメーターは Unicode 文字列である必要があります。
• バッファー値は、プールからではなく、プロセス仮想メモリに割り当てる必要があります。

返された資格情報の使用が完了したら、 FreeCredentialsHandle 関数を呼び出して、資格情報で使用されるメモリを解放します。

必要条件

こちらもご覧ください

SSPI 関数

AcceptSecurityContext (全般)の

InitializeSecurityContext (General)の

FreeCredentialsHandle