SSLMigrationCommands

Use the Jython or Jacl scripting languages to migrate key store configurations. Use the commands in the SSLMigrationCommands group to convert self-signed certificates to chained personal certificates and to enable writable key rings.

The SSLMigrationCommands commands include:

• convertSelfSignedCertificatesToChained command
• enableWritableKeyrings command
• convertSSLConfig command
• convertSSLCertificates command

convertSelfSignedCertificatesToChained command

The convertSelfSignedCertificatesToChained command converts specific self-signed certificates to chained personal certificates.

Chained certificates are the default certificate type in WebSphere Application Server Version 7.0. The convertSelfSignedCertificatesToChained command takes information from the self-signed certificate-such as issued-to DN, size, and life span-and creates a chained certificate with the same information. The new chained certificate replaces the self-signed certificate. Signer certificates from the self-signed certificate that are distributed across the security configuration are replaced with the signer certificates from the root certificate used to sign the chained certificate.

Syntax

The command has the following syntax:

wsadmin>$AdminTask convertSelfSignedCertificatesToChained
                     [-certificateReplacementOption ALL_CERTIFICATES | DEFAULT_CERTIFICATES | KEYSTORE_CERTIFICATES]
                     [-keyStoreName keystore_name]
                     [-keyStoreScope keystore_scope]
                     [-rootCertificateAlias alias_name]

Required parameters:

certificateReplacementOption

Convert self-signed certificates replacement options. (String, required)

Specify the value for the parameter as one of the following options:

ALL_CERTIFICATES

This option looks for all self-signed certificates in all keystores with in the specified scope.

The scope can be provided in the -keyStoreScope parameter. If no scope is provided using the -keyStoreScope parameter, all scopes are visited.

DEFAULT_CERTIFICATES

This option looks for self-signed certificates in the default CellDefaultKeyStore and NodeDefaultKeyStore keystores within the specified scope.

The scope can be provided with the -keyStoreScope parameter. If no scope is provided using the -keyStoreScope parameter, all scopes are visited.

KEYSTORE_CERTIFICATES

This option replaces only those self-signed certificates in the keystore specified by the -keyStoreName parameter.

If no scope is provided using the -keyStoreScope parameter, the default scope is used.

Optional parameters:

keyStoreName

Name of a keystore in which to look for self-signed certificates to convert. Use this parameter with the KEYSTORE_CERTIFICATES option on the certificateReplacementOption parameter. (String, optional)

keyStoreScope

Name of the scope in which to look for the self-signed certificates to convert. (String, optional)

rootCertificateAlias

Root certificate to use from the default root store used to sign the chained certificate. The default is root. (String, optional)

Examples

Batch mode example usage:

• Jacl:

  $AdminTask convertSelfSignedCertificatesToChained {-certificateReplacementOption ALL_CERTIFICATES -keyStoreName testKS}
  

• Jython string:

  AdminTask.convertSelfSignedCertificatesToChained('[-certificateReplacementOption ALL_CERTIFICATES -keyStoreName testKS]')
  

• Jython list:

  AdminTask.convertSelfSignedCertificatesToChained(['-certificateReplacementOption', 'ALL_CERTIFICATES', '-keyStoreName', 'testKS'])
  

  To ensure the migration is successful, go to the security.xml file and change the default of dynamicallyUpdateSSLConfig to false in the file. See Dynamic configuration updates in SSL topic in the information center.

Interactive mode example usage:

• Jacl:

  $AdminTask exchangeSigners {-interactive}
  

• Jython:

  AdminTask.exchangeSigners('-interactive')
  

enableWritableKeyrings command

The enableWritableKeyrings command modifies the keystore and enables writable SAF support. The system uses this command during migration. The command creates additional writable keystore objects for the control region and servant region key rings for SSL keystores.

Required parameters:

-keyStoreName

Name that uniquely identifies the keystore to delete. (String, required)

Optional parameters:

-controlRegionUser

Control region user to use to enable writable key rings. (String, optional)

-servantRegionUser

Servant region user to enable writable key rings. (String, optional)

-scopeName

Name that uniquely identifies the management scope, for example: (cell):localhostNode01Cell. (String, optional)

Examples

Batch mode example usage:

• Jython string:

  AdminTask.enableWritableKeyrings('[-keyStoreName testKS -controlRegionUser CRUser1 -servantRegionUser SRUser1]')
  

• Jython list:

  AdminTask.enableWritableKeyrings(['-keyStoreName', 'testKS', '-controlRegionUser', 'CRUser1', '-servantRegionUser', 'SRUser1'])
  

Interactive mode example usage:

• Jython:

  AdminTask.enableWritablekeyrings('-interactive')
  

convertSSLConfig command

The convertSSLConfig command migrates existing SSL configurations to the new configuration object format for SSL configurations.

Required parameters:

-sslConversionOption

Specifies how the system converts the SSL configuration. Specify the CONVERT_SSLCONFIGS value to convert the SSL configuration objects from the previous SSL configuration object to the new SSL configuration object. Specify the CONVERT_TO_DEFAULT value to convert the SSL configuration to a centralized SSL configuration, which also removes the SSL configuration direct referencing from the servers.

Optional parameters: None.

Examples

Batch mode example usage:

• Jython string:

  AdminTask.convertSSLConfig('[-keyStoreName testKS -controlRegionUser CRUser1 -servantRegionUser SRUser1]')
  

• Jython list:

  AdminTask.convertSSLConfig(['-keyStoreName', 'testKS', '-controlRegionUser', 'CRUser1', '-servantRegionUser', 'SRUser1'])
  

Interactive mode example usage:

• Jython:

  AdminTask.convertSSLConfig('-interactive')
  

convertSSLCertificates command

The convertSSLCertificates command converts SSL personal certificates to a personal certificate created with the desired signature algorithm or lists SSL personal certificates that are not created with the desired signature algorithm.

Required parameters: None

Optional parameters

-convertSSLCertAction

Specify LIST to list certificate that are not created with the signature algorithm specified in the -signatureAlgorithm parameter or specify REPLACE to replace SSL certificates not created with the signature algorithm provided in the -signatureAlgorithm with one created with the signature algorithm specified in the -signatureAlgorithm parameter. The default is LIST.

-signatureAlgorithm

Signature algorithm to check and report what personal certificates are not created with it or the signature algorithm used to create new personal certificates to replaces ones that are not created with the signature algorithm. Valid signature algorithms include SHA1withRSA, SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA1withECDSA, SHA256withECDSA, SHA384withECDSA, SHA512withECDSA. The default is SHA256withRSA.

The stronger signature algorithms will require the unrestricted policy file to be in place for create with them to be used, including the signature algorithms that are SHA384 and SHA512. To use certificates with Elliptical Curve (EC) signature algorithms, your SSL configuration needs to be configured to use them. It must use the TLSv1.2 protocol and Elliptical Curve (EC) ciphers must be configured.

Examples

Batch mode example usage:

• Jython string:

  AdminTask.convertSSLCertificates('[- convertSSLCertAction list -signatureAlgorithm SHA256withRSA')
  

• Jython list:

  AdminTask.convertSSLCertificates(['-convertSSLCertAction', 'list', '-signatureAlgorithm', 'SHA256withRSA'])
  

Interactive mode example usage:

• Jython:

  AdminTask.convertSSLCertificates('-interactive')
  

Related:

Dynamic configuration updates in SSL

Key management for cryptographic uses

wsadmin AdminTask

Automating SSL configurations using scripting

Create an SSL configuration at the node scope using scripting

KeyStoreCommands