共用方式為

AcquireCredentialsHandle (NTLM) 函式

  • 發行項

AcquireCredentialsHandle (NTLM) 函式會取得預先存在安全性主體認證的控制碼。 InitializeSecurityCoNtext (NTLM) 和 AcceptSecurityCoNtext (NTLM) 函式都需要此控制碼。 這些可以是預先存在的 認證，這些認證是透過此處未描述的系統登入所建立，或者呼叫端可以提供替代認證。

注意

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

 

語法

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

參數

pszPrincipal [in]

Null 終止字串的指標，指定控制碼將參考其認證之主體的名稱。

注意

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

 

pszPackage [in]

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

fCredentialUse [in]

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

值 意義
SECPKG_CRED_BOTH
 驗證傳入認證，或使用本機認證來準備傳出權杖。 此旗標會啟用其他兩個旗標。
SECPKG_CRED_INBOUND
 驗證傳入的伺服器認證。 當呼叫 InitializeSecurityCoNtext (NTLM) 或 AcceptSecurityCoNtext (NTLM ) 時，可能會使用驗證授權單位來驗證輸入認證。 如果無法使用這類授權單位，函式將會失敗並傳回SEC_E_NO_AUTHENTICATING_AUTHORITY。 驗證是套件特定的。
SECPKG_CRED_OUTBOUND
 允許本機用戶端認證準備傳出權杖。

 

pvLogonID [in]

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

pAuthData [in]

套件特定資料的指標。 這個參數可以是 Null，這表示必須使用該 安全性套件 的預設認證。 若要使用提供的認證，請傳遞包含此參數中這些認證的 SEC_WINNT_AUTH_IDENTITY 結構。 RPC 執行時間會通過 RpcBindingSetAuthInfo中提供的任何專案。

使用 NTLM 套件時，使用者名稱、密碼和網域的最大字元長度分別為 256、256 和 15。

pGetKeyFn [in]

不會使用此參數，而且應該設定為 Null。

pvGetKeyArgument [in]

不會使用此參數，而且應該設定為 Null。

phCredential [out]

要接收認證控制碼的 CredHandle 結構的指標。

ptsExpiry [out]

TimeStamp結構的指標，可接收傳回認證到期的時間。 這個 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 (NTLM) 函式會傳回主體認證控制碼，例如使用者或用戶端，如特定限制委派所使用的。 這可以是預先存在的認證控制碼，或者函式可以建立一組新的認證並傳回它。 此控制碼可用於 後續對 AcceptSecurityCoNtext (NTLM) 和 InitializeSecurityCoNtext (NTLM) 函式的呼叫。

一般而言， AcquireCredentialsHandle (NTLM) 不允許進程取得其他使用者登入相同電腦的認證控制碼。 不過，具有SE_TCB_NAME 許可權 的呼叫端可以選擇指定 登入識別碼 (LUID) 任何現有的登入會話權杖，以取得該會話認證的控制碼。 一般而言，這是由必須代表登入使用者的核心模式模組使用。

封裝可能會在 RPC 執行時間傳輸所提供的 pGetKeyFn 中呼叫 函式。 如果傳輸不支援擷取認證的回呼概念，此參數必須是 Null。

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

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

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

規格需求

需求 值
最低支援的用戶端
 Windows XP [僅限傳統型應用程式]
最低支援的伺服器
 Windows Server 2003 [僅限桌面應用程式]
標頭
Sspi.h (包含 Security.h)
程式庫
Secur32.lib
DLL
Secur32.dll
Unicode 與 ANSI 名稱
 AcquireCredentialsHandleW (Unicode) 和 AcquireCredentialsHandleA (ANSI)

另請參閱

SSPI 函式

AcceptSecurityCoNtext (NTLM)

InitializeSecurityCoNtext (NTLM)

FreeCredentialsHandle