Targeting Windows Vista with SoftwareShield

The Windows Vista operating system was designed with security as a primary concern. To many peoples surprise, much of the underlying security model is the same as in XP. However, in Vista, most users will be "forced" to work within the boundaries of the new "UAC" (User Access Control system) - which in turn enforces the model. In XP, almost all users ran the operating system as an "administrator" and therfore circumvented much of the inherent security. Now - in Vista, even users who are logged on as an administrator run in a lowered priviledge mode by default and to manipulate any protected area of the system - users must "elevate" their permission level. You must be aware of how this will affect the SoftwareShield systems ability to license your applications and proactively manage the issues that can arise. A thorough discussion of the UAC and understanding how the revised security model of Windows Vista operates is outside the scope of this document. Please consult any of the thousands of developer resources on the web to learn more about fundamentals of Windows Vista, the UAC and how it affects your programs. Below we descibe three approaches to how your protected software can work very well with Windows Vista.

1. Embed a manifest to elevate permissions
2. Manipulate the access control levels of protected resources
3. Install the license and alias files only in the common documents folder and not use virgin registry data at all.
   

Embed A Manifest

A manifest is an XML document that is embedded as a resource in your binary that the Windows loader knows how to find and parse. It uses this information from your application for a variety of reasons. The one we are cencerned with is "security".

By declaring the execution level in your manifest to "requireAdministrator", the application will bring up the UAC elevation prompt whenever it starts up. By elevating the users permission level, the application will have full access to the registry and every directory. Normally, the registry and certain directories such as program files will be restricted to regular users.

You may wish to embed a manifest that elevates permissions on execution for a vriety of reasons as you may find that your application needs access to these resources for its own (non-SoftwareShield) reasons.

Step-By-Step How to Embed A Manifest

1. First thing you do is create the manifest file. The manifest itself is a simple XML file and generally looks like this:
   
   

   <?xml version="1.0" encoding="utf-8" ?> <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> <assemblyIdentity version="1.0.0.0" processorArchitecture="X86" name="MyProjectName" type="win32" /> <description>MyProjectDescription</description> <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3"> <security> <requestedPrivileges> <requestedExecutionLevel level="requireAdministrator" /> </requestedPrivileges> </security> </trustInfo> </assembly>

   The key information here is the Security tags. Under “requestedExecutionLevel” the level must be “requireAdministrator”.

2. Add the manifest to your applications resource file (ofen called an .rc file). You must have the following in the rc file:
   
   1 24 "myprojectname.Manifest"
   
   The indetifiers are constants and must be defined as "1" and "24", your development environment may define constants for you with these values such as "RT_MANIFEST", regardless the values must be "1" and "24". Replace myprojectname.manifest with whatever you named your manifest. The name can acutally be anything just so long as it can find the file so named.

3. Compile and embed your manifest into the application. The way this would be done is dependant on your development environment. All modern IDE's routinely compile and embed resources into your final binary.

Checking if you have embedded your manifest correctly

After embedding your manifest, you can check if it worked properly. Download any tool that allows you to view resources embedded inside binary files. There any many. We recommend CFF explorer. This tool was also recommended by the Windows Certification Program for manifest checking and should be easy to find over the internet.

To check your manifest with CFF explorer:

1. Start CFF explorer
2. Open the main exe of your application with CFF Explorer
3. Click on the Resource Viewer in the tree menu
4. Click on resource 1 (The manifest is most commonly location of the manifest but it may be different depending on your programming language)
5. Look for:
   
   
   

   ... <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3"> <security> <requestedPrivileges> <requestedExecutionLevel level="requireAdministrator" /> </requestedPrivileges> </security> </trustInfo> ...

   
   Make sure the execution level is “requireAdministrator”.
   
   As a final proof, run the program in Windows Vista. Before the program loads, the UAC must pop-up prompting you that the program "wants access to your computer". This confirms that the manifest has been embedded correctly in the program and permissions will be elevated correctly.

Manipulating the Access Control Level

Access to the registry and certain directories is restricted. Your installer may modify the Access Control Level (ACL) of the main license file, alias file locations, and registry locations because installers normally execute at an elevated priviledge level. The access level of those files, folders and registry keys must be set so "all users" or "everyone" is allowed "full control" to them.

The process of manipulating access level would vary on the Installer you are using. But there will be some common elements between them.

1. Require your program to be installed by an Administrator or configure your installer to perform secured actions using elevated privileges. This is usually required anyway since you will have to register the SSCProt.dll COM server and any other ActiveX controls of your own and this is also controlled under Windows.
2. During installation, manipulate the Access Control List (ACL) for any resources (registry hives, folders) you need during licensing execution to allow all users permission to read and write. This can be done a number of ways. Most production quality installer packages (Wise, InstallShield) provide integrated ACL manipulation routines that you can use for this purpose.
   
   Another popular way to manipulate the ACLs is to use a third party program. A popular tool (free - but covered under license) to do this during installation is "SetACL - CmdLine". This program can be executed during installation right from your installer on the command line and will quietly set all your necessary permissions.
   
   Remember to set the following files to have read and write access by all users:

   • Alias files (The containing folder - not the file itself)
   • Virgin Registry entry (The containing key - not the value itself)
   • Registry alias files (The containing key - not the value itself)
   • License files
   • Main License File Folder
   

   Special Notes for Registry alias files

   When writing to the registry you must remember to create the key folder and set the permission to Full Control. This is done to avoid virtualization of the alias registry entries. Also do not use HKEY_CURRENT_USER when targeting Vista. Even if the proper permissions are set, virtualization is unavoidable when using HKEY_CURRENT_USER.

   Special Notes for Windows, System, and Program Files Alias Files

   If you use windows, system, or program files folder alias files; you must create a subdirectory and have it set to have full access for all users with your installer.

   Under the Alias License Files tab, you can declare the subdirectory with the file name.

   Example:
   Let’s say you are using a windows folder alias file called “tiff10db.tlb”. Instead of “tiff10db.tlb” as your file name, you would name it “<subdirectoryname>\tiff10db.tlb”.
   
   When you initiate your license, the alias file will be created under: “C:\windows\<subdirectoryname>\tiff10db.tlb”
   
   The main issue here is the fact that the license and alias states may differ depending on the user. If the folder that stores alias files is not set to have both write access, Vista virtualizes the file and stores it in the user’s virtual store. This could bring a problem when attempting to corroborate the alias and license file.

   More information can be found in the Windows Permissions and Security Considerations section of the help file for manipulating access control.

Putting All Files in "Common Documents"

The third method would be putting files into the common documents folder. The common documents folder and files within it are set so all users have read and write access by default on Vista. This would mean that elevated access would not be necessary for your application to run.

Unfortunately, if you choose this option, you would not be able to use virgin registry entries or any alias files aside from common documents alias files.

During installation, you must put the license file into the common documents folder. When you start your application, it must determine where the common documents folder is, so you can locate your license file.

Unlike Windows Vista, XP and 2000 has a different default permission structure for common documents. Files created in the common documents folder are given write access only to the creator on XP and 2000. So, if you want your application to work both in XP and Vista, you must manipulate the ACL for these files if the target OS is not Vista. If there will not be any pre-Vista support, manipulating ACL's for this approach then this step is not necessary.