[This is preliminary documentation and subject to change.]
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, //Points to security descriptor
LONG cAuthSvc, //Count of entries in asAuthSvc
SOLE_AUTHENTICATION_SERVICE * asAuthSvc,
//Array of names to register
void * pReserved1, //Reserved for future use
DWORD dwAuthnLevel, //The default authentication level
// for proxies
DWORD dwImpLevel, //The default impersonation level
// for proxies
SOLE_AUTHENTICATION_LIST * pAuthList,
//Authentication information for
// each authentication service
DWORD dwCapabilities, //Additional client and/or
// server-side capabilities
void * pReserved3 //Reserved for future use
);
The NTLMSSP and Kerberos entries in the list should each contain a pointer to a SEC_WINNT_AUTH_IDENTITY_W or to a SEC_WINNT_AUTH_IDENTITY_EXW structure containing the user name and password.
For the SSL entry, the pAuthInfo member of the SOLE_AUTHENTICATION_INFO structure should be a CAPI handle to a private certificate.
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.
This function supports the standard return value E_INVALIDARG, as well as the following:
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 NT 4 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. For more information on ACLs and ACEs, see Access Control Model.
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.
When a CAPI handle is specified for the SSL entry in pAuthList, the CAPI handle must not be freed until CoUninitialize is called. If the list is specified but there is no entry for SSL, DCOM will try to find a default identity the first time DCOM negotiates SSL as the authentication service. If that succeeds, DCOM will save that identity as the default. Otherwise, the client will be anonymous for SSL.
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in objbase.h.
Import Library: Included as a resource in ole32.dll.
RPC_C_IMP_LEVEL_xxx, RPC_C_AUTHN_LEVEL_xxx, Security in COM