InitializeSecurityCoNtext （一般）函式

發行項
10/18/2023

InitializeSecurityCoNtext （一般） 函式會從認證控制碼起始用戶端輸出安全性內容。函式可用來建置用戶端應用程式與遠端對等之間的安全性內容。 InitializeSecurityCoNtext （一般） 會傳回用戶端必須傳遞至遠端對等的權杖，而對等會透過 AcceptSecurityCoNtext （一般）呼叫提交至本機安全性實作。所有呼叫端都應該將產生的權杖視為不透明。

一般而言， InitializeSecurityCoNtext （一般） 函式會在迴圈中呼叫，直到建立足夠的安全性內容為止。

如需搭配特定安全性支援提供者使用此函式的相關資訊，請參閱下列主題。

主題	說明
InitializeSecurityCoNtext （CredSSP）	使用認證安全性支援提供者（CredSSP）安全性套件，從認證控制碼起始用戶端輸出安全性內容。
InitializeSecurityCoNtext （摘要）	使用摘要式安全性套件，從認證控制碼起始用戶端輸出安全性內容。
InitializeSecurityCoNtext （Kerberos）	使用 Kerberos 安全性套件，從認證控制碼起始用戶端輸出安全性內容。
InitializeSecurityCoNtext （Negotiate）	使用 Negotiate 安全性套件，從認證控制碼起始用戶端輸出安全性內容。
InitializeSecurityCoNtext （NTLM）	使用 NTLM 安全性套件，從認證控制碼起始用戶端輸出安全性內容。
InitializeSecurityCoNtext （Schannel）	使用安全通道安全性套件，從認證控制碼起始用戶端輸出安全性內容。

語法

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

參數

phCredential[in, optional]

AcquireCredentialsHandle 所傳回 之認證的控制碼（一般）。 此控制碼可用來建置安全性內容。 InitializeSecurityCoNtext （一般） 函式至少需要輸出認證。

phCoNtext[in, optional]

CtxtHandle 結構的指標。在第一次呼叫 InitializeSecurityCoNtext （一般） 時，此指標為 NULL 。在第二次呼叫時，此參數是第一次呼叫在 phNewCoNtext 參數中 傳回之部分格式內容的控制碼指標。

此參數是 Microsoft Digest SSP 的選擇性參數，而且可以設定為 NULL 。

使用 Schannel SSP 時，在第一次呼叫 InitializeSecurityCoNtext （一般） 時，指定 NULL 。在未來的呼叫中，指定第一次呼叫此函式之後，在 phNewCoNtext 參數中 收到的權杖。

警告

請勿在對 InitializeSecurityCoNtext （一般） 的並行呼叫 中使用相同的內容控制碼。安全性服務提供者中的 API 實作不是安全線程。

pTargetName[in, optional]

表示內容目標之 Null 終止字串的指標。字串內容是特定安全性套件，如下表所述。此清單並不完整。其他系統 SSP 和協力廠商 SSP 可以新增至系統。

使用中的 SSP	意義
消化	以 Null 結束的字串，可唯一識別所要求資源的 URI。字串必須由 URI 中允許的字元組成，而且必須由 US ASCII 程式碼集表示。百分比編碼可用來代表 US ASCII 程式碼集外的字元。
Kerberos 或 Negotiate	服務主體名稱（SPN）或目的地伺服器的安全性內容。
NTLM	服務主體名稱（SPN）或目的地伺服器的安全性內容。
安全通道/SSL	唯一識別目標伺服器的 Null 終止字串。安全通道會使用此值來驗證伺服器憑證。安全通道也會使用此值在重新建立連線時，在會話快取中找出會話。只有在符合下列所有條件時，才會使用快取的會話： -目標名稱相同。 -快取專案尚未過期。 -呼叫函式的應用程式程式相同。 -登入會話相同。 -認證控制碼相同。

fCoNtextReq[in]

指出內容要求的位旗標。並非所有套件都支援所有需求。用於此參數的旗標前面會加上ISC_REQ_，例如，ISC_REQ_DELEGATE。此參數可以是下列一或多個屬性旗標。

值	意義
ISC_REQ_ALLOCATE_MEMORY	安全性套件會為您配置輸出緩衝區。當您完成使用輸出緩衝區時，請呼叫 FreeCoNtextBuffer 函式來釋放它們。
ISC_REQ_CONFIDENTIALITY	使用 EncryptMessage 函式加密訊息。
ISC_REQ_CONNECTION	安全性內容不會處理格式化訊息。此值是 Kerberos、Negotiate 和 NTLM 限制委派的預設值。
ISC_REQ_DELEGATE	伺服器可以使用內容向其他伺服器進行驗證，做為用戶端。必須設定ISC_REQ_MUTUAL_AUTH 旗標，此旗標才能運作。適用于 Kerberos。忽略限制委派的這個旗標。
ISC_REQ_EXTENDED_ERROR	發生錯誤時，將會通知遠端合作物件。
ISC_REQ_HTTP	使用摘要進行 HTTP。請省略此旗標，以使用摘要作為 SASL 機制。
ISC_REQ_INTEGRITY	使用 EncryptMessage 和 MakeSignature 函式簽署訊息並驗證簽章。
ISC_REQ_MANUAL_CRED_VALIDATION	安全通道不得自動驗證服務器。
ISC_REQ_MUTUAL_AUTH	將會滿足服務的相互驗證原則。注意：這不一定表示執行相互驗證，只會滿足服務的驗證原則。若要確保執行相互驗證，請呼叫 QueryCoNtextAttributes （一般）函式。
ISC_REQ_NO_INTEGRITY	如果設定此旗標，則會忽略ISC_REQ_INTEGRITY 旗標。此值僅受 Negotiate 和 Kerberos 限制委派支援。
ISC_REQ_REPLAY_DETECT	偵測使用 EncryptMessage 或 MakeSignature 函式編碼的重新執行訊息。
ISC_REQ_SEQUENCE_DETECT	偵測已依順序接收的訊息。
ISC_REQ_STREAM	支援資料流程導向連線。
ISC_REQ_USE_SESSION_KEY	必須交涉新的工作階段金鑰。只有 Kerberos 限制委派才支援此值。
ISC_REQ_USE_SUPPLIED_CREDS	通道不得自動嘗試提供用戶端的認證。

用戶端可能不支援要求的屬性。如需詳細資訊，請參閱 pfCoNtextAttr 參數。

如需各種屬性的進一步描述，請參閱內容需求。

Reserved1[in]

此參數是保留的，而且必須設定為零。

TargetDataRep[in]

目標上的資料標記法，例如位元組排序。這個參數可以是SECURITY_NATIVE_DREP或SECURITY_NETWORK_DREP。

此參數不會與 Digest 或 Schannel 搭配使用。將它設定為零。

pInput[in, optional]

SecBufferDesc 結構的指標，其中包含提供做為封裝輸入之緩衝區的指標。除非用戶端內容是由伺服器起始，否則此參數的值必須在 NULL 第一次呼叫函式時。在對函式的後續呼叫或伺服器起始用戶端內容時，此參數的值是配置足夠的記憶體來保存遠端電腦所傳回之權杖之緩衝區的指標。

Reserved2[in]

此參數是保留的，而且必須設定為零。

phNewCoNtext[in, out, optional]

CtxtHandle 結構的指標。在第一次呼叫 InitializeSecurityCoNtext （一般） 時，此指標會收到新的內容控制碼。在第二個呼叫中， phNewCoNtext 可以和 phCoNtext 參數中指定的 控制碼相同。 phNewCoNtext 不應該是 NULL 。

pOutput[in, out, optional]

SecBufferDesc 結構的指標，其中包含接收輸出資料的 SecBuffer 結構的指標。如果緩衝區在輸入中輸入為SEC_READWRITE，則會在輸出中。系統會在要求時配置安全性權杖的緩衝區（透過ISC_REQ_ALLOCATE_MEMORY），並在安全性權杖的緩衝區描述元中填入位址。

使用 Microsoft Digest SSP 時，此參數會收到必須傳送至伺服器的挑戰回應。

使用 Schannel SSP 時，如果指定ISC_REQ_ALLOCATE_MEMORY旗標，Schannel SSP 會配置緩衝區的記憶體，並將適當的資訊放在 SecBufferDesc 中。此外，呼叫端必須傳入類型 為 SECBUFFER_ALERT 的緩衝區。在輸出中，如果產生警示，此緩衝區會包含該警示的相關資訊，且函式失敗。

pfCoNtextAttr[out]

要接收一組位旗標的變數指標，指出已建立內容的屬性。如需各種屬性的描述，請參閱內容需求。

用於此參數的旗標前面會加上ISC_RET，例如ISC_RET_DELEGATE。如需有效值的清單，請參閱 fCoNtextReq 參數。

在最終函式呼叫成功傳回之前，請勿檢查安全性相關屬性。與安全性無關的屬性旗標，例如ASC_RET_ALLOCATED_MEMORY旗標，可以在最終傳回之前檢查。

注意

特定內容屬性可以在與遠端對等進行交涉期間變更。

ptsExpiry[out, optional]

TimeStamp 結構的指標，可接收內容的到期時間。建議安全性套件一律以當地時間傳回此值。此參數是選擇性的， NULL 應該針對短期用戶端傳遞。

Microsoft Digest SSP 安全性內容或認證沒有到期時間。

傳回值

如果函式成功，函式會傳回下列其中一個成功碼。

傳回碼	描述
SEC_I_COMPLETE_AND_CONTINUE	用戶端必須呼叫 CompleteAuthToken ，然後將輸出傳遞至伺服器。用戶端接著會等候傳回的權杖，並在另一個呼叫中將它傳遞至 InitializeSecurityCoNtext （一般）。
SEC_I_COMPLETE_NEEDED	用戶端必須完成建置訊息，然後呼叫 CompleteAuthToken 函式。
SEC_I_CONTINUE_NEEDED	用戶端必須將輸出權杖傳送至伺服器，並等候傳回權杖。傳回的權杖接著會傳入另一個對 InitializeSecurityCoNtext （一般）的呼叫。輸出權杖可以是空的。
SEC_I_INCOMPLETE_CREDENTIALS	搭配 Schannel 使用。伺服器已要求用戶端驗證，且提供的認證不包含憑證，或憑證不是由伺服器信任的憑證授權單位單位所簽發。如需詳細資訊，請參閱＜備註＞。
SEC_E_INCOMPLETE_MESSAGE	搭配 Schannel 使用。未從網路讀取整個訊息的資料。傳回此值時， pInput 緩衝區會包含 SecBuffer 結構，其 BufferType 成員為 SECBUFFER_MISSING 。 SecBuffer 的 cbBuffer 成員包含值，指出函式在函式成功之前必須從用戶端讀取的額外位元組數目。雖然這個數位不一定正確，但使用它有助於藉由避免多次呼叫此函式來改善效能。
SEC_E_OK	安全性內容已成功初始化。不需要另一個 InitializeSecurityCoNtext （一般）呼叫。如果函式傳回輸出權杖，也就是說，如果 pOutput 中的 SECBUFFER_TOKEN為非零長度，則必須將該權杖傳送至伺服器。

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

傳回碼	描述
SEC_E_INSUFFICIENT_MEMORY	記憶體不足，無法完成要求的動作。
SEC_E_INTERNAL_ERROR	未對應至 SSPI 錯誤碼的錯誤發生。
SEC_E_INVALID_HANDLE	傳遞至函式的控制碼無效。
SEC_E_INVALID_TOKEN	錯誤是因為格式不正確的輸入權杖，例如傳輸中損毀的權杖、大小不正確的權杖，或傳入錯誤安全性套件的權杖。如果用戶端和伺服器未交涉適當的安全性套件，將權杖傳遞至錯誤的封裝可能會發生。
SEC_E_LOGON_DENIED	登入失敗。
SEC_E_NO_AUTHENTICATING_AUTHORITY	無法連絡任何授權單位進行驗證。驗證方功能變數名稱可能不正確、網域無法連線，或可能有信任關係失敗。
SEC_E_NO_CREDENTIALS	安全性套件中沒有可用的認證。
SEC_E_TARGET_UNKNOWN	無法辨識目標。
SEC_E_UNSUPPORTED_FUNCTION	fCoNtextReq 參數中指定了不正確內容屬性旗標（ISC_REQ_DELEGATE或ISC_REQ_PROMPT_FOR_CREDS）。
SEC_E_WRONG_PRINCIPAL	接收驗證要求的主體與傳遞至 pszTargetName 參數的主體不同。這表示相互驗證失敗。

備註

呼叫端負責判斷最終內容屬性是否足夠。例如，如果要求機密性，但無法建立，某些應用程式可能會選擇立即關閉連線。

如果安全性內容的屬性不足，用戶端必須藉由呼叫 DeleteSecurityCoNtext 函式釋放部分建立的內容。

InitializeSecurityCoNtext （一般） 函式是由用戶端用來初始化輸出內容。

針對雙腿安全性內容，呼叫順序如下所示：

用戶端會呼叫函式，並將 phCoNtext 設定為， NULL 並以輸入訊息填入緩衝區描述元。
安全性套件會檢查參數並建構不透明權杖，並將它放在緩衝區陣列的 TOKEN 元素中。 如果 fCoNtextReq 參數包含 ISC_REQ_ALLOCATE_MEMORY 旗標，則安全性套件會配置記憶體並傳回 TOKEN 元素中的指標。
用戶端會將 pOutput 緩衝區中傳回的 權杖傳送至目標伺服器。然後，伺服器會在呼叫 AcceptSecurityCoNtext （General）函式時，將權杖當做輸入引數傳遞。
AcceptSecurityCoNtext （一般）可能會傳回權杖，如果第一個呼叫傳回SEC_I_CONTINUE_NEEDED，伺服器會傳送給用戶端以進行第二次初始化SecurityCoNtext （一般）呼叫。

針對多回合安全性內容，例如相互驗證，呼叫順序如下所示：

用戶端會如先前所述呼叫函式，但封裝會傳回SEC_I_CONTINUE_NEEDED成功程式碼。
用戶端會將輸出權杖傳送至伺服器，並等候伺服器的回復。
收到伺服器的回應時，用戶端會再次呼叫 InitializeSecurityCoNtext （一般）， 並將 phCoNtext 設定為最後一個呼叫傳回的控制碼。從伺服器收到的權杖會在 pInput 參數中 提供。
請勿在對 InitializeSecurityCoNtext （一般）的並行呼叫 中使用 phCoNtext 值。安全性提供者中的實作不是安全線程。

如果伺服器已成功回應，則安全性套件會傳回SEC_E_OK且已建立安全會話。

如果函式傳回其中一個錯誤回應，則不接受伺服器的回應，而且不會建立會話。

如果函式傳回SEC_I_CONTINUE_NEEDED、SEC_I_COMPLETE_NEEDED或SEC_I_COMPLETE_AND_CONTINUE，則會重複步驟 2 和 3。

若要初始化安全性內容，視基礎驗證機制以及 fCoNtextReq 參數中指定的 選項而定，可能需要多次呼叫此函式。

fCoNtextReq 和 pfCoNtextAttributes 參數是代表各種內容屬性的位元遮罩。如需各種屬性的描述，請參閱內容需求。 pfCoNtextAttributes 參數在任何成功傳回時都有效，但只有在最終成功傳回時，您才能檢查內容安全性層面的相關旗標。中繼傳回可以設定ISC_RET_ALLOCATED_MEMORY旗標。

如果已設定ISC_REQ_USE_SUPPLIED_CREDS旗標，安全性套件必須在 pInput 輸入緩衝區中 尋找SECBUFFER_PKG_PARAMS緩衝區類型。這不是一般解決方案，但可在適當時允許強式配對的安全性套件和應用程式。

如果指定了ISC_REQ_ALLOCATE_MEMORY，呼叫端必須呼叫 FreeCoNtextBuffer 函式來釋放記憶體。

例如，輸入權杖可能是 LAN 管理員的挑戰。在此情況下，輸出權杖會是 NTLM 加密對挑戰的回應。

用戶端採用的動作取決於此函式的傳回碼。如果傳回碼是SEC_E_OK，就不會有第二次 InitializeSecurityCoNtext （一般） 呼叫，而且不會預期伺服器回應。如果傳回碼是SEC_I_CONTINUE_NEEDED，用戶端會預期來自伺服器的權杖，並在第二次呼叫 InitializeSecurityCoNtext （General） 中傳遞權杖。 SEC_I_COMPLETE_NEEDED傳回碼表示用戶端必須完成建置訊息並呼叫 CompleteAuthToken 函式。 SEC_I_COMPLETE_AND_CONTINUE程式碼會併入這兩個動作。

如果 InitializeSecurityCoNtext （一般）在第一次（或僅限） 呼叫上傳回成功，則呼叫端最終必須在傳回的控制碼上呼叫 DeleteSecurityCoNtext 函式，即使呼叫在驗證交換的稍後回合失敗也一樣。

用戶端可以在成功完成之後再次呼叫 InitializeSecurityCoNtext （一般）。 這表示安全性套件需要重新驗證。

核心模式呼叫端有下列差異：目標名稱是 Unicode 字串，必須使用 VirtualAlloc 在虛擬記憶體中配置;它不得從集區配置。在 pInput 和 pOutput 中傳遞和提供的緩衝區必須位於虛擬記憶體中，而不是在集區中。

使用 Schannel SSP 時，如果函式傳回SEC_I_INCOMPLETE_CREDENTIALS，請檢查您是否在認證中指定了有效且受信任的憑證。呼叫 AcquireCredentialsHandle （一般）函式時，會指定憑證。憑證必須是伺服器信任的憑證授權單位單位（CA）所簽發的用戶端驗證憑證。若要取得伺服器信任的 CA 清單，請呼叫 QueryCoNtextAttributes （一般）函式並指定 SECPKG_ATTR_ISSUER_LIST_EX 屬性。

使用 Schannel SSP 時，用戶端應用程式從伺服器信任的 CA 收到驗證憑證之後，應用程式會呼叫 AcquireCredentialsHandle （一般）函式，然後再次呼叫 InitializeSecurityCoNtext （一般） 來建立新的認證，並在 phCredential 參數中 指定新的認證。

需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
標題	Sspi.h （包括 Security.h）
程式庫	Secur32.lib
DLL	Secur32.dll
Unicode 和 ANSI 名稱	InitializeSecurityCoNtextW （Unicode）和 InitializeSecurityCoNtextA （ANSI）