AcquireCredentialsHandle (Schannel) 関数は、セキュリティ プリンシパルの既存の資格情報へのハンドルを取得します。 このハンドルは、 InitializeSecurityContext (Schannel) 関数と AcceptSecurityContext (Schannel) 関数で必要です。 これらは、ここでは説明されていないシステム ログオンによって確立される既存の 資格情報か、呼び出し元が代替資格情報を提供できます。
注
これは "ネットワークへのログオン" ではなく、資格情報の収集を意味するものではありません。
構文
SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
_In_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_opt_ PLUID pvLogonID,
_In_opt_ PVOID pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_In_opt_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
パラメーター
pszPrincipal[in, optional]
ハンドルが参照する資格情報を持つプリンシパルの名前を指定する null で終わる文字列へのポインター。
Schannel SSP を使用する場合、このパラメーターは使用されず、 NULLに設定する必要があります。
注
ハンドルを要求するプロセスが資格情報にアクセスできない場合、関数はエラーを返します。 null 文字列は、プロセスで実行されている セキュリティ コンテキスト のユーザーの資格情報へのハンドルが必要であることを示します。
pszPackage[in]
これらの資格情報を使用する セキュリティ パッケージ の名前を指定する null で終わる文字列へのポインター。 これは、EnumerateSecurityPackages 関数によって返される SecPkgInfo 構造体の Name メンバーで返されるセキュリティ パッケージ名です。 コンテキストが確立されると、 queryContextAttributes (Schannel) を ulAttribute を SECPKG_ATTR_PACKAGE_INFO に設定して呼び出し、使用中の セキュリティ パッケージ に関する情報を返すことができます。
Schannel SSP を使用する場合は、このパラメーターを UNISP_NAME に設定します。
注
AcquireCredentialsHandle (Schannel) を呼び出した後に InitializeSecurityContext (Schannel) を呼び出すときに問題が発生したカーネル モードの呼び出し元は、pszPackage を SCHANNEL_NAME に設定することもできます。
fCredentialUse[in]
これらの資格情報の使用方法を示すフラグ。 このパラメーターには、次のいずれかの値を指定できます。
| 価値 | 意味 |
|---|---|
| SECPKG_CRED_INBOUND | 受信サーバーの資格情報を検証します。 InitializeSecurityContext (Schannel) または AcceptSecurityContext (Schannel) が呼び出されたときに、認証機関を使用して受信資格情報を検証できます。 このような権限を使用できない場合、関数は失敗し、 SEC_E_NO_AUTHENTICATING_AUTHORITYを返します。 検証はパッケージ固有です。 |
| SECPKG_CRED_OUTBOUND | ローカル クライアントの資格情報で送信トークンを準備できるようにします。 |
pvLogonID[in, optional]
ユーザーを識別する ローカル一意識別子 (LUID) へのポインター。 このパラメーターは、ネットワーク リダイレクターなどのファイル システム プロセスに対して提供されます。 このパラメーターは NULLできます。
Schannel SSP を使用する場合、このパラメーターは使用されず、 NULLに設定する必要があります。
pAuthData[in, optional]
パッケージ固有のデータへのポインター。 このパラメーターは NULLできます。これは、その セキュリティ パッケージ の既定の資格情報を使用する必要があることを示します。 指定された資格情報を使用するには、このパラメーターにこれらの資格情報を含む SEC_WINNT_AUTH_IDENTITY 構造体を渡します。 RPC ランタイムは、 RpcBindingSetAuthInfo で指定されたものを渡します。
Schannel SSP を使用する場合は、使用するプロトコルと、さまざまなカスタマイズ可能なチャネル機能の設定を示す SCH_CREDENTIALS 構造を指定します。
pGetKeyFn[in, optional]
このパラメーターは使用されず、 NULLに設定する必要があります。
pvGetKeyArgument[in, optional]
このパラメーターは使用されず、 NULLに設定する必要があります。
phCredential[out]
資格情報ハンドルを受け取る CredHandle 構造体へのポインター。
ptsExpiry[out, optional]
返された資格情報の有効期限が切れる時刻を受け取る TimeStamp 構造体へのポインター。 この TimeStamp 構造体で返される値は、 制約付き委任によって異なります。 セキュリティ パッケージは、ローカル時刻でこの値を返す必要があります。
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 (Schannel) 関数は、特定の制約付き委任で使用されるプリンシパル (ユーザーやクライアントなど) の資格情報へのハンドルを返します。 これは、既存の資格情報のハンドルであるか、関数が新しい資格情報のセットを作成して返すことができます。 このハンドルは、 AcceptSecurityContext (Schannel) 関数と InitializeSecurityContext (Schannel) 関数の後続の呼び出し で 使用できます。
一般 に、AcquireCredentialsHandle (Schannel) では、プロセスが同じコンピューターにログオンしている他のユーザーの資格情報のハンドルを取得することはできません。 ただし、 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) |
こちらもご覧ください
AcceptSecurityContext (Schannel)