共用方式為

AcquireCredentialsHandleA 函式 （sspi.h）

  • 發行項

AcquireCredentialsHandle （CredSSP） 函式會取得 安全性主體 預先 存在的句柄。 InitializeSecurityContext （CredSSP） 和 AcceptSecurityContext （CredSSP） 函式都需要此句柄。 這些認證可以是預先存在的 認證，這些認證是透過此處未描述的系統登入所建立，或呼叫者可以提供替代認證。

注意 這不是「登入網路」，也不表示收集認證。
 

語法

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [in]            unsigned long  fCredentialUse,
  [in, optional]  void           *pvLogonId,
  [in, optional]  void           *pAuthData,
  [in, optional]  SEC_GET_KEY_FN pGetKeyFn,
  [in, optional]  void           *pvGetKeyArgument,
  [out]           PCredHandle    phCredential,
  [out, optional] PTimeStamp     ptsExpiry
);

參數

[in, optional] pszPrincipal

Null 終止字串的指標，指定句柄所參考之認證之主體的名稱。

注意 如果要求句柄的進程無法存取認證，函式會傳回錯誤。 Null 字串表示進程需要使用者的認證句柄，其 安全性內容 執行的用戶認證。
 

[in] pszPackage

Null 終止字串的指標，指定將使用這些認證 安全性套件的名稱。 這是 EnumerateSecurityPackages 函式所傳回 SecPkgInfo 結構 Name 成員中傳回的安全性套件名稱。 建立內容之後，QueryContextAttributes （CredSSP） 可以呼叫，並將 ulAttribute 設為 SECPKG_ATTR_PACKAGE_INFO，以傳回使用中安全性套件的相關信息。

[in] fCredentialUse

旗標，指出如何使用這些認證。 此參數可以是下列其中一個值。

價值 意義
SECPKG_CRED_INBOUND
0x1
 驗證傳入的伺服器認證。 呼叫 InitializeSecurityContext （CredSSP） 或 AcceptSecurityContext （CredSSP） 時，可能會使用驗證授權單位來驗證輸入認證。 如果無法使用這類授權單位，函式將會失敗並傳回 SEC_E_NO_AUTHENTICATING_AUTHORITY。 驗證是套件專屬的。
SECPKG_CRED_OUTBOUND
0x2
 允許本機客戶端認證準備傳出令牌。

[in, optional] pvLogonId

識別使用者的本機唯一標識碼 （LUID） 指標。 此參數會提供給檔案系統進程，例如網路重新導向器。 此參數可以是 NULL。

[in, optional] pAuthData

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

[in, optional] pGetKeyFn

保留。 不使用此參數，而且應該設定為 NULL。

[in, optional] pvGetKeyArgument

保留。 這個參數必須設定為 NULL。

[out] phCredential

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

[out, optional] ptsExpiry

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。

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

  • 這兩個字串參數必須 Unicode 字串。
  • 緩衝區值必須配置於進程虛擬記憶體中，而不是從集區配置。
當您完成使用傳回的認證時，請呼叫 FreeCredentialsHandle 函式來釋放認證所使用的記憶體。

注意

sspi.h 標頭會根據 UNICODE 預處理器常數的定義，將 AcquireCredentialsHandle 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 sspi.h （include Security.h）
連結庫 Secur32.lib
DLL Secur32.dll

另請參閱

AcceptSecurityContext （CredSSP）

FreeCredentialsHandle

InitializeSecurityContext （CredSSP）

SSPI 函式