CoInitializeSecurity

Registers security and sets the default security values. For legacy applications, COM automatically calls this function with values from the registry.

HRESULT CoInitializeSecurity(

PSECURITY_DESCRIPTOR pVoid,

//Points to security descriptor

DWORD 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

RPC_AUTH_IDENTITY_HANDLE pAuthInfo,

//Reserved; must be set to NULL

DWORD dwCapabilities,

//Additional client and/or server-side capabilities

void * pvReserved2

//Reserved for future use

);

Parameters

pVoid: [in] Security descriptor. If NULL, no ACL checking will be done. If not NULL, COM will check ACLs on new connections. If not NULL, dwAuthnLevel cannot be RPC_C_AUTHN_LEVEL_NONE.
cAuthSvc: [in] Count of entries in asAuthSvc. Zero means register no services. A value of -1 tells COM to choose which authentication services to register.
asAuthSvc

[in] Array of authentication/authorization/principal names to register. These values are registered to allow incoming calls. After that they are ignored. The default authentication/authorization/principal for each proxy will be negotiated regardless of whether these are set. For example, if the application registers RPC_C_AUTHN_WINNT and receives and interface from a machine that only supports RPC_C_AUTHN_DEC_PUBLIC, COM will choose RPC_C_AUTHN_DEC_PUBLIC if this machine supports it.

pReserved1: [in] Reserved for future use; must be NULL.
dwAuthnLevel: [in] The default authentication level for proxies. On the server side, COM will fail calls that arrive at a lower level. All calls to AddRef and Release are made at this level.
dwImpLevel: [in] The default impersonation level for proxies. This value is not checked on the server side. AddRef and Release calls are made with this impersonation level so even security aware apps should set this carefully. Setting IUnknown security only affects calls to QueryInterface, not AddRef or Release.
pAuthInfo: [in] Reserved for future use; must be NULL.
dwCapabilities: [in] Additional client and/or server-side capabilities. Any set of EOAC flags may be passed. Currently only EOAC_MUTUAL_AUTH, EOAC_SECURE_REFS, and EOAC_NONE are defined.
pReserved2: [in] Reserved for future use; must be zero.

Return Values

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

S_OK: Indicates success.

Remarks

The CoInitializeSecurity layer initializes the security layer and sets the specified values as the security default. The pSecDesc parameter contains two ACLs. The discretionary ACL (DACL) indicates who is allowed to call this process and who is explicitly denied. The system ACL (SACL) contains audit information; this is not supported in the current release, so this portion of pSecDesc must be NULL, so there is no auditing.

A NULL DACL will allow calls from anyone. A DACL with no ACEs allows no access. For information on ACLs and ACEs, refer to Win32 Programmers Reference/Overviews/System Services/Security/Security/Security Model.

The owner and group of the SECURITY_DESCRIPTOR must be set &emdash; applications should call AccessCheck (not IsValidSecurityDescriptor) to ensure that their security descriptor is correctly formed prior to calling CoInitializeSecurity.

If the application passes a NULL security descriptor, COM will construct one that allows calls from the current user and local system. All new connections will be audited. Distributed COM will copy the security descriptor.

If mutual authentication is enabled all calls will fail unless the server identity is verified to match the principal name set on the proxy. Without mutual authentication, security only helps the server; the client has no idea who is handling his call. While CoInitializeSecurity takes principal names as parameters, that does not mean that the server can register any arbitrary name. The security provider verifies that the server has a right to use the names registered.

Secure references cause DCOM to make extra callbacks to insure that objects are not released maliciously.

PSECURITY_DESCRIPTOR pVoid,	//Points to security descriptor
DWORD 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
RPC_AUTH_IDENTITY_HANDLE pAuthInfo,	//Reserved; must be set to NULL
DWORD dwCapabilities,	//Additional client and/or server-side capabilities
void * pvReserved2	//Reserved for future use
);