InitializeSecurityCoNtext (CredSSP) 函式

  • 發行項

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

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

語法

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

參數

phCredential[in, optional]

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

phCoNtext[in, optional]

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

在第一次呼叫 InitializeSecurityCoNtext (CredSSP) 上，指定 NULL 。 在未來呼叫時，請在第一次呼叫此函式之後，指定 phNewCoNtext 參數中收到的權杖。

警告

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

pTargetName[in, optional]

可唯一識別目標伺服器的 Null 終止字串指標。 安全通道會使用此值來驗證伺服器憑證。 Schannel 也會使用此值在重新建立連線時，在會話快取中找出會話。 只有在符合下列所有條件時，才會使用快取的會話：

  • 目標名稱相同。
  • 快取專案尚未過期。
  • 呼叫函式的應用程式進程相同。
  • 登入會話相同。
  • 認證控制碼相同。

fCoNtextReq[in]

指出內容要求的位旗標。 並非所有套件都支援所有需求。 用於此參數的旗標前面會加上 ISC_REQ_，例如，ISC_REQ_DELEGATE。

此參數可以是下列一或多個屬性旗標。

值 意義
ISC_REQ_ALLOCATE_MEMORY
0x100		 安全性套件會為呼叫端配置輸出緩衝區。 當您完成使用輸出緩衝區時，請呼叫 FreeCoNtextBuffer 函式來釋放它們。
ISC_REQ_CONNECTION
0x800		 安全性內容不會處理格式化訊息。
ISC_REQ_EXTENDED_ERROR
0x4000		 發生錯誤時，將會通知遠端合作物件。
ISC_REQ_MANUAL_CRED_VALIDATION
0x80000		 認證安全性支援提供者 (CredSSP) 不得自動驗證服務器。 使用 CredSSP 時，一律會設定此旗標。
ISC_REQ_SEQUENCE_DETECT
0x8		 偵測依序接收的訊息。
ISC_REQ_STREAM
0x8000		 支援資料流程導向連線。
ISC_REQ_USE_SUPPLIED_CREDS
0x80		 CredSSP 不得嘗試自動提供用戶端的認證。
ISC_REQ_DELEGATE
0x1		 指出使用者的認證要委派給伺服器。
如果未指定此旗標，則會將一組空的認證委派給伺服器。
Windows Server 2008 和 Windows Vista： 這是必要旗標。
ISC_REQ_MUTUAL_AUTH
0x2		 表示不需要伺服器驗證。 如果未指定此旗標，仍會強制執行委派原則。
Windows Server 2008 和 Windows Vista： 系統會忽略此旗標。

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

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

Reserved1[in]

保留的。 此參數必須設定為零。

TargetDataRep[in]

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

pInput[in, out, optional]

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

在初始呼叫之後呼叫此函式時，必須有兩個緩衝區。 第一個具有類型 SECBUFFER_TOKEN ，並包含從伺服器收到的權杖。 第二個緩衝區的類型 為 SECBUFFER_EMPTY;將 pvBuffer 和 cbBuffer 成員都設定為零。

Reserved2[in]

保留的。 此參數必須設定為零。

phNewCoNtext[in, out, optional]

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

pOutput[out, optional]

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

如果指定 ISC_REQ_ALLOCATE_MEMORY 旗標，CredSSP 會配置緩衝區的記憶體，並將適當的資訊放在 SecBufferDesc中。

pfCoNtextAttr[out]

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

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

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

注意

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

ptsExpiry[out, optional]

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

傳回值

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

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

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

傳回碼 描述
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參數的值無效。 未指定必要的旗標，或已指定 CredSSP 不支援的旗標。
SEC_E_WRONG_PRINCIPAL 接收驗證要求的主體與傳遞至 pszTargetName 參數的主體不同。 此錯誤表示相互驗證失敗。
SEC_E_DELEGATION_POLICY 原則不支援將認證委派給目標伺服器。
SEC_E_POLICY_NLTM_ONLY 當無法達成相互驗證時，不允許將認證委派給目標伺服器。
SEC_E_MUTUAL_AUTH_FAILED 在 fCoNtextReq 參數中指定ISC_REQ_MUTUAL_AUTH旗標時，伺服器驗證失敗。

備註

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

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

用戶端會 呼叫 InitializeSecurityCoNtext (CredSSP) 函式來初始化輸出內容。

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

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

如果伺服器已成功回應，安全性套件會 傳回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 (CredSSP) 呼叫，而且不會預期來自伺服器的回應。 如果傳回碼 SEC_I_CONTINUE_NEEDED，則用戶端預期會從伺服器回應權杖，並在第二次呼叫 InitializeSecurityCoNtext (CredSSP) 傳遞 權杖。 SEC_I_COMPLETE_NEEDED傳回碼表示用戶端必須完成建置訊息，並呼叫CompleteAuthToken函式。 SEC_I_COMPLETE_AND_CONTINUE程式碼會納入這兩個動作。

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

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

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

如果函式傳回 SEC_I_INCOMPLETE_CREDENTIALS，請檢查傳遞給 AcquireCredentialsHandle (CredSSP) 函式的 r 認證是否指定有效且受信任的憑證。憑證必須是由伺服器信任的憑證授權單位單位所簽發的用戶端驗證憑證。 若要取得伺服器信任的 CA 清單，請使用SECPKG_ATTR_ISSUER_LIST_EX屬性呼叫QueryCoNtextAttributes (CredSSP) 函式。

從伺服器信任的憑證授權單位單位接收驗證憑證之後，用戶端應用程式會建立新的認證。 它會呼叫 AcquireCredentialsHandle (CredSSP) 函式，然後再次呼叫 InitializeSecurityCoNtext (CredSSP) ，並在 phCredential 參數中指定新的認證。

規格需求

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

另請參閱

SSPI 函式

AcceptSecurityCoNtext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken

DeleteSecurityCoNtext

FreeCoNtextBuffer

SecBuffer

SecBufferDesc