SspiAcquireCredentialsHandleAsyncA 関数 (sspi.h)

  • [アーティクル]

SspiAcquireCredentialsHandleAsyncA 関数は、セキュリティ プリンシパルの既存の資格情報へのハンドルを非同期的に取得します。

このハンドルは、 SspiInitializeSecurityContextAsync 関数と SspiAcceptSecurityContextAsync 関数で必要です。 これらは、ここでは説明されていないシステム ログオンを介して確立される既存の 資格情報か、呼び出し元が代替資格情報を提供できます。

注意

この関数は、 AcquireCredentialsHandle に対応する非同期関数として機能します。

構文

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncA(
  SspiAsyncContext *AsyncContext,
  LPSTR            pszPrincipal,
  LPSTR            pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

パラメーター

AsyncContext

非同期呼び出しコンテキスト。

pszPrincipal

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

pszPackage

これらの資格情報を使用する セキュリティ パッケージ の名前を指定する null で終わる文字列へのポインター。

「AcquireCredentialsHandleA: pszPackage」を参照してください。

fCredentialUse

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

値
意味
SECPKG_CRED_INBOUND 受信サーバーの資格情報を検証します。 SspiInitializeSecurityContextAsync または SspiAcceptSecurityContextAsync が呼び出されたときに、認証機関を使用して受信資格情報を検証できます。 このような権限が使用できない場合、関数は失敗し、 SEC_E_NO_AUTHENTICATING_AUTHORITYを返します。 検証はパッケージ固有です。
SECPKG_CRED_OUTBOUND ローカル クライアントの資格情報で送信トークンを準備できるようにします。

pvLogonId

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

pAuthData

Schannel パッケージと Negotiate パッケージの両方の認証データを指定する CREDSSP_CRED 構造体へのポインター。

pGetKeyFn

GetKey() 関数へのポインター。

pvGetKeyArgument

GetKey() に渡します。

phCredential

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

ptsExpiry

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

戻り値

資格情報ハンドルを取得するための非同期要求が正常にキューに登録された場合は、 SEC_E_OK を返します。 それ以外の場合は、キューに入ろうとして生成されたエラーを返します。 操作の状態を取得するには、 SspiGetAsyncCallStatus を使用します。

ハンドルが取得された場合、SspiGetAsyncCallStatus は SEC_E_OKを返します。 それ以外の場合は、呼び出しがまだ進行中の場合、 または 次の表に示す致命的なエラー コードのいずれかをSEC_I_ASYNC_CALL_PENDING返す可能性があります。

リターン コード
説明
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 パッケージに指定された資格情報が認識されませんでした。

注釈

SspiAcquireCredentialsHandleAsyncA 関数は、特定のセキュリティ パッケージで使用される、ユーザーやクライアントなどのプリンシパルの資格情報へのハンドルを返します。 関数は、既存の資格情報または新しく作成された資格情報のいずれかにハンドルを返し、それを返すことができます。 このハンドルは、 SspiAcceptSecurityContextAsync 関数と SspiInitializeSecurityContextAsync 関数の後続の呼び出しで使用できます。

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

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

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

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

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

要件

要件 値
サポートされている最小のクライアント Windows 10バージョン 1607 [カーネル モード ドライバーのみ]
サポートされている最小のサーバー Windows Server 2016 [カーネル モード ドライバーのみ]
Header sspi.h

こちらもご覧ください

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

SSPI 関数