CoInitializeSecurity

CoInitializeSecurity

COM

CoInitializeSecurity

Registers security and sets the default security values for the process. 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 CoInitializeSecurity values will be used.

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
);

Parameters

pVoid: [in] Defines 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 can be NULL or a pointer to one of three types: an AppID, an IAccessControl object, or a Win32 SECURITY_DESCRIPTOR. See the Remarks section for more information.

cAuthSvc: [in] Count of entries in asAuthSvc. 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 if this parameter is -1.

asAuthSvc: [in] 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 calls CoInitializeSecurity. For more information, see SOLE_AUTHENTICATION_SERVICE.

pReserved1: [in] Reserved for future use; this value 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 flags from the RPC_C_AUTHN_LEVEL_xxx enumeration. 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 the RPC_C_IMP_LEVEL_xxx enumeration. 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.

Note:
Except for RPC_C_AUTHN_LEVEL_DEFAULT, all other default security constants (such as RPC_C_IMP_LEVEL_DEFAULT) are invalid for use as CoInitializeSecurity parameters. These other default constants are defined as placeholders for proxy blanket negotiated settings.

pAuthList: [in] This value must be NULL on Windows NT 4. On Windows 2000, this parameter is a pointer to a 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 calls CoInitializeSecurity. For more information, see SOLE_AUTHENTICATION_INFO.

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

pReserved3: [in] Reserved for future use; it must be set to NULL.

Return Values

This function supports the standard return value E_INVALIDARG, as well as the following:

S_OK: Indicates success.

RPC_E_TOO_LATE: CoInitializeSecurity has already been called.

RPC_E_NO_GOOD_SECURITY_PACKAGES: asAuthSvc 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 call CoInitializeSecurity, 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.

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

If pVoid points to an AppID, the EOAC_APPID flag must be set in dwCapabilities and, when the EOAC_APPID flag is set, all other parameters to CoInitializeSecurity are ignored. CoInitializeSecurity looks for the authentication level under the AppID key in the registry and uses it to determine the default security. Before Windows NT 4 SP 4, CoInitializeSecurity returned an error if it did not find the specified AppID in the registry. For more information about how the AppID key is used to set security, see Setting Processwide Security Through the Registry.

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

If pVoid is a pointer to a Win32 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.

Note:
The SECURITY_DESCRIPTOR must be in absolute format.

If pVoid 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 will construct a SECURITY_DESCRIPTOR that allows calls from anyone.

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

Requirements

For an explanation of the requirement values, see Requirements (COM).

Windows NT/2000/XP: Requires Windows NT 4.0 or later.

Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.

Header: Declared in objbase.h.

Library: Use ole32.lib.