AcquireCredentialsHandle (Negotiate) 関数

[アーティクル]
06/13/2023

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

注意

これは "ネットワークへのログオン" ではなく、資格情報の収集を意味するものではありません。

構文

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 で終わる文字列へのポインター。

注意

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

pszPackage [in]

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

Negotiate SSP を使用してこの関数を正常に呼び出すには、このパラメーターを "Negotiate" に設定します。

fCredentialUse [in]

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

値	説明
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	セキュリティでは、資格情報マネージャーからの既定のログオン資格情報や資格情報は使用されません。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値はサポートされていません。
SECPKG_CRED_BOTH	受信資格情報を検証するか、ローカル資格情報を使用して送信トークンを準備します。このフラグは、他の両方のフラグを有効にします。
SECPKG_CRED_INBOUND	受信サーバーの資格情報を検証します。 InitializeSecurityContext (Negotiate) または AcceptSecurityContext (Negotiate) が呼び出されたときに、認証機関を使用して受信資格情報を検証できます。このような権限が使用できない場合、関数は失敗し、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 でもかまいません。

pAuthData [in]

パッケージ固有のデータへのポインター。このパラメーターには NULL を指定できます。これは、その セキュリティパッケージ の既定の資格情報を使用する必要があることを示します。指定した資格情報を使用するには、前の呼び出しから返された PSEC_WINNT_AUTH_IDENTITY_OPAQUE 構造体を SspiPromptForCredentials 関数に 渡します。

Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP:PSEC_WINNT_AUTH_IDENTITY_OPAQUE型と SspiPromptForCredentials 関数はサポートされていません。指定された資格情報を使用するには、それらの資格情報を含む SEC_WINNT_AUTH_IDENTITY または SEC_WINNT_AUTH_IDENTITY_EX 構造体へのポインターを渡します。

RPC ランタイムは、 RpcBindingSetAuthInfo で指定されたものを渡します。

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

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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

phCredential [out]

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

ptsExpiry [out]

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

戻り値

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

関数が失敗した場合は、次のいずれかのエラーコードが返されます。

リターンコード	説明
SEC_E_INSUFFICIENT_MEMORY	要求されたアクションを完了するのに十分なメモリがありません。
SEC_E_INTERNAL_ERROR	SSPI エラーコードにマップされないエラーが発生しました。
SEC_E_NO_CREDENTIALS	制約付き委任では資格情報を使用できません。
SEC_E_NOT_OWNER	関数の呼び出し元には、必要な資格情報がありません。
SEC_E_SECPKG_NOT_FOUND	要求されたセキュリティパッケージが存在しません。
SEC_E_UNKNOWN_CREDENTIALS	パッケージに指定された資格情報が認識されませんでした。

解説

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

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

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

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

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

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

必要条件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ]
ヘッダー	Sspi.h (Security.h を含む)
ライブラリ	Secur32.lib
[DLL]	Secur32.dll
Unicode 名と ANSI 名	AcquireCredentialsHandleW (Unicode) と AcquireCredentialsHandleA (ANSI)

次の方法で共有

AcquireCredentialsHandle (Negotiate) 関数

構文

パラメーター

戻り値

解説

必要条件

関連項目

フィードバック

その他のリソース