CoInitializeSecurity function

Registers security and sets the default security values for the process. 寄存器安全和设置进程默认安全等级

Syntax

C++

HRESULT CoInitializeSecurity(
  _In_opt_ PSECURITY_DESCRIPTOR        pSecDesc,
  _In_     LONG                        cAuthSvc,
  _In_opt_ SOLE_AUTHENTICATION_SERVICE *asAuthSvc,
  _In_opt_ void                        *pReserved1,
  _In_     DWORD                       dwAuthnLevel,
  _In_     DWORD                       dwImpLevel,
  _In_opt_ void                        *pAuthList,
  _In_     DWORD                       dwCapabilities,
  _In_opt_ void                        *pReserved3
);

Parameters

pSecDesc [in, optional]

The access permissions that a server will use to receive calls. This parameter is used by COM only when a server calls CoInitializeSecurity. Its value is a pointer to one of three types: an AppID, an IAccessControl object, or a SECURITY_DESCRIPTOR, in absolute format. See the Remarks section for more information.

cAuthSvc [in]

The count of entries in the asAuthSvc parameter. This parameter is used by COM only when a server calls CoInitializeSecurity. If this parameter is 0, no authentication services will be registered and the server cannot receive secure calls. A value of -1 tells COM to choose which authentication services to register, and if this is the case, the asAuthSvc parameter must be NULL. However, Schannel will never be chosen as an authentication service by the server if this parameter is -1.

asAuthSvc [in, optional]

An array of authentication services that a server is willing to use to receive a call. This parameter is used by COM only when a server callsCoInitializeSecurity. For more information, see SOLE_AUTHENTICATION_SERVICE.

pReserved1 [in, optional]

This parameter is reserved and must be NULL.

dwAuthnLevel [in]

The default authentication level for the process. Both servers and clients use this parameter when they call CoInitializeSecurity. COM will fail calls that arrive with a lower authentication level. By default, all proxies will use at least this authentication level. This value should contain one of the authentication level constants. By default, all calls to IUnknown are made at this level.

dwImpLevel [in]

The default impersonation level for proxies. The value of this parameter is used only when the process is a client. It should be a value from theimpersonation level constants, except for RPC_C_IMP_LEVEL_DEFAULT, which is not for use with CoInitializeSecurity.

Outgoing calls from the client always use the impersonation level as specified. (It is not negotiated.) Incoming calls to the client can be at any impersonation level. By default, all IUnknown calls are made with this impersonation level, so even security-aware applications should set this level carefully. To determine which impersonation levels each authentication service supports, see the description of the authentication services in COM and Security Packages. For more information about impersonation levels, see Impersonation.

pAuthList [in, optional]

A pointer to SOLE_AUTHENTICATION_LIST, which is an array of SOLE_AUTHENTICATION_INFO structures. This list indicates the information for each authentication service that a client can use to call a server. This parameter is used by COM only when a client callsCoInitializeSecurity.

dwCapabilities [in]

Additional capabilities of the client or server, specified by setting one or more EOLE_AUTHENTICATION_CAPABILITIES values. Some of these value cannot be used simultaneously, and some cannot be set when particular authentication services are being used. For more information about these flags, see the Remarks section.

pReserved3 [in, optional]

This parameter is reserved and must be NULL.

Return value

This function can return the standard return value E_INVALIDARG, as well as the following values.

Return code	Description
S_OK	Indicates success.
RPC_E_TOO_LATE	CoInitializeSecurity has already been called.
RPC_E_NO_GOOD_SECURITY_PACKAGES	The asAuthSvc parameter was not NULL, and none of the authentication services in the list could be registered. Check the results saved in asAuthSvc for authentication service–specific error codes.
E_OUT_OF_MEMORY	Out of memory.

 

Remarks

The CoInitializeSecurity function initializes the security layer and sets the specified values as the security default. If a process does not callCoInitializeSecurity, COM calls it automatically the first time an interface is marshaled or unmarshaled, registering the system default security. No default security packages are registered until then.

This function is called exactly once per process, either explicitly or implicitly. It can be called by the client, server, or both. For legacy applications and other applications that do not explicitly call CoInitializeSecurity, COM calls this function implicitly with values from the registry. If you set processwide security using the registry and then call CoInitializeSecurity, the AppID registry values will be ignored and the CoInitializeSecurityvalues will be used.

CoInitializeSecurity can be used to override both computer-wide access permissions and application-specific access permissions, but not to override the computer-wide restriction policy.

If pSecDesc points to an AppID, the EOAC_APPID flag must be set in dwCapabilities and, when the EOAC_APPID flag is set, all other parameters toCoInitializeSecurity are ignored. CoInitializeSecurity looks for the authentication level under the AppID key in the registry and uses it to determine the default security. For more information about how the AppID key is used to set security, see Setting Process-Wide Security Through the Registry.

If pSecDesc is a pointer to an IAccessControl object, the EOAC_ACCESS_CONTROL flag must be set and dwAuthnLevel cannot be none. TheIAccessControl object is used to determine who can call the process. DCOM will AddRef the IAccessControl and will Release it when CoUninitializeis called. The state of the IAccessControl object should not be changed.

If pSecDesc is a pointer to a SECURITY_DESCRIPTOR, neither the EOAC_APPID nor the EOAC_ACCESS_CONTROL flag can be set in dwCapabilities. The owner and group of the SECURITY_DESCRIPTOR must be set, and until DCOM supports auditing, the system ACL must be NULL. The access-control entries (ACEs) in the discretionary ACL (DACL) of the SECURITY_DESCRIPTOR are used to find out which callers are permitted to connect to the process's objects. A DACL with no ACEs allows no access, while a NULL DACL will allow calls from anyone. For more information on ACLs and ACEs, see Access Control Model. Applications should call AccessCheck (not IsValidSecurityDescriptor) to ensure that their SECURITY_DESCRIPTOR is correctly formed prior to calling CoInitializeSecurity.

Passing pSecDesc as NULL is strongly discouraged. An appropriate alternative might be to use a SECURITY_DESCRIPTOR that allows Everyone. IfpSecDesc is NULL, the flags in dwCapabilities determine how CoInitializeSecurity defines the access permissions that a server will use, as follows:

• If the EOAC_APPID flag is set, CoInitializeSecurity will look up the application's .exe name in the registry and use the AppID stored there.
• If the EOAC_ACCESS_CONTROL flag is set, CoInitializeSecurity will return an error.
• If neither the EOAC_APPID flag nor the EOAC_ACCESS_CONTROL flag is set, CoInitializeSecurity allows all callers including Local and Remote Anonymous Users.

The CoInitializeSecurity function returns an error if both the EOAC_APPID and EOAC_ACCESS_CONTROL flags are set in dwCapabilities.

Requirements

Minimum supported client	Windows 2000 Professional [desktop apps | Windows Store apps]
Minimum supported server	Windows 2000 Server [desktop apps | Windows Store apps]
Minimum supported phone	Windows Phone 8
Header	Objbase.h
Library	Ole32.lib
DLL	Ole32.dll

整个进程安全

整个进程安全可以通过CoInitializeSecurity和相应参数设置。这个API内每个使用COM的进程（客户机和服务器）调用一次，如果不是显式调用，则COM用应用程序AppID中的安全设置（如有）或整个机器范围的缺省调用CoInitializeSecurity。CoInitializeSecurity说明如下：
HRESULT CoInitializeSecurity(
PSECURITY_DESCRIPTOR pVoid,
LONG cAuthSvc,
SOLE_AUTHENTICATION_SERVICE * asAuthSvc,
void * pReserved1,
DWORD dwAuthnLevel,
DWORD dwImpLevel,
SOLE_AUTHENTICATION_LIST * pAuthList,
DWORD dwCapabilities,
void * pReserved3
);
说明：每个进程调用CoInitializeSercurity一次，再次调用会失败，并返回RPC_E_TOO_LATE。要实现微调安全控制，可以指定接口范围的安全设置，覆盖CoInitializeSecurity中指定的整个进程范围设置。编写基于DLL的COM应用程序时，不能调用CoInitializeSecurity,因为代理会调用CoInitializeSecurity.
指定访问控制信息
第一个参数pVoid在进程作为COM服务器时传送访问控制信息，它可以取NULL，这时COM生成允许任何人访问的SID。也可以取参数pVoid，它为下列三种类型之一的指针：
1、AppID中的指针，COM查找和使用注册表指定AppID中存放的安全设置。这时CoInitializeSecurity的所有其它参数均忽略。
2、Win32 SID指针，这个Win32 SID中包含DACL（自主访问控制列表）指定谁能访问这个服务器。COM搜索这个DACL中的COM_RIGHTS_EXECUTE权限.由于COM目前不支持监查,因此SACL(系统访问控制列表)应该为NULL.
3、IAcessControl接口的指针。IAccessControl是COM定义的接口，提供COM服务器上的访问控制信息。如果向CoInitializeSecurity传送IAccessControl接口的指针，则COM在需要时，可从任何线程中调用接口的方法，检查用户对服务器上的访问权限。因此，实现IAccessControl时，要保证其为线程安全的。
说明：别把IAccessControl与COMTrader的IAccessControl接口混起来，它们完全无关，IID也不同。
指定验证服务信息
asAuthSvc参数指定验证服务信息数组。COM用这个信息选择安全提供者（例如NTLM或Kerberos)，用来输入方法调用；输出调用可以用任何安全提供者。这个数组中的元素个数在cAuthSvc中指定。每个元素的类型为SOLE_AUTHENTICATION_SERVICE(底部认证服务),定义如下:
typedef struct tagSOLE_AUTHENTICATION_SERVICE{
DWORD dwAuthnSvc;
DWORD dwAuthzSvc;
OLECHAR* pPrincipalName;
HRESULT hr;
}SOLE_AUTHENTICATION_SERVICE;
其中:1、dwAuthnSvc指定枚举类型RPC_C_AUTHN_xxx所定义清单中的验证服务,目前只支持两个值:RPC_C_AUTHN_WINNT与RPC_C_AUTHN_GSS_KERBEROS(仅适用于Windows 2000)
2、dwAuthzSvc指定枚举类型RPC_C_AUTHZ_xxx中的授权服务.目前只支持RPC_CAUTHZ_NONE.在Windows 2000中还可以指定RPC_C_AUTHZ_DEFAULT.让COM在安全总括协议中选择授权服务.
3、pPrincipalName指定验证服务使用的用户标识符(主体名).对NTLM和Kerberos,它为NULL,COM用当前用户标识符.
4、hr返回调用注册验证服务的结果.如果CoInitializeSecurity失败,则可以检查hr,确定调用注册验证服务是否失败,为什么.
dwAuthnLevel指定RPC_C_AUTHN_LEVEL_xxx所定义的验证级别之一.同样dwImpLevel指定代理的缺省扮演级别.本章前面曾介绍过,客户机指定扮演级别,因此这个参数只在进程作为客户机时才适用.dwImpLevel应为RPC_C_IMP_LEVEL_XXX定义的级别。
pAuthList包含SOLE_AUTHENTICATION_INFO结构的数组，类似于前面介绍的SOLE_AUTHENTICATION_SERVICE结构。COM在安全总括协商之后选择验证服务时搜索pAuthList中针对所选服务的验证信息。
指定验证功能
CoInitializeSecurity最后一个有趣的参数dwCapabilites指定EOLE_AUTHENTICATION_CAPABILITES枚举类型中的一个或几个标志。这些标志在CoInitializeSecurity中设置其它安全信息。
例如，指定EOAC_SECURE_REFS时COM验证分布式引用次数调用（AddRef和Release)，防止服务器对象恶意提前释放。其它标志包括EOAC_STATIC_CLOAKING和EOAC_DYNAMIC_CLOAKING,分别指定静态和动态掩盖。也可以用标志EOAC_APPID和EOAC_ACCESS_CONTROL表示CoInitializeSecurity第一个参数pVoid是AppID或IAccessControl的指针。