共用方式為

InitializeSecurityCoNtext (Negotiate) 函式

  • 發行項

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

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

語法

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 (Negotiate) 所傳回之認證的控制碼。 此控制碼是用來建置 安全性內容。 InitializeSecurityCoNtext (Negotiate) 函式至少需要輸出認證。

phCoNtext[in, optional]

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

警告

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

pszTargetName[in, optional]

以 Null 結尾的字串指標，表示服務主體名稱 (SPN) 或目的地伺服器 的安全性內容 。

應用程式必須提供有效的 SPN，以協助減輕重新執行攻擊。

fCoNtextReq[in]

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

值 意義
ISC_REQ_ALLOCATE_MEMORY 安全性套件會為您配置輸出緩衝區。 當您完成使用輸出緩衝區時，請呼叫 FreeCoNtextBuffer 函 式來釋放它們。
ISC_REQ_CONFIDENTIALITY 使用 EncryptMessage 函式加密訊息。
ISC_REQ_CONNECTION 安全性內容不會處理格式化訊息。 這是預設值。
ISC_REQ_DELEGATE 伺服器可以使用內容，以用戶端身分向其他伺服器進行驗證。 必須設定 ISC_REQ_MUTUAL_AUTH 旗標，此旗標才能運作。 適用于 Kerberos。 忽略此旗標進行 限制委派。
ISC_REQ_EXTENDED_ERROR 發生錯誤時，將會通知遠端合作物件。
ISC_REQ_INTEGRITY 使用 EncryptMessage 和 MakeSignature 函式簽署訊息並驗證簽章。
ISC_REQ_MUTUAL_AUTH 將會滿足服務的相互驗證原則。
謹慎： 這不一定表示會執行相互驗證，只會滿足服務的驗證原則。 若要確保執行相互驗證，請呼叫 QueryCoNtextAttributes (Negotiate) 函式。
ISC_REQ_NO_INTEGRITY 如果設定此旗標，則會忽略 ISC_REQ_INTEGRITY 旗標。
ISC_REQ_REPLAY_DETECT 偵測已使用 EncryptMessage 或 MakeSignature 函式編碼的重新執行訊息。
ISC_REQ_SEQUENCE_DETECT 偵測序列外收到的訊息。
ISC_REQ_STREAM 支援資料流程導向連線。

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

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

Reserved1[in]

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

TargetDataRep[in]

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

pInput[in, optional]

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

Reserved2[in]

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

phNewCoNtext[in, out, optional]

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

pOutput[in, out, optional]

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

pfCoNtextAttr[out]

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

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

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

注意

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

ptsExpiry[out, optional]

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

傳回值

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

傳回碼 描述
SEC_E_OK 已成功初始化安全性內容。 不需要另一個 InitializeSecurityCoNtext (Negotiate) 呼叫。 如果函式傳回輸出權杖，也就是說，如果 pOutput 中的SECBUFFER_TOKEN為非零長度，則必須將該權杖傳送至伺服器。
SEC_I_COMPLETE_AND_CONTINUE 用戶端必須呼叫 CompleteAuthToken ，然後將輸出傳遞至伺服器。 接著，用戶端會等候傳回的權杖，並在另一個呼叫中傳遞至 InitializeSecurityCoNtext (Negotiate) 。
SEC_I_COMPLETE_NEEDED 用戶端必須完成建置訊息，然後呼叫 CompleteAuthToken 函式。
SEC_I_CONTINUE_NEEDED 用戶端必須將輸出權杖傳送至伺服器，並等候傳回權杖。 傳回的權杖接著會傳入另一個 對 InitializeSecurityCoNtext 的呼叫， (Negotiate) 。 輸出權杖可以是空的。

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

傳回碼 描述
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 (Negotiate) 函式來初始化輸出內容。

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

  1. 用戶端會呼叫 將 phCoNtext 設定為 NULL 的函式，並使用輸入訊息填入緩衝區描述元。
  2. 安全性套件會檢查參數，並建構不透明的權杖，並將它放在緩衝區陣列的 TOKEN 元素中。 如果 fCoNtextReq 參數包含 ISC_REQ_ALLOCATE_MEMORY 旗標， 安全性套件 會配置記憶體，並傳回 TOKEN 元素中的指標。
  3. 用戶端會將 pOutput 緩衝區中傳回的權杖傳送至目標伺服器。 接著，伺服器會在對 AcceptSecurityCoNtext (Negotiate) 函式的呼叫中傳遞權杖作為輸入引數。
  4. AcceptSecurityCoNtext (Negotiate) 可能會傳回權杖，如果第一次呼叫傳回SEC_I_CONTINUE_NEEDED，則伺服器會傳送給用戶端，以便第二次呼叫 InitializeSecurityCoNtext (Negotiate) 。

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

  1. 用戶端會如先前所述呼叫 函式，但封裝會傳回SEC_I_CONTINUE_NEEDED成功程式碼。
  2. 用戶端會將輸出權杖傳送至伺服器，並等候伺服器的回復。
  3. 收到伺服器的回應時，用戶端會 再次呼叫 InitializeSecurityCoNtext (Negotiate) ， 並將 phCoNtext 設定為上次呼叫傳回的控制碼。 從伺服器收到的權杖會在 pInput 參數中提供。
  4. 請勿在同時呼叫InitializeSecurityCoNtext (Negotiate) 中使用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 (Negotiate) 呼叫，而且不會預期伺服器回應。 如果傳回碼SEC_I_CONTINUE_NEEDED，用戶端預期會從伺服器回應權杖，並在第二次呼叫 InitializeSecurityCoNtext (Negotiate) 傳遞 權杖。 SEC_I_COMPLETE_NEEDED傳回碼表示用戶端必須完成建置訊息，並呼叫 CompleteAuthToken 函式。 SEC_I_COMPLETE_AND_CONTINUE程式碼會納入這兩個動作。

如果 InitializeSecurityCoNtext (Negotiate) 在第一次 (或只傳回) 呼叫時傳回成功，則呼叫端最終必須在傳回的控制碼上呼叫 DeleteSecurityCoNtext 函式，即使呼叫在稍後的驗證交換時失敗也一樣。

用戶端可以在成功完成之後 ，再次呼叫 InitializeSecurityCoNtext (Negotiate) 。 這表示 安全性套件 需要重新驗證。

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

規格需求

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

另請參閱

SSPI 函式

AcceptSecurityCoNtext (Negotiate)

AcquireCredentialsHandle (Negotiate)

CompleteAuthToken

DeleteSecurityCoNtext

FreeCoNtextBuffer

SecBuffer

SecBufferDesc