When migrating to Version 6.1, you can update the format for SSL
configuration or you can continue to use the Version 6.0 format. If you encounter
errors with your existing administration scripts for SSL configurations, use
this task to manually convert your SSL configuration to the Version 6.1 format.
Before you begin
About this task
When migrating to Version 6.1, you can
use the WASPreUpgrade command to
save the configuration of your previously installed version into a migration-specific
backup directory. When migration is complete, you can use the WASPostUpgrade
command to retrieve the saved configuration and WASPostUpgrade script
to migrate your previous configuration. The -scriptCompatibility parameter
for the WASPostUpgrade command is used to specify whether
to maintain the Version 5.x or Version 6.0.x configuration definitions
or to upgrade the format to Version 6.1 configuration definitions. If you
used the default value, or -scriptCompatibility true when migrating,
you do not need to perform this task. If you set the scriptCompatibility parameter
to false during migration, you may notice that your existing administration
scripts for SSL configurations do not work correctly. If this occurs, use
this task to convert your Version 5.x or 6.0.x SSL configuration definitions
to Version 6.1. This process creates a new SSL configuration based on the
existing configuration.
Follow the steps below to modify the existing
SSL configuration:
<repertoire xmi:id="SSLConfig_1" alias="Node02/DefaultSSLSettings">
<setting xmi:id="SecureSocketLayer_1" keyFileName="$install_root/etc/MyServerKeyFile.jks"
keyFilePassword="password" keyFileFormat="JKS" trustFileName="$install_root/etc/MyServerTrustFile.jks"
trustFilePassword="password" trustFileFormat="JKS" clientAuthentication="false" securityLevel="HIGH"
enableCryptoHardwareSupport="false">
<cryptoHardware xmi:id="CryptoHardwareToken_1" tokenType="" libraryFile="" password="{custom}"/>
<properties xmi:id="Property_6" name="com.ibm.ssl.protocol" value="SSL"/>
<properties xmi:id="Property_7" name="com.ibm.ssl.contextProvider" value="IBMJSSE2"/>
</setting>
</repertoire>
Procedure
- Create a key store that references the key store attributes in
the old configuration.
- In the existing configuration, find the keyFileName, keyFilePassword,
and keyFileFormat attributes.
keyFileName="${install_root}/etc/MyServerKeyFile.jks" keyFilePassword="password" keyFileFormat="JKS"
- Use the keyFileName, keyFilePassword, and keyFileFormat attributes
to create a new KeyStore object. For this example, set the name as "DefaultSSLSettings_KeyStore".
Using Jacl:
$AdminTask createKeyStore {-keyStoreName DefaultSSLSettings_KeyStore -keyStoreLocation
${install_root}/etc/MyServerKeyFile.jks -keyStoreType JKS -keyStorePassword
password -keyStorePasswordVerify password }
The
resulting configuration object in the security.xml file is:
<keyStores xmi:id="KeyStore_1" name="DefaultSSLSettings_KeyStore" password="password"
provider="IBMJCE" location="$install_root/etc/MyServerKeyFile.jks" type="JKS" fileBased="true"
managementScope="ManagementScope_1"/>
Note: If you specify
the cryptoHardware values in your configuration, create the KeyStore object
using these values instead. Associate the -keyStoreLocation parameter with
the libraryFile attribute, the -keyStoreType parameter with the tokenType
attribute, and the -keyStorePassword parameter with the password attribute.
<cryptoHardware xmi:id="CryptoHardwareToken_1" tokenType="" libraryFile="" password=""/>
- Create a trust store that references the trust store attributes
from the existing configuration.
- Find the trustFileName, trustFilePassword, and trustFileFormat attributes
in the existing configuration.
trustFileName="$install_root/etc/MyServerTrustFile.jks" trustFilePassword="password" trustFileFormat="JKS"
- Use the trustFileName, trustFilePassword, and trustFileFormat attributes
to create a new KeyStore object. For this example, set the name as "DefaultSSLSettings_TrustStore".
Using Jacl:
$AdminTask createKeyStore {-keyStoreName DefaultSSLSettings_TrustStore -keyStoreLocation
$install_root/etc/MyServerTrustFile.jks -keyStoreType JKS -keyStorePassword password
-keyStorePasswordVerify password }
The resulting
configuration object in the security.xml file is:
<keyStores xmi:id="KeyStore_2" name="DefaultSSLSettings_TrustStore" password="password"
provider="IBMJCE" location="$install_root/etc/MyServerTrustFile.jks" type="JKS" fileBased="true"
managementScope="ManagementScope_1"/>
- Create a new SSL configuration using the new key store and trust
store. Include any other attributes from the existing configuration which
are still valid. Use a new alias for your updated SSL configuration.
You can not create an SSL configuration with the same name as your existing
configuration.
Using Jacl:
$AdminTask createSSLConfig {-alias DefaultSSLSettings -trustStoreName DefaultSSLSettings_TrustStore
-keyStoreName DefaultSSLSettings_KeyStore -keyManagerName IbmX509 -trustManagerName IbmX509
-clientAuthentication true -securityLevel HIGH -jsseProvider IBMJSSE2 -sslProtocol SSL }
Results
The new SSL configuration is:
<repertoire xmi:id="SSLConfig_1" alias="DefaultSSLSettings" managementScope="ManagementScope_1">
<setting xmi:id="SecureSocketLayer_1" clientAuthentication="true" securityLevel="HIGH" enabledCiphers=""
jsseProvider="IBMJSSE2" sslProtocol="SSL" keyStore="KeyStore_1" trustStore="KeyStore_2" trustManager="TrustManager_1"
keyManager="KeyManager_1"/>
</repertoire>
Note: The default management scope is used if it is not specified.