共用方式為

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

CREDSSP_CRED 結構的指標，指定 Schannel 和 Negotiate 套件的驗證數據。

pGetKeyFn

GetKey () 函式的指標。

pvGetKeyArgument

傳遞至 GetKey () 。

phCredential

將接收認證句柄之 CredHandle 結構的指標。

ptsExpiry

選TimeStamp 結構的指標，可接收傳回認證到期的時間。 收到的結構值取決於安全性套件，必須指定當地時間中的值。

傳回值

如果取得認證句柄的異步要求已成功排入佇列以執行，則傳回 SEC_E_OK 。 否則，它會傳回嘗試將它排入佇列時所產生的錯誤。 若要擷取作業的狀態，請使用 SspiGetAsyncCallStatus。

如果已取得句柄，SspiGetAsyncCallStatus 會傳回 SEC_E_OK。 否則，如果呼叫仍在進行中，或下表中下列任何嚴重錯誤碼，它可能會傳回 SEC_I_ASYNC_CALL_PENDING 。

傳回碼
Description
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。

對於核心模式呼叫端，必須注意下列差異：

  • 這兩個字串參數必須是 Unicode 字串。
  • 緩衝區值必須配置在進程虛擬記憶體中，而不是從集區配置。

當您完成使用傳回的認證時，請呼叫 SspiFreeCredentialsHandleAsync 函式來釋放認證所使用的記憶體。

規格需求

需求 值
最低支援的用戶端 Windows 10 版本 1607 [僅限內核模式驅動程式]
最低支援的伺服器 Windows Server 2016 [僅限內核模式驅動程式]
標頭 sspi.h

另請參閱

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

SSPI 函式