Procedure – Encrypting Static .xconf Managed Single-Valued Properties
New properties that are xconf managed, have a static property name, that is the property name never changes, and contain a single value can be encrypted using the same means that Windchill relies on for the out-of-the-box encryption of these properties.
Encrypting a Property Value
This assumes that you have already created your new .xconf managed property:
1. Edit <Windchill>/bin/adminTools/sip/validProperties.list file and add the property name to a new line below the last file entry. This tells the encryption mechanism that this property should be encrypted.
2. From a Windchill shell run xconfmanager to set a value for this property. For example, <Windchill>/bin/xconfmanager -s <name>=<value> - p. This will encrypt the propertyValue. In your site.xconf and companion .properties file where the value lives you’ll see the encrypted value and not the value entered on the command line. The actual value is stored by Windchill’s encryption mechanism.
You can also encrypt additional .xconf properties that Windchill provides out-of-the-box if your value for that property is sensitive information. To do so, follow the above procedure, the only difference is that the property is provided by Windchill and not created as part of a customization.
Additionally, there is a secondary means to encrypt a password using the EncryptPasswords.xml file.
1. Edit <Windchill>/bin/adminTools/sip/validProperties.list file and add the property name to a new line below the last file entry. This tells the encryption mechanism that this property should be encrypted.
2. From a Windchill shell, run <Windchill>/bin/adminTools/sip/EncryptPasswords.xml encryptPw -DpropertyName=<property> -Dpassword=<password_value>.
3. For additional details see System Password Encryption Options.
This encrypts the property value. However, for the value to be used properly by code that relies on the value, the code must be updated to decrypt the value prior to use. For out-of-the-box properties, Windchill decrypts properties at the appropriate interface locations.
Any code that relies on this value must be updated to properly decrypt it.
Procedure — Decrypting a Property Value
1. All code that extends Windchill base classes which retrieve property values must be updated if they overwrite methods that return property values. For custom code that obtain and use property values you can decrypt an encrypted value by using the following:
a. com.ptc.windchill.keystore.WTKeyStoreUtil provides an API to obtain the decrypted value of a property value if it is encrypted (see the Javadoc for complete details). The API is:
public static String decryptProperty(String property_name,
String property_value,String product_root)
String property_value,String product_root)
Where property_name is the property name for which you want to decrypt a value for, property_value is the value that may currently be encrypted and product_root is the fully qualified path to <Windchill> (or <adapter_home> for adapter installations).
A code example for the usage of this API is as follows:
final String encrypted_value = "encrypted.wt.pom.dbPassword";
final String property = "wt.pom.dbPassword";
final String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
final String property = "wt.pom.dbPassword";
final String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
The string decrypted now contains the decrypted value and can be used properly elsewhere in the code where it is relied on.
Procedure – Encrypting Dynamic .xconf Managed Single-Valued Properties
New properties that are xconf managed, have a dynamic property name, that is the property name changes, and contain a single value can be encrypted using the same means that Windchill relies on for the out-of-the-box encryption of these properties.
A dynamic property name could be one that is built on-the-fly in code and relies on specified derived information such as a hostname for example.
Care must be taken when encrypting a dynamic property. Dynamic property encryption is based on the use of regular expressions due to the properties dynamic nature. As a result, the regular expression used to encrypt a property must ensure that it is restrictive enough to only encrypt those properties which are intended for encryption. If a too broad regular expression is used an unwanted consequence is that additional properties could be encrypted with the necessary decryption code not yet existing.
Encrypting a Property Value
This assumes that you have already created your new .xconf managed property:
1. Edit <Windchill>/bin/adminTools/sip/validProperties.list file and add the property name token to a new line below the last file entry. This tells the encryption mechanism that this property token will be used to encrypt properties matching regular expressions. For consistency, the property name token should resemble the regular expression used for matching properties.
2. It is then necessary to add to WTKeyStore.java’s implementation by extending private Static List<String> getEncryptionPropertiesRegExList(final String productRoot) method. This methods implementation generates a Collection of regular expression used to match property names. If a property name matches a regular expression the property value is encrypted accordingly.
This methods implementation should be overridden through a custom implementation.
3. There is additional work needed to change the <Windchill>/bin/adminTools/sip/EncryptPasswords.xml file. Certain Ant targets within this file validate property name inputs. The -validInput private target would require updating to also validate the regular expression added in step 2. The files current implementation can be examined for guidance on how to accomplish this.
 |
Any code that relies on this value must be updated to properly decrypt it.
|
Decrypting a Property Value:
1. All code that extends Windchill base classes which retrieve property values must be updated if they overwrite methods that return property values. For custom code that obtain and use property values you can decrypt an encrypted value by using the following:
com.ptc.windchill.keystore.WTKeyStoreUtil provides an API to obtain the decrypted value of a property value if it is encrypted (see the Javadoc for complete details). The API is public static String decryptProperty(String property_name, String property_value, String product_root).
A code example for the usage of this API is as follows:
final String encrypted_value = "encrypted.wt.federation.defaultAuthorization.machine123.subnet.net";
inal String property = "wt.federation.defaultAuthorization.machine123.subnet.net";
inal String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
inal String property = "wt.federation.defaultAuthorization.machine123.subnet.net";
inal String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
The string decrypted now contains the decrypted value and can be used properly elsewhere in the code where it is relied on.
Where property_name is the property name for which you want to decrypt a value for, property_value is the value that may currently be encrypted and product_root is the fully qualified path to <Windchill> (or <adapter_home> for adapter installations).
Procedure – Encrypting Non-.xconf Managed Properties
New properties that are non-.xconf managed and contain can be encrypted using Windchill’s encryption mechanism. However, you must create a means to encrypt the password as well as decrypt it.
Encrypting a Property Value
1. You must create a means to encrypt your property value. This can be done through a Java class that can be invoked through a main() method and through modifying <Windchill>/bin/adminTools/sip/EncryptPasswords.xml.
a. <Windchill>/bin/adminTools/sip/EncryptPasswords.xml contains ANT targets, encryptWVSWorkerAgent and encryptWVSCADAgent, that encrypt property values that are not xconf managed. These targets can be examined for an example on how to do this. You must create a new target that accepts parameters that invokes a Java class to do the encryption.
b. The Java class that is invoked uses the parameters, a property and value, and encrypts them using the Windchill encryption mechanism. This Java class must also contain logic to property encrypt the file where this property is stored as well as placing the correct value in the Java keystore. The WTKeyStoreUtilWVS.java class contains code that is invoked by the encryptWCSWorkerAgent and encryptWCSCADAgent targets which can be examined for an example on the logic used to encrypt a file where the property value is stored.
This encrypts the property value. However, for the value to be used properly by code that relies on the value, the code must be updated to decrypt the value prior to use. For out-of-the-box properties, Windchill decrypts properties at the appropriate interface locations.
|
|
Any code that relies on this value must be updated to properly decrypt it.
|
Decrypting a Property Value
All code that extends Windchill base classes which retrieve property values must be updated if they overwrite methods that return property values. For custom code that obtain and use property values you can decrypt an encrypted value by using the following:
com.ptc.windchill.keystore.WTKeyStoreUtil provides an API to obtain the decrypted value of a property value if it is encrypted (see the Javadoc for complete details). The API is public static String decryptProperty(String property_name, String property_value, String product_root)
Where property_name is the property name for which you want to decrypt a value for, property_value is the value that may currently be encrypted and product_root is the fully qualified path to <Windchill> (or <adapter_home> for adapter installations).
A code example for the usage of this API is as follows:
final String encrypted_value = "encrypted.wt.pom.dbPassword";
final String property = "wt.pom.dbPassword";
final String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
final String property = "wt.pom.dbPassword";
final String PATH = "D:\ptc\Windchill\";
String decrypted = com.ptc.windchill.keystore.WTKeyStoreUtil.decryptProperty(property,encrypted_value, PATH);
The string decrypted now contains the decrypted value and can be used properly elsewhere in the code where it is relied on.