Profile Key Manager Command Line Utility Reference
This topic describes the ProfileKeyManager.exe command line utility and its options and parameters. It also shows how you use them to address various usage scenarios. ProfileKeyManager.exe is located, by default, in the \Program Files\Microsoft Commerce Server 2007\Tools folder on the server where you installed Commerce Server 2009.
Procedures
To use the ProfileKeyManager tool
Open a command prompt.
If it is not in your path, navigate to the folder where ProfileKeyManager.exe is located. By default, this is in the \Program Files\Microsoft Commerce Server 2007\Tools folder.
Run the ProfileKeyManager.exe command-line tool, specifying the appropriate options found in this topic.
Usage 1: Creating a New Key
The syntax for creating a new key using the ProfileKeyManager.exe command-line tool is as follows:
ProfileKeyManager /kn [/l <keylength>] [/f] [/o [<file>] [/facl <user> [/facl...]]] [/reg <regkey> [/racl <user> [/racl...]]]
/kn
Generates a new public/private key pair. The /l option is specific to the /kn option in the tool./lkeylength
The key length to use for the public/private key pair generated. The default is 1024./f
Specifies that the file specified in the /o parameter, and the registry key specified in the /reg parameter should be overwritten if they already exist. If not specified, key generation will fail if either the registry key or file already exists./ofile
The new key pair is written to the file specified. If file is not provided, the file name used is "NewKeyPair_timestamp" where timestamp is the current timestamp. Access control lists (ACLs) are assigned so that only the user running the tool and local administrators can access it. Can be specified only with the /kn or /ke option./facluser
Specifies a user that should be granted read-only access to the file generated by the /o parameter. /facl can only be used when /o is specified. Multiple /facl parameters can be specified./regregkey
The keys generated are encrypted using DPAPI with the local machine key, and then placed into the registry key specified. The public key will be named “PublicKey,” and the private key will be named "PrivateKey." If the /o parameter is specified, the properly formatted registry key paths will be written to the output file, rather than the clear-text encryption keys./racluser
Specifies a user that should be granted read-only access to the registry key generated by the /reg parameter. /racl can only be used when /reg is specified. Multiple /racl parameters can be specified.
Usage 2: Encrypting Existing Keys
The syntax for encrypting existing keys using the ProfileKeyManager.exe command-line tool is as follows:
ProfileKeyManager /ke /kf <keyfile> /reg <regkey> [/f] [/racl <user> [/racl...]] [/o [<file>] [/facl <user> [/facl...]]]
/ke
Takes an existing key file, encrypts the keys using DPAPI with the local computer account, and adds them to the system registry. This mode of operation should be used to deploy the same encryption keys to multiple servers in a Web farm in a secure fashion./kfkeyfile
The already existing key file containing the encryption keys that should be added to the system registry. The key file should have the following format:<?xml version="1.0"?> <Keys xmlns="https://schemas.microsoft.com/CommerceServer/2006/08/ProfilesKeyFile"> <PublicKey>"Hexadecimal_public_key" or "registry_key_path"</PublicKey> <PrivateKey>"Hexadecimal_private_key" or "registry_key_path"</PrivateKey> </Keys>If a registry_key_path is provided, it will have the format registry:hive[\subkey],[valuename]. hive is the key hive name (such as HKLM, HKEY_CURRENT_USER, and so on). subkey is an optional subkey name. valuename is an optional name of the value in the registry key. If {valuename} is not specified, the default value is used.
Example: registry:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007\Encryption Keys,PublicKey
/regregkey
The keys generated are encrypted using DPAPI with the local machine key, and then placed into the registry key specified. The public key will be named “PublicKey,” and the private key will be named "PrivateKey." If the /o parameter is specified, the properly formatted registry key paths will be written to the output file, rather than the clear-text encryption keys./f
Specifies that the file specified in the /o parameter, and the registry key specified in the /reg parameter should be overwritten if they already exist. If not specified, key generation will fail if either the registry key or file already exists./racluser
Specifies a user that should be granted read-only access to the registry key generated by the /reg parameter. /racl can only be used when /reg is specified. Multiple /racl parameters can be specified./ofile
The new key pair is written to the file specified. If file is not provided, the file name used is “NewKeyPair_timestamp”where timestamp is the current timestamp. Access control lists (ACLs) are assigned so that only the user running the tool and local administrators can access it. Can be specified only with the /kn or /ke option./facluser
Specifies a user that should be granted read-only access to the file generated by the /o parameter. /facl can only be used when /o is specified. Multiple /facl parameters can be specified.
Usage 3: Rolling Data
The syntax for rolling data using the ProfileKeyManager.exe command-line tool is as follows:
ProfileKeyManager /kc [/kfo <OldKeyFile>] {/kfn <NewKeyFile>} [/i {1 | 2}] [/config <ConfigFile>] [/wc <ProfileName1> <WhereClause1> ... [<ProfileNameN> <WhereClauseN>]] [/p <PropertyToBeEncrypted1> ... [<PropertyToBeEncryptedN>]]
/kc
Rolls the data by encrypting it with the new keys supplied. The following options are specific to the /kc option in the tool./kfoOldKeyFile
An XML file that contains the old key pair used for encrypting the data. See the /kf parameter for the file format./kfnNewKeyFile
An XML file that contains the new key pair used for encrypting the data. The file is similar to the file OldKeyFile./i {1 | 2}
The new global key index. Valid values are 1 and 2. The key index property is extremely important, and must be aligned correctly with the global key index value. That is, if the current global key index value is 1, then the new key index must be 2 and vice versa. Incorrect key specification can result in data loss. It is the responsibility of the site administrator to verify the correctness of the value supplied at run time; the tool is unable to check this value./configConfigFile
Specifies the XML file that stores the BizData, BDAO, and Profiles service connection string. The name of the file can consist of only 260 alphanumeric characters. Here is a sample file:<?xml version="1.0"?> <!-- This is a sample XML document. --> <Configuration> <ProfileConnectionString>Provider=CSOLEDB;Data Source=CommerceMachine;Initial Catalog=BlankSite_commerce;Integrated Security=SSPI; </ProfileConnectionString> <ProviderConnectionString>provider=commerce.dso.1;data source=mscop://INPROCCONNECT/Server=CommerceMachine;Catalog=Profile Definitions;Database=BlankSite_Commerce:Trusted=True;</ProviderConnectionString> <BDAOConnectionString>Provider=SQLOLEDB;Data Source=CommerceMachine;Initial Catalog=BlankSite_commerce;Integrated Security=SSPI;Network Library=;</BDAOConnectionString> </Configuration>Note
Because the file contains passwords, you must make sure that the file is handled carefully, and you should destroy it after use.
/wcProfileName1WhereClause1 … [ProfileNameNWhereClauseN]
Specifies the profile name in which clause pairs that can be used to restrict the profiles are rolled currently. For example:ProfileKeyManager … /wc MyProfile1 "WHERE MyIntegerPrimaryKey > 1 AND MyIntegerPrimaryKey <= 1000"You must make sure that the WHERE clause is enclosed in quotation marks so that the tool treats it as a single token.
/pPropertyToBeEncrypted1 … [PropertyToBeEncryptedN]
This option is followed by a list of properties that must be encrypted. The maximum length for property names is 128 characters; valid characters are alphanumeric, underscore (_), and hyphen (-). The properties should be prefixed by the name of the profile. For example, if you have a UserObject profile in which you want to encrypt the property MyProperty, which is nested under the group MyGroup, you would provide UserObject.MyGroup.MyProfile as an argument. If you specify properties that do not exist, that are primary keys, or that are already encrypted, it will produce errors.
See Also
Other Resources
How to Add Encrypted Properties for Profiles
Preparing to Use the Profile Key Manager
Generating a New Encryption Key