AcquireCredentialsHandle (General) 函式
AcquireCredentialsHandle (General) 函式會取得預先存在安全性主體認證的控制碼。 InitializeSecurityCoNtext (General) 和AcceptSecurityCoNtext (General) 函式都需要此控制碼。 這些可以是預先存在的認證，這些認證是透過此處未描述的系統登入所建立，或者呼叫端可以提供替代認證。
注意
這不是「登入網路」，並不表示收集認證。
如需搭配特定 安全性支援提供者 使用此函式的相關資訊， (SSP) ，請參閱下列主題。
| 主題 | 描述 |
|---|---|
|
AcquireCredentialsHandle (CredSSP) |
取得使用認證安全性支援提供者 (CredSSP) 之安全性主體的既有認證控制碼。 |
|
AcquireCredentialsHandle (Digest) |
取得使用 Digest 之安全性主體的既有認證控制碼。 |
|
AcquireCredentialsHandle (Kerberos) |
取得控制碼，以預先存在使用 Kerberos 的安全性主體認證。 |
|
AcquireCredentialsHandle (Negotiate) |
取得控制碼，以預先存在使用 Negotiate 的安全性主體認證。 |
|
AcquireCredentialsHandle (NTLM) |
取得使用 NTLM 之安全性主體預先存在認證的控制碼。 |
|
AcquireCredentialsHandle (安全通道) |
取得使用安全通道之安全性主體的既有認證控制碼。 |
語法
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 終止字串的指標，指定控制碼將參考其認證之主體的名稱。
使用摘要式 SSP 時，此參數是選擇性的。
使用安全通道 SSP 時，不會使用此參數，而且應該設定為 Null。
注意
如果要求控制碼的進程無法存取認證，函式會傳回錯誤。 Null 字串表示進程需要其執行 安全性內容 之使用者的認證控制碼。
-
pszPackage [in]
-
Null 終止字串的指標，指定將使用這些認證 的安全性套件 名稱。 這是EnumerateSecurityPackages函式所傳回的 SecPkgInfo結構Name成員中傳回的安全性套件名稱。 建立內容之後，可以使用ulAttribute設定為 SECPKG_ATTR_PACKAGE_INFO 呼叫QueryCoNtextAttributes (General) ，以傳回使用中安全性套件的相關資訊。
使用摘要式 SSP 時，請將此參數設定為 WDIGEST_SP_NAME。
使用安全通道 SSP 時，請將此參數設定為 UNISP_NAME。
-
fCredentialUse [in]
-
指出如何使用這些認證的旗標。 此參數可以是下列其中一個值。
值 意義 - SECPKG_CRED_AUTOLOGON_RESTRICTED
- 0x00000010
安全性不會使用認證 管理員的預設登入認證或認證。
只有交涉 限制委派才支援這個值。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援這個值。- SECPKG_CRED_BOTH
驗證傳入認證，或使用本機認證來準備傳出權杖。 此旗標會啟用其他兩個旗標。 此旗標對摘要和通道 SSP 無效。 - SECPKG_CRED_INBOUND
驗證傳入的伺服器認證。 呼叫 InitializeSecurityCoNtext (一般) 或 AcceptSecurityCoNtext (一般 ) 時，可能會使用驗證授權單位來驗證輸入認證。 如果無法使用這類授權單位，函式將會失敗並傳回SEC_E_NO_AUTHENTICATING_AUTHORITY。 驗證是套件特定的。 - SECPKG_CRED_OUTBOUND
允許本機用戶端認證準備傳出權杖。 - SECPKG_CRED_PROCESS_POLICY_ONLY
- 0x00000020
函式會處理伺服器原則並傳回 SEC_E_NO_CREDENTIALS，指出應用程式應該提示輸入認證。
只有交涉 限制委派才支援這個值。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援這個值。 -
pvLogonID [in]
-
本機 唯一識別碼 的指標， (LUID) 識別使用者。 這個參數會提供給檔案系統進程，例如網路重新導向器。 此參數可以是 Null。
使用安全通道 SSP 時，不會使用此參數，而且應該設定為 Null。
-
pAuthData [in]
-
套件特定資料的指標。 這個參數可以是 Null，這表示必須使用該 安全性套件 的預設認證。 若要使用提供的認證，請傳遞包含此參數中這些認證的 SEC_WINNT_AUTH_IDENTITY 結構。 RPC 執行時間會通過 RpcBindingSetAuthInfo中提供的任何專案。
使用摘要式 SSP 時，此參數是 SEC_WINNT_AUTH_IDENTITY 結構的指標，其中包含用來尋找認證的驗證資訊。
使用安全通道 SSP 時，請指定 SCHANNEL_CRED 結構，指出要使用的通訊協定，以及各種可自訂通道功能的設定。
使用 NTLM 或 Negotiate 套件時，使用者名稱、密碼和網域的最大字元長度分別為 256、256 和 15。
-
pGetKeyFn [in]
-
不會使用此參數，而且應該設定為 Null。
-
pvGetKeyArgument [in]
-
不會使用此參數，而且應該設定為 Null。
-
phCredential [out]
-
要接收認證控制碼的 CredHandle 結構的指標。
-
ptsExpiry [out]
-
TimeStamp結構的指標，可接收傳回認證到期的時間。 這個 TimeStamp 結構中傳回的值取決於 限制委派。 安全性套件必須在當地時間傳回此值。
此參數設定為常數最大時間。 摘要 式安全性內容或認證在使用摘要式 SSP 時，沒有到期時間。
使用安全通道 SSP 時，此參數是選擇性的。 當要用於驗證的認證是憑證時，此參數會收到該憑證的到期時間。 如果未提供任何憑證，則會傳回最大時間值。
傳回值
如果函式成功，函式會傳回SEC_E_OK。
如果函式失敗，它會傳回下列其中一個錯誤碼。
| 傳回碼 | 描述 |
|---|---|
|
記憶體不足，無法完成要求的動作。 |
|
未對應至 SSPI 錯誤碼的錯誤。 |
|
限制委派中沒有可用的認證。 |
|
函式的呼叫端沒有必要的認證。 |
|
要求 的安全性套件 不存在。 |
|
無法辨識提供給封裝的認證。 |
備註
AcquireCredentialsHandle (General) 函式會傳回主體的認證控制碼，例如使用者或用戶端，如特定限制委派所使用。 這可以是預先存在認證的控制碼，或者函式可以建立一組新的認證，並傳回它。 此控制碼可用於對 AcceptSecurityCoNtext (General) 和 InitializeSecurityCoNtext (General) 函式的後續呼叫。
一般而言， AcquireCredentialsHandle (一般) 不允許進程取得其他使用者登入相同電腦的認證控制碼。 不過，具有SE_TCB_NAME 許可權 的呼叫端可以選擇指定任何現有登入會話權杖的登入 識別碼 (LUID) ，以取得該會話認證的控制碼。 一般而言，這是由必須代表登入使用者的核心模式模組使用。
套件可能會在 RPC 執行時間傳輸所提供的 pGetKeyFn 中呼叫 函式。 如果傳輸不支援擷取認證的回呼概念，此參數必須是 Null。
對於核心模式呼叫端，必須注意下列差異：
- 這兩個字串參數必須是 Unicode 字串。
- 緩衝區值必須配置在進程虛擬記憶體中，而不是從集區配置。
當您完成使用傳回的認證時，請呼叫 FreeCredentialsHandle 函式來釋放認證所使用的記憶體。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows Server 2003 [僅限傳統型應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|
| Unicode 與 ANSI 名稱 |
AcquireCredentialsHandleW (Unicode) 和 AcquireCredentialsHandleA (ANSI) |
另請參閱