AcquireCredentialsHandle (CredSSP) 関数
AcquireCredentialsHandle (CredSSP) 関数は、セキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。 このハンドルは、 InitializeSecurityContext (CredSSP) 関数と AcceptSecurityContext (CredSSP) 関数で 必要です。 これらは、ここでは説明されていないシステム ログオンを介して確立される既存の 資格情報か、呼び出し元が代替資格情報を提供できます。
Note
これは "ネットワークへのログオン" ではなく、資格情報の収集を意味するものではありません。
構文
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle(
_In_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ unsigned long fCredentialUse,
_In_opt_ void *pvLogonID,
_In_opt_ void *pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_Reserved_ void *pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
パラメーター
pszPrincipal [in, optional]
ハンドルが参照する資格情報を持つプリンシパルの名前を指定する、null で終わる文字列へのポインター。
Note
ハンドルを要求するプロセスが資格情報にアクセスできない場合、関数はエラーを返します。 null 文字列は、プロセスで実行されているセキュリティ コンテキストを持つユーザーの資格情報へのハンドルが必要であることを示します。
pszPackage [in]
これらの資格情報を使用するセキュリティ パッケージの名前を指定する null で終わる文字列へのポインター。 これは、EnumerateSecurityPackages 関数によって返される SecPkgInfo 構造体の Name メンバーで返されるセキュリティ パッケージ名です。 コンテキストが確立されると、 QueryContextAttributes (CredSSP) を ulAttribute を SECPKG_ATTR_PACKAGE_INFO に設定して呼び出して、使用中のセキュリティ パッケージに関する情報を返すことができます。
fCredentialUse [in]
これらの資格情報の使用方法を示すフラグ。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 説明 |
|---|---|
|
SECPKG_CRED_INBOUND 0x1 |
受信サーバーの資格情報を検証します。 InitializeSecurityContext (CredSSP) または AcceptSecurityContext (CredSSP) が呼び出されたときに、認証機関を使用して受信資格情報を検証できます。 このような権限が使用できない場合、関数は失敗し、 SEC_E_NO_AUTHENTICATING_AUTHORITYを返します。 検証はパッケージ固有です |
|
SECPKG_CRED_OUTBOUND 0x0 |
ローカル クライアントの資格情報で送信トークンを準備できるようにします。 |
pvLogonId [in, optional]
ユーザーを識別する ローカル一意識別子 (LUID) へのポインター。 このパラメーターは、ネットワーク リダイレクターなどのファイル システム プロセスに対して提供されます。 このパラメーターは、NULL でもかまいません。
pAuthData [in, optional]
Schannel パッケージと Negotiate パッケージの両方の認証データを指定する CREDSSP_CRED 構造体へのポインター。
pGetKeyFn [in, optional]
予約済み。 このパラメーターは使用されず、 NULL に設定する必要があります。
pvGetKeyArgument [in, optional]
予約済み。 このパラメーターは NULL に設定する必要があります。
phCredential [out]
資格情報ハンドルを受け取る CredHandle 構造体へのポインター。
ptsExpiry [out, optional]
返された資格情報の有効期限が切れる時刻を受け取る 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 (CredSSP) 関数は、特定のセキュリティ パッケージで使用される、ユーザーやクライアントなどのプリンシパルの資格情報へのハンドルを返します。 関数は、既存の資格情報または新しく作成された資格情報のいずれかにハンドルを返し、それを返すことができます。 このハンドルは、AcceptSecurityContext (CredSSP) 関数と InitializeSecurityContext (CredSSP) 関数の後続の呼び出しで使用できます。
一般 に、AcquireCredentialsHandle (CredSSP) は、同じコンピューターにログオンしている他のユーザーの資格情報を提供しません。 ただし、SE_TCB_NAME 特権 を持つ呼び出し元は、そのセッションの ログオン識別子 (LUID) を指定することで、既存のログオン セッションの資格情報を取得できます。 通常、これは、ログオンしているユーザーの代わりに動作する必要があるカーネル モード モジュールで使用されます。
パッケージは、RPC ランタイム トランスポートによって提供される pGetKeyFn の関数を呼び出す場合があります。 トランスポートが資格情報を取得するためのコールバックの概念をサポートしていない場合、このパラメーターは NULL である必要があります。
カーネル モードの呼び出し元の場合は、次の違いに注意する必要があります。
- 2 つの文字列パラメーターは Unicode 文字列である必要があります。
- バッファー値は、プールからではなく、プロセス仮想メモリに割り当てる必要があります。
返された資格情報の使用が完了したら、 FreeCredentialsHandle 関数を呼び出して、資格情報で使用されるメモリを解放します。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| ヘッダー | Sspi.h (Security.h を含む) |
| ライブラリ | Secur32.lib |
| [DLL] | Secur32.dll |
| Unicode 名と ANSI 名 | AcquireCredentialsHandleW (Unicode) と AcquireCredentialsHandleA (ANSI) |