coInitializeSecurity 函式 (combaseapi.h)

發行項
03/05/2024

註冊安全性，並設定進程的預設安全性值。

語法

HRESULT CoInitializeSecurity(
  [in, optional] PSECURITY_DESCRIPTOR        pSecDesc,
  [in]           LONG                        cAuthSvc,
  [in, optional] SOLE_AUTHENTICATION_SERVICE *asAuthSvc,
  [in, optional] void                        *pReserved1,
  [in]           DWORD                       dwAuthnLevel,
  [in]           DWORD                       dwImpLevel,
  [in, optional] void                        *pAuthList,
  [in]           DWORD                       dwCapabilities,
  [in, optional] void                        *pReserved3
);

參數

[in, optional] pSecDesc

伺服器將用來接收呼叫的訪問許可權。只有在伺服器呼叫 CoInitializeSecurity 時，COM 才會使用此參數。其值是三種類型之一的指標：AppID、 IAccessControl 對象或絕對格式的SECURITY_DESCRIPTOR。如需詳細資訊，請參閱＜備註＞一節。

[in] cAuthSvc

asAuthSvc 參數中的項目計數。只有在伺服器呼叫 CoInitializeSecurity 時，COM 才會使用此參數。如果此參數為 0，則不會註冊任何驗證服務，而且伺服器無法接收安全呼叫。 -1 的值會告知 COM 選擇要註冊的驗證服務，如果是這種情況， asAuthSvc 參數必須是 NULL。不過，如果此參數為 -1，則伺服器永遠不會選擇 Schannel 作為驗證服務。

[in, optional] asAuthSvc

伺服器願意用來接收呼叫的驗證服務數位。只有在伺服器呼叫 CoInitializeSecurity 時，COM 才會使用此參數。如需詳細資訊，請參閱 SOLE_AUTHENTICATION_SERVICE。

[in, optional] pReserved1

此參數是保留的，而且必須是 NULL。

[in] dwAuthnLevel

進程的預設驗證層級。伺服器和用戶端在呼叫 CoInitializeSecurity 時都會使用此參數。 COM 將會失敗，這些呼叫會以較低的驗證層級送達。根據預設，所有 Proxy 都會至少使用此驗證層級。此值應該包含其中一個驗證層級常數。根據預設，所有對IUnknown 的呼叫都會在此層級進行。

[in] dwImpLevel

Proxy 的預設模擬層級。只有當行程是用戶端時，才會使用此參數的值。它應該是模擬層級常數中的值，但RPC_C_IMP_LEVEL_DEFAULT除外，這不適用於 CoInitializeSecurity。

來自客戶端的傳出呼叫一律使用指定的模擬層級。 (不會交涉。) 用戶端的連入呼叫可以位於任何模擬層級。根據預設，所有 IUnknown 呼叫都是使用此模擬層級進行，因此即使是安全性感知應用程式也應該謹慎設定此層級。若要判斷每個驗證服務支援的模擬層級，請參閱 COM 和安全性套件中的驗證服務描述。如需模擬層級的詳細資訊，請參閱模擬。

[in, optional] pAuthList

SOLE_AUTHENTICATION_LIST指標，這是SOLE_AUTHENTICATION_INFO 結構的陣列。此清單指出客戶端可用來呼叫伺服器之每個驗證服務的資訊。只有在用戶端呼叫 CoInitializeSecurity 時，COM 才會使用此參數。

[in] dwCapabilities

藉由設定一或多個 EOLE_AUTHENTICATION_CAPABILITIES 值來指定客戶端或伺服器的其他功能。其中某些值無法同時使用，有些則無法在使用特定驗證服務時設定。如需這些旗標的詳細資訊，請參閱一節。

[in, optional] pReserved3

此參數是保留的，而且必須是 NULL。

傳回值

此函式可以傳回標準傳回值E_INVALIDARG，以及下列值。

傳回碼	描述
S_OK	表示成功。
RPC_E_TOO_LATE	已呼叫 CoInitializeSecurity 。
RPC_E_NO_GOOD_SECURITY_PACKAGES	asAuthSvc 參數不是 NULL，而且清單中沒有任何驗證服務可以註冊。檢查儲存在 asAuthSvc 中的結果，以取得驗證服務特定的錯誤碼。
E_OUT_OF_MEMORY	記憶體不足。

備註

CoInitializeSecurity 函式會初始化安全性層，並將指定的值設定為安全性預設值。如果進程未呼叫 CoInitializeSecurity，COM 會在第一次封送處理或取消封送處理介面時自動呼叫它，並註冊系統默認安全性。在之後，不會註冊預設安全性套件。

每個進程會明確或隱含地呼叫此函式一次。用戶端、伺服器或兩者都可以呼叫它。對於未明確呼叫 CoInitializeSecurity 的舊版應用程式和其他應用程式，COM 會以登錄中的值隱含呼叫此函式。如果您使用登錄設定全進程安全性，然後呼叫 CoInitializeSecurity，則會忽略 AppID 登錄值，並使用 CoInitializeSecurity 值。

CoInitializeSecurity 可用來覆寫全計算機訪問許可權和應用程式特定的訪問許可權，但不能覆寫整個計算機的限制原則。

如果 pSecDesc 指向 AppID，則必須在 dwCapabilities 中設定EOAC_APPID旗標，而且設定EOAC_APPID旗標時，會忽略 CoInitializeSecurity 的所有其他參數。 CoInitializeSecurity 會在登錄中的 AppID 機碼下尋找驗證層級，並使用它來判斷預設安全性。如需 AppID 機碼如何用來設定安全性的詳細資訊，請參閱透過登錄設定安全性 Process-Wide。

如果 pSecDesc 是 IAccessControl 物件的指標，則必須設定EOAC_ACCESS_CONTROL旗標， 而且 dwAuthnLevel 不能是 none。 IAccessControl 物件可用來判斷誰可以呼叫進程。 DCOM 將會 AddRefIAccessControl，並在呼叫 CoUninitialize 時釋出它。不應該變更 IAccessControl 物件的狀態。

如果 pSecDesc 是 SECURITY_DESCRIPTOR的指標，則無法在 dwCapabilities 中設定EOAC_APPID或EOAC_ACCESS_CONTROL旗標。必須設定 SECURITY_DESCRIPTOR 的擁有者和群組，而且在DCOM支援稽核之前，系統 ACL 必須是 NULL。 (ACL) 的任意 ACL (DACL) SECURITY_DESCRIPTOR 存取控制 專案會用來 找出哪些呼叫端可以連線至進程的物件。沒有 ACE 的 DACL 不允許存取， 而 NULL DACL 則會允許任何人呼叫。如需 ACL 和 ACE 的詳細資訊，請參閱存取控制模型。應用程式應該呼叫 AccessCheck (不是 IsValidSecurityDescriptor) ，以確保其 SECURITY_DESCRIPTOR 在呼叫 CoInitializeSecurity 之前已正確形成。

強烈建議不要將 pSecDesc 傳遞為 NULL 。適當的替代方式可能是使用允許所有人的SECURITY_DESCRIPTOR 。如果 pSecDesc 為 NULL，dwCapabilities 中的旗標會決定 CoInitializeSecurity 如何定義伺服器將使用的訪問許可權，如下所示：

如果已設定EOAC_APPID旗標， CoInitializeSecurity 會在登錄中查閱應用程式的 .exe 名稱，並使用儲存在該處的 AppID。
如果已設定EOAC_ACCESS_CONTROL旗標， CoInitializeSecurity 將會傳回錯誤。
如果未設定EOAC_APPID旗標或EOAC_ACCESS_CONTROL旗標， CoInitializeSecurity 會允許包括本機和遠端匿名用戶在內的所有呼叫端。

如果 EOAC_APPID 和 EOAC_ACCESS_CONTROL 旗標都設定在 dwCapabilities 中，CoInitializeSecurity 函式會傳回錯誤。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	combaseapi.h (包含 Objbase.h)
程式庫	Ole32.lib
Dll	Ole32.dll

另請參閱

CoSetProxyBlanket

COM 中的安全性

共用方式為

coInitializeSecurity 函式 (combaseapi.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源