Chapter 4: Data and Settings Management

Article
06/30/2006

Windows 2000 provides an underlying infrastructure that supports state separation of user data, user settings, and computer settings. Applications that properly use this infrastructure offer the following benefits:

Support for roaming users
Support for multiple users on a single machine, each with their own settings
Simplified machine replacement
Operation in a secure Windows environment
Helps ensure proper functioning on Terminal Services

IntelliMirror uses these features along with software installation and maintenance technologies described in "Chapter 2: Windows Install Service" to provide the "follow me" feature that allows users' data, settings, and software to follow them to any Windows 2000-based desktop.

Customer Benefits

Users can easily back up their individual documents and settings without having to backup application and operating system files
Applications can be installed and run in a secure Windows environment
Multiple users can share a single computer, each with their own preferences and settings
A single user can roam to multiple computers, maintaining their own documents and settings from one computer to another
Administrators can easily manage corporate desktops

Requirements

4.1 Default to My Documents for storage of user-created data

4.2 Classify and store application data correctly

4.3 Degrade gracefully on access denied

4.4 Run in a secure Windows environment

4.5 Adhere to system-level Group Policy settings

4.6 Applications that create ADM files must properly store their ADM file settings in the registry

References

"Windows 2000 Default Access Control Settings" at: https://www.microsoft.com/windows/server/Technical/security
Whitepapers on Windows 2000 Management Services at: https://www.microsoft.com/windows/server/Technical/management
Information on registry settings for system-level Group Policy: System.adm file, installed on Windows 2000 systems

How to Comply with Data and Settings Management Requirements

4.1 Default to My Documents for storage of user-created data

If your application allows for local file I/O, then the first time an application is run per user, the application’s Common File Open and Save dialogs must default to the My Documents folder or descendant folder the first time these dialogs are called. On subsequent calls to these dialogs, it is recommended to default to the previously used path.

Calling the Common File Open/Save with no parameters will default to the My Documents folder or you can target the My Documents folder directly by passing CSIDL_PERSONAL to SHGetFolderPath().

Note The My Documents folder is for user-created data, but not for temporary storage or application state data. Non-user data must be stored using the proper AppData path, as described in Requirement 4.2.

Note For imaging applications, it is recommended to use My Pictures, a descendant of My Documents, in place of My Documents.

Benefits for using the My Documents folder as the default for data storage are:

Users have one familiar place to organize and store all their data
Data sharing is facilitated between applications because all applications using Common File Open can easily access the My Documents folder
My Documents is an abstracted location and can be redirected to the network transparently by an administrator
My Documents is available on the Desktop
The My Documents folder is part of a user's profile information, so by default, other users can’t read its contents

Retrieving the path to My Documents: The preferred way to do this is by using passing CSIDL_PERSONAL to the SHGetFolderPath API.

TCHAR szMyDocs[MAX_PATH]; 
... 
hr = SHGetFolderPath(NULL, CSIDL_PERSONAL, NULL, 0, szMyDocs)

SHGetFolderPath behaves consistently across Windows 95, Windows 98, Windows NT 4, and Windows 2000 and is exported from SHFOLDER.DLL. SHFOLDER.DLL ships in Windows 2000 as well as Windows NT 4 Service Pack 4 (and later), Internet Explorer 5, and Windows 98 Second Edition. SHFOLDER.DLL is a redistributable component that contains support for CSIDL_PERSONAL as well as many other special folders. (See: "Appendix A: Best Practices".) SHFOLDER.DLL is installed by the Windows Installer redistributable. Software vendors are encouraged to redistribute this component as much as possible to enable this support on Windows operating systems prior to Windows 2000. Windows 2000 includes this DLL as a protected system file and as such, this DLL cannot be replaced on Windows 2000 or greater.

To help ensure your application can run on Windows 9x, Windows NT 4 as well as Windows 2000, always link to the SHGetFolderPath implementation in SHFOLDER.DLL. Windows 2000 natively implements SHGetFolderPath in SHELL32.DLL, but other versions of Windows do not include SHGetFolderPath in SHELL32.DLL.

4.2 Classify and store application data correctly

Application data, such as user preferences, application state, temp files, and so on, must be stored in application data folders or the registry according to the following classifications:

Per user, roaming
Per user, non-roaming
Per machine (non-user specific and non-roaming)

Guidelines on classifying application data among these three choices are provided below, though the final decision is left to the software developer. Classifying application data according to these three types ensures a consistent and abstracted location for user data, enables roaming, enforces per-user separation of application data, and allows the operating system and its applications to be secured. In a roaming scenario, data that is designated as roaming will be copied to and from the server during logon/logoff processing. It is important to prioritize carefully what should be roamed vs. not roamed so as to minimize the amount of information that is transferred across the network.

In general, use application data folders rather than the registry for storing application data in excess of 64KB. The registry is acceptable for small amounts of data. At install time your application must not store more than a total of 128KB across HKCU and HKLM (HK Classes Root is excluded).

Using Application Data Folders

The CSIDL values described here provide a consistent, unified way to access the physical paths to the desired folder locations, independent of the operating system. The preferred API is SHGetFolderPath, because it behaves consistently across all versions of Windows. To access the path for application data, applications should call SHGetFolderPath with the appropriate CSIDL and then append [company name]\[product name]\[version] to the returned path.

Specifically, to retrieve the CSIDL _APPDATA path:

TCHAR szAppData[MAX_PATH];
…
hr = SHGetFolderPath(NULL, CSIDL_APPDATA, NULL, 0, szAppData);

When storing application data in the user profile, applications should use the same hierarchy under Application Data and Templates as is used in the registry:

   [User Profile]\
      Application Data\
         [company name]\
            [product name]\
               [version]\
                  [file or folder]

Data Type	Folder CSIDL	Folder Location
Per user, roaming	CSIDL_APPDATA	[user profile]\Application data
Per user, non-roaming	CSIDL_LOCAL_APPDATA	[user profile]\Local Settings\Application data
Per machine (non-user specific & non- roaming)	CSIDL_COMMON_APPDATA	All Users\Application data

CSIDL_APPDATA

As part of the User profile, this folder will roam. Use this folder to store all user-specific application preferences. For example, if a user can specify a custom dictionary to be used in your application, you should store it here. That way if the user roams from computer to computer, their dictionary will roam with them. This also allows other users to have their own individual custom dictionaries.
CSIDL_LOCAL_APPDATA

This folder is for application data that does not roam. It is still part of the User profile, so this is still per-user information. Application data that is machine-dependent, such as user specified monitor resolution, should be stored here. This data must not roam because different machines have different monitors. In addition, large blocks of data which can easily be re-created should be placed here to minimize download time that is incurred when roaming. For example, Internet Explorer keeps its cache of downloaded html/gif pages here so that they don't roam with the user. But the smaller cookie and history lists are stored in CSIDL_APPDATA so that they roam.
CSIDL_COMMON_APPDATA

This folder should be used for application data that is not user specific. For example, an application may store a spell check dictionary, a database of clip-art or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer. By default, this location is read-only for normal (non-admin, non-power) Users. If an application requires normal Users to have write access to an application specific subdirectory of CSIDL_COMMON_APPDATA, then the application must explicitly modify the security on that sub-directory during application setup. The modified security must be documented in the Vendor Questionnaire.

Using the Registry

Applications may also use the registry for storing read/write application data and configuration files.

The HKCU registry is appropriate for storing small amounts of data (<64KB) and for policy settings that are per user
Avoid writing to HKLM during runtime, because normal Users have Read Only access to the entire HKLM tree by default; also, HKLM does not support roaming
Larger, file-based data should be placed in the Application Data folder; for example, Internet Explorer's Temporary Internet Cache is stored within the user profile and not in the registry
At install time your application must not store more than a total of 128KB across HKCU and HKLM (HK Classes Root is excluded)

Additional Considerations

Files may be shared in UserProfile\Application Data. Multiple computers may use them simultaneously in different versions of the application

The data may also be used by multiple applications, for example, applications in a productivity suite. Applications should only get a write exclusive on the file when necessary. For example, applications using CreateFile should only specify GENERIC_WRITE when a write is required, but they should always set FILE_SHARE_READ.
Paths returned by SHGetFolderPath are valid Win32 file system names that may contain spaces and may be in the UNC format
PathAppend() and PathCombine() APIs can be used to concatenate the relative path information onto the paths returned by SHGetFolderPath; for example:
```
PathAppend(szAppData, "Company\Product\File.txt")
```
Any user can write into the All Users\Documents location

By default, only the creator of the document (and administrators) will be able to subsequently modify the document. All other (non-admin) Users will have read-only access to the document by default. If an application requires that all normal Users to have write access to a given application specific subdirectory of CSIDL_COMMON_DOCUMENTS, then the application must explicitly modify the security on that sub-directory during application setup. The modified security must be documented in the Vendor Questionnaire.
By default normal Users have read only access to all locations other than those specified in Requirement 4.4; normal Users cannot write to the Winnt directory, system32, or the Program Files directory

4.3 Degrade gracefully on access denied

By default on Windows 2000, normal (non-admin, non-power) Users cannot write to per-machine locations such as HKLM and the Winnt directory. Only applications that classify and store data correctly, as described above, will be able to avoid access denied errors and run successfully in this secure environment. There are, however, legitimate scenarios where access denied errors are encountered by applications which classify and store data correctly. For example:

An unprivileged User may attempt to run an administrative application that is designed to modify system-wide settings; in this case, the User is allowed to run the application, but cannot carry out any system-wide modifications
An unprivileged User may run an application that allows users to modify objects based on permissions; in this case, a User is allowed to modify objects which they own, but not objects owned by the administrator or other Users
An unprivileged User may direct an application to save per-user data in a per-machine location, for example, by choosing the system directory as the destination for a File\Save operation

In these cases, the application should degrade gracefully when the access denied error is encountered. Degrading gracefully can be accomplished by:

Disabling the operation in the first place.

This is the approach taken by System Settings in Control Panel. A User cannot set system-wide environment variables, but they can set their own environment variables. Thus, when a User launches this applet, the system-wide environment variable option is "grayed-out". When an administrator launches it, the system-wide environment variables can be modified.
Display an appropriate error message. For example:
- "You must be an administrator to perform this operation"
- "You only have permissions to view the properties of this object"
- "You must have xyz privilege to perform this operation"
- "You must have write access to abc.xyz to perform this operation"

4.4 Run in a secure Windows environment

Your application must function properly in a secure Windows environment. Complying with the previous requirements in this chapter will help ensure that your application meets this requirement.

A secure Windows environment is defined as the environment exposed to a normal (non-admin\non-power) User by default on a clean-installed NTFS system. In this environment, Users can only write to three* specific locations:

Their own portion of the registry (HKEY_CURRENT_USER)

Users cannot write to the following subsections of HKCU:
```
\Software\Policies 
\Software\Microsoft\Windows\CurrentVersion\Policies 
```
Their own user profile directory (CSIDL_PROFILE)
A Shared Documents location (CSIDL_COMMON_DOCUMENTS)

By default, Users cannot write to other Users’ shared documents, they can only read other Users’ shared documents. Applications are free to modify this default security on an application-specific subdirectory of CSIDL_COMMON_DOCUMENTS provided the modification is documented in the Vendor Questionnaire.

Users can also write to subkeys and subdirectories of these locations. For example, users can write to CSIDL_PERSONAL (My Documents) because it is a subdirectory of CSIDL_PROFILE. Users have Read-Only access to the rest of the system.

Note Applications are free to modify the default security for an application-specific subdirectory of CSIDL_COMMON_APPDATA provided the modification is documented in the vendor questionnaire. This may provide a fourth location for Users to write to for a given application.

**Exception **When the major features of the application can be successfully run as a non-privileged User, exceptions may be made for minor features that are not considered important for the operation of the program and which are not installed by any default mechanism (e.g. a minimal or typical install) other than a "complete" install. Examples of such minor features include components necessary to support legacy file formats. In some cases, entire applications may be exempted, provided that the primary purpose of the application is to perform some administrative function that is technically not possible for normal Users to perform. For any feature that does not work as User, you must document in the Vendor Questionnaire what objects (file system\registry keys) need to be opened in order for that feature\function to work. Requests for exemptions are judged on a case-by-case basis.

4.5 Adhere to system-level Group Policy settings

Group Policy settings allow administrators to control and manage their users’ PC environments by mandating specific user and computer settings across the network. System-level Group Policy settings may be set by administrators to control specific capabilities of the system. For each policy listed below, your application must adhere to any policy settings that are enabled at the time your application is launched. Adherence to an enabled policy is defined by "Application Action" in the charts below. The "Registry Information" indicates where the policy setting information is stored.

For many applications, no action is required to adhere to these policies. However, if your application replaces or duplicates operating system functionality, specific steps may be required on the part of the application.

Policy Setting	Remove Run menu from Start Menu
Description	When this policy is enabled, Windows 2000 removes Run from the Start Menu and disables users from launching the Run dialog via pressing the Windows Key + R
Application Action	If your application has a "run" function that allows a user to start a program by typing in its name and path in a dialog, then your application must disable that functionality when this policy is enabled
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value Name: NoRun

Policy Setting	Hide these specified drives in My Computer
Description	When enabled, this policy removes the icons representing the selected disk drives from My Computer, Windows Explorer, and My Network Places and from Common Dialogs
Application Action	Your application must hide any drives that are hidden by the system when this policy is enabled; this includes any buttons, menu options, icons, or any other visual representation of drives in your application. This does not preclude the user from accessing drives by manually entering drive letters in dialogs
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value Name: NoDrives

Policy Setting	Run only allowed Windows Applications
Description	When this policy is enabled, users can only run applications that are listed under the following key: Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\RestrictRun
Application Action	Your application must not start any application that is not on this list; if you use ShellExecuteEx, Windows 2000 will handle this for you automatically
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value Name: RestrictRun

Policy Setting	Remove "Map Network Drive" and "Disconnect Network Drive"
Description	When this policy is enabled, users are prevented from using Windows Explorer and My Network Places to connect to other computers or to close existing connections
Application Action	When this policy is enabled, applications must not provide buttons, menu options, icons, or any other visual representation that enables a user to map or disconnect network drives
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value Name: NoNetConnectDisconnect

Policy Setting	No Entire Network in My Network Places
Description	When enabled, this policy removes all computers outside of the user's workgroup or local domain from lists of network resources in Windows Explorer and My Network Places
Application Action	When this policy is enabled, applications that allow users to browse network resources must limit browsing functionality to local workgroup or domain
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Network Value Name: NoEntireNetwork

Policy Setting	Do not keep history of recently open documents
Description	When this policy is enabled, the system does not save shortcuts to most recently used (MRU) documents in the start menu
Application Action	When this policy is enabled, applications must not display any MRU lists (for example, in file menu and save/open dialogs)
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value name: NoRecentDocsHistory

Policy Setting	Disable/Remove the Shut Down command
Description	This policy prevents the user from using the Windows user interface to shut down the system
Application Action	When this policy is enabled, applications that enable the user to shut down Windows must disable this capability
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer Value Name: NoClose

Policy Setting	Hide Common Dialog Places Bar
Description	The places bar allows users to navigate via the common dialog directly to the following locations: History folder, Desktop, My Documents, My Computer, and My Network Places. When this policy is enabled, Windows 2000 removes the places bar from the Windows common dialog
Application Action	When this policy is set, applications that provide their own file/open dialogs must remove any functionality equivalent to the places bar. Applications that use the Windows common dialog API will automatically comply with this policy
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32 Value Name: NoPlacesBar

Policy Setting	Hide Common Dialog Back button
Description	When this policy is enabled, Windows 2000 removes the back button from the common dialog, preventing the user from browsing to the previous folder accessed from the dialog
Application Action	When this policy is set, applications that provide their own file/open dialogs must remove or disable any back button functionality from these dialogs; applications that use the Windows common dialog API will automatically comply with this policy
Registry Information	Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32 Value Name: NoBackButton

Policy Setting	Hide the dropdown list of recent files
Description	When this policy is enabled, Windows 2000 removes the MRU list from the common dialog
Application Action	When this policy is set, applications that provide their own file/open dialogs must not display an MRU list in these dialogs;applications that use the Windows common dialog API will automatically comply with this policy
Registry Information	Key: HKCU\ Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32 Value Name: NoFileMru

To comply with the Application Specification, your application must adhere to the policies listed above. Additional system-level policies exist and it is recommended that your application honor these as well. For example:

Don’t save settings at exit: when this policy is set, applications should not save settings such as Window size/location and toolbar locations
Disable changes to Taskbar and Start Menu settings; when this policy is set, applications should not add or remove any items to the Start Menu

Registry settings for system-level policies can be found in the system.adm file on Windows 2000 systems. We recommend that developers review the system.adm file to ensure their applications respect any additional policies that the administrator may set.

4.6 Applications that create ADM files must properly store their ADM file settings in the registry

Administrative Template (ADM) files allow administrators to implement Group Policy settings. If your application offers management capabilities via ADM files, it must store these settings under the following registry keys:

HKCU\Software\Policies for user specific policy settings
HKLM\Software\Policies for machine specific policy settings

How to Pretest Applications for Data and Settings Management Requirements

To Pretest Correct Storage of User Data and Defaults

Clean-install Windows 2000 onto an NTFS partition.

When testing in an NT4 environment, Security Configuration Manager should be used to configure the NT4 systems in a secure manner that is consistent with the Windows 2000 defaults. After installing Windows NT4 and the proper service pack, install the command line version of the Security Configuration Manager and configure the system using the w2kdefsec.inf security template. This template is included in the Support Files for the Windows NT4 Test Plan, available at: https://msdn.microsoft.com/certification/download.asp.
Log in as Administrator.
Remove all members of the Power Users group.

By default, Interactive users are Power Users.
Install the application into the Program Files directory
Log in as a normal (non-admin, non-power) User (e.g. "User1").

This must be a different account than the one used to install the application.
Verify that the application runs successfully as a normal User.

A normal user should be able to perform all advertised functionality.

The application must degrade gracefully when a normal user attempts to perform any administrative functions exposed by the application (e.g. Changing System Time, System Environment Variables, System Security Settings etc.)
Modify user preferences, create files, etc.
Log in as a different (non-admin, non-power) User (e.g. "User2").
Verify that User1's custom preferences do not apply to User2.
Roam to a different machine that also has the application installed. Log in as the same user as in step 6 (User1). (Make sure that this user has a roaming profile enabled on the network.)
Launch the application and verify that User1's custom preferences are available on the new machine.

Partager via