AppID Key
A version of this page is also available for
4/8/2010
This key groups the configuration options, a set of named values, for one or more distributed COM objects into one centralized location in the registry. To simplify the management of common security and configuration settings, DCOM objects hosted by the same executable are grouped into one AppID. The HKEY_LOCAL_MACHINE\SOFTWARE\Classes key corresponds to the HKEY_CLASSES_ROOT key, which was retained for compatibility with earlier versions of COM. The AppID value is stored under the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\{AppID_value}\named_value = value
AppIDs are located in a newly created registry key hierarchy. The AppID_value is a 128-bit Globally Unique Identifier (GUID) that identifies the AppID key.
AppIDs are mapped to executables and classes using the following two different mechanisms:
- Classes indicate the corresponding AppID under the CLSID key in a named-value "AppID" of type REG_SZ. This contains the string value corresponding to the AppID_value under the AppID key. This mapping is used during activation.
- Executables are registered under the AppID key in a named value indicating the module name (such as "MYOLDAPP.EXE"). This named value is of type REG_SZ and contains the string representation of the AppID associated with the executable. This mapping is used to obtain the default access permissions and authentication level.
For COM servers, the mapping is usually generated and written to the registry during the registration process or when running dcomcnfg.exe. However, COM clients that want to set security using the AppID key must create appropriate registry keys and specify the required mapping by calling Win32 registry functions or using regedit. Then values such as AccessPermissions or AuthenticationLevel can be set for the client. For example, if the name of your executable for your client process is "YourClient.exe" and you want to set the authentication level to None; use guidgen.exe or uuidgen.exe to create the GUID that is the AppID for your executable. Then, you would set values in the registry as shown in the following code example, where 00000001 represents an authentication level of None:
[REGEDIT4]
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\yourclient.exe]
@="YourClient"
"AppID"="{YourGuid}"
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\{YourGuid}]
@="YourClient"
"AuthenticationLevel"=dword:00000001
Note
The AuthenticationLevel named value is supported only the full version of COM.
The following table shows the named values for the HKEY_LOCAL_MACHINE\SOFTWARE\Classes\APPID\{AppID_value} key.
| Value : type | Description |
|---|---|
RemoteServerName |
A server may install the RemoteServerName named-value on client machines to configure the client to request the object be run at a particular machine whenever an activation function is called for which a COSERVERINFO structure is not specified. One of the parameters of the distributed COM activation is a pointer to a COSERVERINFO structure. When this value is not NULL, the information in the COSERVERINFO structure overrides the setting of the RemoteServerName key for the function call. RemoteServerName allows simple configuration management of client applications – they may be written without hard-coded server names, and can be configured by modifying the RemoteServerName registry values of the classes of objects they use. |
ActivateAtStorage |
The ActivateAtStorage capability provides a transparent way to allow clients to locate running objects on the same machine as the data that they use. This reduces network traffic, because the object performs local file-system calls instead of calls across the network. Servers can install this named-value on client machines. When this value is not overridden by certain parameters passed to distributed COM activation API functions, the ActivateAtStorage named-value configures the client to instantiate objects on the same machine as the persistent state they are using or from which they are initialized. The ActivateAtStorage named-value can be set by the server to configure the client to instantiate its objects on the same machine as the persistent state used or from which the objects are initialized. The value is a REG_SZ; any value beginning with "Y" or "y" means that ActivageAtStorage should be used. When a value is set for ActivateAtStorage, this becomes the default behavior in calls to the CoGetInstanceFromFile and CoGetInstanceFromIStorage functions, as well as to the file moniker implementation of IMoniker::BindToObject. In all of these calls, specifying a COSERVERINFO structure overrides the setting of ActivateAtStorage for the duration of the function call. The caller can pass COSERVERINFO information to IMoniker::BindToObject through the BIND_OPTS2 structure. The value set for ActivateAtStorage is also the default behavior when CLSCTX_REMOTE_SERVER is specified if no registry information for the class is installed on the client's machine. Client applications written to take advantage of ActivateAtStorage may therefore require less administration. |
LaunchPermission : REG_BINARY |
Contains data describing the Access Control List (ACL) of the principals that can start new servers for this class. The LaunchPermission named-value may be added, under any AppID key, to limit activation by remote clients of specific classes. Upon receiving a local or remote request to launch the server of this class, the ACL described by the LaunchPermission value is checked while impersonating the client, and its success either allows or disallows the launching of the server. If this value does not exist, the machine-wide DefaultLaunchPermission value is checked in the same way as a default to determine if the class code can be launched. |
AccessPermission : REG_BINARY |
Contains data describing the Access Control List (ACL) of the principals that can access instances of this class. This ACL is only used by applications that do not call CoInitializeSecurity. This named-value is a REG_BINARY. It contains data describing the Access Control List (ACL) of the principals that can access instances of this class. Upon receiving a request to connect to an existing object of this class, the ACL is checked by the application being called while impersonating the caller. If the access-check fails, the connection is disallowed. If this named-value does not exist, the machine-wide DefaultAccessPermission ACL is tested in an identical manner (see above) as a default to determine if the connection is to be allowed. |
DllSurrogate |
Enables DLL servers to run in a surrogate process. If an empty string is specified, the system-supplied surrogate is used; otherwise the value specifies the path of the surrogate to be used. HKEY_CLASSES_ROOT is equivalent to HKEY_LOCAL MACHINE\SOFTWARE\Classes. These keys can be used interchangeably. HKEY_CLASSES_ROOT also provides compatibility with Microsoft® Windows 3.1 and Windows 95. The DllSurrogate named value specifies that the class is a DLL that is to be activated in a surrogate EXE process, and the surrogate process to be used. The surrogate_path value is of type REG_SZ. To use the system-supplied generic surrogate process, set surrogate_path to an empty string or NULL. To specify another surrogate process, set surrogate_path to the path of the surrogate. As in the specification of the path of an EXE server under the LocalServer32 key, a full path specification is not necessary. The surrogate EXE must be written to properly communicate with the DCOM. The DllSurrogate named value must be present for a DLL server to be activated in a surrogate. Activation refers to a call to CoGetClassObject, CoCreateInstance, CoCreateInstanceEx, CoGetInstanceFromFile, CoGetInstanceFromIStorage, or IMoniker::BindToObject. DLL servers can be written using standard development tools such as Microsoft Visual Basic® and Microsoft Visual Studio®. Running DLLs in a surrogate process provides the benefits of an executable implementation, including fault isolation, the ability to serve multiple clients simultaneously, and allowing the server to provide services to remote clients in a distributed environment. |
AuthenticationLevel : REG_DWORD |
Sets the authentication level for all applications that do not call CoInitializeSecurity or for applications that call CoInitializeSecurity and specify an AppID. The AuthenticationLevel value is similar to the LegacyAuthenticationLevel value. If the AuthenticationLevel value is present, it will be used instead of the LegacyAuthenticationLevel value for that AppID. Values correspond to the RPC_C_AUTHN_LEVEL_xxxconstants. The following values are valid:
If the AuthenticationLevel value is of the wrong type or out of range, CoInitializeSecurity will fail, causing interface marshaling to fail. This will prevent the application from making any calls at all (cross-apartment, cross-thread, cross-process, or cross-machine). The AuthenticationLevel and AccessPermission values under the AppID are independent. If one is not present, the default will be used. The following rules list the interaction between the AuthenticationLevel value and the AccessPermission value.
|
See Also
Concepts
COM and DCOM Registry Settings
COM and DCOM Security