AcceptSecurityContext （Digest） 函式

  • 發行項

AcceptSecurityContext （Digest） 函式可讓傳輸應用程式的伺服器元件在伺服器與遠端用戶端之間建立安全性內容。 遠端用戶端會使用 InitializeSecurityContext （Digest） 函式來啟動建立安全性內容的程式。 伺服器可能需要來自遠端用戶端的一或多個回復令牌，才能完成建立安全性內容。

語法

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

參數

phCredential [in, optional]

伺服器的認證句柄。 伺服器會呼叫 AcquireCredentialsHandle （Digest） 函式，並將SECPKG_CRED_INBOUND或SECPKG_CRED_BOTH旗標設定為擷取此句柄。

phContext [in, out, optional]

CtxtHandle 結構的指標。 在第一次呼叫 AcceptSecurityContext （Digest）時，此指標為 NULL。 在後續的呼叫中，phContext 是第一次呼叫在 phNewContext 參數中傳回之部分格式內容的句柄。

警告

請勿在 AcceptSecurityContext （Digest） 的並行呼叫中使用相同的內容句柄。 安全性服務提供者中的 API 實作不是安全線程。

pInput [in, optional]

由用戶端呼叫 InitializeSecurityContext （Digest） 所產生之 SecBufferDesc 結構的指標，其中包含輸入緩衝區描述元。

下表顯示摘要 HTTP 的緩衝區組態。 第一個緩衝區的類型必須是 SECBUFFER_TOKEN，其餘的必須是類型 SECBUFFER_PKG_PARAMS。 SASL 只需要緩衝區零。

緩衝區 #/緩衝區類型 意義
0
SECBUFFER_TOKEN		 第一次呼叫的空白，以及第二次呼叫從用戶端收到的挑戰回應。
1
SECBUFFER_PKG_PARAMS		 方法。 字元是來自要求行的線路格式。 US ASCII 單位元組字元。
2
SECBUFFER_PKG_PARAMS		 已保留。
3
SECBUFFER_PKG_PARAMS		 HEntity。 H（entity-body） 的十六進位表示法。 US ASCII 單位元組字元。
4
SECBUFFER_PKG_PARAMS		 領域。 挑戰的領域字串。 必須以 US ASCII 表示的 Unicode 字串。
5
| SECBUFFER_CHANNEL_BINDINGS SECBUFFER_READONLY		 包含通道系結令牌值。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援此值。

fContextReq [in]

指定伺服器建立內容所需屬性的位旗標。 您可以使用位 OR 作業來合併位旗標。 此參數可以是下列其中一或多個值。

值 意義
ASC_REQ_ALLOCATE_MEMORY 摘要會為您配置輸出緩衝區。 當您完成使用輸出緩衝區時，請呼叫 FreeContextBuffer函 式來釋放它們。
ASC_REQ_ALLOW_MISSING_BINDINGS 表示 Digest 不需要內部和外部通道的通道系結。 當不知道端點通道系結的支援時，這個值會用於回溯相容性。
這個值與 ASC_REQ_PROXY_BINDINGS互斥。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援此值。
ASC_REQ_CONFIDENTIALITY 加密和解密訊息。
摘要式 SSP 僅支援 SASL 的這個旗標。
ASC_REQ_PROXY_BINDINGS 表示 Digest 需要通道系結。
這個值與 ASC_REQ_ALLOW_MISSING_BINDINGS互斥。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援此值。
ASC_REQ_CONNECTION 安全性內容不會處理格式化訊息。
ASC_REQ_EXTENDED_ERROR 發生錯誤時，將會通知遠端合作物件。
ASC_REQ_HTTP （0x10000000） 使用摘要進行 HTTP。 請省略此旗標，以使用摘要作為 SASL 機制。
ASC_REQ_INTEGRITY 簽署訊息並驗證簽章。
ASC_REQ_REPLAY_DETECT 偵測重新執行的封包。
ASC_REQ_SEQUENCE_DETECT 偵測已依順序接收的訊息。

如需可能的屬性旗標及其意義，請參閱 內容需求。 用於此參數的旗標前面會加上ASC_REQ，例如ASC_REQ_DELEGATE。

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

TargetDataRep [in]

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

此參數不會與摘要 SSP 搭配使用。 當您使用摘要 SSP 時，請為此參數指定零。

phNewContext [in, out, optional]

CtxtHandle 結構的指標。 在第一次呼叫 AcceptSecurityContext （Digest）時，此指標會收到新的內容句柄。 在後續呼叫時，phNewContext 可以和 phContext 參數中指定的句柄相同。 phNewContext 不應該是 NULL。

pOutput [in, out, optional]

SecBufferDesc 結構的指標，其中包含輸出緩衝區描述元。 此緩衝區會傳送至用戶端，以輸入至 InitializeSecurityContext （Digest） 的其他呼叫。 即使函式傳回SEC_E_OK，仍可能會產生輸出緩衝區。 產生的任何緩衝區都必須傳送回用戶端應用程式。

pfContextAttr [out]

接收一組位旗標的變數指標，指出已建立內容的屬性。 如需各種屬性的描述，請參閱 內容需求。 用於此參數的旗標前面會加上 ASC_RET，例如ASC_RET_DELEGATE。

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

ptsTimeStamp [out, optional]

TimeStamp 結構的指標，可接收內容的到期時間。 建議 安全性套件 一律以當地時間傳回此值。

此參數會設定為常數最大時間。 摘要式安全性內容或認證沒有到期時間，或使用摘要式 SSP 時。

注意

在驗證程序的最後一次呼叫之前，內容到期時間可能不正確，因為交涉後續階段將提供更多資訊。 因此， ptsTimeStamp 必須 NULL 等到最後一次呼叫函式為止。

傳回值

此函式會傳回下列其中一個值：

傳回碼 + 值 描述
SEC_E_INSUFFICIENT_MEMORY
0x80090300L		 函式失敗。 記憶體不足，無法完成要求的動作。
SEC_E_INTERNAL_ERROR
0x80090304L		 函式失敗。 未對應至 SSPI 錯誤碼的錯誤發生。
SEC_E_INVALID_HANDLE
0x80100003L		 函式失敗。 傳遞至函式的句柄無效。
SEC_E_INVALID_TOKEN
0x80090308L		 函式失敗。 傳遞至函式的令牌無效。
SEC_E_LOGON_DENIED
0x8009030CL		 登入失敗。
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L		 函式失敗。 無法連絡任何授權單位進行驗證。 這可能是因為下列情況所造成：
-驗證方域名不正確。
-網域無法使用。
-信任關係失敗。
SEC_E_NO_CREDENTIALS
0x8009030EL		 函式失敗。 phCredential 參數中指定的認證句柄無效。
SEC_E_OK
0x00000000L		 此函數已成功。 已接受從用戶端接收的安全性內容。 如果函式產生輸出令牌，則必須將它傳送至客戶端進程。
SEC_E_SECURITY_QOS_FAILED
0x80090332L		 函式失敗。 在 fContextReq 參數中指定了無效的內容屬性旗標。
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 此函數已成功。 伺服器必須呼叫 CompleteAuthToken ，並將輸出令牌傳遞至用戶端。 伺服器接著會等候用戶端傳回令牌，然後對 AcceptSecurityContext （Digest） 進行另一個呼叫。
SEC_I_COMPLETE_NEEDED
0x00090313L		 此函數已成功。 伺服器必須完成從用戶端建置訊息，然後呼叫 CompleteAuthToken 函式。
SEC_I_CONTINUE_NEEDED
0x00090312L		 此函數已成功。 伺服器必須將輸出令牌傳送至用戶端，並等候傳回的令牌。 傳回的令牌應該在 pInput 中傳遞，以便對 AcceptSecurityContext （Digest） 進行另一個呼叫。
STATUS_LOGON_FAILURE
0xC000006DL		 函式失敗。 在建立指定的內容之後，會呼叫 AcceptSecurityContext （Digest） 函式。
SEC_E_BAD_BINDINGS
0x80090346L		 函式失敗。 通道系結原則未滿足。

備註

AcceptSecurityContext （Digest） 函式是 InitializeSecurityContext （Digest） 函式的伺服器對應專案。

當伺服器從用戶端接收要求時，伺服器會使用 fContextReq 參數來指定會話所需的專案。 以這種方式，伺服器可以指定客戶端必須能夠使用機密或 完整性檢查的會話，而且它可以拒絕不符合該需求的用戶端。 或者，伺服器不需要任何專案，而且用戶端可以在 pfContextAttr 參數中傳回或要求的任何專案。

對於支援多回合驗證的套件，例如相互驗證，呼叫順序如下所示：

  1. 用戶端會將令牌傳送至伺服器。
  2. 伺服器第一次呼叫 AcceptSecurityContext （Digest）， 這會產生回復令牌，然後傳送至用戶端。
  3. 用戶端會收到令牌，並將它傳遞至 InitializeSecurityContext （Digest） 。 如果 InitializeSecurityContext （Digest） 傳回SEC_E_OK，則相互驗證已完成，且安全會話可以開始。 如果 InitializeSecurityContext （Digest） 傳回錯誤碼，相互驗證交涉就會結束。 否則，InitializeSecurityContext 傳回 的安全性令牌會 傳送至用戶端，並重複步驟 2 和 3。
  4. 請勿在 AcceptSecurityContext （Digest） 的並行呼叫中使用 phContext 值。 安全性提供者中的實作不是安全線程。

fContextReq 和 pfContextAttr 參數是代表各種內容屬性的位掩碼。 如需各種屬性的描述，請參閱 內容需求。

注意

pfContextAttr 參數在任何成功傳回時都有效，但只有在最後成功傳回時，才檢查內容安全性層面的相關旗標。 中繼傳回可以設定ISC_RET_ALLOCATED_MEMORY旗標。

呼叫端負責判斷最終內容屬性是否足夠。 例如，如果要求機密性（加密），但無法建立，某些應用程式可能會選擇立即關閉連線。 如果無法建立安全性內容，伺服器必須藉由呼叫DeleteSecurityContext函式釋放部分建立的內容。 如需何時呼叫 DeleteSecurityContext 函式的相關信息，請參閱 DeleteSecurityContext。

建立 安全性內容 之後，伺服器應用程式可以使用 QuerySecurityContextToken 函式來擷取客戶端憑證所對應的用戶帳戶句柄。 此外，伺服器可以使用 ImpersonateSecurityContext 函式來模擬使用者。

需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
頁首 Sspi.h （包括 Security.h）
程式庫 Secur32.lib
DLL Secur32.dll

另請參閱

SSPI 函式

DeleteSecurityContext

InitializeSecurityContext （摘要）