共用方式為

InitializeSecurityContextA 函式 (sspi.h)

  • 發行項

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

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

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

主題 描述
InitializeSecurityContext (CredSSP) 使用認證安全性支援提供者 (CredSSP) ，起始來自認證句柄的客戶端輸出安全性內容。
InitializeSecurityContext (Digest) 使用摘要式安全性套件，從認證句柄起始客戶端輸出安全性內容。
InitializeSecurityContext (Kerberos) 使用 Kerberos 安全性套件，從認證句柄起始客戶端輸出安全性內容。
InitializeSecurityContext (Negotiate) 使用 Negotiate 安全性套件，從認證句柄起始客戶端的輸出安全性內容。
InitializeSecurityContext (NTLM) 使用 NTLM 安全性套件，從認證句柄起始客戶端輸出安全性內容。
InitializeSecurityContext (Schannel) 使用 Schannel 安全性套件，從認證句柄起始客戶端輸出安全性內容。

語法

SECURITY_STATUS SEC_ENTRY InitializeSecurityContextA(
  [in, optional]      PCredHandle    phCredential,
  [in, optional]      PCtxtHandle    phContext,
                      SEC_CHAR       *pszTargetName,
  [in]                unsigned long  fContextReq,
  [in]                unsigned long  Reserved1,
  [in]                unsigned long  TargetDataRep,
  [in, optional]      PSecBufferDesc pInput,
  [in]                unsigned long  Reserved2,
  [in, out, optional] PCtxtHandle    phNewContext,
  [in, out, optional] PSecBufferDesc pOutput,
  [out]               unsigned long  *pfContextAttr,
  [out, optional]     PTimeStamp     ptsExpiry
);

參數

[in, optional] phCredential

AcquireCredentialsHandle (General) 傳回之認證的句柄。 此句柄可用來建置 安全性內容。 InitializeSecurityContext (General) 函式至少需要輸出認證。

[in, optional] phContext

CtxtHandle 結構的指標。 在第一次呼叫 InitializeSecurityContext (General) 時，此指標為 NULL。 在第二次呼叫時，此參數是第一次呼叫在 phNewContext 參數中傳回之部分格式內容的句柄指標。

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

使用 Schannel SSP 時，在第一次呼叫 InitializeSecurityContext (General) 時，指定 NULL。 在未來呼叫時，請在第一次呼叫此函式之後，指定 phNewContext 參數中收到的令牌。

pszTargetName

TBD

[in] fContextReq

指出內容要求的位旗標。 並非所有套件都支援所有需求。 用於此參數的旗標前面會加上 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 (General) 函式。
 
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
 Schannel 不得嘗試自動提供客戶端的認證。
 

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

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

[in] Reserved1

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

[in] TargetDataRep

目標上的數據表示法，例如位元組順序。 此參數可以是SECURITY_NATIVE_DREP或SECURITY_NETWORK_DREP。

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

[in, optional] pInput

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

[in] Reserved2

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

[in, out, optional] phNewContext

CtxtHandle 結構的指標。 在第一次呼叫 InitializeSecurityContext (General) 時，此指標會收到新的內容句柄。 第二次呼叫時， phNewContext 可以與 phContext 參數中指定的句柄相同。

使用 Schannel SSP 時，在第一次呼叫之後呼叫時，將傳回的句柄傳遞為 phContext 參數，並指定 phNewContext 的 NULL。

[in, out, optional] pOutput

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

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

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

[out] pfContextAttr

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

用於此參數的旗標前面會加上ISC_RET，例如ISC_RET_DELEGATE。

如需有效值的清單，請參閱 fContextReq 參數。

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

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

[out, optional] ptsExpiry

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

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

傳回值

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

傳回碼 Description
SEC_I_COMPLETE_AND_CONTINUE
 客戶端必須呼叫 CompleteAuthToken ，然後將輸出傳遞至伺服器。 然後，用戶端會等候傳回的令牌，並在另一個呼叫中將其傳遞至 InitializeSecurityContext (General) 。
SEC_I_COMPLETE_NEEDED
 客戶端必須完成建置訊息，然後呼叫 CompleteAuthToken 函式。
SEC_I_CONTINUE_NEEDED
 客戶端必須將輸出令牌傳送至伺服器，並等候傳回令牌。 然後，傳回的令牌會傳入另一個對 InitializeSecurityContext 的呼叫， (General) 。 輸出令牌可以是空的。
SEC_I_INCOMPLETE_CREDENTIALS
 搭配 Schannel 使用。 伺服器已要求客戶端驗證，且提供的認證不包含憑證，或憑證不是由伺服器信任的 證書頒發機構單位 所簽發。 如需詳細資訊，請參閱＜備註＞。
SEC_E_INCOMPLETE_MESSAGE
 搭配 Schannel 使用。 整個訊息的數據未從網路讀取。

傳回這個值時，pInput 緩衝區包含具有 BufferType 成員的 SecBuffer 結構SECBUFFER_MISSING。 SecBuffer 的 cbBuffer 成員包含值，指出函式在函式成功之前，必須從客戶端讀取的額外位元組數目。 雖然這個數位不一定正確，但使用它可藉由避免多次呼叫此函式來協助改善效能。
SEC_E_OK
 安全性 內容 已成功初始化。 不需要另一個 InitializeSecurityContext (一般) 呼叫。 如果函式傳回輸出令牌，也就是說，如果 pOutput 中的SECBUFFER_TOKEN為非零長度，則必須將該令牌傳送至伺服器。
 

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

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

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

  1. 用戶端會呼叫函式，並將 phContext 設定為 NULL ，並使用輸入訊息填入緩衝區描述元。
  2. 安全性套件會檢查參數，並建構不透明的令牌，並將它放在緩衝區陣列的 TOKEN 元素中。 如果 fContextReq 參數包含 ISC_REQ_ALLOCATE_MEMORY 旗標，安全性套件會配置記憶體，並傳回 TOKEN 元素中的指標。
  3. 用戶端會將 pOutput 緩衝區中傳回的令牌傳送至目標伺服器。 然後，伺服器會在對 AcceptSecurityContext (General) 函式的呼叫中傳遞令牌作為輸入自變數。
  4. AcceptSecurityContext (General) 可能會傳回令牌，如果第一次呼叫傳回SEC_I_CONTINUE_NEEDED，伺服器會傳送給用戶端，以第二次呼叫 InitializeSecurityContext (General) 。
針對多回合安全性內容，例如相互驗證，呼叫順序如下所示：
  1. 如先前所述，用戶端會呼叫 函式，但封裝會傳回SEC_I_CONTINUE_NEEDED成功碼。
  2. 用戶端會將輸出令牌傳送至伺服器，並等候伺服器的回復。
  3. 收到伺服器的回應時，用戶端會再次呼叫 InitializeSecurityContext (General) ，並將 phContext 設定為上一次呼叫所傳回的句柄。 從伺服器收到的令牌會在 pInput 參數中提供。
如果伺服器已成功回應，安全性套件會傳回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 (General) 在第一次 (或只傳回) 呼叫時傳回成功，則呼叫端最終必須在傳回的句柄上呼叫 DeleteSecurityContext 函式，即使呼叫在稍後的驗證交換時失敗也一樣。

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

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

使用安全通道 SSP 時，如果函式傳回SEC_I_INCOMPLETE_CREDENTIALS，請檢查您是否在認證中指定了有效且受信任的憑證。 呼叫 AcquireCredentialsHandle (General) 函式時，會指定憑證。 憑證必須是由 證書頒發機構單位 所發行的客戶端驗證憑證， (CA) 由伺服器信任。 若要取得伺服器信任的 CA 清單，請呼叫 QueryContextAttributes (General) 函式，並指定 SECPKG_ATTR_ISSUER_LIST_EX 屬性。

使用安全通道 SSP 時，用戶端應用程式從伺服器信任的 CA 收到驗證憑證之後，應用程式會呼叫 AcquireCredentialsHandle (General) 函式，然後再次呼叫 InitializeSecurityContext (General) ，並在 phCredential 參數中指定新認證，以建立新的認證。

注意

sspi.h 標頭會將 InitializeSecurityContext 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

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

另請參閱

AcceptSecurityContext (一般)

AcquireCredentialsHandle (General)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SSPI 函式

SecBuffer

SecBufferDesc