System Password Encryption Options
The PTC Solution Installer (PSI) encrypts an initial set of system passwords that would otherwise be stored in plain text in installed files. A majority of the passwords are stored in Windchill and Info*Engine files. Additional passwords can be stored in files managed by third-party products. The following sections provide details on how to encrypt system passwords and details on the encryption mechanism itself.
Encrypting passwords that had previously been stored in plain text improves the password security of your Windchill solution. However, if you had previously used a text editor to view and change the passwords, you must change your process for managing the passwords. With encrypted passwords, you cannot examine the contents of Windchill files to determine password values. Instead, when passwords are set, your site process should include having a secure place outside of your Windchill directories for recording the passwords.
Since passwords are encrypted, ensure that there is a process established at your site to safely record the passwords set during the installation and to record those passwords set when managing Windchill. By implementing this process, system passwords are available to those who need them, but are not available to anyone else.
|
|
Windchill and the optional products that work with Windchill often create backups of files that are being modified before the modifications take place. The processes described in this topic only encrypt passwords that are stored in the latest version of affected files and do not encrypt passwords in any backup files that are present.
To ensure that there are no plain-text passwords in any files, you must remove all backups of files containing plain-text passwords. This includes removing the backup files created as part of the encryption process. For example, consider removing backups of the files that have plain-text passwords that are mentioned in the sections that follow (such as agent.ini and auth.properties).
Since system passwords are encrypted during installation, you do not need to the remove backup files for the site.xconf file or for property files with passwords that you may have backed up (such as wt.properties, db.properties, ie.properties, and esi.properties).
|
Password Encryption Details
To encrypt system passwords, Windchill and Info*Engine code uses a JCEKS KeyStore class in conjunction with a password-based encryption. JCEKS KeyStore is a strong version of the Sun KeyStore class implementation. The Sun KeyStore implementation is standard with the Java SE Development Kit (JDK).
The actual encrypted passwords are stored in a keystore file located outside of the codebase directory. The keystore file itself is encrypted using a random character string. If your site requires that you periodically change the encryption on this file (for example, for Sarbanes-Oxley Act (SOX) compliance), see the section Changing Keystore File Encryption.
As a result of encrypting passwords, you cannot view the passwords in Windchill files. Instead, the password value is shown in a file using the following general format:
encrypted.<related_name>
where <related_name> is system-generated text. The text uniquely identifies the encrypted password that is stored in the keystore file. For example, the database password value stored in the wt.pom.dbPassword property is shown as:
encrypted.wt.pom.dbPassword
Since the database password is set in a Windchill properties file, both the site.xconf file and the properties file where the database password is set (in this case, db.properties) show encrypted.wt.pom.dbPassword in place of the actual password as follows:
wt.pom.dbPassword=encrypted.wt.pom.dbPassword
Therefore, you cannot view passwords that have been encrypted by opening the associated properties file (or the site.xconf file) nor are passwords displayed when you display values using the xconfmanager -d option.
In another example, assume the encrypted password for the default worker agent user is shown as:
encrypted.auth.D:\\ptc\\Windchill\\auth.properties
Then this password is set on a Windows system in the D:\ptc\Windchill\auth.properties authorization file and replaces the password as follows:
auth=<user_name>:encrypted.auth.D:\\ptc\\Windchill\\auth.properties
where <user_name> is the name of the default worker agent user.
As you set passwords that are encrypted, ensure that you have a process set up to record the passwords outside of your Windchill environment. You cannot view encrypted passwords nor can you decrypt them. If you cannot remember a password that is encrypted, your only option is to change the password to a known value.
Encrypting Passwords Stored in Windchill Property Files
When your Windchill solution was installed, passwords were set as part of the installation. The initial set of passwords entered during a Windchill installation are displayed in plain text in the installation summary at the end of the installation but are stored as encrypted passwords in Windchill properties and Info*Engine properties.
|
|
Be sure to set up a site best practice to ensure that the passwords set for Windchill are stored in a secure place outside of your Windchill system so that only those who are authorized to change system passwords have access to the password values that are set. Also, if you encrypt additional passwords after installation, be sure to remove any backup files that contain plain-text passwords.
|
The following sections describe how to encrypt system passwords that are stored in Windchill property files and identify an initial set of Windchill properties that contain passwords.
|
|
If your site has customized Windchill, there could be additional passwords that should be encrypted.
|
Encrypting Windchill System Passwords
By default, a set of Windchill system passwords are encrypted. Encrypting additional system passwords is a three-step process:
1. Identify the properties that contain the passwords you want encrypted and update the validProperties.list file to reflect this list of properties.
2. Run the encryptAllPasswords target available from the EncryptPasswords.xml script to encrypt all passwords currently stored in plain text in the Windchill properties identified in the validProperties.list file that was updated in step 1.
3. Restart Windchill so that the changes made to property values take effect.
Details for completing steps 1 and 2 are in the following sections.
Windchill Password Properties
The following properties are in the out-of-the-box validProperties.list file and the property values contain passwords that can be encrypted. For a password to be encrypted, the corresponding property must be set to a plain-text password value.
|
|
If the property value is not set or is set to a null value, the password is not encrypted.
|
ie.ldap.managerPw
The LDAP administrator password that is set in this property is set when the LDAP settings are specified during installation and is stored in both the <Windchill>/codebase/WEB-INF/ieStructProperties.txt file and the <Windchill>/codebase/WEB-INF/ie.properties. As part of the installation process, the passwords entered during installation are automatically encrypted.
When an Info*Engine adapter has been installed on a server that is not the Windchill server, the password in the ie.ldap.managerPw property must also be encrypted on that server. For details on encrypting the LDAP administrator password on a remote host, see the corresponding adapter guide.
jms.passwordjms.verify.password
When installing Windchill Enterprise Systems Integration (Windchill ESI), an installation panel prompts for the password of the user who is used to logon to the Java Messaging System (JMS) through the EAI software components and also prompts to verify the password. These service-related properties are stored in LDAP and encrypted as part of the Info*Engine encryption process for LDAP entries. See the section Encrypting Passwords Stored in Info*Engine Properties.
mapcredentials.admin.adaptersmapcredentials.nonprivileged.adapters
These properties are used to modify the MapCredentials.xml file that is installed. The MapCredentials.xml file is used to specify the authentication access to a specific Info*Engine adapter. The file is used when a more restrictive access to an enterprise directory is required. The default access is anonymous. Each property includes a password. Using the xconfmanager utility to set the values of the properties encrypts the passwords.
If after completing your initial installation, your site has configured an additional enterprise LDAP directory (such as the Active Directory Server (ADS) directory) and has set administrative access control privileges for the directory by modifying the MapCredentials.xml file, then the MapCredentials.xml file can contain plain-text passwords. To encrypt passwords stored in the MapCredentials.xml file, add the properties to validProperties.list and complete the steps identified in the section Encrypting Windchill System Passwords.
wt.cognos.admin.password
This property is used to store the password of the Windchill Business Reporting administrative user. Although the property is always available in the db.properties file, it is only used when Windchill Business Reporting has been installed and configured. By default, the initial value is set to wcadmin.
wt.pom.dbPassword
This property is stored in the db.properties file and is the database user password. The property is set during the installation process when there are changes to the database that require the entry of the database user name and password. As part of the installation process, the password is encrypted.
Updating System Passwords in Windchill Property Files
You can update the system passwords that are encrypted in Windchill properties files by using the following parameter on the xconfmanager utility command:
-s (or --set)
Enter the new password in plain text. Windchill encrypts the new password before storing it. For example, to change the database password that is stored in db.properties to newPW123, enter the following command from a Windchill shell:
xconfmanager -s wt.pom.dbPassword=newPW123 -t db.properties -p
For information about using the xconfmanager utility, see
Using the xconfmanager Utility.
Because the encrypted password is not actually stored in the property file or in the site.xconf file, the property value displayed in these files is unchanged after you set a new password. The updated value is stored in the keystore file.
The list of properties containing Windchill system passwords that are encrypted when you set the passwords using the xconfmanager utility is maintained in the validProperties.list file. This file is located in the <Windchill>/bin/adminTools/sip directory. If a property is not listed in the validProperties.list file, the password is not encrypted when you enter an xconfmanager command to set the password.
|
|
Modifying the validProperties.list file affects which passwords are encrypted through the xconfmanager utility, as well as the passwords encrypted by the encryptAllPasswords target available from the EncryptPasswords.xml script. After initially selecting which passwords to encrypt, you should not modify the file unless you are changing your product configuration or customizing Windchill and need to change which passwords are encrypted.
|
Encrypting Passwords Stored in Info*Engine Properties
System passwords that are entered through the Info*Engine Property Administrator are encrypted. These passwords are stored in Info*Engine properties which, when set, are stored in your LDAP directory server.
For example, assume that you are setting up the default user and password used when connecting to an LDAP directory server in a JNDI adapter form. The following fields are displayed in the form:
When you type the password in the Directory System Agent Credentials field, the characters entered are masked with asterisk (*) characters. When you click OK to save the form, the actual password value is encrypted and stored in the keystore and the property value points to the encrypted value in the keystore.
The property is stored in your LDAP directory server.
For example, assume that you have entered a password of PW173& in the Directory System Agent Credentials field of a JNDI adapter form. Then the property is stored as:
<service>.dsaCredentials=encrypted.<service>.dsaCredentials
where <service> is the service name of the JNDI adapter.
Although the password information in this property value is not the actual password, it uniquely identifies the password to the encryption software being used and, therefore, any changes made to the information can cause the password to no longer be valid.
Updating Encrypted Info*Engine Passwords
Use the Info*Engine Property Administrator to update any Info*Engine passwords that were originally set through the Property Administrator. When you enter a new password and save the changes on an updated form, the actual password value in the associated property does not change, but the encrypted password stored in the keystore is updated.
If you have forgotten a password, there is no method available to retrieve the password. To reset a password to a known value, use the Info*Engine Property Administrator. Edit the form where the password was originally set and enter a new password.
Encrypting Passwords Stored in WVS Authentication Files
| Beginning at Windchill 10.2, PTC has changed the location of the wvs.properties file. The file has been moved from the $WT_HOME/codebase directory to the $WT_HOME/codebase/WEB-INF/conf directory. Be sure to make any necessary changes to your code to reflect this location change. |
An administrator is responsible for setting up the workers and their publishers that are used for publishing and generating viewables on the Windchill server. The administrator can create one authentication file for each publisher, though often only one file is used. The names of authentication files are defined in the useworkerdownload value of each specific CadConvert property in wvs.properties. The out-of-the-box wvs.properties file includes the useworkerdownload property and that property identifies one authentication file named auth.properties.
Initially, each authentication file created contains user names and plain text passwords for workers that support file synchronization. For details on creating an authentication file, see the following topics:
Additionally, if you are using the Adobe Experience Manager Assembler application to modify PDF files that are stored in a Representation, you create an authentication file (such as the livecycleauth.properties) containing a user name and plain text password. Encryption of the password in this file is done using the same ant script that is used for other WVS authentication files.
For details on setting up the Adobe Experience Manager Assembler application, see
WVS Adobe Experience Manager Server Integration.
Encrypting Authentication Passwords
| Beginning at Windchill 10.2, PTC has changed the location of the wvs.properties file. The file has been moved from the $WT_HOME/codebase directory to the $WT_HOME/codebase/WEB-INF/conf directory. Be sure to make any necessary changes to your code to reflect this location change. |
To encrypt the passwords stored in WVS authentication files, enter the following script from a Windchill shell:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml
encryptWVSWorkerAgent
where <Windchill> is the Windchill installation directory.
This script encrypts any plain-text passwords it finds in all WVS authentication files, including those identified in the useworkerdownload and edrload.livecycle.authfile properties that are in the wvs.properties file. After you encrypt the passwords in the authentication files, the passwords are replaced with the following:
encrypted.<auth_keyword>.<auth_properties_file_path>
where:
• <auth_keyword> is the keyword at the beginning of the authentication line for the password that is encrypted.
• <auth_properties_file_path> is the full file path of the PROPERTIES file containing the password on Windows platforms and a path starting with the Windchill installation bin directory on UNIX platforms.
The following lines show an example authentication file that is located on a Windows system at D:\ptc\Windchill\auth.properties before encryption:
auth=user1:pw123abc
auth.RemoteSiteA.PROE=user2:pw789xyz
After running the encryption script from a Windows system, the encrypted passwords include the file path with required escape characters (formatted to page width):
auth=user1:encrypted.D:\\ptc\\Windchill\\auth.properties
auth.RemoteSiteA.PROE=user2:encrypted.auth.RemoteSiteA.PROE. D:\\ptc\\Windchill\\auth.properties
The following lines show an example authentication file that is located on a UNIX system at /opt/ptc/Windchill/auth.properties before encryption:
auth=user1:pw123abc
auth.RemoteSiteA.PROE=user2:pw789xyz
After running the encryption script from a UNIX system, the encrypted passwords include a file path starting with the Windchill installation bin directory (formatted to page width):
auth=user1:encrypted.auth./opt/ptc/Windchill/bin/../auth.properties
auth.RemoteSiteA.PROE=user2:encrypted.auth.RemoteSiteA.PROE. /opt/ptc/Windchill/bin/../auth.properties
Although the password information in the file is not the actual password, it uniquely identifies the password to the encryption software being used and, therefore, any changes made to the information can cause the password to no longer be valid.
| Do not change encrypted password information unless you are changing the actual password. |
Updating Encrypted Passwords Stored in WVS Authentication Files
After the passwords in authentication files are encrypted, you can change existing passwords or add lines that contain additional user names and passwords to the file.
To change a password that is encrypted, complete the following steps:
1. Open the WVS authentication file in a text editor.
2. Locate the authentication line for the user whose password you want to change.
3. Replace the password information on that line with the new password (in plain text). For example, assume the authentication line is as follows:
auth=user1:encrypted.auth.D:\\ptc\\Windchill\\auth.properties
Replace encrypted.auth.D:\\ptc\\Windchill\\auth.properties with the new password you want to use. If the new password is user1PW, then the updated line is:
auth=user1:user1PW
4. Save your changes and close the file.
5. Run the EncryptPasswords.xml script with the encryptWVSWorkerAgent target (as described in the section Encrypting Authentication Passwords) to encrypt the changed password.
Encrypting Passwords Stored in the Worker Agent Configuration File
| Beginning at Windchill 10.2, PTC has changed the location of the wvs.properties file. The file has been moved from the $WT_HOME/codebase directory to the $WT_HOME/codebase/WEB-INF/conf directory. Be sure to make any necessary changes to your code to reflect this location change. |
An administrator is responsible for setting up the workers that are used for publishing and generating viewables on the Windchill server. This administrator updates the worker agent configuration file by using the Worker Agent Administration utility. Workers can be configured to use FTP to transfer files to and from the worker machine; the worker agent configuration file stores the FTP passwords. To locate this administrative tool, click > > . The location of worker agent configuration file is defined in the cadagent.inifile property in wvs.properties. The out-of-the-box wvs.properties file includes the cadagent.inifile property and that property identifies worker agent configuration file as agent.ini.
For details on configuring a worker agent, see
Configuring the Worker Agent.
Encrypting Worker Agent Passwords
| Beginning at Windchill 10.2, PTC has changed the location of the wvs.properties file. The file has been moved from the $WT_HOME/codebase directory to the $WT_HOME/codebase/WEB-INF/conf directory. Be sure to make any necessary changes to your code to reflect this location change. |
To encrypt the passwords stored in the worker agent configuration file, enter the following script from a Windchill shell:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml
encryptWVSCADAgent
where <Windchill> is the Windchill installation directory.
This script encrypts any plain-text password it finds in the worker agent configuration file identified in the cadagent.inifile property that is set in the wvs.properties file. After you encrypt the passwords in the worker agent configuration file, the passwords are replaced with the following:
encrypted.<host>-<shapetype>
where <host> is the host name listed on the host= line of the worker agent configuration file and <shapetype> is the name listed on the shapetype= line of the file.
The following lines show an example section in the worker agent configuration file before encryption:
;###############################################
; Remote CATIA Worker
;###############################################
[worker4]
shapetype=CATIA
host=nimrod
hosttype=unix
exe=nohup cat2ol -w triumph &
starttime=20
username=catadm19
password=CATADM19
prompt=nimrod>
localpath=ftp:/usr/tmp/sharecatia
remotepath=/usr/tmp/sharecatia
In this example <host> is nimrod and <shapetype> is CATIA.
After running the encryption script, the lines are updated as follows:
;###############################################
; Remote CATIA Worker
;###############################################
[worker4]
shapetype=CATIA
host=nimrod
hosttype=unix
exe=nohup cat2ol -w triumph &
starttime=20
username=catadm19
password=encrypted.nimrod-CATIA
prompt=nimrod>
localpath=ftp:/usr/tmp/sharecatia
remotepath=/usr/tmp/sharecatia
Although the password information in the file is not the actual password, it uniquely identifies the password to the encryption software being used and, therefore, any changes made to the information could cause the password to no longer be valid.
| Do not change encrypted password information in the file unless you are changing the actual password. |
Updating Encrypted Passwords Stored in the Worker Agent Configuration File
After the passwords in the worker agent configuration file are encrypted, you can change existing passwords or add workers (with user names and passwords) in the following ways:
• Use the Worker Agent Administration utility (accessed by clicking > > ).
• Edit the worker agent configuration file using a text editor.
To change a password that is encrypted by editing the worker agent configuration file, complete the following steps:
1. Open the worker agent configuration file in a text editor.
2. Locate the password line for the user whose password you want to change.
3. Replace the password information on that line with the new password (in plain text). For example, assume the password line is as follows:
password=encrypted.nimrod-CATIA
Replace encrypted.nimrod-CATIA with the new password you want to use. If the new password is CADuser1PW, then the updated line is:
password=CADuser1PW
4. Save your changes and close the file.
After changing or adding new passwords that are not encrypted, you must run the EncryptPasswords.xml script with the encryptWVSCADAgent target (as described in the section Encrypting Worker Agent Passwords.) to encrypt the changed or new passwords.
Changing Keystore File Encryption
The keystore file that Windchill uses for storing encrypted passwords is created during the installation process and is itself encrypted using a unique random character string that is generated for each installation.
If you have a general process that requires that you periodically change passwords (for example, to be compliant with the Sarbanes-Oxley Act (SOX)), you can choose to change the encryption on the keystore file. This encryption acts like a password and can be changed by entering the following command from a Windchill shell:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml
changeKeystoreEncryption
where <Windchill> is the Windchill installation directory.
The ant command executes a script that generates a new random character string and then encrypts the keystore file using the string. The script changes the key to the keystore that is maintained in <Windchill>/bin/adminTools/sip/ksp/sip.ksp.
| There is no Windchill requirement that you change the encryption on the keystore file. |
Using the EncryptPasswords.xml Script
PTC provides the general EncryptPasswords.xml script that you can use to encrypt passwords.
| When working on the Windchill server, always execute the EncryptPasswords.xml script from a Windchill shell. |
The general format for entering the EncryptPasswords.xml script is as follows:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml
<target> [optional_arguments]
where:
• <Windchill> is the Windchill installation directory.
• <target> is the target to execute.
• [optional_arguments] is the arguments required by the target. Some targets do not require any arguments.
To obtain a short description of the available targets, enter the script with the -projecthelp target. The following is a list of available targets:
• addValueToKeyStore
• changeKeystoreEncryption
• encryptAllPasswords
• encryptPw
• encryptWVSCADAgent
• encryptWVSWorkerAgent
• recreateKeyStore
• recreateKeyStoreForAdapter
For an explanation of the encryptAllPasswords target, see the section Encrypting Windchill System Passwords.
For an explanation of the targets for encrypting passwords in WVS files, see the section Encrypting Authentication Passwords and Encrypting Worker Agent Passwords.
For an explanation of the changeKeystoreEncryption target, see the section Changing Keystore File Encryption.
Other targets are described in the sections that follow.
addValueToKeyStore Target
Encrypts the specified property with the specified password in the specified encryption keystore.
Using this target on a host where an out-of-process adapter has been installed allows you to encrypt and store passwords on that host. The password is initially entered on the Windchill host in the adapter form from within the Info*Engine Property Administrator. When the adapter is installed on a host different from the Windchill host, the password must also be encrypted and stored on the host where the adapter is installed.
| If the property exists in the named keystore, running this target replaces the existing keystore value of the named property. |
To use this target, navigate to the directory where the EncryptPasswords.xml file resides on the host where you want to encrypt the password and enter an ant command with the following format:
ant -f EncryptPasswords.xml addValueToKeyStore
-DpropertyName=<property> -Dpassword=<password_value>
-Dwt.home=<Windchill_location>
where:
• <property> is the name of the property used to set the password. For example, the JDBC adapter form sets a password property named passwd. Assume that the JDBC service is named JDBCadapter1. Then the password property is JDBCadapter1.passwd.
• <password_value> is the plain-text password that was set in on the Windchill host.
• <Windchill_location> is the directory path as designated in the following keystore path:
<Windchill_location>/bin/adminTools/sip
This entire path identifies the path to the keystore where the encrypted password is stored. For adapter passwords, enter the location where the files extracted from the IeAdapter.zip file reside.
For additional details on encrypting passwords for adapters, see the corresponding adapter guide or help topics.
encryptPw Target
If you have customized Windchill and have added an additional password, you can use the encryptPw target that is available from the EncryptPasswords.xml script to encrypt the password value for a specific property. Be aware that this target does only the encryption; it does not change the Windchill code needed to use the additional password.
| When using a non-customized Windchill system, use xconfmanager utility to change and encrypt existing passwords instead of using this target. See the section Encrypting Passwords Stored in Windchill Property Files. |
To use this target, enter an ant command with the following format:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml encryptPw
-DpropertyName=<property> -Dpassword=<password_value>
where:
• <Windchill> is the Windchill installation directory.
• <property> is the name of the property used to set the password.
• <password_value> is the plain-text password.
The following example sets the password for the database user in the installed keystore file to dbuserpw123. The wt.pom.dbPassword property is updated to point to the keystore for the actual encrypted value:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml encryptPw
-DpropertyName=wt.pom.dbPassword -Dpassword=dbuserpw123
recreateKeyStore Target
Use the recreateKeyStore target that is available from the EncryptPasswords.xml script to generate a new keystore file.
Run this target only when you have one or more of the following issues:
• The keystore has been deleted and there is no backup file that can been used in recovering the keystore.
• There have been manual edits made to the keystore file.
• The keystore or a key becomes corrupted and can no longer be read or accessed.
To recreate the keystore file, enter the following command from a Windchill shell:
ant -f <Windchill>/bin/adminTools/sip/EncryptPasswords.xml
recreateKeyStore
where <Windchill> is the Windchill installation directory.
As the script runs, you are prompted for the password values that are applicable to the Windchill installation and stored in the properties listed in the validProperties.list file. For more information about the validProperties.list file, see the section Updating validProperties.list.
recreateKeyStoreForAdapter Target
Use the recreateKeyStoreForAdapter target that is available from the EncryptPasswords.xml script to generate a new keystore file specifically for an Info*Engine adapter that resides on a server that is not the Windchill server.
| Running this target on a Windchill server replaces the existing keystore that contains encrypted Windchill and Info*Engine passwords. |
Run this target on the server where the adapter resides only when you want to use the adapter as an out-of-process adapter and the server has the required files.
For additional information about using the recreateKeyStoreForAdapter target, see the adapter guide or help topics that describe the adapter for which you want to create the keystore.
