CoInitializeSecurity

  • Article

This function 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 or the 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 process-wide 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. This parameter is used when the process calling CoInitializeSecurity acts as a server. Its value can be NULL or a pointer to one of three types: either an AppID, an IAccessControl object, or a Win32 security descriptor. The type of data that pVoid points to is indicated by a flag set in the dwCapabilities parameter. If EOAC_APPID is specified, pVoid must be a pointer to a GUID that specifies the AppID of the process. In this case, all other parameters of the call are ignored, and registry values are used for security checks. If EOAC_ACCESS_CONTROL is specified, pVoid must be a pointer to an IAccessControl object, which determines who can call the process. If the capability flags (dwCapabilities) do not include either EOAC_APPID or EOAC_ACCESS_CONTROL, pVoid must be a pointer to a Win32 security descriptor. If pVoid is NULL, no ACL checking will be done. If it is not NULL, COM will check ACLs on calls and dwAuthnLevel cannot be RPC_C_AUTHN_LEVEL_NONE. See the Remarks section for more information.

  • cAuthSvc
    [in] Count of entries in asAuthSvc. Zero means register no authentication services. If you specify zero, you 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 zero. This value is used by COM when the process acts as a server.

  • asAuthSvc
    [in] Array of authentication service information used by COM to choose the authentication service for the process when it acts as a server. These values are control which security providers are used for incoming calls. Outgoing calls may use any security provider installed on the machine. The entries for NTLMSSP, Kerberos, and Snego must have the pPrincipalName member set to NULL.

  • pReserved1
    [in] Reserved for future use; this value must be NULL.

  • dwAuthnLevel
    [in] The default authentication level for the process. 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 applies when the process is the 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.

  • pAuthList
    [in] This parameter is a pointer to a SOLE_AUTHENTICATION_LIST, which is an array of SOLE_AUTHENTICATION_INFO structures. This list indicates the default authentication information to use for each authentication service. It applies only to clients. When DCOM negotiates the default authentication service for a proxy, it picks the default authentication information from this list. If the pAuthInfo member of the SOLE_AUTHENTICATION_INFO structure representing the chosen authentication service is NULL, DCOM will use the process identity to represent the client. If both pAuthList and one of the cloaking flags are set, CoInitializeSecurity will return an error.

    The NTLMSSP and Kerberos entries in the list should each contain a pointer to a SEC_WINNT_AUTH_IDENTITY structure containing the user name and password.

    For Snego, the pAuthInfo member should be NULL or point to a SEC_WINNT_AUTH_IDENTITY_EXW structure. If non-NULL, the structure's PackageList member must point to a string containing a comma-separated list of authentication service names, and the PackageListLength member must give the number of bytes in the PackageList string. If pAuthInfo is NULL, Snego will pick a list of authentication services to try based on those available on the client machine.

    For more information, see the Remarks section.

  • dwCapabilities
    [in] Additional capabilities of the client or server. If a flag other than one of the following EOLE_AUTHENTICATION_CAPABILITIES flags is specified, CoInitializeSecurity will return an error: EOAC_APPID, EOAC_ACCESS_CONTROL, EOAC_STATIC_CLOAKING, EOAC_DYNAMIC_CLOAKING, EOAC_AUTO_IMPERSONATION, EOAC_SECURE_REFS, EOAC_REQUIRE_FULLSIC, EOAC_MAKE_FULLSIC, EOAC_ANY_AUTHORITY, or EOAC_MUTUAL_AUTH. Some of these flags cannot be set simultaneously.

  • 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

Remarks

The CoInitializeSecurity function initializes the security layer and sets the specified values as the security default. If the 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.

When the EOAC_APPID flag is set in dwCapabilities, pVoid points to an AppID and all other parameters to CoInitializeSecurity are ignored (and must be zero). CoInitializeSecurity looks for the authentication level under the AppID key in the registry and uses it to determine the default security. If pVoid is NULL, CoInitializeSecurity will look up the application .exe name in the registry and use the AppID stored there. This gives the same security settings as if the process had not called CoInitializeSecurity. Before Windows NT® version 4.0 SP 4, CoInitializeSecurity returned an error if it did not find the specified AppID in the registry. For more information on how the AppID key is used to set security, see Setting Process-wide Security Through the Registry and the EOLE_AUTHENTICATION_CAPABILITIES enumeration.

If the EOAC_ACCESS_CONTROL flag is set, pVoid is a pointer to an IAccessControl object, which determines 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 EOAC_ACCESS_CONTROL is specified, the dwAuthnLevel cannot be none.

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

If neither the EOAC_APPID nor the EOAC_ACCESS_CONTROL flag is specified in dwCapabilities, pVoid must be a pointer to a Win32 SECURITY_DESCRIPTOR. A security descriptor contains two ACLs: the discretionary ACL (DACL) indicates who is (and who is not) allowed to call the process; the system ACL (SACL) contains audit information. DCOM looks for the COM_RIGHTS_EXECUTE flag in the DACL to find out which callers are permitted to connect to the process's objects. Until DCOM supports auditing, the SACL must be NULL. A DACL with no ACEs allows no access. A NULL DACL will allow calls from anyone.

If pVoid is a security descriptor, the owner and group of the SECURITY_DESCRIPTOR must be set — applications should call AccessCheck (not IsValidSecurityDescriptor) to ensure that their security descriptor is correctly formed prior to calling CoInitializeSecurity. DCOM will copy the specified security descriptor. If the application passes a NULL security descriptor, COM will construct one that allows calls from anyone.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Objbase.h.
Link Library: Ole32.lib.

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.