CoInitializeSecurity 函数 (combaseapi.h)

  • 项目

注册安全性并设置进程的默认安全值。

语法

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 将失败以较低身份验证级别到达的调用。 默认情况下，所有代理将至少使用此身份验证级别。 此值应包含 身份验证级别常量之一。 默认情况下，对 IUnknown 的所有调用都在此级别进行。

[in] dwImpLevel

代理的默认模拟级别。 仅当进程是客户端时，才使用此参数的值。 它应该是 模拟级别常量中的值，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，并且列表中的任何身份验证服务都无法注册。 检查另存为 AuthSvc 中的结果，以获取特定于身份验证服务的错误代码。
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 将添加IAccessControl，并在调用 CoUninitialize 时发布它。 不应更改 IAccessControl 对象的状态。

如果 pSecDesc 是指向 SECURITY_DESCRIPTOR的指针，则不能在 dwCapabilities 中设置EOAC_APPID和EOAC_ACCESS_CONTROL标志。 必须设置 SECURITY_DESCRIPTOR 的所有者和组，在 DCOM 支持审核之前，系统 ACL 必须为 NULL。 SECURITY_DESCRIPTOR的任意 ACL (DACL) 中) 的 访问控制条目 (ACE 用于找出允许哪些调用方连接到进程的对象。 没有 ACE 的 DACL 不允许访问，而 NULL DACL 将允许任何人调用。 有关 ACL 和 ACE 的详细信息，请参阅访问控制模型。 应用程序应调用 AccessCheck (而不是 IsValidSecurityDescriptor) ，以确保在调用 CoInitializeSecurity 之前，其SECURITY_DESCRIPTOR已正确形成。

强烈建议不要将 pSecDesc 作为 NULL 传递。 适当的替代方法可能是使用允许“每个人 ”的SECURITY_DESCRIPTOR 。 如果 pSecDesc 为 NULL， 则 dwCapabilities 中的标志确定 CoInitializeSecurity 如何定义服务器将使用的访问权限，如下所示：

  • 如果设置了EOAC_APPID标志， CoInitializeSecurity 将在注册表中查找应用程序的 .exe 名称，并使用存储在注册表中的 AppID。
  • 如果设置了EOAC_ACCESS_CONTROL标志， CoInitializeSecurity 将返回错误。
  • 如果EOAC_APPID标志和EOAC_ACCESS_CONTROL标志均未设置， 则 CoInitializeSecurity 允许包括本地和远程匿名用户在内的所有调用方。
如果在 dwCapabilities 中同时设置了EOAC_APPID和EOAC_ACCESS_CONTROL标志，CoInitializeSecurity 函数将返回错误。

要求

要求 值
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 combaseapi.h (包括 Objbase.h)
Library Ole32.lib
DLL Ole32.dll

另请参阅

CoSetProxyBlanket

COM 中的安全性