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成員中傳回的安全性套件名稱。 建立內容之後，可以使用ulAttribute設定為SECPKG_ATTR_PACKAGE_INFO呼叫QueryCoNtextAttributes (CredSSP) ，以傳回使用中安全性套件的相關資訊。

[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。

如果函式失敗，它會傳回下列其中一個錯誤碼。

傳回碼 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
 無法辨識提供給封裝的認證。

備註

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 [僅限傳統型應用程式]
目標平台 Windows
標頭 sspi.h (包含 Security.h)
程式庫 Secur32.lib
Dll Secur32.dll

另請參閱

AcceptSecurityCoNtext (CredSSP)

FreeCredentialsHandle

InitializeSecurityCoNtext (CredSSP)

SSPI 函式