CoInitializeSecurity

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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 your application sets process-wide security using the registry and then calls CoInitializeSecurity, the AppID registry values will be ignored, and the CoInitializeSecurity values will be used.

Syntax

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:

  • An AppID
  • An IAccessControl object
  • 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. This value is used by COM when the process acts as a server.

  A value of zero indicates that the function should register no authentication services. Your application should supply a value of zero if it cannot receive secure calls.

  A value of -1 tells the function to choose which authentication services to register. In this case, the asAuthSvc parameter must be zero.

• 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 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 Value

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
  Not enough memory to complete the requested operation.

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.

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

See Also

Reference

COM Functions