AcquireCredentialsHandle (General) 関数

  • [アーティクル]

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

Note

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

 

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

トピック 説明
AcquireCredentialsHandle (CredSSP)
 資格情報セキュリティ サポート プロバイダー (CredSSP) を使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。
AcquireCredentialsHandle (Digest)
 Digest を使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。
AcquireCredentialsHandle (Kerberos)
 Kerberos を使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。
AcquireCredentialsHandle (ネゴシエート)
 ネゴシエートを使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。
AcquireCredentialsHandle (NTLM)
 NTLM を使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。
AcquireCredentialsHandle (Schannel)
 Schannel を使用しているセキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。

 

構文

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 に設定する必要があります。

Note

ハンドルを要求するプロセスが資格情報にアクセスできない場合、関数はエラーを返します。 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
 受信資格情報を検証するか、ローカル資格情報を使用して送信トークンを準備します。 このフラグは、他の両方のフラグを有効にします。 このフラグは、ダイジェストおよび 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 構造体で返される値は、 制約付き委任によって異なります。 セキュリティ パッケージは、ローカル時刻にこの値を返す必要があります。

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

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

戻り値

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

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

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

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

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

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

必要条件

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

関連項目

SSPI 関数

AcceptSecurityContext (全般)

InitializeSecurityContext (全般)

FreeCredentialsHandle