The CoInitializeSecurity function is a powerful function that allows you to set the default security for an application programmatically. This section describes some of its standard uses and some details on its capabilities.
There are several reasons that you might want to use CoInitializeSecurity to set process-wide security within your program. Although you can set the authentication level and the access permissions in the registry, for example, the default impersonation level for the machine might not be the one you want for your process. The only way to change this default for your process is to call CoInitializeSecurity.
Another common reason for setting process-wide security programmatically is that you would like to set default security for the entire process, but you have one or more objects within that process that expose interfaces with special security requirements. In this case, you can call CoInitializeSecurity to set security for the process, allowing COM to handle most of the security checks, and you can call other methods to set security for the objects with special security needs. Calling these methods and functions are described in Setting Security at the Interface Proxy Level.
If your application has very specialized security requirements, such as allowing certain groups access to different objects depending upon the time of day, you might want to handle all of your security programmatically, ensuring that COM does no automatic checking for you at all. To do this, you must call CoInitializeSecurityset the dwAuthnLevel parameter to none and the pVoid parameter to NULL. You might also need to register your security package in the pAuthnSvc parameter. Then you can handle all of your own security programmatically through calls to the proxy-level interface and functions described in Setting Security at the Interface Proxy Level.
CoInitializeSecurity offers a rich set of capabilities. If you call CoInitializeSecurity, the registry values are ignored, and the security initialization values you pass in to the call are used instead. The first parameter, pVoid, can point to three different types of values, depending on the result you want. In most cases, you will use Win32 functions to create a security descriptor to give to CoInitializeSecurity.
You might, instead, prefer to pass in a pointer to an access control object that COM will use to check access. This technique is supported in Windows NT 4.0 SP2 and all later versions. Windows 95 does not support security descriptors, so if you want your application to run on both Windows NT and Windows 95, you should use an IAccessControl object instead of a security descriptor. The IAccessControl interface is a simple interface for defining an access control list, and COM provides a system implementation of this interface. To tell CoInitializeSecurity that you are passing an IAccessControl object to pVoid, you must pass the EOAC_ACCESS_CONTROL value to the dwCapabilities parameter. Since CoInitializeSecurity caches the results of access checks, the access control list must not be changed after calling CoInitializeSecurity. For more information about the system-supplied implementation of IAccessControl, see IAccessControl.
The third type of value you can pass to the pVoid parameter is a pointer to a GUID, which is the AppID of your application. You must also specify EOAC_APPID in the pCapabilities parameter, so the function knows what value to expect in pVoid. If pVoid does point to an AppID, CoInitializeSecurity uses only the registry for authentication values and ignores all other parameters to CoInitializeSecurity. For more information, see CoInitializeSecurity.