IBM Security Key Lifecycle Manager : Scenarios · Use the IBM Security Key Lifecycle Manager installation program and repeat the same steps that you took on the primary computer

IBM Security Key Lifecycle ManagerVersion 4.0

Scenarios

IBM

Note

Before you use this information and the product it supports, read the information in “Notices” on page139.

Copyright statement

Note: This edition applies to version 4.0 of IBM® Security Key Lifecycle Manager (product number 5724-T60) and to allsubsequent releases and modifications until otherwise indicated in new editions.© Copyright International Business Machines Corporation 2008, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Chapter 1. Scenarios............................................................................................. 1Scenario: To provide a primary and replica server..................................................................................... 1

Backup and restore practices................................................................................................................ 2Backup and restore runtime requirements........................................................................................... 2Setting up a replica computer................................................................................................................ 3Responding after significant replica server activity...............................................................................3

Scenario: To request for a third-party certificate........................................................................................4Creating a certificate request.................................................................................................................5Importing a certificate............................................................................................................................7Certificate request problems................................................................................................................. 9

Scenario: To set up SSL handshake between IBM Security Key Lifecycle Manager server andclient device..........................................................................................................................................10Creating a self-signed SSL/KMIP server certificate............................................................................ 10Exporting a server certificate............................................................................................................... 11Importing a client communication certificate..................................................................................... 11

Scenario: To migrate a Multi-Master cluster in inline mode.....................................................................12Scenario: To cross-migrate an IBM Security Key Lifecycle Manager Multi-Master cluster.....................13Scenario: To plan a disaster recovery solution using IBM Security Key Lifecycle Manager....................14

Notices..............................................................................................................139Terms and conditions for product documentation.................................................................................140Trademarks..............................................................................................................................................141

iii

iv

Chapter 1. ScenariosScenarios demonstrate how to apply technology to accomplish business goals and solve problems. Theydescribe hypothetical business situations to bring the discussions to life.

These scenarios explore some of the first steps and some of the more advanced tasks that you can do byusing IBM Security Key Lifecycle Manager. As a prerequisite for these scenarios, install the IBM SecurityKey Lifecycle Manager server and verify that its components are running.

For scenarios related to Multi-Master cluster configuration, see the technote: https://www.ibm.com/support/pages/node/1072470

Note: The user IDs, names, and passwords that are used in these scenarios are examples only.

Scenario: To provide a primary and replica serverTo ensure continuous key and certificate availability to encrypting devices, configure a primary and areplica IBM Security Key Lifecycle Manager server for your enterprise. Then, provide repeated backup andrestore actions that protect critical data.

On Windows systems and other systems, both systems must have the required memory, speed, andavailable disk space to meet the workload.

IBM Security Key Lifecycle Manager creates backup files in a manner that is independent of operatingsystems and directory structure of the application. You can restore the backup files to an operatingsystem that is different from the one it was backed up from.

Figure 1. Primary and replica IBM Security Key Lifecycle Manager server

Before you create a replica server, catalog the requirements in your operation, which might include:

• Disaster recovery procedures that are unique to your site. The procedures might require ad hoc orperiodic activities to ensure concurrent availability of a primary and replica IBM Security Key LifecycleManager server.

Your site might require periodic exercises to demonstrate that a simulated failure of a primary IBMSecurity Key Lifecycle Manager server causes an immediate response from a replica.

The IBM Security Key Lifecycle Manager server does not provide automatic failover. You mustseparately set up the necessary device controls to ensure that the replica server is available if theprimary server fails.

• Initial installation and configuration of IBM Security Key Lifecycle Manager server and the devices inyour installation that require keys and certificates.

You might choose to also install and configure IBM Security Key Lifecycle Manager server and itsprerequisites on another server, and set a schedule to back up and restore critical data.

• Cycles of time at which your organization normally changes keys and certificates.

© Copyright IBM Corp. 2008, 2019 1

https://www.ibm.com/support/pages/node/1072470

https://www.ibm.com/support/pages/node/1072470

If your organization replaces keys and certificates on a monthly or quarterly basis, ensure that the keymaterials and other data are backed up when new keys and certificates begin their usage cycle.

• Events that cause you to create a certificate request and send the request to a certificate authority.

Use the secure communication process that your site or the certificate authority requires. Run a backupto protect keys and data that are associated with a certificate request until the actual certificate returns.

• Upgrades and related middleware fix packs for the IBM Security Key Lifecycle Manager server.

Run a backup to ensure that the upgraded IBM Security Key Lifecycle Manager server has the samekeys and other critical data that were in use immediately prior to the upgrade.

Backup and restore practicesWhen a change occurs, such as adding or changing devices, keys, and certificates, you must back up theIBM Security Key Lifecycle Manager critical data. IBM Security Key Lifecycle Manager provides a task thatcreates a backup file of configuration files, database, and other data. You can restore this backup file toan operating system that is different from the one it was backed up from.

Failure to back up your critical data properly might result in unrecoverableloss of all access to your encrypted data. Do not encrypt your backup file, orstore a backup file on an encrypting device. Failure to back up data might also result in alater inconsistency of the key manager and potential data loss on the storage device.

You can follow these practices:

• Maintain both a primary IBM Security Key Lifecycle Manager server and at least one replica IBMSecurity Key Lifecycle Manager server that run concurrently. Ensure that a storage device has access toits keys if the primary server fails.

The IBM Security Key Lifecycle Manager server does not provide automatic failover. You mustseparately set up the necessary device controls to ensure that the replica server is available if theprimary server fails.

• Run the backup task whenever you add or change devices, keys, or certificates. Restore the IBMSecurity Key Lifecycle Manager backup file to a replica IBM Security Key Lifecycle Manager server.

• Do not make changes to the IBM Security Key Lifecycle Manager server on the replica computer undernormal operating conditions in which a primary server is always available. If failure events causesignificant activity on the replica server while the primary server is down, back up the replica server andrestore the backup file to the primary server.

• Use only the IBM Security Key Lifecycle Manager backup and restore tasks to create a backup file. Useonly IBM Security Key Lifecycle Manager to restore the data that the backup file contains. Do not takeother manual steps to back up or to restore files.

• Keep backup files in a safe place, separate from the computer on which the IBM Security Key LifecycleManager server runs. Ensure that function can be rebuilt on a replacement server if files on the primaryIBM Security Key Lifecycle Manager server are lost. These files might reside at a geographicallyseparate location.

Backup and restore runtime requirementsYou must prevent timeout failure by increasing the time interval that is allowed for backup and restoretransactions for large key populations. Specify a larger value for the totalTranLifetimeTimeoutsetting in the server.xml file.

WAS_HOME/profiles/KLMProfile/config/cells/SKLMCell/nodes/SKLMNode/servers/server1/server.xml

Additionally, these conditions must be true:

• Ensure that the task occurs during a time interval that allows a halt to key serving activity.• For a backup task, the IBM Security Key Lifecycle Manager server must be running in a normal

operational state. The IBM Security Key Lifecycle Manager database instance must be available.

2 IBM Security Key Lifecycle Manager : Scenarios

• For a restore task, the IBM Security Key Lifecycle Manager database instance must be accessiblethrough the IBM Security Key Lifecycle Manager data source.

Before you start a restore task, ensure that you have the password that was used when the backup filewas created. Restored files must be written to the same IBM Security Key Lifecycle Manager serverfrom which the data was previously backed up. Alternatively, the restored files must be written to areplica computer.

• Ensure that the directories, which are associated with the tklm.backup.dir property exist. Also,ensure read and write access to these directories for the system and IBM Security Key LifecycleManager administrator accounts under which the IBM Security Key Lifecycle Manager server and theDb2® server run.

Setting up a replica computerA replica computer for IBM Security Key Lifecycle Manager must have the same or greater storagecapacity and free disk space as the primary computer on which IBM Security Key Lifecycle Managerserver customarily runs.

About this task

Use the IBM Security Key Lifecycle Manager installation program and repeat the same steps that you tookon the primary computer.

Procedure

1. Obtain a computer that has the same or greater storage capacity and free disk space as the computeron which IBM Security Key Lifecycle Manager server customarily runs.

2. Install and configure an operating system and fixes on the replica computer to match the system onthe computer on which IBM Security Key Lifecycle Manager server customarily runs.

3. Complete the installation steps and verification steps that are described in the “Installing andconfiguring” section on IBM Knowledge Center for IBM Security Key Lifecycle Manager.

What to do next

Configure and test the replica computer after you install and verify the primary computer on which IBMSecurity Key Lifecycle Manager customarily runs.

Verify that a current backup file that you create on the primary IBM Security Key Lifecycle Manager servercan be successfully restored on the replica computer.

Responding after significant replica server activityA replica server might have significant activity while the primary IBM Security Key Lifecycle Managerserver is down. Select an announced maintenance interval, when network traffic is stopped, to back upthe replica server and restore the backup file to the primary server.

About this task

No alerts are issued if the replica server provides keys to a device. Validate that there is actually a need toback up the replica computer and then restore the backup file to the primary server. For example, youmight determine whether a write request caused a key to be served to a device. Use thetklmServedDataList command to query the database and to list served data. Less significantinformation might be available in the audit log for read requests from devices.

Procedure

1. At an announced time when network traffic is stopped, back up the replica computer.2. Restore the backup file from the replica computer onto the primary computer on which IBM Security

Key Lifecycle Manager server customarily runs.

Chapter 1. Scenarios 3

What to do next

Verify that the primary IBM Security Key Lifecycle Manager server is active and that the backup file wassuccessfully restored.

Scenario: To request for a third-party certificateIBM Security Key Lifecycle Manager can generate a certificate request in PKCS #10 format that you cansend to a certificate authority. Use the returned CA certificate to protect data on an encryption-enableddevice, or for SSL communication.

1. Before you begin, determine whether the usage of the certificate is for SSL authentication, or forsecure communication with 3592 tape drives or DS8000® Turbo drives.

2. For each of the certificates that you anticipate in your next business cycle, create a certificate request.

The generated certificate request files reside in the SKLM_HOME directory. For example, a generatedcertificate request might be a file such as SKLM_HOME\080419154137–sslcert001.csr.

The certificate request file is an encoded, base64 format, which is not readable with an editor.

The certificate request file contains the base64 format information, including:

• The version number.• The subject name, which is the X.500 name of the requestor. For example, an X.500 name contains

values for a common name (cn), organization, and other values that identify the subject.• The public key data and the algorithm unique identifier. You can use the algorithm, such as RSA orECDSA.

• A generated signature for the data that is signed by the private key of the user.

The keystore database contains the private key that was used to generate the signature for thecertificate request.

Additionally, information related to the certificate request is stored in the database. The informationincludes the X.500 subject name, the start, expiration, and retirement date, and other values for otherattributes that are normally specified for a certificate, including a pending state for the certificaterequest. The values are updated when the returned certificate is imported.

3. Protect certificate requests until the certificate returns. It is important to run a backup task for thekeystore database after you create and send a certificate request, just as when you change actual keysor certificates in a keystore database.

4. After ensuring that a backup file is in place, manually send a certificate request to your selectedcertificate authority, by using the secure communication process that your site or the certificateauthority requires for e-mail or https transmission.

5. Import a returned certificate that matches an earlier certificate request.

Upon receipt of a valid request, the certificate authority returns a DER, base64, or PEM encodedcertificate to you. The certificate contains the public key that was provided in the certificate request,and a signature from the certificate authority, which specify that the public key is valid, and that yourenterprise is the authentic owner. The certificate subject name is the X.500 subject name that youprovided in the certificate request.

6. Again back up the keystore database, which contains the new certificate.


Creating a certificate requestUse the Create Certificate dialog, tklmCertGenRequest command, or Certificate GenerateRequest REST Service to create certificate requests.

About this task

Before you begin, determine your site policy and process to obtain certificates that are issued by acertificate authority.

Procedure

1. Navigate to the appropriate page or directory:

• Graphical user interface:

a. Log on to the graphical user interface.b. In the Key and Device Management section on Welcome page, select the 3592 or DS8000 device

group.c. Click Go to > Guided key and device creation.d. Alternatively, right-click 3592 or DS8000 and select Guided key and device creation.

• Command-line interface

a. Go to the <WAS_HOME>/bin directory. For example,Windows

cd drive:\Program Files\IBM\WebSphere\AppServer\binLinux

cd /opt/IBM/WebSphere/AppServer/binb. Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin. For example,

Windows

wsadmin.bat -username SKLMAdmin -password mypwd -lang jython

Linux

./wsadmin.sh -username SKLMAdmin -password mypwd -lang jython

• REST interface:

– Open a REST client.2. Request a certificate:


a. On the Step 1: Create Certificates page, click Create.b. On the Create Certificate dialog, select a certificate request for a third-party provider.c. Specify values for the required and optional parameters.d. Click Create Certificate.

• Command-line interface:

Type tklmCertGenRequest to create a certificate request file. For example:

– SSL communication

print AdminTask.tklmCertGenRequest('[-alias sklmSSLCertificate1 -cn sklm -ou sales -o myCompanyName -locality myLocation -country US -validity 999 -keyStoreName defaultKeyStore -fileName mySSLCertRequest1.crt -usage SSLSERVER]')


– 3592 tape drives

print AdminTask.tklmCertGenRequest('[-alias sklmCertificate1 -cn sklm -ou marketing -o CompanyName -locality myLocation -country US -validity 999 -keyStoreName defaultKeyStore -fileName myCertRequest1.crt -usage 3592]')

– DS8000 Turbo drives

print AdminTask.tklmCertGenRequest('[-alias sklmCertificate3 -cn sklm -ou sales -o myCompanyName -locality myLocation -country US -validity 999 -keyStoreName defaultKeyStore -fileName myCertRequest3.crt -usage DS8000]')

• REST interface:

a. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager RESTservices. For more information about the authentication process, see “Authentication process forREST services” on page 27.

b. To invoke Certificate Generate Request REST Service, send the HTTP POST request.Pass the user authentication identifier that you obtained in Step a along with the requestmessage as shown in the following example.


POST https://localhost:<port>/SKLM/rest/v1/certificatesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"type":"certreq","alias":"sklmSSLCertificate1","cn":"sklm","ou":"sales","o":"myCompanyName","usage":"SSLSERVER","country":"US","validity":"999","fileName":"mySSLCertRequest1.crt","algorithm":"ECDSA"}


POST https://localhost:9080/SKLM/rest/v1/certificatesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"type":"certreq","alias":"sklmCertificate1","cn":"sklm","ou":"sales","o":"myCompanyName","usage":"3592","country":"US","validity":"999","fileName":"myCertRequest1.crt","algorithm":"ECDSA"}


POST https://localhost:<port>/SKLM/rest/v1/certificatesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"type":"certreq","alias":"sklmCertificate3","cn":"sklm","ou":"sales","o":"myCompanyName","usage":"DS8000","country":"US","validity":"999","fileName":"myCertRequest1.crt","algorithm":"ECDSA"}

3. A success indicator varies, depending on the interface:


The certificate or certificate request appears as an item in the Certificates table. Return to theWelcome page. On the Welcome page, in the Action Items, the certificate request appears as anitem in the Pending Certificate table.


A completion message indicates success.• REST interface:


The status code 200 OK indicates success.

What to do next

Manually send the certificate request to a certificate authority, by using the secure communicationprocess that your organization provides. Additionally, retain the alias value of the certificate request, foruse when you import the returned certificate, which must match a certificate request.

Importing a certificateYou can use the pending certificates link on the Welcome page of graphical user interface, thetklmCertImport CLI command, or Certificate Import REST Service to import a certificate thatyou earlier requested from a certificate authority.

About this task

Before you begin, ensure that the alias of the incoming certificate matches the alias of a previouscertificate request, such as sklm cert1. Write the certificate file to a temporary directory.

Retrieve the alias of original certificate request, for use when you import the returned certificate, whichmust specify the correct alias.

To look up the X.500 subject name of a certificate request, to determine whether it matches the X.500subject name of the certificate, run the tklmCertList command or Certificate List RESTService, by specifying the state attribute with a value of pending.

To look at the subject name of the certificate file, you might take these steps:

• Windows systems:

Open the certificate file directly. A Windows native utility displays the information in the certificate inreadable format.

• Other systems:

Import the certificate into IBM Security Key Lifecycle Manager by using a new alias. Then, run thetklmCertList command or the Certificate List REST Service, specifying the alias, to viewthe certificate information.

Procedure

1. Go to the appropriate page or directory:


Log on to the graphical user interface. The Welcome page is displayed.• Command-line interface




Windows


Linux


• REST interface:


– Open a REST client.2. Import a certificate.

• Graphical user interface

a. In the Action Items section of the Welcome page, in the Key Groups and Certificates area, clickYou have pending certificates.

b. In the Pending Certificates table, select the appropriate pending certificatec. Click Import.d. Click Browse to specify the certificate request file location under <SKLM_DATA>. For the

definition of <SKLM_DATA>, see “Definitions for HOME and other directory variables” on page31.

e. The File name and location field displays the default <SKLM_DATA> directory path, where thecertificate file is saved, for example, C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data. For the definition of <SKLM_DATA>, see “Definitions for HOME andother directory variables” on page 31. Click Browse to specify a location under <SKLM_DATA>directory.

f. Click Import.• Command-line interface:

Type tklmCertImport to import a certificate. For example:


print AdminTask.tklmCertImport ('[-fileName myTempPath\\mySSLCertRequest1.cer -alias sklmSSLCertificate1 -format base64 -keyStoreName defaultKeyStore -usage SSLSERVER]')


print AdminTask.tklmCertImport ('[-fileName myTempPath\\myCertRequest2.cer -alias sklmCertificate2 -format base64 -keyStoreName defaultKeyStore -usage 3592]')


print AdminTask.tklmCertImport ('[-fileName myTempPath\\myCertRequest3.cer -alias sklmCertificate3 -format base64 -keyStoreName defaultKeyStore -usage DS8000]')

• REST interface

a. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager RESTservices. For more information about the authentication process, see “Authentication process forREST services” on page 27.

b. To run Certificate Import REST Service, send the HTTP POST request. Pass the userauthentication identifier that you obtained in Step a along with the request message as shownin the following example.


POST https://localhost:<port>/SKLM/rest/v1/certificates/importContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"fileName":"/mycertfilenam.base64","alias","sklmSSLCertificate1","format":"base64","usage":"SSLSERVER"}



POST https://localhost:<port>/SKLM/rest/v1/certificates/importContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"fileName":"/mycertfilenam.base64","alias","sklmSSLCertificate2","format":"base64","usage":"3592"}


POST https://localhost:<port>/SKLM/rest/v1/certificates/importContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth authId=139aeh34567m{"fileName":"/mycertfilenam.base64","alias","sklmSSLCertificate3","format":"base64","usage":"DS8000"}

3. A success indicator varies, depending on the interface:


The pending certificate entry is removed from the Pending Certificates table on the Welcome page.If there are no more certificates to be imported, the Pending Certificates table is removed from theAction Items section of the Welcome page.


A completion message indicates success.• REST interface:

The status code 200 OK indicates success.

What to do next

Ensure that you back up the key materials to protect the certificate. Then, you might associate thecertificate with one or more devices.

Certificate request problemsYou must solve problems in either creating a certificate request, or enabling a returned certificate for use.

• Before you create a certificate request, solve these problems as administrator:

– Problem: You might not have permission to write to the certificate request file. Alternatively, theremight not be sufficient free disk space, or the database might not be available.

Solution: Ensure that your permissions are correct, that there is sufficient free disk space, and thatthe database connection is available. If not, make the appropriate corrections. Then, try theoperation again.

– Problem: A value is not specified for the common name. The common name (cn) is part of the uniqueidentification for the certificate. For example, the value of cn is used in the subject name for acertificate, which can identify whether a certificate that is being imported matches an originalcertificate request.

Solution: Specify the common name for the certificate. Then, try the operation again.– Problem: The certificate request file exists.

Solution: The file name that you specified in the certificate request matches an existing certificaterequest file name. Specify a different file name for the certificate request. For example, specifymyUniqueRequest.crt. Then, try the operation again.

• When you import a returned CA certificate, solve these problems:

– Problem: The subject name of the certificate that returned from a certificate authority does notmatch the subject name in the original certificate request.

Solution: Correct the file name or alias specification. Then, try the import operation again.


– Problem: An error occurs while verifying the key and certificate. The certificate request that yousubmitted to a certificate authority and the certificate that returned, do not match.

Solution: The problem might be an internal processing error. Collect any information that might be inthe audit log and then contact IBM Software Support.

– Problem: The key in the certificate to be imported does not match the key in the original certificaterequest.

Solution: You attempted to match a returned certificate to an incorrect certificate request. Importthe certificate by using an alias that corresponds to this response. Then, try the operation again.

– Problem: When you import a certificate with the expiration year greater than 50 years, you might seethese messages:Using command-line interface

CTGKM0002E Command failed: javax.management.MBeanException: RuntimeException thrown in RequiredModelMBean while trying to invoke operation importCertificate

Using graphical user interface

Cannot import certificate to the keystore.javax.management.MBeanException: RuntimeException thrown in RequiredModelMBean while trying to invoke operation importCertificate

Workaround: The certificate expiration period cannot be greater than 50 years. To modify theexpiration period, change the value of the maximum.keycert.expiration.period.in.yearsparameter in theSKLMConfig.properties file.

Scenario: To set up SSL handshake between IBM Security Key LifecycleManager server and client device

The SSL handshake enables IBM Security Key Lifecycle Manager server and client devices to establish theconnection for secure communication. IBM Security Key Lifecycle Manager provides the ServerConfiguration Wizard to configure server and the client device for SSL handshake.

You must complete the following steps in the wizard for SSL/TLS handshake:

1. Creating a self-signed SSL/KMIP server certificate.2. Exporting the SSL/KMIP server certificate that is created in Step 1 to a certificate file in an encoded

format for use by the client device. You can also export an existing certificate.3. Importing client communication certificate to the IBM Security Key Lifecycle Manager server.

Creating a self-signed SSL/KMIP server certificateAs a first activity, you might create an SSL/KMIP server certificate for use with IBM Security Key LifecycleManager.

Procedure

1. Log on to the graphical user interface.2. Click the Review the configuration parameters and/or create an SSL server certificate link.

Immediately after you install IBM Security Key Lifecycle Manager, the Review the configurationparameters and/or create an SSL server certificate link is the only available option to configure IBMSecurity Key Lifecycle Manager for SSL/TLS handshake with the client devices. This link is not visible ifyou previously created an SSL server certificate.

3. Alternatively, on the Welcome page, click Configuration > SSL/KMIP > Launch Server ConfigurationWizard.


4. Click Create SSL/KMIP Server Certificate.5. On the Add SSL/KMIP Certificate dialog, select Create self-signed certificate.6. Specify values for the parameters according to your requirements.7. Click Create Certificate.

What to do next

You might need to export the IBM Security Key Lifecycle Manager SSL/KMIP server certificate that youcreated to a file in an encoded format for use by the client device. Click the Export Certificate link or clickthe Export SSL/KMIP Server Certificate tab. You can also export an existing SSL/KMIP server certificateby selecting Use an existing certificate. See “Exporting a server certificate” on page 11.

Exporting a server certificateYou must export the IBM Security Key Lifecycle Manager SSL/KMIP server certificate to a file in anencoded format for use by the client device. The client device imports this certificate for securecommunication with the server.

Procedure

1. Log on to the graphical user interface.2. On the Welcome page, click Configuration > SSL/KMIP > Launch Server Configuration Wizard.3. To create a self-signed certificate, click Create SSL/KMIP Server Certificate. See the “Creating a self-

signed SSL/KMIP server certificate” on page 10 topic for more information.4. Click Export SSL/KMIP Server Certificate.5. On the Export Certificate dialog, select the server certificate from the Certificate name list.6. Specify certificate name in the File name field.7. The File location field displays the default <SKLM_DATA> directory path, where the certificate is

exported, for example, C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data. For the definition of <SKLM_DATA>, see “Definitions for HOME and other directory variables”on page 31. Click Browse to specify a location under <SKLM_DATA> directory.

8. Specify the certificate type, such as BASE64 or DER.9. Click Export Certificate.

What to do next

You might go the next step to import the client device communication certificate for securecommunication between IBM Security Key Lifecycle Manager server and the client device. Click the Go toNext Step link or select Import SSL/KMIP Server Certificate. See “Importing a client communicationcertificate” on page 11.

Importing a client communication certificateYou must import communication certificate to the IBM Security Key Lifecycle Manager server for securecommunication with the client device.

Procedure

1. Log on to the graphical user interface.2. On the Welcome page, click Configuration > SSL/KMIP > Launch Server Configuration Wizard.3. To create a self-signed certificate, click Create SSL/KMIP Server Certificate. See the “Creating a self-

signed SSL/KMIP server certificate” on page 10 topic for more information.4. Click Export SSL/KMIP Server Certificate to export the IBM Security Key Lifecycle Manager SSL/

KMIP server certificate to a file in an encoded format for use by the client device. See the “Exporting aserver certificate” on page 11 for more information.

5. Click Import SSL/KMIP Client Certificate.


6. On the Import Certificate dialog, specify values for the parameters according to your requirements.7. Click Import.

Scenario: To migrate a Multi-Master cluster in inline modeTo ensure the Multi-Master cluster configuration is replicated after you migrate from IBM Security KeyLifecycle Manager version 3.0.0.x (source) to version 4.0 (target), you need to plan the Multi-Mastercluster migration, and perform the inline migration in a specific order. You can choose to not migrate theMulti-Master configuration but only migrate the master servers to the newer version.

Migrating an IBM Security Key Lifecycle Manager Multi-Master cluster in inline mode

1. Plan the Multi-Master cluster migration.2. Migrate the master servers in the Multi-Master cluster.3. Complete the post-migration tasks.

Planning the Multi-Master cluster migration

• Ensure that the configuration of all the master servers in the Multi-Master cluster is correct. Forexample, check for any discrepancy in the actual role of the master server and the role that isconfigured in the SKLMConfig.properties file. If a master server is acting primary, ensure its role inthe configuration file is Primary. Else, the inline migration fails.

• Note down the HTTPS ports that you plan to use for the master servers in the migrated cluster.• If a master server in the cluster is running the Linux operating system, ensure that the permissions for

the /tmp directory on the server is set to 777 that is full execute, read, and write permissions.• Create a properties file on the primary master server to store the configuration details of the Multi-

Master cluster.

– In a temporary directory, create the mmsetup.properties file. Example of temporary directory:

Windows: %temp%Linux: $TMPDIR

– In the mmsetup.properties file, include the host names and HTTPS ports that you plan to use forthe master servers in the migrated cluster.

– Ensure that you specify the same host names that are provided in the cluster configuration of thesource IBM Security Key Lifecycle Manager master server.

– Sample mmsetup.properties file:

PRIMARY_HTTP_PORT=9443PRIMARY_IP_HOSTNAME=myprimaryhostPRIMARY_HADR_PORT=60027 (optional)STANDBY_1_HTTP_PORT=9443STANDBY_1_IP_HOSTNAME=mystandbyhost1 STANDBY_2_HTTP_PORT=9443STANDBY_2_IP_HOSTNAME=mystandbyhost2 NODE_1_HTTP_PORT=9443NODE_1_IP_HOSTNAME=mynonhadrhost1 NODE_2_HTTP_PORT=9443NODE_2_IP_HOSTNAME=mynonhadrhost2

Note: If you do not specify the PRIMARY_HADR_PORT value in the file, the default port value 60027 isused.

• During the inline migration process, only the master servers that are correctly specified in themmsetup.properties file are added to the migrated Multi-Master cluster.


Migrating the master servers in the Multi-Master cluster in inline mode

1. Migrate all the standby and non-HADR master servers in the IBM Security Key Lifecycle Manager Multi-Master cluster. For instructions, see “Supported upgrade paths and migration methods” on page 15and “Upgrading: Installing IBM Security Key Lifecycle Manager silently” on page 16.

2. Ensure that all the migrated standby and non-HADR master servers are up and running.3. Migrate the primary master server.

For instructions, see “Installing IBM Security Key Lifecycle Manager in silent mode” on page 29.

Completing the post-migration tasks

• Verify whether all the configuration properties are correctly updated in the SKLM_HOME/config/SKLMConfig.properties file on the IBM Security Key Lifecycle Manager target server.

• Verify whether all the master servers are correctly added in the newly created cluster, and check theirDB2 HADR configuration status. For instructions, see “Viewing the configuration status of all masterservers” on page 39.

• If any master servers of the earlier Multi-Master cluster are not automatically configured in the newcluster, add them by using one of the following methods:

– Run the createCluster.bat or createCluster.sh script file. The file is located in the followingpath:

Windows: SKLM_HOME\migration\binLinux: SKLM_HOME/migration/bin

Note: The script file uses the mmsetup.properties file as input. Ensure that themmsetup.properties file is correctly updated.

Run the command as follows:Windows

createCluster.bat

Linux

./createCluster.sh

– Add the master servers manually. For instructions, see “Adding a master server to a cluster” on page40.

• Review the logs for the cluster migration. The logs are stored in the temporary directory.

Windows: %temp%/cluster_migration.log Linux: $TMPDIR/cluster_migration.log

Scenario: To cross-migrate an IBM Security Key Lifecycle Manager Multi-Master cluster

Complete the steps from this topic to migrate a Multi-Master cluster from an earlier version (source) ofIBM Security Key Lifecycle Manager to version 4.0 (target). You need to use the cross-migration utility.

1. Configure the new cluster.

a. Identify servers to create the new IBM Security Key Lifecycle Manager Multi-Master cluster.b. Install IBM Security Key Lifecycle Manager version 4.0 on the servers that will be added to the new

cluster. See “Installing” on page 127.c. Add master servers to the new cluster. See “Adding a master server to a cluster” on page 40.


d. Ensure that the new cluster is up and running. See “Multi-Master cluster configuration status” onpage 128.

2. Migrate data from the source cluster to the target cluster.

Important: Plan for sufficient downtime for this step.

a. Back up the primary master server on the source IBM Security Key Lifecycle Manager cluster.b. Restore the backup files on a new server and use it as the primary master server.

For instructions, see “Migrating data from an earlier version of IBM Security Key Lifecycle Manager” onpage 42.

3. Configure the clients (for example, storage devices) that are using the source cluster.

a. Configure the clients to use the new cluster.b. Verify that the clients are working with the new cluster.

Note: After you ensure that the devices are able to work with new cluster, you can remove the sourcecluster.

Scenario: To plan a disaster recovery solution using IBM Security KeyLifecycle Manager

As an administrator, you can use replication in IBM Security Key Lifecycle Manager to protect mission-critical data and ensure business continuity.

IBM Security Key Lifecycle Manager replication ensures availability of the key materials, configurationfiles, and other data on a server by having at least one copy or replica of the data on another server. Eachserver is available for data recovery when the other one fails. In replication, IBM Security Key LifecycleManager creates a backup of the data and copies it to the other server as per the configured schedule.

Master server is the primary system that is being backed up and replicated to one or more secondaryservers, called clone servers. You must configure IBM Security Key Lifecycle Manager on the master andclone servers to schedule replication. New keys are created only on the master server. Clone servers canserve keys.

For more information, see “Configuring replication” on page 42.

Solution

To achieve a disaster recovery solution, you can configure your IBM Security Key Lifecycle Managerservers to use replication with one master server and at least one clone server in geographically differentzones. Enable incremental replication so that the clone server always contains almost up-to-date IBMSecurity Key Lifecycle Manager data.

You can configure maximum 20 clone servers.

Prerequisites

Ensure that IBM Security Key Lifecycle Manager is installed on the master and clone servers.

Steps

1. Configure full replication on the master and clone servers. For more information, see “Enabling andconfiguring full replication” on page 43.

2. Enable incremental replication on the master server. For more information, see “Enabling andconfiguring incremental replication” on page 43.


Other data recovery options

You can consider the following options for achieving a disaster recovery solution. But they have specificconsiderations and limitations.Backup and restore

Creating a data backup and restoring it on another server is a basic and simple method for protectingdata. This method is manual and inexpensive. It relies on snapshots which are copies of the data thatare taken at a predetermined point in time. Hence, in case of a disaster, you can only recover thesnapshot that was last restored.

For more information, see “Configuring backup and restore” on page 45.

Multi-Master clusterA Multi-master cluster solution provides high availability of data and supports recovery of data in caseof a disaster. This method is automated and continuously replicates data in real time. However, itinvolves specific installation requirements, additional configuration, and requires a specialized Db2administrator.

For more information, see “Configuring a Multi-Master cluster” on page 46.

Supported upgrade paths and migration methodsSteps to upgrade IBM Security Key Lifecycle Manager depend on the existing version that is installed onthe host system.

Upgrade process overview

IBM Security Key Lifecycle Manager does not support a direct upgrade from the existing version (installedon the host system) to the target version (to which you want to upgrade).

To upgrade, you must complete the following high-level operations:I. Install the target version.

You can install the product by using the graphical user interface or silently.You can install the target version on the same system that hosts the existing version, or on anotherhost system. For example, when the system configuration of the host of the existing version does notmeet the requirements of the target version, or when you need to upgrade IBM Security Key LifecycleManager on to a different operating system, you need to install the target version on another hostsystem.

II. Migrate data from the existing version to the target version.There are two methods of data migration:Inline migration

When the host system of the target version is the same as the existing version, use inlinemigration of data.

Cross migrationWhen the host system of the target version is different than the host system of the existingversion, use cross migration of data. IBM Security Key Lifecycle Manager provides sampleresponse files that you can use to cross migrate data.

Note: Migration does not remove the earlier version of IBM Security Key Lifecycle Manager.

Supported upgrade paths and migration methods

Use the following table to understand the supported upgrade paths and migration methods.


Table 1. Supported upgrade paths and migration methods

Existing version Minimum requiredlevel

Supported? Notes

Inline migration Cross migration

3.0.1 General availability(GA)

“Upgrading IBMSecurity KeyLifecycle Managerto Version 4.0” onpage 129

3.0 General availability(GA)


2.6 Fix pack 2

2.5** Fix pack 3

IBM Tivoli KeyLifecycle ManagerV 2.0.1**

Fix pack 5 Upgrade path:

(→ V2.7 → V4.0)*

“Upgrading IBMTivoli Key LifecycleManager to IBMSecurity KeyLifecycle Manager4.0” on page 130

IBM Tivoli KeyLifecycle ManagerV 2.0**

Fix pack 6


Fix pack 7

Encryption KeyManager V 2.1**

- “UpgradingEncryption KeyManager to IBMSecurity KeyLifecycle Manager4.0” on page 130

* - Cross-migration of IBM Tivoli Key Lifecycle Manager data to IBM Security Key Lifecycle Manager,Version 4.0 consists of the following two stages:

1. Migrating the IBM Tivoli Key Lifecycle Manager data to a system where IBM Security Key LifecycleManager, Version 2.7 is installed.

2. Migrating IBM Security Key Lifecycle Manager, Version 2.7 data to a system where IBM Security KeyLifecycle Manager, Version 4.0 is installed.

** - End of support (EOS) version. For more information, see IBM Support - Software lifecycle.

Upgrading: Installing IBM Security Key Lifecycle Manager silentlyYou can choose to migrate data during the installation of IBM Security Key Lifecycle Manager V 4.0(target) or migrate the data as a separate step.

Before you begin

• Read the license terms for the product. To locate the license term files, in the root directory in which theinstallation package is located, navigate to the disk1/im/license subdirectory. The/licensesubdirectory has the license files in text format.

• Select the appropriate sample response file to create the response file to be used for the installation.


https://www-01.ibm.com/software/support/lifecycleapp/PLCSearch.wss?q=security+key+lifecycle+manager

IBM Security Key Lifecycle Manager includes platform-specific sample response files that you can useas a template for creating your own response file. A separate response file is available depending on theoperating system of the host system and the data migration approach.

Table 2. Response files

Approach Sample response file name Example: Install target versionon a host system that isrunning Linux with existing(source) version as 3.0

Install IBM Security KeyLifecycle Manager target versionwith inline data migration

SKLM_Silent_platform_Mig_version_Resp.xml

SKLM_Silent_Linux_Mig_30_Resp.xml

Install IBM Security KeyLifecycle Manager target versiononly (Skip data migration duringinstallation)

SKLM_Silent_platform_Resp.xml

SKLM_Silent_Linux_Resp.xml

Where,

– platform is the operating system that is running on the host system.– version is the existing (source) version of IBM Security Key Lifecycle Manager or Encryption Key

Manager.

The response files and license term files are available in the root directory of the installation image files.The /license subdirectory has the license files in text format.

Important: Before you use a sample response file, complete the following changes to the line thatspecifies the license in the file, otherwise installation will fail:

– Set the default value to true to indicate that you agree with the terms of the license.– Uncomment the line by removing the pound sign (#) character at the beginning of the line.

• If you are upgrading from Encryption Key Manager, use the SKLM_Silent_platform_Resp.xmlresponse file.

• Obtain the encrypted values of the passwords for following administrators of the source version: IBMSecurity Key Lifecycle Manager, WebSphere® Application Server, and database.

Also, create an encrypted password for the database administrator of the target version.

These passwords are used in the silent inline migration procedure.

To create the encrypted password, use the IBM Installation Manager utility. For more information, seeEncrypted password for response file elements.

• Ensure that the correct administrator password is specified in the response file.

Procedure

1. Open the sample response file in edit mode and update the following parameters:repository location

Specify the full path to the directory in which the installation package is located.

Note: If you enter an invalid value for this parameter, the installation program exits without anerror message. Also, the error is not logged.

The file has two instances of this parameter and both must be updated. Specify the values asshown here:

<repository location='myRepositoryLocation\im'/><repository location='myRepositoryLocation\'/>


where myRepositoryLocation is the full path to the installation package directory.

For example, if the installation package exists in the C:\SKLM40 directory, update this parameteras follows:

<repository location='/SKLM40/disk1/im'/><repository location='/SKLM40/disk1/'/>

user.DB2_ADMIN_PWD,com.ibm.sklm40.db2.platform.ofngSpecify the encrypted password for the database administrator of the target version.For example:

<data key='user.DB2_ADMIN_PWD,com.ibm.sklm40.db2.linux.ofng' value='QTh/0AiFacssjhs9gnOYkGA=='/>

user.CONFIRM_PASSWORD,com.ibm.sklm40.db2.platform.ofngSpecify the same password that you provided in theuser.DB2_ADMIN_PWD,com.ibm.sklm40.db2.platform.ofng parameter.For example:

<data key='user.CONFIRM_PASSWORD,com.ibm.sklm40.db2.linux.ofng' value='QTh/0AiFacssjhs9gnOYkGA=='/>

user.WAS_HOME,com.ibm.sklm40.platformSpecify the WAS_HOME directory path for WebSphere Application Server of the target version. Forthe definition of WAS_HOME, see “Definitions for HOME and other directory variables” on page 31.For example:

<data key='user.WAS_HOME,com.ibm.sklm40.linux' value='/opt/IBM/WebSphere/AppServer'/>

user.WAS_ADMIN_ID,com.ibm.sklm40.platformSpecify the user ID for the WebSphere Application Server administrator of the source version.For example:

<data key='user.WAS_ADMIN_ID,com.ibm.sklm40.linux' value='wasadmin'/>

user.WAS_ADMIN_PASSWORD,com.ibm.sklm40.platformSpecify the encrypted password for the WebSphere Application Server administrator of the sourceversion. This password is used for the target WebSphere Application Server administrator.For example:

<data key='user.WAS_ADMIN_PASSWORD,com.ibm.sklm40.linux' value='e9PjN93MeQxyzSs9VXJFMw=='/>

user.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.platformSpecify the same password that you provided in theuser.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.platform parameter.For example:

<data key='user.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.linux' value='e9PjN93MeQxyzSs9VXJFMw=='/>

user.SKLM_ADMIN_USER,com.ibm.sklm40.platformSpecify the user ID for the IBM Security Key Lifecycle Manager administrator of the source version.For example:

<data key='user.SKLM_ADMIN_USER,com.ibm.sklm40.linux' value='sklmadmin'/>


user.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.platformSpecify the encrypted password for the IBM Security Key Lifecycle Manager administrator of thesource version. This password applies to the IBM Security Key Lifecycle Manager administrator ofthe target version.For example:

<data key='user.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.linux' value='9YTRJMRIydDSdfhaHPs1mn=='/>

user.SKLM_ADMIN_CONF_PWD,com.ibm.sklm40.platformSpecify the same password that you provided in theuser.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.platform parameter.For example:

<data key='user.SKLM_ADMIN_CONF_PWD,com.ibm.sklm40.linux' value='9YTRJMRIydDSdfhaHPs1mn=='/>

user.TKLM_VERSION,com.ibm.sklm40.platformSpecify the source IBM Security Key Lifecycle Manager version.For example, if you are upgrading from version 3.0 on a server that is running on Linux, update thisparameter as follows:

<data key='user.TKLM_VERSION,com.ibm.sklm40.linux' value='3.0.0.0'/>

user.TKLM_TIP_HOME,com.ibm.sklm40.platformFor IBM Security Key Lifecycle Manager 2.5 and later, specify the WAS_HOME directory path for theWebSphere Application Server of the source version. For the definition of WAS_HOME, see“Definitions for HOME and other directory variables” on page 31.For example:

<data key='user.TKLM_TIP_HOME,com.ibm.sklm40.linux' value='/opt/IBM/WebSphere/AppServer'/>

user.TKLM_INSTALLED,com.ibm.sklm40.platformEnsure that the value is true, which indicates that an earlier version of IBM Security Key LifecycleManager is already installed on the server.For example:

<data key='user.TKLM_INSTALLED,com.ibm.sklm40.linux' value='true'/>

user.TKLM_DB_PWD,com.ibm.sklm40.platformSpecify the encrypted password for the database of the source version.For example:

<data key='user.TKLM_DB_PWD,com.ibm.sklm40.linux' value='SwIhGBTDHcJok80Ux4Sb3g=='/>

user.SKLM_APP_PORT,com.ibm.sklm40.platformSpecify the port number that the IBM Security Key Lifecycle Manager server of the target versionlistens on for HTTPS requests.For example:

<data key='user.SKLM_APP_PORT,com.ibm.sklm40.linux' value='8443'/>

user.WAS_ADMIN_PORT,com.ibm.sklm40.platformSpecify the port number that the WebSphere Application Server of the target version listens on forrequests.For example:

<data key='user.WAS_ADMIN_PORT,com.ibm.sklm40.linux' value='8083'/>


user.SKLM_APP_NS_PORT,com.ibm.sklm40.platformSpecify the port number that the IBM Security Key Lifecycle Manager server of the target versionlistens on for HTTP requests.For example:

<data key='user.SKLM_APP_NS_PORT,com.ibm.sklm40.linux' value='8080'/>

2. Only when upgrading from Encryption Key Manager with inline migration: Set the followingproperties in the response file.user.EKM_PROPFILE,@[email protected]

Specify the properties file name.For example:

<data key='user.EKM_PROPFILE,@[email protected]' value='/opt/IBM/KeyManagerConfig.properties'/>

user.EKM_MIGRATION,@[email protected] false to indicate that data is to be migrated inline.For example:

<data key='user.EKM_MIGRATION,@[email protected]' value='false'/>

3. Save the response file and close it.4. Check whether the Db2 JAR file db2jcc.jar exists in the installation directory. If not, copy the file

from the installation package into the installation directory.

For example, copy the file from disk1/im/jre_7.0.9040.20160504_1613/jre/lib/extinto /opt/IBM/InstallationManager/eclipse/jre_7.0.9040.20160504_1613/jre/lib/ext.

5. Open command line and run the silent installation command as follows:

./silent_install.sh myResponseFile -acceptLicense

Where, myResponseFile is the response file that you want to use. For example,SKLM_Silent_Linux_30_Resp.xml.

By specifying the -acceptLicense parameter, you agree to and accept the license terms for thisproduct.

6. Verify that the installation was successful by reviewing the log files. You can view the IBM InstallationManager logs at the following locations.Windows

drive:\<IM_DATA_DIR>\logs\native.

For example, C:\ProgramData\IBM\Installation Manager\logs\native.

drive:\<IM_DATA_DIR>\logs\sklmLogs\.

For example, C:\ProgramData\IBM\Installation Manager\logs\sklmLogs\.

Linux/<IM_DATA_DIR>/logs/native.

For example, /var/ibm/installationmanager/logs/native.

/<IM_DATA_DIR>/logs/sklmLogs/.

For example, /var/ibm/InstallationManager/logs/sklmLogs/.

For the definition of <IM_DATA_DIR>, see “Definitions for HOME and other directory variables” onpage 31.


What to do nextDepending on the version that you are upgrading from, go to the next step from the topic:

• Upgrading Encryption Key Manager• Upgrading IBM Tivoli Key Lifecycle Manager• Upgrading IBM Security Key Lifecycle Manager















Supported? Notes






2.6 Fix pack 2

2.5** Fix pack 3



(→ V2.7 → V4.0)*



Fix pack 6


Fix pack 7








Before you begin














Where,


Manager.





• Obtain the encrypted values of the passwords for following administrators of the source version: IBMSecurity Key Lifecycle Manager, WebSphere Application Server, and database.





Procedure





































































Authentication process for REST servicesBefore you access IBM Security Key Lifecycle Manager REST services, authenticate to the IBM SecurityKey Lifecycle Manager server by using your user name and password.

You can use a REST client to access the IBM Security Key Lifecycle Manager REST services. To access aREST service, you must complete the following process:

1. Log in to the IBM Security Key Lifecycle Manager server with your login credentials. You can use “LoginREST Service” on page 27 to access the server. The “Login REST Service” on page 27 accepts username and password and returns a unique user authentication identifier.

2. Access the IBM Security Key Lifecycle Manager REST services that provide the required serverfunctions. To access an IBM Security Key Lifecycle Manager REST service, pass the userauthentication identifier that you obtained in Step 1 along with the request message.

3. Log out of the IBM Security Key Lifecycle Manager server by using “Logout REST Service” on page 56.To log out, you must pass the user authentication identifier that you obtained in Step 1.

Login REST ServiceUse Login REST Service to log in to the IBM Security Key Lifecycle Manager server with valid usercredentials. The REST service validates the credentials and returns a unique user authentication identifierfor all subsequent service requests.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/login

By default, IBM Security Key Lifecycle Manager server listens to non-secure port 9080 (HTTP) and secureport 9443 (HTTPS) for communication. During IBM Security Key Lifecycle Manager installation, you canmodify these default ports. If you are using the default port for HTTP or HTTPS, the port is an optionalpart of the URL.

Request

Request Parameters

Parameter Description

host Specify the IP address or host name of the IBM Security Key LifecycleManager server.

port Specify the port number on which the IBM Security Key LifecycleManager server listens for requests.

Request headers

Header name Value

Content-Type application/json


Request headers (continued)

Header name Value

Accept application/json

Request body

JSON Object with the following specification:


userid Specify the user ID to access the IBM Security Key Lifecycle Managerserver.

password Specify the password that is associated with the user ID.

Response

Response headers

Header name Value and description

Status Code 200 OKThe request was successful. The response body contains therequested representation.

400 Bad RequestThe authentication information was not provided in the correctformat.

401 UnauthorizedThe authentication credentials were missing or incorrect.

500 Internal Server ErrorThe processing of the request fails because of an unexpectedcondition on the server.


Success response body

JSON object with the following specification:

JSON property name Description

userAuthId Returns a unique identifier for the authenticated user.

Error Response Body

JSON object with the following specification.


code Returns the application error code.

message Returns a message that describes the error.

ExamplesService request for user authentication

POST https://localhost:<port>/SKLM/rest/v1/ckms/loginContent-Type: application/json


Accept : application/json{"userid" : "admin1", "password" : "pswd"}

Success response

Status Code : 200 OK{"userAuthId" : "37ea1939-1374-4db7-84cd-14e399be2d20"}

Error response

Status Code : 401 Unauthorised{"code" : "CTGKM6001E", "message" : "Authentication Failure : Incorrect user ID/password combination"}

Installing IBM Security Key Lifecycle Manager in silent modeYou can install IBM Security Key Lifecycle Manager in silent installation mode. This installation method isuseful if you want identical installation configurations on multiple workstations. Silent installationrequires a response file that defines the installation configuration.

Before you begin

• Complete the planning tasks.• Download and extract the files for IBM Security Key Lifecycle Manager to a directory. These files are

available for download from the IBM Passport Advantage website.• Review the considerations and restrictions for installing and configuring IBM Security Key Lifecycle

Manager.• IBM Security Key Lifecycle Manager includes sample response files that you can use as a template for

creating your own response file. Modify the sample file for the specifics of your environment before itcan be used.




Note: You can change the installation locations (installLocation parameter in the response file) ofthe package groups. Ensure that the non-administrator or non-root user account has access to thelocations that you specify.

About this task

Before installation, you must also read and agree to the license terms for this product. To locate theresponse files and license term files, look in the root directory of the installation image files. The/license subdirectory has the license files in text format.

Installation fails unless you take these steps.

In the response file, make following changes to the line that specifies the license:

• Set the default value to true to indicate that you agree with the terms of the license.• Uncomment the line by removing the pound sign (#) character at the beginning of the line.

Procedure

1. Edit the repository location information and other details in the response file. The sample responsefiles are in the directory in which your installation package is located.


Note: If you enter an invalid value for the full_path_to_response_file parameter, such as anincomplete path, the installation program exits. No error message is displayed or logged.

You must update the response file with the correct repository location. The repository location is theplace where your installation package is located.

<repository location='<user repository location>\im'/><repositoryima location='<user repository location>\'/>

If you have extracted the installation package in C:\sklm40, update repository location in theSKLM_install_Win_Resp.xml response file as shown in the following example.

<repository location='<C:\sklm40\disk1\im'>\im'/><repository location='<C:\sklm40\disk1\'/>

2. To add the encrypted passwords to the relevant elements of the response file, use the IBM InstallationManager utility to create encrypted passwords.

For information about how to encrypt the password, see Encrypted password for response fileelements.

3. Open a command prompt and run the silent installation command.Windows

Go to the <installation package directory>\disk1 directory and run the followingcommand.

silent_install.bat SKLM_Silent_Win_Resp.xml --acceptLicense

LinuxGo to the <installation package directory>/disk1 directory and run the followingcommand.

silent_install.sh SKLM_Silent_Linux_Resp.xml --acceptLicense

4. Verify that the installation was successful by reviewing the log files. You can view the InstallationManager logs at the following locations.Windows










What to do nextBefore you use IBM Security Key Lifecycle Manager, run the postinstallation tasks that are described in“Postinstallation tasks” on page 50.


Definitions for HOME and other directory variablesYou can customize the HOME directory for your specific implementation. Substitute the definition of thedirectory variable appropriately.

The following table contains default definitions that are used in this information to represent the HOMEdirectory level for various product installation paths.

Table 5. HOME and other directory variables

Directory variable Default definition Description

DB_HOME Windows systemsdrive:\Program Files\IBM\DB2SKLMV40

AIX and Linux systems/opt/IBM/DB2SKLMV40

The directory that contains the Db2application for IBM Security KeyLifecycle Manager.

DB_INSTANCE_HOME Windowsdrive\db2adminID

For example, if the value of drive isC: and the default Db2administrator is sklmdb40,DB_INSTANCE_HOME isC:\SKLMDB40.

Linux and AIX®/home/db2adminID

The directory that contains the Db2database instance for IBM SecurityKey Lifecycle Manager.

WAS_HOME Windowsdrive:\Program Files\IBM\WebSphere\AppServer

Linux and AIXpath/IBM/WebSphere/AppServer

For example: /opt/IBM/WebSphere/AppServer

The WebSphere Application Serverhome directory.

SKLM_HOME WindowsWAS_HOME\products\sklm

Linux and AIXWAS_HOME/products/sklm

The IBM Security Key LifecycleManager home directory.

SKLM_INSTALL_HOME Windowsdrive:\Program Files\IBM\SKLMV40

Linux and AIXpath/IBM/SKLMV40

The directory that contains the IBMSecurity Key Lifecycle Managerlicense and migration files.


Table 5. HOME and other directory variables (continued)

Directory variable Default definition Description

SKLM_DATA WindowsWAS_HOME\products\sklm\dataC:\Program Files\IBM\WebSphere\AppServer\products\sklm\data

Linux and AIXWAS_HOME\products\sklm/data/opt/IBM/WebSphere/AppServer/products/sklm/data

The directory that contains the filesthat are exported from IBMSecurity Key Lifecycle Managersuch as backup files, exportedcertificates, and device groupexport files. Also, you must savethe files that you want to importinto IBM Security Key LifecycleManager in this directory.

IM_INSTALL_DIR Windowsdrive:\Program Files\IBM\Installation Manager

Linux and UNIX/opt/ibm/InstallationManager

The directory where IBMInstallation Manager is installed.

IM_DATA_DIR Windowsdrive:\ProgramData\IBM\Installation Manager

Linux and UNIX/var/ibm/InstallationManager

The data directory, which is used tostore information about productsthat are installed with InstallationManager.

Note: ProgramData\ is a hiddenfolder, and to see it you mustmodify your view preferences inExplorer to show hidden files andfolders.

Overview of device group export and importWhen multiple IBM Security Key Lifecycle Manager instances are maintained across operating systems,you might need to move device group data from one instance to another according to your businessrequirements. You can use the device group export and import operations to export and import dataacross IBM Security Key Lifecycle Manager instances with the same version as of the source IBM SecurityKey Lifecycle Manager instance, on the same or different operating systems, while maintaining dataintegrity. The exported device group data is encrypted and protected through a password.

Device groups for all the default device types are created during installation of IBM Security Key LifecycleManager. When you add a device type by using the graphical user interface, command-line interface, orREST interface, the corresponding device group is created in the database. Name of the device group issame as the device type that you created.

Device group export

You can export device group by using the IBM Security Key Lifecycle Manager graphical user interface orREST interface. The export device group operation creates a compressed archive with the extension .expin a location that you specify. Except for the manifest and summary.json files, all the following files ofthe archive are encrypted by the password that was specified during device group export operation.

• Manifest file, which lists all the device group data files in the archive


• summary.json, which contains summary information for the device group• Files specific to devices• Files specific to keys• Files specific to certificates

Device group import

You can import device group data to an IBM Security Key Lifecycle Manager instance from an encryptedarchive that was exported from another IBM Security Key Lifecycle Manager instance. During devicegroup import operation, you must specify the password that was used for device group export operationto import and decrypt data. Use the IBM Security Key Lifecycle Manager graphical user interface or RESTinterface to import device group.

Note: You must restart the server after you run the device group import operation.

Device group import conflicts

At times, the device group data that is imported might conflict with an existing data in the database. Forexample, a key in the imported device group might be a duplicate key of a device group in the currentinstance of IBM Security Key Lifecycle Manager where the data is being imported. When conflicts occur,they must be resolved before the import process can continue.

The device group import operation includes the following tasks:

• Saving export file in the target IBM Security Key Lifecycle Manager server where the device group isbeing imported. You must have the same encryption password that was used for creating the export fileto extract and decrypt data

• Evaluating duplicates between the data that is imported and the data in the target server• Resolving the conflicts• Importing device group data to the target server

You can view the list of conflicting items, if any, during device group import operation. Then, you canexport the conflict information to a file in comma-separated values (CSV) format for further analysis.






II. Migrate data from the existing version to the target version.There are two methods of data migration:


Inline migrationWhen the host system of the target version is the same as the existing version, use inlinemigration of data.







Supported? Notes






2.6 Fix pack 2

2.5** Fix pack 3



(→ V2.7 → V4.0)*



Fix pack 6


Fix pack 7










Before you begin












Where,


Manager.











Procedure



















user.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.platformSpecify the same password that you provided in theuser.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.platform parameter.


For example:
















user.SKLM_APP_PORT,com.ibm.sklm40.platformSpecify the port number that the IBM Security Key Lifecycle Manager server of the target versionlistens on for HTTPS requests.


For example:































Viewing the configuration status of all master serversYou can view the list of IBM Security Key Lifecycle Manager master servers and their health status in theMulti-Master cluster to help you to identify problems, if any, in the masters. You can also view the Db2HADR configuration status of the primary and standby masters.

About this task

In a Multi-Master cluster, regularly monitoring the health status of IBM Security Key Lifecycle Managerinstances are essential to quickly identify and correct the problems. You can check to see whether all thecommunication ports are active and reachable on each master server in your Multi-Master deployment.

Use the IBM Security Key Lifecycle Manager Multi-Master page or Get All Masters Status RESTService to view the list of servers and their status.

You can also view the list of masters and status information on the IBM Security Key Lifecycle Managerwelcome page.

Procedure

1. Go to the appropriate page or directory.Graphical user interface

a. Log on to the graphical user interface.b. On the Welcome page, click Administration > Multi-master.

REST interfaceOpen a REST client.

2. View the list of servers and their status information to identity problems, if any.Graphical user interface

Db2 HADR configuration status is displayed on the IBM Security Key Lifecycle Manager Multi-Master page.

a. Click the Masters tab to view the list of master servers and their configuration status.b. Click the HADR Databases tab to view the list of master servers that are configured with Db2

HADR and their configuration status.


REST interface

a. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle ManagerREST services. For more information about the authentication process, see “Authenticationprocess for REST services” on page 27.

b. To run Get All Masters Status REST Service, send the HTTP POST request. Pass theuser authentication identifier that you obtained in Step a along with the request message asshown in the following example.

GET https://localhost:<port>/SKLM/rest/v1/ckms/nodes/allNodeStatusContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en

For more information, see Get All Masters Status REST Service.

What to do nextUse the status information in the table to investigate problems, if any, and to take the necessary actions.

Adding a master server to a clusterIn IBM Security Key Lifecycle Manager, high-availability solution is implemented by using Multi-Mastercluster configuration. Adding a master server to a cluster is part of setting up a Multi-Master environment.

Before you beginComplete the following tasks:

• Review the considerations and restrictions that are listed in the Requirements and considerations forMulti-Master configuration topic.

• Before you add a non-HADR master to the Multi-Master cluster, ensure that at least one standby masteris added in the cluster. For more information, see “Adding a standby master server to a cluster” on page67.

About this task

When you create a Multi-Master cluster, the server from which you add a master server or standby serverto the cluster becomes the primary master. After the cluster is created with a minimum of one primaryand standby master servers each, you can add master servers to the cluster from any of the masterservers. Your role must have the permission to add master server to the Multi-Master cluster.

You cannot add a master server to the cluster by using the Multi-Master Configuration - Add Masterpage when a standby or master server in the cluster is out of network or not reachable. To add a masterserver in this scenario, you must use the Add Master REST Service with additional parameters. Formore information, see “REST service for adding a master when other master in the cluster is notreachable” on page 69.

Procedure


a. Log in to the graphical user interface.b. On the Welcome page, click Administration > Multi-Master > Masters > Add Master.


2. Add a master to the cluster.


Graphical user interface

a. Click the Basic Properties tab.b. On the Basic Properties dialog, specify information for the master that you are adding.

Host name / IP address Specify the host name of the IBM Security KeyLifecycle Manager instance that is added tothe cluster.

IBM Security Key Lifecycle Manager username

Specify the name of the IBM Security KeyLifecycle Manager administrator. Theadministrator name is displayed by default.

IBM Security Key Lifecycle Managerpassword

Specify the password for the IBM Security KeyLifecycle Manager server administrator.

WebSphere Application Server user name Specify the WebSphere Application Serverlogin user ID for the IBM Security KeyLifecycle Manager server administratorprofile. The WebSphere Application Serverlogin ID is displayed by default.

WebSphere Application Server password Specify the password for the WebSphereApplication Server login user ID.

UI port Specify the HTTPS port to access IBMSecurity Key Lifecycle Manager graphical userinterface and REST services. The port numberis displayed by default.

c. If you want the primary master to automatically accept the certificate of the master that youare adding, select Accept host certificate automatically. Otherwise, manually add thecertificate to the truststore of the primary master. For instructions, see “Adding a certificate tothe truststore” on page 73.

Note: By default, the certificate is not automatically accepted.d. Click Check Prerequisites. The master server performs some checks. For example,

communication between the standby master server that you are adding and the current primarymaster is successful, user login credentials are valid, and so on.

e. Click Add.

REST interface


b. Run “Check Prerequisites REST Service” on page 64 to ensure that the master server that youwant to add meets all requirements and conditions that are defined for a Multi-Masterconfiguration.

c. Run the Add Master REST Service. For example:

POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/addNodes[{"clusterName" : "multimaster","primaryHadrPort" : "60020"},{"type" : "Node","ipHostname": "cimkc2b151","httpPort": "9443","sklmUsername": "sklmadmin","sklmPassword": "SKLM@admin123","wasUsername": "wasadmin","wasPassword": "WAS@admin123",


"autoAccept": "Yes"}]

What to do next

The primary master restarts, and is temporarily unavailable during this process after you add a master tothe cluster. Verify whether the master with its health status information is listed in the Masters table, andalso on the IBM Security Key Lifecycle Manager welcome page.

Migrating data from an earlier version of IBM Security Key Lifecycle ManagerYou can use the cross-platform backup utility of IBM Security Key Lifecycle Manager V4.0 (target) tomigrate data from its earlier version.

Note: For greater security, change the IBM Security Key Lifecycle Manager User password soon after thedata migration process.

Configuring replicationIBM Security Key Lifecycle Manager replication ensures availability of the key materials, configurationfiles, and other data on a server by having at least one copy or replica of the data on another server. Eachserver is available for data recovery when the other one fails. In replication, IBM Security Key LifecycleManager creates a backup of the data and copies it to the other server as per the configured schedule.

Master server is the primary system that is being backed up and replicated to one or more secondaryservers, called clone servers. You must configure IBM Security Key Lifecycle Manager on the master andclone servers to schedule replication. New keys are created only on the master server. Clone servers canserve keys.

The following data in the master server is replicated to the clone server:

• IBM Security Key Lifecycle Manager database tables• Truststore and keystore with the master key• IBM Security Key Lifecycle Manager configuration files

Replication configurationTo schedule replication, you need to configure IBM Security Key Lifecycle Manager on the master andclone servers. You can configure one master and up to 20 clone servers. Cloning of the IBM Security KeyLifecycle Manager environment on the master server to the clone servers is independent of theiroperating systems and directory structure.

Types of replication

You can configure automatic replication in two ways:Full replication

Creates full backup of the data on the master server and then replicates the data to the clone servers.By default, full replication runs every 24 hours (daily). It is triggered only when new cryptographicobjects are added to or modified on the master server.

For detailed instructions, see “Enabling and configuring full replication” on page 43.

Incremental replicationReplicates data from the master to the clone server incrementally with the delta changes. If you havefrequent updates to the cryptographic objects in a master server, use incremental replication so thatthe clone servers always have almost up-to-date data. By default, incremental replication runs every60 seconds (1 minute). You can configure this frequency based on your requirement. You must


configure full replication before you can configure incremental replication. You can configureincremental replication when you configure full replication as well.

For detailed instructions, see “Enabling and configuring incremental replication” on page 43.

You can use the graphical user interface, command-line interface, or REST interface to configure full andincremental replication.

Automated backup configuration

To schedule automatic backups, you need to configure IBM Security Key Lifecycle Manager on the masterserver only. For instructions, see “Scheduling automatic backups” on page 74.

Replicating large amount of data

You can configure IBM Security Key Lifecycle Manager to replicate large amount of data. Before youbegin, ensure that the master and clone servers are identical. The operating system, directory structures,and Db2 admin user must be the same on the master and clone servers. For more information, see“Backing up large amount of data” on page 58.

Backup protection

IBM Security Key Lifecycle Manager creates a cryptographic key to encrypt the backup files. Dependingon the encryption method that is selected in configuration, when the automatic backup or replicationoperation runs, the cryptographic key is encrypted by a password or by the master key in HSM.

For more information about the encryption methods for backup and replication, see “Backup encryptionmethods for replication activities” on page 76.

Enabling and configuring full replicationYou must configure the master and clone servers to replicate IBM Security Key Lifecycle Manager datafrom the master server to the clone servers.

About this taskYou can use the graphical user interface, REST APIs, or command-line interface to configure fullreplication. You need to configure settings on both, the master and clone servers.

Procedure

• Using graphical user interface

See “Enabling and configuring full replication by using the graphical user interface” on page 77.• Using REST interface

See “Enabling and configuring full replication by using REST APIs” on page 78.• Using CLI commands

See “Enabling and configuring full replication by using command-line interface” on page 80.

ResultsReplication is now set up and it checks for new cryptographic objects after every 24 hours. You canchange this interval and set up a specific time. You can also use the “Replication Now REST Service” onpage 83 to run replication immediately.

Enabling and configuring incremental replicationYou can incrementally replicate the IBM Security Key Lifecycle Manager critical data from the masterserver to the clone servers. With incremental replication, the master server updates the clone servers


with the delta changes frequently. You can use the graphical user interface, REST APIs, or command-lineinterface to enable and schedule incremental replication.

Before you beginEnsure that full replication is already configured on the master server. For more information, see“Enabling and configuring full replication” on page 43.

About this task

Incremental replication needs to be configured on the master server. No configuration is required on theclone server.

Procedure

• Using graphical user interfacea) Log in to the graphical user interface.b) Click Administration > Replication.c) Ensure that Master role is selected.d) Click the Advanced Properties tab.e) In the Replication Scheduler Section, select the Incremental replication frequency check box.f) Optional: Specify the frequency (in seconds) at which you want the incremental replication

operation to run.By default, the incremental replication operation runs every 60 seconds, which is one minute.

g) Click Start Replication Server.h) Click OK.

• Using REST APIsa) Open a REST client.b) Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST

services. For more information about the authentication process, see “Authentication process forREST services” on page 27.

c) Run “Update Replication Config Property REST Service” on page 86 to enable incrementalreplication.For example:

PUT https://localhost:<port>/SKLM/rest/v1/replicationConfigProperties{"replication.Incremental.Enable": "true"}

d) Optional: To modify the default frequency (60 seconds) of the incremental replication, run “UpdateReplication Config Property REST Service” on page 86 and provide the frequency (in seconds) atwhich you want the incremental replication operation to run.For example:

PUT https://localhost:<port>/SKLM/rest/v1/replicationConfigProperties{"replication.Incremental.CheckFrequency": "120"}

e) Start Replication server.Run “Replication Start REST Service” on page 88.

• Using command-line interfacea) Go to the WAS_HOME/bin directory.

For example:Windows

cd drive:\Program Files\IBM\WebSphere\AppServer\bin


Linuxcd /opt/IBM/WebSphere/AppServer/bin

b) Start the wsadmin interface by using SKLMAdmin user credentials.For example:Windows


Linux


c) Run the “tklmReplicationConfigUpdateEntry” on page 91 command to enable incrementalreplication.For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.Incremental.Enable -value true]')

d) Optional: To modify the default frequency (60 seconds) of incremental replication, run the“tklmReplicationConfigUpdateEntry” on page 91 command and provide the frequency (inseconds) at which you want the incremental replication operation to run.For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.Incremental.CheckFrequency -value 120]')

e) Start Replication server.Run “tklmReplicationStart” on page 91.

ResultsIncremental replication is enabled and configured. You can immediately run the operation by clickingReplicate Now. Otherwise, the operation runs based on the value given in the Incremental replicationfrequency field. The operation runs until you disable it.

Configuring backup and restoreIBM Security Key Lifecycle Manager provides a set of operations to back up and restore current, activefiles and data.

IBM Security Key Lifecycle Manager creates cross-platform backup files in a manner that is independentof operating systems and directory structure of the server. You can restore the backup files to anoperating system that is different from the one it was backed up from. For example, you can restore abackup file that is taken on a Linux system and restore it on a Windows system.

You can use the cross-platform backup utility to run backup operation on earlier versions of IBM SecurityKey Lifecycle Manager and IBM Tivoli Key Lifecycle Manager to back up critical data. You can restorethese backup files on current version of IBM Security Key Lifecycle Manager across operating systems.

Note: In IBM Security Key Lifecycle Manager, Version 3.0 and later, the Solaris operating system is notsupported. If you are using IBM Security Key Lifecycle Manager on Solaris systems, use the cross-platform backup utility to back up the data. You can then run the restore operation to restore data on aIBM Security Key Lifecycle Manager, Version 3.0 or later system that is deployed on any of the supportedoperating systems, such as Windows, Linux, or AIX.

Backed up files include the following data:

• Data in the IBM Security Key Lifecycle Manager database tables• Truststore and keystore with the master key


• IBM Security Key Lifecycle Manager configuration files

Your role must have permissions to back up or to restore files.

Failure to back up your critical data properly might result in unrecoverableloss of all access to your encrypted data. Do not encrypt your backup file, orstore a backup file on an encrypting device. Failure to back up data might also result in alater inconsistency of the key manager and potential data loss on the storage device.

The IBM Security Key Lifecycle Manager backup and restore operations support the use of AES 256-bitkey length for data encryption/decryption to conform to the PCI DSS (Payment Card Industry DataSecurity Standard) standards for increased data security.

Encryption methods to back up IBM Security Key Lifecycle Manager data

IBM Security Key Lifecycle Manager supports the following encryption methods for backups:Password-based encryption

During the backup process, a password is specified to encrypt the backup key, and you must specifythe same encryption password to decrypt and restore the backup files.

HSM-based encryptionYou can configure IBM Security Key Lifecycle Manager to use Hardware Security Module (HSM) forstoring the master encryption key. During the backup process, the backup key is encrypted by themaster key, which is stored in HSM. During the restore process, the master key in HSM decrypts thebackup key. Then, the backup key is used to restore backup contents.

High-performance backup and restore

High-performance backup and restore provide backup and restoration of large amounts of encryptionkeys. You can configure IBM Security Key Lifecycle Manager for high-performance backup and restoreoperations by setting the following parameter in the SKLMConfig.properties configuration file.

enableHighScaleBackup=true

When IBM Security Key Lifecycle Manager is configured for high-performance backup and restore, IBMDB2 native backup technology is used to run the backup and restore operation for more efficiency.However, with this configuration, you can restore the backup only in an identical operating environment.The operating system, middleware components, and directory structures must be identical on bothsystems.

You cannot create a cross-platform compatible backup file if IBM Security Key Lifecycle Manager isconfigured for high-performance backup and restore activities. For information about how to back uplarge amount of data, see “Backing up large amount of data” on page 58.

Configuring a Multi-Master clusterYou can implement high availability of real-time data by configuring IBM Security Key Lifecycle Managerservers in a Multi-Master cluster.

You can use IBM Security Key Lifecycle Manager Multi-Master configuration for data transmission toachieve the following objectives:

• Ensure consistent and continuous data availability of IBM Security Key Lifecycle Manager across theorganization.

• Avoid a single point of failure.• Ensure data availability across servers that are located in several physical sites, that is, distributed

across the network.


Overview

All IBM Security Key Lifecycle Manager servers in the Multi-Master cluster are called master servers. Eachserver points to a single data source (primary database). The server that hosts the primary database iscalled the primary master server. The other master servers are called as standby master servers, and thedatabases on these servers are the standby databases.

You can configure a Multi-Master cluster by using the graphical user interface (GUI) or REST APIs. Formore information, see “Setting up a Multi-Master cluster” on page 47.

Db2 high availability disaster recovery (HADR) is used as the underlying feature that ensures dataredundancy. HADR configuration is managed internally by IBM Security Key Lifecycle Manager. HADRprotects against data loss by transmitting data changes from the primary database to the standbydatabases. Db2 HADR supports multiple standby databases in a Multi-Master setup.

Key features of a Multi-Master configuration

• Keys that are created on a master server are accessible to other master servers in the cluster.• IPP devices and KMIP clients that are registered on a master server can access keys on another master

server in the cluster.

Related information

Setting up a Multi-Master clusterYou can use the IBM Security Key Lifecycle Manager graphical user interface or REST services to set up aMulti-Master cluster.

Before you beginReview values of the following Multi-Master cluster configuration properties, and if required, modifythem:

• takeoverRetryTimeInterval• takeoverRetryFrequency

Procedure

1. Review the Multi-Master deployment architecture and requirements for configuring a cluster. and“Requirements and considerations for Multi-Master configuration” on page 63.

2. Configure the cluster with the first master server with Primary Db2 database (Primary master server).See “Adding a master server to a cluster” on page 40.

3. Add a master server with standby Db2 database (Principal standby master server) to the cluster. See“Adding a standby master server to a cluster” on page 67.

4. (Optional) Add one or two master servers with standby Db2 database (Auxiliary standby masterservers) to the cluster. See “Adding a master server to a cluster” on page 40.

5. (Optional) Add non-HADR master servers to the cluster. See “Adding a master server to a cluster” onpage 40.

6. Review the Multi-Master cluster configuration and ensure that the cluster is healthy. See “Viewing theconfiguration status of all master servers” on page 39.

What to do nextYou can create or use an application or utility to consume the notification events that the Notificationservice generates. For example, a utility to trigger email notifications.


https://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.1.0/com.ibm.db2.luw.admin.ha.doc/doc/c0011267.html

Multi-Master configuration REST servicesYou can use multi-master REST services to configure IBM Security Key Lifecycle Manager master serversfor multi-master replication.

For more information about IBM Security Key Lifecycle Manager multi-master configuration, see“Configuring a Multi-Master cluster” on page 46.

Installation images and fix packsObtain IBM Security Key Lifecycle Manager installation files from the IBM Passport Advantage® websiteand fix packs from Fix Central. You can also obtain the files by another means, such as a DVD as providedby your IBM sales representative.

The Passport Advantage website provides packages, referred to as eAssemblies, for various IBM productsat http://www-01.ibm.com/software/passportadvantage/pao_customer.html.

You can use Fix Central to find the fixes that are provided by IBM Support for various products, includingIBM Security Key Lifecycle Manager at https://www-945.ibm.com/support/fixcentral. With Fix Central,you can search, select, order, and download fixes for your system with a choice of delivery options. A IBMSecurity Key Lifecycle Manager product fix might be available to resolve your problem.

Installation guidelinesFor a successful installation, ensure that you understand and follow the rules and guidelines to installIBM Security Key Lifecycle Manager.

• On a Linux or AIX operating system, ensure that Bash shell (bash) and C shell (sch) are installed. Also,ensure that bash is the default shell.

• On a Linux operating system, ensure that SELinux is disabled and umask is set to 022.• Installation can take more than an hour.• Do not install from a network drive or mounted drive.• Ensure that you select the correct language at prompts during installation. Correcting a locale error

requires uninstalling and reinstalling IBM Security Key Lifecycle Manager and Db2.• When you install IBM Security Key Lifecycle Manager, the Db2 password that you specify must comply

with the password policy of the underlying operating system.• If you are using an existing user as Db2 Administrator, ensure that the password is correctly specified.• When you install IBM Security Key Lifecycle Manager on Linux, certain Db2 configuration changes made

during installation might require that you restart the system. Close any other applications before yourestart the system. After the system restarts, run the installation program again.

• Ensure that the host name of the system is set correctly.• Entries for all fields are restricted to alphabetical characters (A-Z and a-z), numeric characters (0-9),

and , and the underscore character (_). Additionally, the password fields allow selected specialcharacters. For more information, see Supported special characters in passwords.

The restriction also applies to the values in the response file that is used for silent installation.• Ensure that the installation path does not contain Unicode characters.• Ensure that there are no non-ASCII characters in the installation path.• When you install IBM Security Key Lifecycle Manager, retain the default path for Shared Resources

Directory. IBM Installation Manager uses this location to download artifacts and to store informationabout the installed packages.

• Do not install IBM Security Key Lifecycle Manager on systems with hardened operating system.


http://www-01.ibm.com/software/passportadvantage/pao_customer.html

https://www-945.ibm.com/support/fixcentral

https://www.ibm.com/support/pages/supported-special-characters-ibm-security-key-lifecycle-manager-passwords

In a hardened system, you might have restricted access to the specific directories, or you might not be apart of the administrator group. On Windows, you might not have access to certain directories in thesystem even if you are part of the administrator group. To install IBM Security Key Lifecycle Manager,you must have access to all the installation directories with Read, Write, and Execute permissions.

Encrypted password for response file elementsYou must add the encrypted passwords to the relevant elements of the response file. Use the IBMInstallation Manager utility to create an encrypted password.

You must add the encrypted passwords to the relevant elements of the response file. Use the IBMInstallation Manager utility to create an encrypted password.Windows

For example, if you extract the IBM Security Key Lifecycle Manager product image to the C:\SKLM\disk1 directory, run the following command to create an encrypted password.

cd C:\SKLM\disk1\im\toolsimcl.exe encryptString password

Add the encrypted password that you created in the response file as shown in the following example.

<data key='user.DB2_ADMIN_PWD,com.ibm.sklm40.db2.win.ofng'value='<encrypted password>'/><data key='user.CONFIRM_PASSWORD,com.ibm.sklm40.db2.win.ofng'value='<encrypted password>'/>...<data key='user.WAS_ADMIN_PASSWORD,com.ibm.sklm40.win'value='<encrypted password>'/><data key='user.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.win'value='<encrypted password>'/>...<data key='user.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.win'value='<encrypted password>'/><data key='user.SKLM_ADMIN_CONF_PWD,com.ibm.sklm40.win'value='<encrypted password>'/>

LinuxFor example, if you extract the IBM Security Key Lifecycle Manager product image to the /SKLM/disk1 directory, run the following command to create an encrypted password.

cd /SKLM/disk1/im/tools./imcl encryptString password

Add the encrypted password that you created in the response file as shown in the following example.

<data key='user.DB2_ADMIN_PWD,com.ibm.sklm40.db2.lin.ofng'value='<encrypted password>'/><data key='user.CONFIRM_PASSWORD,com.ibm.sklm40.db2.lin.ofng'value='<encrypted password>'/>...<data key='user.WAS_ADMIN_PASSWORD,com.ibm.sklm40.linux'value='<encrypted password>'/><data key='user.WAS_ADMIN_CONF_PWD,com.ibm.sklm40.linux'value='<encrypted password>'/>...<data key='user.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.linux' value='<encrypted password>'/><data key='user.SKLM_ADMIN_CONF_PWD,com.ibm.sklm40.linux'value='<encrypted password>'/>

You can create a different encrypted password for each user.


Postinstallation tasksComplete the following postinstallation tasks in the given order to verify the installation and to ensurethat the product is functional.














Supported? Notes






2.6 Fix pack 2

2.5** Fix pack 3


Table 8. Supported upgrade paths and migration methods (continued)


Supported? Notes




(→ V2.7 → V4.0)*



Fix pack 6


Fix pack 7








Before you begin














Where,


Manager.










Procedure
























user.SKLM_ADMIN_PASSWORD,com.ibm.sklm40.platformSpecify the encrypted password for the IBM Security Key Lifecycle Manager administrator of thesource version. This password applies to the IBM Security Key Lifecycle Manager administrator ofthe target version.


For example:












































Logout REST ServiceUse Logout REST Service to stop the user session and log out of the IBM Security Key LifecycleManager server. The server automatically logs out the user after 15 minutes of inactivity.

OperationDELETE

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/logout


Request

Request Parameters




Request headers

Header name Value



Request body



userAuthId Specify the user authentication identifier that you must use to log outfrom the IBM Security Key Lifecycle Manager server.

Response


Response headers










userId Returns the user identifier.

logout Indicates whether the user is logged out of the server. Valid values aretrue or false.

Error Response Body





ExamplesService request for user logout

DELETE https://localhost:<port>/SKLM/v1/ckms/logoutContent-Type: application/jsonAccept : application/json{"userAuthId" : "37ea1939-1374-4db7-84cd-14e399be2d20"}

Success response

Status Code : 200 OK{"userid" : "admin","logout" : "true”}

Error response

Status Code : 400 Bad Request{"code" : ""CTGKM6002E"", "message" : "Invalid Request: Invalid user authentication ID or invalid request format"}


Backing up large amount of dataYou can configure IBM Security Key Lifecycle Manager to backup and replicate to back up or replicatelarge number of encryption keys. The enableHighScaleBackup property in theSKLMConfig.properties configuration file is used.

About this task

You can use the Backup and Restore page to back up data. Alternatively, you can use thetklmBackupRun command or Backup Run REST Service. Your role must have the permission toback up files.

Note:

• You cannot create a cross-platform compatible backup file if IBM Security Key Lifecycle Manager isconfigured for high performance backup and restore activities. You can use the backup file to restoredata in an identical operating environment. The operating system, middleware components, anddirectory structures must be identical on both systems.

• The db2restore.log file is created during restore process only when IBM Security Key LifecycleManager is configured for high performance backup and restore operations.

Procedure

1. Set the enableHighScaleBackup=true property in the <SKLM_HOME>/config/SKLMConfig.properties file.Command-line interface


cd drive:\Program Files (x86)\IBM\WebSphere\AppServer\binLinux


Windows


Linux


c. Run the tklmConfigUpdateEntry command to set enableHighScaleBackup property inthe SKLMConfig.properties configuration file.

print AdminTask.tklmConfigUpdateEntry ('[-name enableHighScaleBackup -value true]')

REST interface

a. Open a REST client.b. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager

REST services. For more information about the authentication process, see “Authenticationprocess for REST services” on page 27.

c. Run Update Config Property REST Service to set enableHighScaleBackup propertyin the SKLMConfig.properties configuration file. Pass the user authentication identifier thatyou obtained in Step b along with the request message as shown in the following example.

PUT https://localhost:<port>/SKLM/rest/v1/configPropertiesContent-Type: application/jsonAccept : application/json


Authorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en{ "enableHighScaleBackup" : "true"}

2. Go to the appropriate page or directory for backing up data.Graphical user interface

a. Log in to the graphical user interface.b. On the Welcome page, click Administration > Backup and Restore.

Command-line interface

a. Go to the <WAS_HOME>/bin directory.b. Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin.


3. Create a backup file. Only one backup or restore task can run at a time.Graphical user interface

a. On the Backup and Restore table, the Backup repository location field displays the default<SKLM_DATA> directory path, where the backup file is saved, for example, C:\ProgramFiles\IBM\WebSphere\AppServer\products\sklm\data. For the definition of<SKLM_DATA>, see “Definitions for HOME and other directory variables” on page 31. ClickBrowse to specify a backup repository location under <SKLM_DATA> directory.

Directory path in the Backup repository location field changes based on the value that you setfor the tklm.backup.dir property in the SKLMConfig.properties file.

b. Click Create Backup.c. On the Create Backup page, specify information such as a value for the encryption password

and backup description. A read-only backup file location is displayed in the Backup locationfield. Ensure that you retain the encryption password for future use in case you restore thebackup.

Note: If HSM-based encryption is used for the backups, you need not specify the password.d. Click Create Backup.

Command-line interface

Type tklmBackupRun and specify the needed values to create a backup file as shown in thefollowing example.

print AdminTask.tklmBackupRun ('[-password myBackupPwd]')

REST interfaceRun Backup Run REST Service by sending the HTTP POST request as shown in the followingexample.

POST https://localhost:<port>/SKLM/rest/v1/ckms/backupsContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en{"backupDirectory":"/sklmbackup1","password":"myBackupPwd"}

4. A message is displayed to indicate that the backup file was created, or that the backup operationsucceeded.

The time stamp on a backup file has a Greenwich Mean Time (GMT) offset represented in RFC 822format. The file name contains a +hhmm or -hhmm element to specify a timezone ahead of or behindGMT. For example, a file name might be sklm_v3.0.1.0_20170123144220-0800_backup.jar,where -0800 indicates that the timezone is eight hours behind GMT.


Note: Backup success messages are system wide. Two administrators might run backup tasks thatoverlap in time. During this interval, the administrator who starts a second task that fails might see afalse success message from the first backup task.

What to do next

Retain the encryption password for future use in case you restore the backup. Review the directory thatcontains the backup files to ensure that the backup file exists. Do not edit a file in the backup JAR file. Thefile that you attempt to edit becomes unreadable.

Preinstallation tasksBefore you install IBM Security Key Lifecycle Manager, understand the prerequisites and plan yourenvironment accordingly.

Complete the following prerequisite tasks:

• Ensure that the system meets the minimum hardware and software requirements. For moreinformation, see IBM Security Key Lifecycle Manager Support Matrix.

• Use the preinstallation worksheets for planning.• Determine the IBM Security Key Lifecycle Manager topology.• Decide the installation mode you want to use to install IBM Security Key Lifecycle Manager: graphical

mode or silent mode.

Get All Masters Status REST ServiceUse Get All Masters Status REST Service to obtain status information that indicates whether allthe communication ports in the master servers are reachable.

OperationGET

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/nodes/allNodeStatus


Request

Request Parameters




Request Headers

Header name Value




https://www.ibm.com/support/pages/ibm-security-key-lifecycle-manager-support-matrix

Request Headers (continued)

Header name Value

Authorization SKLMAuth userAuthId=<authIdValue>

Accept-Language Any valid locale that is supported by IBM Security Key LifecycleManager. For example: en or de

Response

Response Headers





404 Not Found ErrorThe processing of the request fails.



Content-Language Locale for the response message.


JSON array that contains JSON objects with the following specification:


nodeType Returns the master type, such as PRIMARY, STANDBY, or LOCAL.

nodeIP Returns the IP address of the master.

ippPortStatus Returns the status code that indicates whether the IBM ProprietaryProtocol (IPP) port is reachable.

kmipPortStatus Returns the status code that indicates whether the Key ManagementInteroperability Protocol (KMIP) port is reachable.

agentPortStatus Returns the status code that indicates whether the agent port in themaster is reachable.

sslPortStatus Returns the status code that indicates whether the SSL port is reachable.

adminPortStatus Returns the status code that indicates whether the WebSphereApplication Server port for the IBM Security Key Lifecycle Managerprofile is reachable.

dbPortStatus Returns the status code that indicates whether the DB2 service listeningport is reachable.




(continued)


httpPortStatus Returns the status code that indicates whether the HTTPS port isreachable.

actingPrimary Returns whether the master is promoted as a primary master.

lastUpdateTimeStamp Returns the time stamp that the master status was last updated.

Error Response Body





ExamplesService request to get status of all the masters in the cluster

GET https://localhost:<port>/SKLM/rest/v1/ckms/nodes/allNodeStatusContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en

Success response

Status Code : 200 OKContent-Language: en[ { "nodeType":"STANDBY", "nodeIP":"cimkc2a177", "ippPortStatus":0, "kmipPortStatus":0, "agentPortStatus":0, "sslPortStatus":0, "adminPortStatus":0, "dbPortStatus":0, "httpPortStatus":0, "actingPrimary":false, "lastUpdateTimeStamp":"2017-07-21 13:32:40.536" }, { "nodeType":"PRIMARY", "nodeIP":"cimkc2a176", "ippPortStatus":0, "kmipPortStatus":0, "agentPortStatus":0, "sslPortStatus":0, "adminPortStatus":0, "dbPortStatus":0, "httpPortStatus":0, "actingPrimary":true, "lastUpdateTimeStamp":"2017-07-21 13:06:36.752" }]

Error response

Status Code : 400 Bad RequestContent-Language: en


{"code" : "CTGKM6002E", "message" : "CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format."}

Requirements and considerations for Multi-Master configurationBefore you set up IBM Security Key Lifecycle Manager Multi-Master environment, review therequirements and considerations to ensure a successful configuration.

Operating system and database requirements

• Ensure that the master servers with primary and standby Db2 HADR database host systems have thesame operating system version and fix pack levels. The non-HADR master servers can have a differentoperating system.

• IBM Security Key Lifecycle Manager Multi-Master architecture is based on Db2 High Availability DisasterRecovery (HADR) technology to implement high-availability solution. Therefore, all the Db2 HADRconfiguration rules and guidelines are applicable for IBM Security Key Lifecycle Manager Multi-Masterconfiguration.

• Db2 user name and password must be same on all the master servers of the IBM Security Key LifecycleManager Multi-Master cluster.

Port requirements

• Ensure that the agent port (60015) and HADR port (60027) that are used for Multi-Master configurationare not blocked by the firewall.

Default agent port is 60015, which you can update through UI. Default HADR port is 60027, which isassigned during the Multi-Master setup. It is configurable.

• Ensure that the KMIP, SSL, TCP, and agent ports are not blocked for communication before you set upIBM Security Key Lifecycle Manager masters for Multi-Master configuration.

• A TCP/IP interface must be available between primary and standby Db2 HADR database host systemswith a dedicated, high speed, and high capacity network bandwidth.

Other requirements and considerations

• If you want to add an existing IBM Security Key Lifecycle Manager server to the cluster, use the devicegroup export and import feature. For more information, see “Adding an existing IBM Security KeyLifecycle Manager instance with data to the Multi-Master cluster” on page 95.

• The IBM Security Key Lifecycle Manager server that you want to add to a Multi-Master cluster must notcontain any data. Adding of server with data results in loss of data that was previously created.

• For IBM Security Key Lifecycle Manager Multi-Master deployment, the cluster must contain a minimumof one primary master server and one standby master server. When you set up a Multi-Master cluster,the server from which you add a master server or standby master server to the cluster becomes theprimary master server. You must add at least one standby master server to the cluster before you addother master servers.

• Server certificate must be created in the IBM Security Key Lifecycle Manager server before you add it tothe cluster as the primary master.

• IBM Security Key Lifecycle Manager Multi-Master cluster supports up to three standby master servers.When you add a standby master server to the cluster, the priority index value must be in the range of1-3.

• After the Multi-Master cluster is configured, you must avoid running manual backup and restoreoperations on any of the master servers in the cluster.

• Run the IBM Security Key Lifecycle Manager Multi-Master configuration operations only from theprimary master server of the cluster to avoid any problems.


• Before you add a server that runs the Linux operating system, to a cluster, the permissions for the /tmpdirectory must be set to 777 that is full execute, read, and write permissions.

• If you want to configure the Multi-Master cluster to use HSM to store the master key, you mustconfigure all the master servers in the cluster to use the same HSM.

• Before you add a master server to the cluster through the migrated system, modify the IBM SecurityKey Lifecycle Manager administrator user name and the password in the following situations:

1. When users and groups are migrated from previous version to version 4.0 through cross-migrationprocess.

2. IBM Security Key Lifecycle Manager administrator user name and the password are different thanthat of the credentials specified during version 4.0 installation.

• You cannot remove a standby master server from the Multi-Master cluster if a standby server is down.• Ensure that the master servers are not configured to back up large amount of data. So in theSKLMConfig.properties configuration file on every master server, ensure that theenableHighScaleBackup property does not exist or is set to false.

• If you plan to integrate LDAP with the Multi-Master setup for user authentication, you must configureLDAP on all master servers before configuring the Multi-Master cluster. Ensure that all the masterservers use the same LDAP, and have the same users as IBM Security Key Lifecycle ManagerAdministrator.

Best practice: If you plan to use IBM Security Key Lifecycle Manager REST services to connect to theIBM Security Key Lifecycle Manager server for key management operations, integrate with LDAP foruser authentication and management.

• The MMConfig.properties file contains the Multi-Master configuration properties.

Note: Do not update the configuration file manually.

Check Prerequisites REST ServiceUse Check Prerequisites REST Service to verify whether the master server that you want to addto the cluster meets all requirements and conditions that are defined for IBM Security Key LifecycleManager multi-master configuration.

You can use Check Prerequisites REST Service to check whether the following conditions aremet:

• DB2 and operating system levels are the same as that of the primary master.• Database name and password are same on both the systems.• Ports of the master server that you want to add are valid and accessible.• The system has permission to read-write-execute on the /tmp folder.• IBM Security Key Lifecycle Manager master server is freshly installed.• Remote agent is accessible.• The specified IBM Security Key Lifecycle Manager user credentials are valid.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/nodes/checkPreRequisite


Request


Request Parameters




Request Headers

Header name Value





Request body


Property name Description

ipHostname Specify the IP address or host name of the IBM Security Key LifecycleManager server master server that you are adding.

clusterName Specify the name for the multi-master cluster to which the master to beadded.

sklmUsername Specify the name of the IBM Security Key Lifecycle Manager serveradministrator.

sklmPassword Specify the password for the IBM Security Key Lifecycle Manager serveradministrator.

wasUsername Specify the WebSphere Application Server login user ID for the IBMSecurity Key Lifecycle Manager server administrator profile.

wasPassword Specify the password for the WebSphere Application Server login userID.

sklmUIPort Specify the port number on which the IBM Security Key LifecycleManager server listens for requests from devices that communicate byusing the SSL protocol.

standbyHadrPort Specify the HADR port of the standby server.

autoaccept Specify whether the cluster must automatically accept the certificate ofthe master server that is being added.

This property has two values: true, false.

The default value is false to indicate that the cluster does notautomatically accept the certificate of the master server that is beingadded.


Request body


(continued)


hadrType Specify the role of the master server.

Possible values are: Standby, Node

Use Node to indicate a non-HADR master server.

Response

Response Headers












code Returns the code that is specified by the status property.

status Returns the status to indicate whether the configuration of masters in thecluster you specify was successful.

Error Response Body






ExamplesService request to check whether the master server meets all the configuration conditions

POST https://localhost:<port>/SKLM/rest/v1/ckms/nodes/checkPreRequisiteContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en{ "ipHostname" : "civ4cez199", "clusterName" : "multimaster", "sklmUsername" : "sklmadmin", "sklmPassword" : "SKLM@admin123", "wasUsername" : "wasadmin", "wasPassword" : "WAS@admin123", "sklmUIPort" : "9443", "standbyHadrPort" : "60020"}

Success response

Status Code: 200 OK{"code":"0","status":"CTGKM3002I civ4cez199 met all the pre requisites and can be added into the cluster."}

Error response

{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format."}

Adding a standby master server to a clusterIn IBM Security Key Lifecycle Manager, high-availability solution is implemented by using Multi-Mastercluster configuration. IBM Security Key Lifecycle Manager Multi-Master cluster must contain a primarymaster server and a standby master server. Add a standby master server to the cluster for setting up aMulti-Master environment.

Before you beginBefore you add a standby master server to the cluster, review the considerations and restrictions that arelisted in the Requirements and considerations for Multi-Master configuration topic.

About this task

To provide continuous data availability to all the IBM Security Key Lifecycle Manager instances in a Multi-Master cluster, Db2 high-availability disaster recovery (HADR) configuration is used. Db2 HADR is adatabase replication feature that provides a high-availability solution. HADR protects against data loss byreplicating data changes from a source database, called primary, to a target database, called the standby.Db2 HADR supports up to three standby databases in your Multi-Master setup.

When you create an IBM Security Key Lifecycle Manager Multi-Master cluster, the server from which youadd a master or standby to the cluster becomes the primary master. Once the cluster is created with aminimum of one primary master and standby master, you can then add masters to the cluster from any ofthe masters in the cluster. Use the Multi-Master Configuration - Add Master dialog or Add MasterREST Service to add a master to the cluster. Your role must have a permission to add standby masterto the IBM Security Key Lifecycle Manager Multi-Master cluster.

You cannot add a standby master to the cluster by using the Multi-Master Configuration - Add Masterpage when a standby or master server in the cluster is out of network or not reachable. To add a standbymaster in this scenario, you must use Add Master REST Service with additional parameters. Formore information about the REST service, see “REST service for adding a master when other master in thecluster is not reachable” on page 69.


Procedure


a. Log in to the graphical user interface.b. On the Welcome page, click Administration > Multi-Master > Masters > Add Master.


2. Add a standby master server to the cluster.Graphical user interface

a. Click the Basic Properties tab.b. On the Basic Properties dialog, specify information for the standby master that you are adding.

Host name / IP adress Specify the host name of the IBM Security Key Lifecycle Managerstandby master that is added to the cluster.

IBM Security KeyLifecycle Manager username

Specify the name of the IBM Security Key Lifecycle Manageradministrator. The administrator name is displayed by default.

IBM Security KeyLifecycle Managerpassword

Specify the password for the IBM Security Key Lifecycle Managerserver administrator.

WebSphere ApplicationServer user name

Specify the WebSphere Application Server login user ID for theIBM Security Key Lifecycle Manager server administrator profile.The WebSphere Application Server login ID is displayed bydefault.

WebSphere ApplicationServer password

Specify the password for the WebSphere Application Serverlogin user ID.

UI port Specify the HTTPS port to access IBM Security Key LifecycleManager graphical user interface and REST services. The portnumber is displayed by default.

c. Click the Advanced Properties tab.d. On the Advanced Properties dialog, specify information for the standby master that you are

adding.

Do you want to set thismaster as standbydatabase?

Select Yes to add the current instance of IBM Security KeyLifecycle Manager as a standby master to the cluster.

HADR port Specify the port number for the standby HADR database tocommunicate with the primary HADR database.

Standby priority index Specify the priority index value for the standby database totakeover when the primary database is down. You can set thepriority index to any value in the range 1-3. The standby serverwith a higher priority index level (lower number) takesprecedence over the lower-priority databases.

e. If you want the primary master to automatically accept the certificate of the master that youare adding, select Accept host certificate automatically. Otherwise, manually add thecertificate to the truststore of the primary master. For instructions, see “Adding a certificate tothe truststore” on page 73.

Note: By default, the certificate is not automatically accepted.


f. Click Check Prerequisites. The master server performs some checks. For example,communication between the standby master server that you are adding and the current primarymaster is successful, user login credentials are valid, and so on.

g. Click Add.

REST interface


b. Run “Check Prerequisites REST Service” on page 64 to ensure that the master server that youwant to add meets all requirements and conditions that are defined for IBM Security KeyLifecycle Manager Multi-Master configuration.

c. Run Add Master REST Service. For example:

POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/addNodes[{"clusterName" : "multimaster","hadrPort" : "60020"},{"type" : "Standby","ipHostname" : "cimkc2b151","httpPort" : "9443","sklmUsername" : "sklmadmin","sklmPassword" : "SKLM@admin123","wasUsername" : "wasadmin","wasPassword" : "WAS@admin123","standbyPriorityIndex" : "1","autoAccept" : "Yes"}]

What to do next

The primary master server restarts, and is temporarily unavailable during this process after you add astandby master server to the cluster. Verify that the standby master server is listed in the Masters table,and also on the IBM Security Key Lifecycle Manager Welcome page.

REST service for adding a master when other master in the cluster is notreachable

To add a standby or master server to the cluster when a standby or master server in the cluster is out ofnetwork or not reachable, use the Add Master REST Service with additional parameters,ignoreStandbys and ignoreNodes.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/config/nodes/addNodes


Request


Request Parameters




Request Headers

Header name Value





Request body



clusterName Specify a name for the multi-master cluster to which the masters to beadded.

primaryHadrPort Specify the port number for the HADR primary database. You mustspecify the value for this property for the first time only when stand-alone IBM Security Key Lifecycle Manager server instance is configuredas "Primary" along with "Standby" or "Node".

type Specify the IBM Security Key Lifecycle Manager server instance type. Forexample, Primary, Standby, or Node.

ipHostname Specify the host name of the IBM Security Key Lifecycle Manager serverserver.

standbyPriorityIndex Specify the priority index value for the standby database to takeoverwhen the primary database is down. You can set the priority index to anyvalue in the range 1-3. The standby server with a higher priority indexlevel (lower number) takes precedence over the lower-prioritydatabases.

httpPort Specify the port number on which the IBM Security Key LifecycleManager server server listens for requests from devices thatcommunicate by using the SSL protocol.

sklmUsername Specify the name of the IBM Security Key Lifecycle Manager serveradministrator.

sklmPassword Specify the password for the IBM Security Key Lifecycle Manager serveradministrator.

wasUsername Specify the WebSphere Application Server login user ID for the IBMSecurity Key Lifecycle Manager server administrator profile.

wasPassword Specify the password for the WebSphere Application Server login userID.


Request body


(continued)


ignoreStandbys Specify the host name of standby server that is not reachable.

ignoreNodes Specify the host name of master server that is not reachable.

autoAccept Specify whether the cluster automatically accepts the certificate of themaster server that is being added. This property has two values: Yes, No.The default value is No, which indicates that the cluster does notautomatically accept the certificate of the master server that is beingadded.

Response

Response Headers












code Returns the code that is specified by the status property.

status Returns the status to indicate whether the master is added to the multi-master cluster.

Error Response Body





Error Response Body


(continued)



ExamplesService request to add master to the cluster when a master or standby server is not reachable

Example for adding a standby.

POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/addNodesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en[{"clusterName" : "multimaster","primaryHadrPort" : "60027""ignoreStandbys" : "cimkc2b151","ignoreNodes" : "cimkc2b152"},{"type" : "Standby","ipHostname" : "cimkc2b150","httpPort" : "9443","sklmUsername" : "sklmadmin","sklmPassword" : "SKLM@admin123","wasUsername" : "wasadmin","wasPassword" : "WAS@admin123","standbyPriorityIndex" : "2","autoAccept" : "Yes"}]

Example for adding a master.

POST https://localhost:<port>/SKLM/rest/v1/ckms/config/nodes/addNodesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en[{"clusterName" : "multimaster""ignoreStandbys" : "cimkc2b151","ignoreNodes" : "cimkc2b152"},{"type" : "Node","ipHostname" : "cimkc2b153","httpPort" : "9443","sklmUsername" : "sklmadmin","sklmPassword" : "SKLM@admin123","wasUsername" : "wasadmin","wasPassword" : "WAS@admin123","autoAccept" : "Yes"}]

Success response

Status Code: 200 OK{"code":"0","status":"CTGKM3002I Successfully added the master in Multi-Master cluster."}


Error response

{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format."}

Adding a certificate to the truststoreYou might add a certificate from a certificate file that is in DER or base64 format to the IBM Security KeyLifecycle Manager internal truststore. The certificate is used for communication between IBM SecurityKey Lifecycle Manager and the device that identifies itself by using this certificate or the root certificatefor this certificate.

About this task

You can use the Add Certificate dialog, tklmTrustStoreCertAdd command, or TruststoreCertificate Add REST Service to add a certificate to the IBM Security Key Lifecycle Managertruststore. Your user ID must have the klmSecurityOfficer role.

Procedure

1. Go to the appropriate page or directory.


a. Log on to the graphical user interface.b. Click IBM Security Key Lifecycle Manager > Configuration > Truststore.c. On the Truststore page, click Add.





Windows


Linux


• REST interface

– Open a REST client.2. Add a certificate from a certificate file that is in DER or base64 format to the truststore.


a. In the Certificate alias field, specify alias name for the certificate.b. Click Browse to specify the certificate file location under <SKLM_DATA> directory, for example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data. For the definitionof <SKLM_DATA>, see “Definitions for HOME and other directory variables” on page 31.

c. Select the certificate file format such as DER or base64.d. Click Add Certificatre.



Type tklmTrustStoreCertAdd to add a certificate file to the truststore. For example, to add acertificate file in DER format, run the following command.

print AdminTask.tklmTrustStoreCertAdd ('[-fileName d:\\mypath\\mycertfilename.der -format DER -alias myCertAlias]')

• REST interface

Use Truststore Certificate Add REST Service to add a certificate. For example, you cansend the following HTTP request.

PUT https://localhost:<port>/SKLM/rest/v2/trustStoreCertificates/addCertToTrustStoreContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"certFile":"C:\\Program Files\\IBM\\WebSphere\\AppServer\\products\\sklm\\data\\clientsslcert.cer","certFormat":"DER","certAlias":"myCert"}

Scheduling automatic backupsUse the Replication page to automatically backup the IBM Security Key Lifecycle Manager critical data atregular intervals.

About this task

You can use the graphical user interface, REST services, or CLI commands to configure automaticbackups by using password-based encryption.

Procedure

• Using graphical user interfacea) Log on to the graphical user interface.b) Click IBM Security Key Lifecycle Manager > Administration > Replication.c) Select Master.d) Select a replication server management option.

Start Replication ServerClick Start Replication Server to start the replication server for backing up IBM Security KeyLifecycle Manager data based on a configured schedule.

Stop Replication ServerClick Stop Replication Server to stop the replication server so that the IBM Security KeyLifecycle Manager data is not backed up.

Replicate NowClick Replicate Now to immediately run the IBM Security Key Lifecycle Manager replicationtask, and to force a backup file creation.

e) Configure the settings.Basic Properties

Certificate from keystore Select a certificate from the list. Ensure that SSL/TLS certificateexists on the master and all clone systems that you configurefor replication.

Replication backupencryption passphrase

Encryption password for the backup file to ensure data security.You need the same password to decrypt and restore the file.

Note: If HSM-based encryption is used for the backups, youneed not specify the password.


Confirm replication backupencryption passphrase

Specify the same password again to verify the password thatyou specified.

Master listen port Port number for communication when unserialized or delayedreplications take place. Default master listen port is 1111.

Advanced Properties

Replication backupdestination directory

Location to store the backup files. The Replication backupdestination directory field displays the default <SKLM_DATA>directory path, where the backup file is saved, for example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data. For the definition of <SKLM_DATA>,see “Definitions for HOME and other directory variables” onpage 31. Click Browse to specify a backup repository locationunder <SKLM_DATA> directory.

Maximum number ofreplication files to keepbefore rollover

Maximum number of replication files that you want to keep. Thevalue must be a positive integer between 2 - 10. When thenumber of files exceed the specified limit, the oldest file isdeleted.

Replication frequency (inhours)

Frequency to check whether the backup operation is necessary.Default value is set to 1 hour. This parameter is ignored if thevalue for Daily Start Replication Time is set.

Daily replication time (inHH:MM format)

Time in HH:MM format to run the replication task every day.

Replication log file name Name and location for the replication log file. Default value forthis parameter is <WAS_HOME>\products\sklm\logs\replication.

Maximum log file size (inKB)

Maximum size of a log file before rollover occurs. Default valueis 1000 KB (kilobytes). When the file reaches the maximumsize, a new log file is created.

Maximum number of logfiles to keep

Maximum number of log files that you want to keep. By default,IBM Security Key Lifecycle Manager keeps the last 3 log files.When the number of files exceed the specified limit, the oldestfile is deleted.

f) Click OK.• Using REST services

a) Open a REST client.b) Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST


c) To run Get Single Config Property REST Service, send the HTTP GET request. Pass theuser authentication identifier that you obtained in Step a along with the request message asshown in the following example.Service request

GET https://localhost:<port>/SKLM/rest/v1/configProperties/replication.roleContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language: en


Success response

Status Code : 200 OKContent-Language: en{"replication.role" : "none"}

d) Specify the changes. For example, you can use Update Replication Config Property RESTService to send the following service request to change the value of the replication.roleproperty.

PUT https://localhost:<port>/SKLM/rest/v1/configPropertiesContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth authId=139aeh34567mAccept-Language: en{ "replication.role": "master"}

• Using CLI commandsa) Go to the WAS_HOME/bin directory.

For example,Windows


cd /opt/IBM/WebSphere/AppServer/binb) Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin.

For example:Windows


Linux


c) Type the tklmReplicationConfigGetEntry command on one line to get the current value ofthe target property in the ReplicationSKLMConfig.properties file.For example, type:

wsadmin>print AdminTask.tklmReplicationConfigGetEntry ('[-name replication.role]')

An example response might be:

none

d) Specify the changes. For example, to change the value of the replication.role property tomaster, type on one line.

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.role -value master]')

Backup encryption methods for replication activitiesIBM Security Key Lifecycle Manager supports password-based encryption and HSM-based encryption forbackups and replication activities.

Password-based encryption

When you run the IBM Security Key Lifecycle Manager automated replication program on the masterserver, you must specify a password to encrypt the backup key. This backup key is used to encrypt


backup contents. The encrypted backup data, the backup key, and the password are replicated on theclone server that you configured for replication. The clone server uses the replicated password to decryptand restore the backup files.

HSM-based encryption

When you run the automated replication on the master server, data is backed up and encrypted by abackup key. If Hardware Security Module (HSM) is configured with IBM Security Key Lifecycle Manager,master key in HSM encrypts the backup key. When data is replicated on the clone server with HSMconfigured, the master key, which is stored in HSM, decrypts the backup key. Then, the backup key isused to restore backup contents.

Consider the following guidelines for using HSM-based encryption.

• Same HSM partition must be present with all its key entries intact on all the clone servers.• Master key that you used for the backup key encryption must be intact to replicate the backup file on

the clone server. If the master key is refreshed, all the older backups are inaccessible or unusable.• You must connect to the same HSM and the master key for automated replication irrespective of

whether you use HSM-based encryption or password-based encryption.

HSM-based encryption is the default method for the backups and replication when HSM is configured tostore the master key. You can also use the password-based encryption when HSM is configured by settingthe following property in the SKLMConfig.properties file.

enablePBEInHSM=true

Note:

• If HSM is not configured, you can only use password-based encryption for the backups and replication.• If the value for enablePBEInHSM is not set or set to any other value than true, the value is assumed

as false.• You can replicate and restore a backup file that is created by using either password-based or HSM-

based encryption irrespective of the value set for enablePBEInHSM.

Replication configuration

Enabling and configuring full replication by using the graphical userinterface

To enable replication, you need to configure settings on both master and clone servers.

Before you beginEnsure that the master and clone servers have a secure communication:

1. Create SSL certificate on the master server. If an SSL server certificate already exists, you can skip thisstep.

2. Export the private key of the SSL certificate. Run “Key Export REST Service” on page 95. For example:

PUT https://master_server_host:port/SKLM/rest/v1/keys/export{"alias":"SKLMSSLCertificate","fileName":"c:/SKLMSSLCertificate","type":"privatekey", "password":"password"}

3. Copy the exported private key file of the master server to the SKLM_DATA folder of the clone server.


4. Import the private key file of the master server. Run “Key Import REST Service” on page 99. Forexample,

POST https://clone_server_host:port/SKLM/rest/v1/keys/import{"alias":"SKLMSSLCertificate","fileName":"c:/Program Files/Websphere/AppServer/products/sklm/data/SKLMSSLCertificate","type":"privatekey","usage":"SSLSERVER", "password":"password"}

Procedure

On the master server1. Log in to the graphical user interface on the master server.2. Configure replication.

a) Click Administration > Replication.b) Select the Master role.c) In the Basic Properties tab, select the SSL server certificate.d) If you are configuring replication by using password-based encryption, enter the passphrase for the

backups that will be created during replication.e) Change the master listener port value.

By default, 1111 is provided.f) To configure a clone server, click Add Clone, enter the IP address or host name, and port number

of the clone server.g) Optional: Repeat the earlier step for every clone server that you want to configure.h) Click OK.

The configuration is saved.i) Click Start Replication Server.

Replication is now configured on the master server.On the clone server3. Log in to the graphical user interface on the clone server.4. Configure replication.

a) Click Administration > Replication.b) Select the Clone role.c) Optional: Modify the default configuration parameters.

For more information, see “Modifying replication configuration for a clone server” on page 104.d) Click Start Replication Server.e) Click OK.

Replication is now configured on the clone server.

Repeat these steps for every clone server that you want to configure.

ResultsReplication is now configured on the master and clone servers. Data is replicated based on the configuredschedule.

Enabling and configuring full replication by using REST APIsTo enable replication, you need to configure settings on both master and clone servers.




2. Export the private key of the SSL certificate. Run “Key Export REST Service” on page 95. For example:

PUT https://master_server_host:port/SKLM/rest/v1/keys/export{"alias":"SKLMSSLCertificate","fileName":"c:/SKLMSSLCertificate","type":"privatekey", "password":"password"}

3. Copy the exported private key file of the master server to the SKLM_DATA folder of the clone server.4. Import the private key file of the master server. Run “Key Import REST Service” on page 99. For

example,

POST https://clone_server_host:port/SKLM/rest/v1/keys/import{"alias":"SKLMSSLCertificate","fileName":"c:/Program Files/Websphere/AppServer/products/sklm/data/SKLMSSLCertificate","type":"privatekey","usage":"SSLSERVER", "password":"password"}

Procedure

1. Open a REST client.(Configure replication on the master server)2. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST APIs

on the master server. For more information about the authentication process, see “Authenticationprocess for REST services” on page 27.

3. Run “Update Replication Config Property REST Service” on page 86 on the master server and specifyvalues for the following mandatory properties:

• Set role to master.• Specify the server certificate that you created• Provide at least one clone server and port number.• Define a master listen port and specify a password.

Note: You need not specify the password when IBM Security Key Lifecycle Manager is configured touse Hardware Security Module (HSM) for storing the master encryption key. For information aboutencryption methods to back up data for replication activities, see Backup encryption methods forreplication activities.

For details about all the available replication configuration parameters, see Replication configurationparameters.

A sample request:

PUT https://master_server_host:port/SKLM/rest/v1/configProperties{ "replication.role": "master", "backup.EncryptionPassword": "mypassword","backup.TLSCertAlias":"sklmSSLCertificate", "backup.ClientIP1": "myhostname","backup.ClientPort1": "2222", "replication.MasterListenPort": "1111" , "backup.CheckFrequency":"60","backup.DailyStartReplicationBackupTime"="23:00"}

Note: You can configure incremental replication, if required. The sample request must include theadditional parameter to enable incremental replication. For example:

PUT https://master_server_host:port/SKLM/rest/v1/configProperties{ "replication.role": "master", "backup.EncryptionPassword": "mypassword","backup.TLSCertAlias":"sklmSSLCertificate", "backup.ClientIP1": "myhostname","backup.ClientPort1": "2222", "replication.MasterListenPort": "1111","backup.CheckFrequency":"60","backup.DailyStartReplicationBackupTime"="23:00","replication.Incremental.Enable"="true"

The replication configuration file ReplicationSKLMConfig.properties is created on the masterserver in the same directory as the IBM Security Key Lifecycle Manager properties file. For example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config\ReplicationSKLMConfig.properties.

4. Start Replication server.


https://www-03preprod.ibm.com/support/knowledgecenter/SSWPVP_4.0.0/com.ibm.sklm.doc/overview/cpt/cpt_ic_oview_tech_replication_hsm.html?view=kc


https://www-03preprod.ibm.com/support/knowledgecenter/SSWPVP_4.0.0/com.ibm.sklm.doc/reference/ref/ref_ic_cfgparams_replication.html?view=kc


Run “Replication Start REST Service” on page 88.5. Optional: To run replication immediately, run “Replication Now REST Service” on page 83.

Replication is now configured on the master server.(Configure replication on the clone server)6. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST

services on the clone server.For more information about the authentication process, see “Authentication process for RESTservices” on page 27.

7. Run “Update Replication Config Property REST Service” on page 86 on the clone server and specifyvalues for the following mandatory properties:

• Set role to clone.• Specify the server certificate that you created• Define a master listen port.• Define a restore listen port. The port must be the same port number that is coded in the

corresponding backup.ClientPort parameter on the master server

For details of all the available replication configuration parameters, see Replication configurationparameters.

A sample request:

PUT https://localhost:port/SKLM/rest/v1/configProperties{ "replication.role": "clone", "backup.TLSCertAlias":"sklmSSLCertificate", "restore.ListenPort": "2222", "replication.MasterListenPort": "1111" }

The replication configuration file ReplicationSKLMConfig.properties is created on the cloneserver in the same directory as the IBM Security Key Lifecycle Manager properties file. For example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config\ReplicationSKLMConfig.properties.

8. Start Replication server on the clone server.Run “Replication Start REST Service” on page 88.




Enabling and configuring full replication by using command-line interfaceTo enable replication, you need to configure settings on both master and clone servers.



2. Export the private key of the SSL certificate. Run “tklmKeyExport” on page 106. For example:

print AdminTask.tklmKeyExport ('[-alias SKLMSSLCertificate -fileName C:/SKLMSSLCertificate-type privatekey -password mypassword]')

3. Copy the exported private key file of the master server to the SKLM_DATA folder of the clone server.




4. Import the private key file of the master server. Run “tklmKeyImport” on page 107. For example,

print AdminTask.tklmKeyImport ('[-alias SKLMSSLCertificate -fileName c:/Program Files/Websphere/AppServer/products/sklm/data/SKLMSSLCertificate -type privatekey -password mypassword] -usage SSLSERVER)

Procedure

(Configure replication on the master server)1. Go to the WAS_HOME/bin directory on the master server.

For example:Windows


cd /opt/IBM/WebSphere/AppServer/bin2. Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin.

For example:Windows


Linux


3. Run “tklmReplicationConfigUpdateEntry” on page 91 on the master server and specify values for thefollowing mandatory properties:

• Set role to master.• Specify the server certificate that you created• Provide at least one clone server and port number.• Define a master listen port and specify a password.

Note: You need not specify the password when IBM Security Key Lifecycle Manager is configured touse Hardware Security Module (HSM) for storing the master encryption key. For information aboutencryption methods to back up data for replication activities, see Backup encryption methods forreplication activities.

For details about all the available replication configuration parameters, see Replication configurationparameters.

For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.role -value master]''[backup.EncryptionPassword=mypassword]''[backup.TLSCertAlias=sklmSSLCertificate]''[backup.ClientIP1=myhostname]''[backup.ClientPort1=2222]''[replication.MasterListenPort=1111]''[backup.CheckFrequency=60]')

Note: You can configure incremental replication, if required. The sample request must include theadditional parameter to enable incremental replication. For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.role -value master]''[backup.EncryptionPassword=mypassword]''[backup.TLSCertAlias=sklmSSLCertificate]''[backup.ClientIP1=myhostname]''[backup.ClientPort1=2222]''[replication.MasterListenPort=1111]'






'[backup.CheckFrequency=60]''[replication.Incremental.Enable=true]')

The replication configuration file ReplicationSKLMConfig.properties is created on the masterserver in the same directory as the IBM Security Key Lifecycle Manager properties file. For example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config\ReplicationSKLMConfig.properties.

4. Start Replication server.Run “tklmReplicationStart” on page 91.

5. Optional: To run replication immediately, run “tklmReplicationNow” on page 110.

Replication is now configured on the master server.(Configure replication on the clone server)6. Go to the WAS_HOME/bin directory on the clone server.

For example:Windows


cd /opt/IBM/WebSphere/AppServer/bin7. Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin.

For example:Windows


Linux


8. Run “tklmReplicationConfigUpdateEntry” on page 91 on the clone server and specify values for thefollowing mandatory properties:

• Set role to clone.• Specify the server certificate that you created• Define a master listen port.• Define a restore listen port. The port must be the same port number that is coded in the

corresponding backup.ClientPort parameter on the master server

For details of all the available replication configuration parameters, see Replication configurationparameters.

For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.role -value clone]''[backup.EncryptionPassword=mypassword]''[backup.TLSCertAlias=sklmSSLCertificate]''[backup.ClientIP1=myhostname]''[backup.ClientPort1=2222]''[replication.MasterListenPort=1111]')

The replication configuration file ReplicationSKLMConfig.properties is created on the cloneserver in the same directory as the IBM Security Key Lifecycle Manager properties file. For example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\config\ReplicationSKLMConfig.properties.

9. Start Replication server on the clone server.Run “tklmReplicationStart” on page 91.







Replication Now REST ServiceUse Replication Now REST Service to immediately run the IBM Security Key Lifecycle Managerreplication task, and to force a backup to be sent to the configured clones.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/replicate/now


Request

Request Parameters




Request Headers

Header name Value





Request body



replicationTargetFromConfig

Conditional. If you specify the value yes, the values for thehostname and port are taken from the configuration file. Else, youmust specify the value for hostname and port.

hostname Conditional. Specify the host name or IP of replication target. If youspecify this parameter, the port parameter is required. The valueis ignored if the value of the replicationTargetFromConfigparameter is yes.


Request body


(continued)


port Conditional. Specify the port number to connect to the replicationclone system. If you specify this parameter, the hostnameparameter is required. The value is ignored if the value of thereplicationTargetFromConfig parameter is yes.

Note: If hostname and port are not specified in the request body, then all the clone servers that areconfigured with the master server are forced for data replication.

You can use Replication Now REST Service to force a replication only from the master server.

Response

Response Headers












code Returns the value that is specified by the message property.




(continued)


message Returns the status message that indicates whether the replication task isrun:CTGKM2200I

Replication has been successful for the hostlisted.

CTGKM2201W.Replication already in progress.

CTGKM2202EReplication has failed for the host listed.

CTGKM2203EReplication has failed for the host listed with aconnection error.

CTGKM2204EReplication has failed for the host listed with avalidation error.

CTGKM2212EReplication for the specified host timed out.

CTGKM2243EReplication can only be invoked on the mastermachine.

CTGKM2222ENo valid replication config file exists.

Error Response Body





ExamplesService request to run the replication task

POST https://localhost:<port>/SKLM/rest/v1/replicate/nowContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"hostname":"remotehost","port":"2222"}

Success response

Status Code : 200 OK[ { "code":"CTGKM2200I","message":" CTGKM2200I Replication successful for remotehost:2222” }]


Service request to run the replication task without specifying the port number

POST https://localhost:<port>/SKLM/rest/v1/replicate/nowContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"hostname":"remotehost"}

Error response

Status Code : 200 OK{"code":"CTGKM0631E","message":"CTGKM0631E Missing required parameter \" port \" ."}

Update Replication Config Property REST ServiceUse Update Replication Config Property REST Service to update one or more properties inthe ReplicationSKLMConfig.properties configuration file to control the replication operation.

OperationPUT

URLhttps://<host>:<port>/SKLM/rest/v1/replicationConfigProperties


Request

Request Parameters




Request Headers

Header name Value





Request body


<propertyNames> Specify the replication configuration property names and values thatyou want to update. You can specify multiple comma-separatedproperties.


Response

Response Headers












property Returns the name of the property that is updated.

status Returns the update status to indicate whether the configuration propertyis updated with an appropriate message.

Note: The success response code 200 OK is returned even if the property you requested is not found. Anappropriate message is returned in the response body.

Error Response Body





ExamplesService request to disable incremental replication

PUT https://localhost:<port>/SKLM/rest/v1/replicationConfigProperties{ "replication.Incremental.Enable":"false"}

Success response

Status Code : 200 OK[{"property":"replication.Incremental.Enable","status":"CTGKM0607I Update successful, change will take effect immediately"}]


Error response

Status Code : 400 Bad Request{"code" : "CTGKM6002E", "message" : "CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format"}

Service request to update the IP address

PUT https://localhost:<port>/SKLM/rest/v1/replicationConfigProperties{ "backup.ClientIP1":"9.118.40.184"}

Success response

Status Code : 200 OK[{"property":"backup.Client","status":"CTGKM0607I Update successful, server restart required for change to take effect"}]

Error response


Service request to update multiple configuration properties

PUT https://localhost:<port>/SKLM/rest/v1/replicationConfigPropertiesContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en {"backup.ClientIP1" : "9.118.40.184", "replication.role" : "master"}

Success response

Status Code : 200 OK[{"property":"backup.ClientIP1","status":"CTGKM0607I Update successful, server restart required for change to take effect"},{"property":"replication.role","status":"CTGKM0606I Update successful, change will take effect immediately"}]

Error response


Replication Start REST ServiceUse Replication Start REST Service to start the replication server for replicating the current IBMSecurity Key Lifecycle Manager active files on clone servers based on a configured schedule.

Note: IBM Security Key Lifecycle Manager data is replicated based on a configured schedule only whennew cryptographic objects are added to the master server.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/replicate/start


Request


Request Parameters




Request Headers

Header name Value





Response

Response Headers
















(continued)


message Returns the status message that indicates the success or failure of thereplication task:CTGKM2207W

IBM Security Key Lifecycle Manager replication taskis already up.

CTGKM2205IIBM Security Key Lifecycle Manager replication taskstarted successfully.

CTGKM2206EIBM Security Key Lifecycle Manager replication taskfailed to start.

Error Response Body





ExamplesService request to start the replication task

POST https://localhost:<port>/SKLM/rest/v1/replicate/startContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m

Success response

Status Code : 200 OK{"code": "CTGKM2205I","message": "CTGKM2205I IBM Security Key Lifecycle Manager replication task started successfully."}}

Service request to start the replication task without specifying the configuration file

POST https://localhost:<port>/SKLM/rest/v1/replicate/startContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m

Error response

Status Code : 200 OK{"code": "CTGKM2222E","message": "CTGKM2222E No valid replication config file exists."}


tklmReplicationConfigUpdateEntryUse the tklmReplicationConfigUpdateEntry command to change an existing entry or to add anentry in the IBM Security Key Lifecycle Manager replication configuration file.

Note: The IBM Security Key Lifecycle Manager command-line interface commands will be deprecated inthe later versions of IBM Security Key Lifecycle Manager. Use the REST interfaces instead.

PurposeUse the tklmReplicationConfigUpdateEntry command to change an existing entry or to add anentry in the IBM Security Key Lifecycle Manager replication configuration file.

Permissions

Your role must have the permission to the configure action.

SyntaxtklmReplicationConfigUpdateEntry -name propertyname -value propertyvalue

Parameters-name

Required. Specify the name of the property.-value

Required. Specify the value of the property.

Examples

• The following command updates the frequency of running the backup operation.

print AdminTask.tklmReplicationConfigUpdateEntry('[-name backup.CheckFrequency -value 60]')

• The following command disables incremental replication:

print AdminTask.tklmReplicationConfigDeleteEntry('[-name replication.Incremental.Enable -value false]')

tklmReplicationStartUse the tklmReplicationStart command to start the IBM Security Key Lifecycle Manager replicationtask.


PurposeUse this command to start the IBM Security Key Lifecycle Manager replication task.

SyntaxtklmReplicationStart

Parameters

There are no parameters.


Example

This Jython-formatted command starts the IBM Security Key Lifecycle Manager replication task.

print AdminTask.tklmReplicationStart()

Hardware requirementsYou must ensure that the system has the required memory, processor speed, and available disk space toinstall IBM Security Key Lifecycle Manager.

Table 10. Hardware requirements

System components Minimum values* Recommended values**

System memory (RAM) 4 GB 8 GB

Processor speed Linux and Windows systems1.0 GHz single processor

AIX systems1.5 GHz (2-way)

Linux and Windows systems3.0 GHz dual processors

AIX systems1.5 GHz (4-way)

Disk space free for IBMSecurity Key LifecycleManager and prerequisiteproducts such as DB2

16 GB 30 GB

Disk space free in /tmp orC:\temp

4 GB 4 GB

DB2 Disk space free in /home directory or systemdrive for DB2

7 GB 25 GB

Disk space free in /vardirectory for DB2

1 GB on Linux and UNIX operatingsystems

1 GB on Linux and UNIX operatingsystems

All file systems must be writable.

* Minimum values: These values enable a basic use of IBM Security Key Lifecycle Manager.

** Recommended values: You must use larger values that are appropriate for your productionenvironment. The most critical requirements are to provide adequate system memory, and free disk andswap space. Processor speed is less important.

On Linux and UNIX operating systems, you must install your DB2 product in an empty directory. If thedirectory that you specify as the installation path contains sub-directories or files, your DB2 installationmight fail.

On Linux and UNIX operating systems, 4 GB of free space is required in the "$HOME" directory.

On Linux and UNIX operating systems, minimum 16 GB of free space is required in the "/" and "/opt"directory.

Installing into mapped network drives/mounted partitions is not supported.

If installation locations of more than one system component fall on the same Windows drive/UNIXpartition, the cumulative space to contain all those components must be available in that drive/partition.


Operating system requirementsIBM Security Key Lifecycle Manager is supported on multiple operating systems. To install IBM SecurityKey Lifecycle Manager, ensure that your system meets the operating system requirements.

Table 11. Operating system requirements

Operating system

Use Db2 AdvancedWorkgroup ServerEdition Version11.1.2.2

AIX version 7.1 and version 7.2 in 64-bit mode. POWER7 processor-based servers aresupported.

• A 64-bit AIX kernel is required.• Use AIX 7.1 Technology Level 4, Service Pack 6. The minimum XL C/C++ runtime

level requires the xlC.rte 12.1.2.0 files.

Windows Server 2012 on x86_64 for:

• Standard Edition

Windows Server 2012 R2 on x86_64 for:


Windows Server 2016 on x86_64 for:


Red Hat Enterprise Linux Version 6.7 on x86_64

Red Hat Enterprise Linux Version 7.1 on x86_64

Red Hat Enterprise Linux Version 7.1 (IBM Z) on x86_64

Red Hat Enterprise Linux Version 7.1 (PowerPC Little Endian (LE)) on x86_64

Ubuntu 16 on x86_64

SuSE Linux Enterprise Server Version 12 on x86_64

SuSE Linux Enterprise Server Version 12 (IBM Z) on x86_64

Do not install IBM Security Key Lifecycle Manager on systems with hardened operating system.

Before you install IBM Security Key Lifecycle Manager on a UNIX or an AIX operating system, ensure thatBash shell (bash) is installed. Also, ensure that it is the default shell.

Before you install IBM Security Key Lifecycle Manager on an AIX operating system, ensure that thenecessary libraries that are described in this technote are installed: http://www-01.ibm.com/support/docview.wss?uid=swg21631478

Before you install IBM Security Key Lifecycle Manager on a Linux operating system, ensure that C shell(csh) is installed.

Before you install IBM Security Key Lifecycle Manager on a Red Hat Enterprise Linux operating system,ensure that the necessary libraries that are described in this technote are installed: https://www-304.ibm.com/support/docview.wss?uid=swg21459143


http://www-01.ibm.com/support/docview.wss?uid=swg21631478

http://www-01.ibm.com/support/docview.wss?uid=swg21631478

https://www-304.ibm.com/support/docview.wss?uid=swg21459143

https://www-304.ibm.com/support/docview.wss?uid=swg21459143

Access requirementsInstall IBM Security Key Lifecycle Manager as an administrator (root user).

You can install IBM Security Key Lifecycle Manager as a non-root user on Linux operating systems only.

Software requirementsIBM Security Key Lifecycle Manager requires middleware programs and other software for its operations.IBM Security Key Lifecycle Manager installs the middleware programs such as WebSphere ApplicationServer, Java Runtime Environment (JRE), and DB2 and are bundled with the IBM Security Key LifecycleManager package.

If you have Db2 already installed on the system, see the details in “Db2 requirements” on page 111.

Db2 kernel settingsEnsure that kernel settings are correct for the operating system, such as the Linux operating system, thatmight require updates.

AIX systemsNone required.

Linux systemsFor more information about kernel settings, see DB2 documentation http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.qb.server.doc/doc/t0008238.html.

Window systemsNone required.

Preinstallation worksheetsBefore you install and configure IBM Security Key Lifecycle Manager, you can complete the preinstallationworksheets to define the configuration parameters that are required to complete the IBM Security KeyLifecycle Manager installation.

The preinstallation worksheets list all of the values that you must specify during an IBM Security KeyLifecycle Manager installation process. Completing the preinstallation worksheets before you install thecomponents can help you plan your installation, save time, and enforce consistency during theinstallation and configuration process.

Stand-alone deployment of IBM Security Key Lifecycle Manager serverThe IBM Security Key Lifecycle Manager installation program deploys the IBM Security Key LifecycleManager server and required middleware components on the same computer.

You must ensure that the computer has the required memory, processor speed, and available disk spaceto meet the workload.

IBM Security Key Lifecycle Manager can run on a member server in a domain controller environment, butis not supported on a primary or backup domain controller.


http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.qb.server.doc/doc/t0008238.html

http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.qb.server.doc/doc/t0008238.html

Figure 2. Main components of IBM Security Key Lifecycle Manager server

Adding an existing IBM Security Key Lifecycle Manager instance with data tothe Multi-Master cluster

You can use the export and import feature of IBM Security Key Lifecycle Manager to add data from anexisting IBM Security Key Lifecycle Manager instance to the Multi-Master cluster. You must import thedata that was exported from the existing stand-alone instance to the Primary master server that isconfigured with DB2 HADR.

About this task

You cannot directly add an existing stand-alone instance with data into the cluster. You must first importdata from the existing IBM Security Key Lifecycle Manager instance to the primary master. Then, add amaster server into the cluster separately.

After data is imported, the data is available on all instances in the cluster. It is up to you to decidewhether to add a master separately.

Procedure

1. Export device group data from the existing IBM Security Key Lifecycle Manager instance. For moreinformation about how to export device group data, see “Exporting a device group” on page 111.

2. Import the data that was exported from the existing stand-alone instance to the primary master serverthat is configured with DB2 HADR. For more information about how to import device group data, see“Importing a device group” on page 113.

3. After you successfully import data to the primary server, you can access data from all the masters inthe cluster. If you need a dedicated IBM Security Key Lifecycle Manager master to access theimported data, add a master to the cluster. For more information about adding a master, see “Adding amaster server to a cluster” on page 40.

What to do nextYou might want to decommission the existing stand-alone IBM Security Key Lifecycle Manager instanceafter you successfully exported the data.

Key Export REST ServiceUse Key Export REST Service to export secret keys or public/private key pairs. A secret key is asymmetric key. A public/private key pair is an asymmetric key pair with a public key and a private key.

OperationPUT

URLhttps://<host>:<port>/SKLM/rest/v1/keys/export



Request

Request Parameters




Request Headers

Header name Value





Request body



alias Specifies an alias of the key that you export. This parameter is requiredif a value is not specified for the aliasRange parameter. For aprivatekey type, a value for alias is required. For a secretkeytype, you must specify a value for either alias or aliasRange.

aliases This parameter is required if values are not specified for the alias andaliasRange parameters.

Specify comma-separated alias values for the keys that you want toexport.

aliasRange This parameter is required if a value is not specified for the aliasparameter. When the value of alias is specified, the value ofaliasRange is ignored. To export a secret key, specify a threecharacter prefix followed by a range of numbers in hexadecimal format.You can use the characters 0 through 9 and a through f. You canspecify the range only for secret keys.

fileName Specifies the relative or full path and the name of a file that IBMSecurity Key Lifecycle Manager creates to store the exported keys. Ifyou do not specify a path name, the value of SKLM_HOME directory isused.

keyAlias This parameter is required if the exported key is a secret key. Specifythe alias of the public key entry in the keystore that is used to encryptthe secret key or keys to the file. Only the holder of the correspondingprivate key can access the keys.


Request body


(continued)


password This parameter is required if the value of the type parameter isprivatekey. Specify a password to protect the PKCS#12 file to whichthe private key and certificate are exported. You might need to retainthe value of the password to import the key.

type Specifies whether the keys are secret or private.secretkey

Specifies a symmetric key.privatekey

Specifies an asymmetric key in a key pair with a public key and aprivate key. If you select this value, a password is required. If youexport private keys to a PKCS#12 file, ensure that the file with thekey is wrapped; use a FIPS-approved method before the file leavesthe computer.

Response

Response Headers












status Returns the status to indicate whether the key is exported with anappropriate message.


Error Response Body





ExamplesService request to export a private key

PUT https://localhost:<port>/SKLM/rest/v1/keys/exportContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"alias":"sklmCertificate","fileName":"myprivatekeys","type":"privatekey","password":"mypassword"}

Success response

Status Code : 200 OK{"code":"0","status":"Succeeded"}

Service request to export a secret key

PUT https://localhost:<port>/SKLM/rest/v1/keys/exportContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"aliasRange":"def0-3","fileName":"mysecretkeys","type":"secretkey","keyAlias":"sklmCertificate"}

Success Response

Status Code : 200 OK{"status":"Exported Successfully"}

Error response

Status Code : 400 Bad Request{"code":"CTGKM0742E","message":"CTGKM0742E Key type not valid: key."}

Service request to export multiple secret keys

PUT https://localhost:<port>/SKLM/rest/v1/keys/exportContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"aliases" : "abc1,abc3","fileName":"mysecretkeys","type":"secretkey","keyAlias":"sklmCertificate"}

Success Response

Status Code : 200 OK{"code":"CTGKM3328I","status":"CTGKM3328I Export of keys successfully finished."}

Error response



Service request to export multiple private keys

PUT https://localhost:<port>/SKLM/rest/v1/keys/exportContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"aliases" : "abc1,abc3","fileName":"myprivatekeys","type":"privatekey","password":"mypassword"}

Success Response

Status Code : 200 OK{"code":"CTGKM3328I","status":"CTGKM3328I Export of keys successfully finished."}

Error response


Key Import REST ServiceUse Key Import REST Service to import secret keys or public/private key pairs. A secret key is asymmetric key. A public/private key pair is an asymmetric key pair that contains a public key and a privatekey. The private key file is in PKCS#12 format.

To import secret keys, the import file might contain multiple keys. Each key contains the required aliasvalue for that key. The import file must be generated by a previous Key Export REST Service.Operation

POSTURL

https://<host>:<port>/SKLM/rest/v1/keys/import


Request

Request Parameters




Request Headers

Header name Value






Request body



alias Required parameter in the following scenarios:

• If the value of the type attribute is secretkey and you want torename the key with the newAlias parameter during the importprocess.

Specify a value for this parameter if you want to import a specificsecret key from a keystore file that has multiple secret keys.

• If the value of the type attribute is privatekey and if the keystorefile contains multiple private keys.

This parameter is not required when the keystore file contains only oneprivate key. If you specify a value, it is ignored.

fileName Required. Specify the path and file name of the file from which the keysare imported.

keyAlias This parameter is required if the value of the type attribute issecretkey. Specify the alias of the private key entry in the keystore thatdecrypts the secret key or keys, from the file. Use the same alias value toimport and export a secret key or keys.

newAlias Specify a new value for the key alias.

password This parameter is required if the type parameter is privatekey. Thispassword was previously specified with the Key Export RESTService. If you export private keys to a PKCS#12 file, ensure that thefile with the key is wrapped with a FIPS-approved method before the fileleaves the computer.

type Specify whether the keys are secret or private.secretkey

Specifies a symmetric key.

If you select this value, specify a value for the usage attribute for adevice group family that administers keys.

privatekeySpecifies an asymmetric key in a key pair with a public key and aprivate key.

If you select this value, specify a value for the usage attribute for adevice group that administers keys. You can specify any of thefollowing values:

• SSLCLIENT• SSLSERVER


Request body


(continued)


usage Specify the target application usage such as LTO device group. You canspecify the following values:LTO

Specifies the LTO device group.3592

Specifies the 3592 device group.DS5000

Specifies the DS5000 device group.DS8000

Specifies the DS8000 device group.BRCD_ENCRYPTOR

Specifies the BRCD_ENCRYPTOR device group that is in the LTOdevice family.

ONESECURESpecifies the ONESECURE device group that is in the DS5000 devicefamily.

usage ETERNUS_DXSpecifies the ETERNUS_DX device group that is in the DS5000 devicefamily.

XIV®Specifies the IBM Spectrum Accelerate (previously known as XIV)device group.

GPFSSpecifies the IBM Spectrum Scale (previously known as GPFS) devicegroup.

PEER_TO_PEERSpecifies the PEER_TO_PEER device group.

DS8000_TCTSpecifies the DS8000_TCT device group that is in the GPFS devicefamily.


Request body


(continued)


usage GENERICSpecifies a device family that uses the Key ManagementInteroperability Protocol to interact with IBM Security Key LifecycleManager. The GENERIC device group enables management of KMIPobjects

Do not use the REST interface to add a device to the GENERIC devicegroup, or to change a GENERIC device group attribute.

SSLCLIENTClient-side certificate that is used in secure communication by usingSecure Socket Layer protocol to authenticate the client device.

SSLSERVERServer-side certificate that is used in secure communication by usingSecure Socket Layer protocol.

ETERNUS_DXSpecifies the ETERNUS_DX device group that is in the DS5000 devicefamily.

XIVSpecifies the XIV device group that is in the DS5000 device family.

userdevicegroupSpecifies a user-defined group that is based on a supported devicefamily.

Response

Response Headers










Success response body for privatekey type



code Returns an integer value such as 0 to indicate the key import status.

status Returns the status to indicate that the key import task is succeeded.

Success response body for secretkey type



ImportedKeys JSON array that contains JSON objects with a list of imported keys. If nokeys are imported, an empty list is returned.

ExistingKeys JSON array that contains JSON objects with a list of duplicate keys. Ifthere are no duplicate keys, an empty list is returned.

FailedToImportKeys JSON array that contains JSON objects with a list of failed keys. If thereare no keys failed keys, an empty list is returned.

Error Response Body





ExamplesService request to import a symmetric key (secretkey type)

POST https://localhost:<port>/SKLM/rest/v1/keys/importContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"keyAlias":" sklmCertificate", "alias":"xyz000000000000000000","newAlias":"ayz000000000000000000","type":"secretkey","fileName":"mykey","usage":"LTO"}

Success response

Status Code : 200 OK{"ImportedKeys":[{"KeyAlias":"ayz000000000000000000"}],"ExistingKeys":[],"FailedToImportKeys":[]}

Service request to import a private key (privatekey type)

POST https://localhost:<port>/SKLM/rest/v1/keys/importContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"type":"privatekey","fileName":"mykey","usage":"SSLSERVER","password":"mypassword","newAlias":"mykey"}

Success response



Service request to import multiple private keys (privatekey type)

POST https://localhost:<port>/SKLM/rest/v1/keys/import Content-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"type":"privatekey","fileName":"mykey","usage":"3592","password":"mypassword","alias":"abc1","newAlias":"mykey"}

Success response


Error response for an invalid request

POST https://localhost:<port>/SKLM/rest/v1/keys/importContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"type":"privatekey","fileName":"privatekeys","usage":"3592","password":"SKLM@admin123","newAlias":"mykey"}

Error response

Status Code : 500 Internal Server Error{"code":"CTGKM3306E","message":"CTGKM3306E Multiple aliases found in the file. Please mention the alias to be imported."}

Modifying replication configuration for a clone serverUse the graphical user interface, REST interface, or CLI interface to change the replication configurationparameters on a clone server. Data is replicated to the clone servers only if new cryptographic objects areadded to the master server.

Procedure

• Using graphical user interfacea) Log in to the graphical user interface.b) Click Administration > Replication.c) Ensure that Clone role is selected.d) Modify the required properties in the Basic Properties tab:

Basic Properties

Clone listen port Port number that the clone server must listen on to receivebackup files. Default port number is 2222.

Master listen port Port number for communication when unserialized or delayedreplications take place. Default master listen port is 1111.

e) To configure or modify the advanced properties, click the Advanced Properties tab:Advanced Properties

Number of retries incase ofrestore failure

Maximum number of retries that are allowed after the firstrestore operation is failed. The value must be a positive integerbetween 0 - 2.

Replication log file name Name and location for the replication log file. Default value forthis parameter is <WAS_HOME>\products\sklm\logs\replication.


Maximum log file size (inKB)

Maximum size of a log file before rollover occurs. Default valueis 1000 KB (kilobytes). When the file reaches the maximumsize, a new log file is created.

Maximum number of logfiles to keep

Maximum number of log files that you want to keep. By default,IBM Security Key Lifecycle Manager keeps the last 3 log files.When the number of files exceed the specified limit, the oldestfile is deleted.

f) Click OK.g) Click Start Replication Server to enable replication of the cryptographic data to the clone servers

based on a configured schedule.• Using REST interface

a) Open a REST client.b) Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST


c) Run “Update Replication Config Property REST Service” on page 86.For example:

PUT https://localhost:port/SKLM/rest/v1/replicationConfigProperties{ "replication.role": "clone", "backup.TLSCertAlias":"sklmSSLCertificate", "restore.ListenPort": "2222", "replication.MasterListenPort": "1111" }

For information about the replication configuration parameters, see “Replication configurationproperties” on page 114.

• Using CLI commandsa) Go to the WAS_HOME/bin directory.

For example:Windows


cd /opt/IBM/WebSphere/AppServer/binb) Start the wsadmin interface by using an authorized user ID, such as SKLMAdmin.

For example:Windows


Linux


c) Run the “tklmReplicationConfigUpdateEntry” on page 91 command.For example:

print AdminTask.tklmReplicationConfigUpdateEntry ('[-name replication.role -value clone]''[backup.EncryptionPassword=mypassword]''[backup.TLSCertAlias=sklmSSLCertificate]''[backup.ClientIP1=myhostname]''[backup.ClientPort1=2222]''[replication.MasterListenPort=1111]')

For information about the replication configuration parameters, see “Replication configurationproperties” on page 114.


What to do next

You might want to change the settings for other clone servers. Complete this procedure on each cloneserver.

tklmKeyExportUse the tklmKeyExport command to export secret keys or public/private key pairs.


PurposeUse this command to export secret keys or public/private key pairs. A secret key is a symmetric key. Apublic/private key pair is an asymmetric key pair with a public key and a private key.

Permissions

To export the key, you must have permission to the configure action, or get action plus the permission tothe appropriate device group. When you export a secret key, you must also have permission to configure,create, or view action for the asymmetric key pair that is specified by the keyAlias parameter.

SyntaxtklmKeyExport -alias keyalias -aliasRange prefixhexnumber1-hexnumberN -keyAlias keyalias -fileName pathandkeyfilename -keyStoreName keystorename -type {secretkey | privatekey} -password exportkeypasswordvalue

Parameters-alias

Required if a value is not specified for the aliasRange parameter. Specify the alias of the key to export.For a privatekey type, a value for -alias is required. For a secretkey type, you must specify a value foreither -alias or -aliasRange.

-aliasesRequired if values are not specified for the alias and aliasRange parameters.Specify comma-separated alias values for the keys that you want to export.

-aliasRangeRequired if a value is not specified for the alias parameter. When the value of alias is specified, thevalue of -aliasRange is ignored.Specify a three character prefix followed by a range of numbers in hexadecimal format (consisting ofthe sixteen characters 0-9, a-f) of secret keys to export. Allowed only for secret keys, not private keys.For example:

-aliasRange ibm1-a

Alternatively, you might specify:

-aliasRange xyz01-fff

-fileNameRequired. Specify the relative or full path, and the name of a file that IBM Security Key LifecycleManager creates to store the exported keys. If you do not specify a path name, the value ofSKLM_DATA directory is used.

-keyAliasRequired if the exported key is a secret key. Specify the alias of the public key entry in the keystorethat is used to encrypt the secret key, or keys, to the file. Only the holder of the corresponding privatekey can access the keys.


-keyStoreNameRequired. Specify the name of the keystore from which the exported keys are exported.

-passwordRequired if the value of the -type attribute is privatekey. Specify a password to protect thePKCS#12 file to which the private key and certificate are exported.

You might want to retain the value of the password for later use with the tklmKeyImport command.

Note: If you migrate data from IBM Security Key Lifecycle Manager Version 1, any scripts orapplications that you previously used to automate key export require modification to specify apassword.

-typeRequired. Specify whether the keys are secret or private. You can include the following values:secretkey

Specifies a symmetric key.privatekey

Specifies an asymmetric key in a key pair with a public key and a private key. If you select thisvalue, a password is required. If you export private keys to a PKCS#12 file, ensure that the filewith the key is wrapped by using a FIPS-approved method before the file leaves the computer.

Example

For tape usage, this Jython-formatted command exports a range of secret keys into a file namedmysecretkeys, in a path that is relative to the SKLM_DATA directory.

print AdminTask.tklmKeyExport ('[ -aliasRange abc1-ff -fileName mysecretkeys -keyStoreName defaultKeyStore -type secretkey -keyAlias mySecretKeyAlias]')

This Jython-formatted command specifies a password and exports a public/private key pair into a filenamed myprivatekeys, in a path that is relative to the SKLM_DATA directory.

print AdminTask.tklmKeyExport ('[ -alias myPrivateKeyAlias -fileName myprivatekeys -keyStoreName defaultKeyStore -type privatekey -password mypassword]')

This Jython-formatted command specifies a password and exports multiple public/private key pairs into afile named myprivatekeys, in a path that is relative to the SKLM_DATA directory.

print AdminTask.tklmKeyExport ('[ -aliases abc1,abc3 -fileName myprivatekeys -keyStoreName defaultKeyStore -type privatekey -password mypassword]')

This Jython-formatted command specifies a password and exports multiple secret keys into a file namedmysecretkeys, in a path that is relative to the SKLM_DATA directory.

print AdminTask.tklmKeyExport ('[ -aliases abc1,abc3 -fileName mysecretkeys -keyStoreName defaultKeyStore -type secretkey -keyAlias sklmCertificate]')

tklmKeyImportUse the tklmKeyImport command to import secret keys or public/private key pairs. A secret key is asymmetric key. A public/private key pair is an asymmetric key pair with a public key and a private key. Theprivate key file is in PKCS#12 format.



PurposeUse this command to import secret keys or public/private key pairs. A secret key is a symmetric key. Apublic/private key pair is an asymmetric key pair with a public key and a private key. The private key file isin PKCS#12 format.

To import secret keys, the import file can contain multiple keys. Each key contains the required aliasvalue for that key. The import file must be generated by a previous tklmKeyExport command.

Permissions

To import the key, you must have permission to the configure action, or, create action and the permissionto the appropriate device group. When you import a secret key, you must also have permission toconfigure, create, or view action for the asymmetric key pair that is specified by the keyAlias parameter.

Syntax

An asterisk (*) indicates a deprecated value. If you enter the deprecated value, do not include theasterisk.

tklmKeyImport -alias keyalias -newAlias newkeyalias -keyAlias keyalias -fileNamepathandkeyfilename -keyStoreName keystorename -usage {LTO | 3592 | DS5000 | DS8000 |BRCD_ENCRYPTOR | ONESECURE | ETERNUS_DX | XIV | GPFS | PEER_TO_PEER | DS8000_TCT |GENERIC | userdevicegroup | SSLSERVER | SSL Server* | SSLCLIENT } -type {secretkey | privatekey} -password passwordvalue

Parameters-alias

Required parameter in the following scenarios:

• If the value of the type attribute is secretkey and you want to rename the key with the newAliasparameter during the import process.

Specify a value for this parameter if you want to import a specific secret key from a keystore file thathas multiple secret keys.

• If the value of the type attribute is privatekey and if the keystore file contains multiple privatekeys.

This parameter is not required when the keystore file contains only one private key. If you specify avalue, it is ignored.

-fileNameRequired. Specify the path and file name of the file from which keys are imported.

-keyAliasRequired if the value of the -type attribute is secretkey. Specify the alias of the private key entry inthe keystore that is used to decrypt the secret key, or keys, from the file. Use the same alias value toimport and export a secret key, or keys.

-keyStoreNameRequired. Specify the name of the keystore into which the imported key is imported.

-newAliasSpecify a new value for the key alias.

-passwordRequired if the value of the -type attribute is privatekey. This password was previously specified byusing the tklmKeyExport command. If you export private keys to a PKCS#12 file, ensure that thefile with the key is wrapped by using a FIPS-approved method before the file leaves the computer.

-typeRequired. Specify whether the keys are secret or private. You can include the following values:secretkey

Specifies a symmetric key.


If you select this value, specify for the -usage attribute a value for a device group family thatadministers keys.

privatekeySpecifies an asymmetric key in a key pair with a public key and a private key.

If you select this value, specify for the -usage attribute a value for a device group that administerscertificates, or specify one of these values:

• SSLCLIENT• SSLSERVER

-usageRequired. Specify the target application usage, such as LTO device group. You can include thefollowing values:LTO

Specifies the LTO device group.3592

Specifies the 3592 device group.DS5000

Specifies the DS5000 device group.DS8000

Specifies the DS8000 device group.BRCD_ENCRYPTOR

Specifies the BRCD_ENCRYPTOR device group that is in the LTO device family.ONESECURE

Specifies the ONESECURE device group that is in the DS5000 device family.ETERNUS_DX

Specifies the ETERNUS_DX device group that is in the DS5000 device family.XIV

Specifies the IBM Spectrum Accelerate (previously known as XIV) device group.GPFS

Specifies the IBM Spectrum Scale (previously known as GPFS) device group.PEER_TO_PEER

Specifies the PEER_TO_PEER device group.DS8000_TCT

Specifies the DS8000_TCT device group that is in the GPFS device family.GENERIC

Specifies a device family that uses the Key Management Interoperability Protocol to interact withIBM Security Key Lifecycle Manager. The GENERIC device group enables management of KMIPobjects.

Do not use the command-line interface to add a device to the GENERIC device group, or to changea GENERIC device group attribute.

SSLCLIENTClient-side certificate that is used in secure communication by using Secure Socket Layer protocolto authenticate the client device.

SSLSERVERServer-side certificate that is used in secure communication by using Secure Socket Layerprotocol.

userdevicegroupSpecifies a user-defined group that is based on a supported device family.


Example

For tape usage, this Jython-formatted command imports a symmetric key named mysecretkey from a filenamed mykey.p12 into a keystore named myKeystore for use with LTO tape drives.

print AdminTask.tklmKeyImport ('[ -alias mysecretkey -type secretkey -keyAlias mySecretKey -newAlias myNewSecretKey -fileName c:\\myimportpath\\mykey.p12 -keyStoreName defaultKeyStore -usage LTO]')

This Jython-formatted command imports an asymmetric key in a key pair with a public key and a privatekey. A password is required.

print AdminTask.tklmKeyImport ('[-alias myprivatekey -type privatekey -fileName c:\\myimportpath\\myprivatekey.p12 -keyStoreName defaultKeyStore -usage SSLSERVER -password mypassword]')

tklmReplicationNowUse the tklmReplicationNow command to immediately run IBM Security Key Lifecycle Managerreplication and forces a backup to be sent to the configured clones.


PurposeUse this command to immediately run IBM Security Key Lifecycle Manager replication and to force abackup to be sent to the configured clones.

SyntaxtklmReplicationNow -hostname hostname | -port portnum

Parameters

Note: If either host name or port parameter is coded, the other must be too.

-hostnameOptional. Specify the host to replicate to.

-portOptional. Specify the port to connect to the replication clone through.

Example

This Jython-formatted command replicates IBM Security Key Lifecycle Manager to all clones defined inthe ReplicationSKLMgrConfig.properties replication configuration file.

print AdminTask.tklmReplicationNow()

The following command replicates IBM Security Key Lifecycle Manager to a specific server.

print AdminTask.tklmReplicationNow('[-hostname myserver -port 1111]')

Types of installationYou can install IBM Security Key Lifecycle Manager in graphical user interface or silent mode.

• A graphical user interface-based installation that is driven by a wizard.• A silent installation that runs unattended, using response files for the configuration options.


Notes:

• IBM Security Key Lifecycle Manager does not support a console mode installation.• Do not install IBM Security Key Lifecycle Manager from a network drive or mounted drive. For example,

do not specify either of these net use statements as the directory location and attempt installation:

net use z: \\server\sharenet use \\server\share

Db2 requirementsThe database stores the data of IBM Security Key Lifecycle Manager. IBM Security Key Lifecycle Managersupports Db2 Advanced Workgroup Server Edition Version 11.1.4.4 interim fix 1. Before you install IBMSecurity Key Lifecycle Manager, ensure that the database requirements are met.

IBM Security Key Lifecycle Manager requires Db2 Advanced Workgroup Server Edition Version 11.1.4.4interim fix 1 and the future fix packs on the same system on which the IBM Security Key LifecycleManager server runs.

Note:

• You must use IBM Security Key Lifecycle Manager to manage the database. To avoid datasynchronization problems, do not use tools that the database application might provide.

• For improved performance of Db2 on AIX systems, ensure that you install and configure the I/Ocompletion ports (IOCP) package that is described in the Db2 documentation (http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.perf.doc/doc/t0054518.html).

• If an existing copy of Db2 Advanced Workgroup Server Edition was installed as the root user at thecorrect version for the operating system, you can use the existing Db2 Advanced Workgroup ServerEdition. IBM Security Key Lifecycle Manager installer does not detect the presence of Db2. You mustspecify the Db2 installation path.

SuSE Linux Enterprise Server Version 12 (System z) systems contain the libstdc++.6.so package. But,IBM Security Key Lifecycle Manager requires the libstdc++.5.so package for Db2 installation.

For more information about Db2 prerequisites, see Db2 documentation (http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.cmd.doc/doc/r0059710.html).

Exporting a device groupYou can export device group data for the selected device group to an encrypted archive. Then, you canimport this device group data into another instance of IBM Security Key Lifecycle Manager acrossoperating systems.

About this task

You can use the Export Device Group dialog box to export a device group. Alternatively, you can useDevice Group Export REST Service.

Your role must have a permission to export device groups.

Note: During data migration from previous versions of IBM Security Key Lifecycle Manager, some of thecertificates might not be associated with the correct device group. As a result, it is possible that a fewcertificates are falsely shown (in UI, REST, or CLI) for a device group, such as 3592 or DS8000, eventhough the certificates do not belong to the device group. When you export such device groups, only thecertificates of the device group are exported. The falsely shown certificates are not exported.

Procedure

1. Go to the appropriate page or directory.


http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.perf.doc/doc/t0054518.html

http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.perf.doc/doc/t0054518.html

http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.cmd.doc/doc/r0059710.html

http://www-01.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.cmd.doc/doc/r0059710.html

Graphical user interface

a. Log in to the graphical user interface.b. On the Welcome page, click Administration > Export and Import. The Export/Import Device

Groups page is displayed.

Alternatively, in the Key and Device Management section, right-click a device group, andselect Export.


2. Export the device group data for the selected device group to the directory you specified.Graphical user interface

a. On the Export/Import Device Groups page, click Export.b. On the Export Device Group dialog box, the Device Group field specifies the selected device

group.c. To change the device group, click Select.d. The Export repository location field displays the default <SKLM_DATA> directory path, where

the export file is saved, for example, C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data. For the definition of <SKLM_DATA>, see “Definitions for HOME andother directory variables” on page 31. Click Browse to specify a export repository locationunder <SKLM_DATA> directory.

Directory path in the Export repository location field changes based on the value that is set forthe browse.root.dir property in the SKLMConfig.properties file.

e. In the Password field, specify a value for the encryption password. Ensure that you retain theencryption password for future use.

f. In the Retype password field, retype the password that you entered in the Password field.g. In the Description field, specify additional information that indicates the purpose of the device

group export file.h. Click Export.

REST interface


b. Run the Device Group Export REST Service. For example:

POST https://localhost:<port>/SKLM/rest/v1/ckms/deviceGroupsExport{"name": "3592", "exportDirectory": "/opt/IBM/WebSphere/AppServer/products/sklm/data/", "password": "mypassword"}

When the export process is complete, a message box is displayed to indicate that the export operationis complete.

What to do next

Ensure that you retain this password for use when you later import and decrypt the device group exportfile into another instance of IBM Security Key Lifecycle Manager. Review the directory that contains theexport archive to ensure that the export file exists. You can also verify whether the archive is listed in thetable on the IBM Security Key Lifecycle Manager > Administration > Export and Import > Export/Import page.


Importing a device groupYou can import device group data that were exported from another IBM Security Key Lifecycle Managerserver if you want to move data across IBM Security Key Lifecycle Manager servers.

Before you beginYou must have the export file and ensure that you have the password that you used when the export filewas created. Save the export files in the default <SKLM_DATA> directory, for example, C:\ProgramFiles\IBM\WebSphere\AppServer\products\sklm\data. For the definition of <SKLM_DATA>, see“Definitions for HOME and other directory variables” on page 31.

The <SKLM_DATA> directory path changes based on the value that is set for the browse.root.dirproperty in the SKLMConfig.properties file.

Version of the IBM Security Key Lifecycle Manager instance where the device group export data is beingimported must be same as the IBM Security Key Lifecycle Manager instance from which the device groupdata were exported.

About this task

At times, the device group data that is imported might conflict with an existing data in the database. Forexample, a key in the imported device group might be a key with same alias name of a device group in thecurrent instance of IBM Security Key Lifecycle Manager where the data is being imported. When conflictsoccur, they must be resolved before the import process can continue.

You can use the Export and Import page. Alternatively, you can use Device Group Import RESTService to import device groups.

Your role must have a permission to import device groups. For more information about device groupexport and import operations, see “Overview of device group export and import” on page 32.

Procedure


a. Log in to the graphical user interface.b. On the Welcome page, click Administration > Export and Import.


2. Import a selected export file. Only one export or import task can run at a time. If you want import a fileto an IBM Security Key Lifecycle Manager instance on a different system, copy the export file to thatsystem by using media such as a disk, or electronic transmission.Graphical user interface

a. Click Browse to specify the export file location under <SKLM_DATA> directory, for example,C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data.

b. Click Display Exports to display the export files.c. In the table, select an export file.d. Click Import.e. Alternatively, double-click or right-click the export file and select Import.f. On the Import from Export Archive dialog, specify the encryption password that you used to

create the export file.g. Click Import to start the import operation.h. If any conflicts arise during the import process, the Conflicts while Importing dialog appears.

For more information, see “Resolving the import conflicts” on page 115.


Else, the progress dialog box appears. When the import process is complete, a message box isdisplayed to indicate that the import operation is complete.

i. Click Close.

REST interface


b. To run Device Group Import REST Service, send the HTTP POST request. Pass the userauthentication identifier that you obtained in Step a along with the request message as shownin the following example.

POST https://localhost:<port>/SKLM/rest/v1/ckms/deviceGroupsImportContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"importFilePath": "C:\\Program Files\\IBM\\WebSphere\\AppServer\\products\\sklm\\data\\sklm_v4.0.0.0_20160728040703-1200_export.exp", "password": "passw0rd123"}

c. If any conflicts arise during the import process, obtain the list of conflicts.

For more information, see “Resolving the import conflicts” on page 115.3. Restart the server. For instructions about how to stop and start the server, see “Restarting the IBM

Security Key Lifecycle Manager server” on page 117.

Replication configuration propertiesReplication configuration properties are stored in the ReplicationSKLMConfig.properties file.

The file is created when you configure replication. The properties in the file are updated automaticallydepending on the modifications to the replication configuration. The file is located in the WAS_HOME/products/sklm/config directory on the IBM Security Key Lifecycle Manager server.

Note: For replication:

• The backup properties are required only on a master system.• The restore properties are required only on a clone system.• You must specify the replication.role property on a clone system.

Replication configuration propertiesReplication configuration properties are stored in the ReplicationSKLMConfig.properties file.

The file is created when you configure replication. The properties in the file are updated automaticallydepending on the modifications to the replication configuration. The file is located in the WAS_HOME/products/sklm/config directory on the IBM Security Key Lifecycle Manager server.

Note: For replication:

• The backup properties are required only on a master system.• The restore properties are required only on a clone system.• You must specify the replication.role property on a clone system.


Resolving the import conflictsWhen the device group data is imported from an export file, its content is analyzed for conflicts with thedata that is stored in the database. The conflicts must be resolved before the data can be imported. Youcan view the list of conflicts to analyze and resolve the problems.

About this task

When you import device group data from an export file into an IBM Security Key Lifecycle Manager server,you might detect conflicts. You can also use Device Group Import Conflicts REST Service toobtain the list of the data conflicts, if any.

You must resolve the conflicts before the data can be imported.

Procedure

1. Open a REST client.2. Use the following REST APIs to resolve the import conflicts:

• Change Name REST Service• Change Certificate Alias REST Service• Change History REST Service• Renew Key Alias REST Service

Related tasks“Importing a device group” on page 113You can import device group data that were exported from another IBM Security Key Lifecycle Managerserver if you want to move data across IBM Security Key Lifecycle Manager servers.

Change History REST ServiceUse Change History REST Service to get information about the historical changes that are done todifferent cryptographic objects such as key alias, certificate alias, device serial number, and UUID in theIBM Security Key Lifecycle Manager instance.

Note: The import conflict REST services make significant changes to the IBM Security Key LifecycleManager instance that might impact its operation and the communication with the storage device. Youmust carefully plan and evaluate the changes that are required on both IBM Security Key LifecycleManager and the storage device. The changes must be atomic; that is the changes must be done both onthe IBM Security Key Lifecycle Manager system and the devices. The import conflict resolution RESTservices handle the changes for IBM Security Key Lifecycle Manager. For the complete process handling,you must take the guidance of your IBM support representative.

OperationGET

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/conflictResolution/getChangeHistory


Request


Request Parameters




Request Headers

Header name Value





Response Headers












getChangeHistory Returns the JSON object that contains the information about thehistorical changes done to the different cryptographic objects in the IBMSecurity Key Lifecycle Manager instance.


Error Response Body





ExamplesService request to get history information

GET https://localhost:<port>/SKLM/rest/v1/ckms/conflictResolution/getChangeHistoryContent-Type: application/jsonAccept : application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567mAccept-Language : en

Success response

Status Code : 200 OKContent-Language: en [{"objectType":"CERTIFICATE","changeType":"ALIAS","oldValue":"cert1","newValue":"cert1_updated","changeTime":"10\/16\/16, 5:26:32 PM GMT-12:00"},…..{"objectType":"KEY","changeType":"ALIAS","oldValue":"abc0074a5aa0000000001","newValue":"fri0074a5aa0000000000","changeTime":"10\/17\/16, 12:48:06 AM GMT-12:00"},……{"objectType":"DEVICE","changeType":"SERIALNUMBER","oldValue":"DEV1LTO12345”,”newValue":"DEV1LTO1234U","changeTime":"10\/17\/16, 6:13:07 AM GMT-12:00"},…]

Error response

Status Code : 400 Bad Request{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format."}

Restarting the IBM Security Key Lifecycle Manager serverRestart of the server causes the server to read its configuration and accept the configuration changes, ifany. To restart the IBM Security Key Lifecycle Manager server, you can use the graphical user interface,REST service, or run the server restart scripts.

About this task

To restart server, use the <IBM Security Key Lifecycle Manager User> link on welcome page header bar,Restart Server REST Service, or run the stopServer and startServer scripts.

Procedure

• Using graphical user interfacea) Log on to the graphical user interface.b) On the Welcome page header bar, click the <IBM Security Key Lifecycle Manager User> link.

For example, click the SKLMAdmin link.c) Click Restart Server.d) Click OK.


Note: The IBM Security Key Lifecycle Manager server is unavailable for a few minutes while the restartoperation is in progress.

• Using REST interfacea) Open a REST client.b) Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager REST

APIs. For more information about the authentication process, see “Authentication process for RESTservices” on page 27.

c) Run the “Restart Server REST Service” on page 121.Sample request:

POST https://localhost:port/SKLM/rest/v1/ckms/servermanagement/restartServer

• Using scriptsa) Go to the WAS_HOME\bin directory.

Windows

C:\Program Files\IBM\WebSphere\AppServer\bin

Linux

/opt/IBM/WebSphere/AppServer/bin

b) Stop the server.Windows

stopServer.bat server1 -username wasadmin -password mypwd

Linux

./stopServer.sh server1 -username wasadmin -password mypwd

Because the administrative security for WebSphere Application Server is enabled, you mustspecify the user ID and password of the WebSphere Application Server administrator asparameters to the stopServer script. If these parameters are omitted, you are prompted tospecify the values.

c) Start the server.Windows

startServer.bat server1

Linux

./startServer.sh server1

What to do next

Determine whether IBM Security Key Lifecycle Manager is running. For example, open IBM Security KeyLifecycle Manager in a web browser and log in.

Change Name REST ServiceUse Change Name REST Service to change the serial number of a storage device.

Note: The import conflict REST services make significant changes to the IBM Security Key LifecycleManager instance that might impact its operation and the communication with the storage device. Youmust carefully plan and evaluate the changes that are required on both IBM Security Key LifecycleManager and the storage device. The changes must be atomic; that is the changes must be done both on


the IBM Security Key Lifecycle Manager system and the devices. The import conflict resolution RESTservices handle the changes for IBM Security Key Lifecycle Manager. For the complete process handling,you must take the guidance of your IBM support representative.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/conflictResolution/changeName


Request

Request Parameters




Request Headers

Header name Value





Request body

JSON object with the following specification


type Specifies that the user can change the name of a device serial number.You can provide the value Device, Client, or LTOKeyGroup.

oldName Specifies the existing value of the storage device serial number.

newName Specifies the new value to be set for the storage device serial number.

Response


Response Headers












code Returns the value that is specified by the status property.

status Returns the status to indicate whether the serial number of the storagedevice is changed with an appropriate message.

Error Response Body





ExamplesService request to change the serial number of a storage device

POST https://localhost:<port>/SKLM/rest/v1/ckms/conflictResolution/changeNameContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"type" : "Device" , "oldName" : "device1", "newName" : "newdevice1"}

Success response

Status Code : 200 OK {"code":"0","status”:”Change of Name successfull.”}


Error response

Status Code: 500 Internal Server Error{"code":"CTGKM2923E","message":"CTGKM2923E Device with Serial number newdevice1 already exists."}

Restart Server REST ServiceUse Restart Server REST Service to restart the IBM Security Key Lifecycle Manager server. Restartof the server causes the server to read its configuration and accept the configuration changes, if any.

OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/servermanagement/restartServer


Request

Request Parameters




Request Headers

Header name Value





Response


Response Headers













message Returns the status message that indicates success or failure of theserver restart operation.

Error Response Body





ExamplesService request to restart the IBM Security Key Lifecycle Manager server

POST https://localhost:<port>/SKLM/rest/v1/ckms/servermanagement/restartServerContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m

Success response

Status Code : 200 OK{"code": "CTGKM2936I","message": "CTGKM2936I IBM Security Key Lifecycle Manager Server restarted successfully. After restarting the SKLM server, it will be unavailable for few minutes."}}

Error response

Status Code : 200 OK{"code": "CTGKM2937E","message": "CTGKM2937E Error restarting IBM Security Key Lifecycle


Manager Server, plesae check logs for more information."}

Change Certificate Alias REST ServiceUse Change Certificate Alias REST Service to change the alias of a certificate present in theIBM Security Key Lifecycle Manager instance.


OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/conflictResolution/changeCertificateAlias


Request

Request Parameters




Request Headers

Header name Value





Request body



oldAlias Specifies the existing value of the alias for the certificate present in IBMSecurity Key Lifecycle Manager system.


Request body


(continued)


newAlias Specifies the new value to be set for the alias of the certificate. Thisvalue must be unique in the IBM Security Key Lifecycle Managersystem.

Response

Response Headers













status Returns the status to indicate whether the certificate alias is changedwith an appropriate message.

Error Response Body






ExamplesService request to change certificate alias

POST https://localhost:<port>/SKLM/rest/v1/ckms/conflictResolution/changeCertificateAliasContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"oldAlias" : "3592cert2" ,"newAlias" : "3592cert3"}

Success response

Status Code : 200 OK {"code":"0","status”:”Certificate alias successfully changed”}

Error response

Status Code: 500 Internal Server Error{“code":"CTGKM2919E","message":"CTGKM2919E Certificate with Alias name 3592cert3 already exists."}

Renew Key Alias REST ServiceUse Renew Key Alias REST Service to change the alias of a key present in the IBM Security KeyLifecycle Manager instance.


OperationPOST

URLhttps://<host>:<port>/SKLM/rest/v1/ckms/conflictResolution/renewKeyAlias


Request

Request Parameters




Request Headers

Header name Value




Request Headers (continued)

Header name Value



Request body



oldAlias Specifies the existing value of the alias for the key that is present in theIBM Security Key Lifecycle Manager system.

newAliasPrefix Specifies the value to be set for the alias of the key.

Response

Response Headers













status Returns the status to indicate whether the key alias is changed with anappropriate message.


Error Response Body





ExamplesService request to renew key alias

POST https://localhost:<port>/SKLM/rest/v1/ckms/conflictResolution/renewKeyAliasContent-Type: application/jsonAccept: application/jsonAuthorization: SKLMAuth userAuthId=139aeh34567m{"oldAlias" : "fri004a19372000000000" ,"newAliasPrefix" : "fri"}

Success response

Status Code : 200 OK {"code":"0","status”:”Renew of Key alias successfull.”}

Error response

Status Code: 500 Internal Server Error{"code":"CTGKM2918E","message":"CTGKM2918E Key with Alias name fri004a19372000000000 doesn't exists."}

InstallingIBM Security Key Lifecycle Manager installation process involves planning activities, installation steps,and postinstallation tasks.

Installation process overview

Complete the following steps to plan, install, and configure IBM Security Key Lifecycle Manager.

1. Complete the preinstallation tasks.2. Install IBM Security Key Lifecycle Manager.3. Complete the postinstallation tasks.

Note: Installation might take more than half an hour.

Upgrading and migratingLearn how to upgrade and migrate data for the product.

Overview


To upgrade, you must complete the following high-level operations:I. Install the target versionII. Migrate data from the existing version to the target version.


Multi-Master cluster configuration statusThe Multi-Master section on the Welcome page of the IBM Security Key Lifecycle Manager graphical userinterface displays the configuration status of the Multi-Master cluster. You can determine whether thecluster configuration in any of the master servers of the cluster is out of sync.

If the cluster configuration is out of sync, you can sync it from the graphical user interface.

Supported master server operations

Adding or removing a standby or non-HADR master server depends on the configuration status of theMulti-Master cluster. The following tables provide details of the operations. Each row providesinformation about whether you can add or remove a standby and non-HADR master server given aspecific cluster status. For example, the first row in the Operation - Add master server table indicatesthat if the primary master server of the cluster is offline, you cannot add any type of master server to thecluster.

Table 12. Operation - Add master server

Cluster status Add master server of type

Standby Non-HADR

Primary master server is offline. No No

One or more standby master servers are offline. No Yes

Non-HADR master server is offline. Yes Yes

Cluster configuration on the standby master server isout of sync.

No

To add a standby masterserver, sync the masterserver that is out of syncand retry the operation.

Yes

Table 13. Operation - Remove master server

Cluster status Remove master server of type

Standby Non-HADR

Primary master server is offline. No No


Table 13. Operation - Remove master server (continued)

Cluster status Remove master server of type

Standby Non-HADR

One or more standby master servers areoffline.

• An online standby master server: Youcannot remove this standby masterserver.

• A offline standby master server:

– If more than one standby masterservers are offline, you can removeall except one offline master server.A cluster must have at least onestandby master server.

– If the standby master server is theonly master server other than theprimary master server in the cluster,you can remove it. This scenario is a"Cluster-break" scenario. Theprimary and standby master serverswill now act as standalone servers.

– If the cluster has an offline standbymaster server and a non-HADRmaster server, you cannot removethe offline standby master server.

To remove the offline Standbymaster server (cluster-breakscenario), first remove all the non-HADR master servers, and thenremove the offline standby masterserver.

Yes

Non-HADR master server is offline. Yes Yes

Cluster configuration on the standbymaster server is out of sync.

No

To remove a standby master server,sync the master server that is out ofsync and retry the operation.

Yes

Upgrading IBM Security Key Lifecycle Manager to Version 4.0Complete the following steps to upgrade earlier versions of IBM Security Key Lifecycle Manager to IBMSecurity Key Lifecycle Manager 4.0.

1. Review the supported upgrade path and determine the migration method. If the existing version is notat the minimum fix pack level, apply the latest fix pack for the version.

2. Review and complete pre-upgrade tasks.3. Install IBM Security Key Lifecycle Manager Version 4.0.4. If you installed the target version on another host server, or if you installed the target version silently,

migrate the data.5. Complete the post-upgrade tasks.


Upgrading IBM Tivoli Key Lifecycle Manager to IBM Security Key LifecycleManager 4.0

Upgrading IBM Tivoli Key Lifecycle Manager requires an interim upgrade to IBM Security Key LifecycleManager version 2.5, 2.6, or 2.7 before you can upgrade to version 4.0.

Note: The procedure in this documentation considers interim upgrade to IBM Security Key LifecycleManager version 2.7.

Procedure

Complete the following steps:

1. Review the supported upgrade path and determine the migration method. If the existing version is notat the minimum fix pack level, apply the latest fix pack for the version.

2. To complete interim upgrade, install IBM Security Key Lifecycle Manager version 2.7.3. Review and complete the pre-upgrade tasks.4. Install IBM Security Key Lifecycle Manager V4.0.5. Migrate the data.

You need to migrate the data from IBM Tivoli Key Lifecycle Manager to IBM Security Key LifecycleManager V2.7, and then from the IBM Security Key Lifecycle Manager V2.7 to IBM Security KeyLifecycle Manager V4.0.

6. Complete the post-upgrade tasks.

Upgrading Encryption Key Manager to IBM Security Key Lifecycle Manager4.0

You can upgrade Encryption Key Manager to IBM Security Key Lifecycle Manager version 4.0 (target).

Complete the following steps:

1. Review the upgrade path and determine the migration method.2. Review the restrictions and requirements.3. Complete the pre-upgrade tasks.4. Install the target version.5. If you installed the target version on another host server, or if you skipped data migration during

installation, migrate data.6. Complete post-upgrade tasks.

Restoring the backup file of an earlier version of IBM Security Key LifecycleManager

Use the graphical user interface, command-line interface, REST interface, or the migration restore scriptto restore the backup file of IBM Security Key Lifecycle Manager version 2.5 or later to a system with IBMSecurity Key Lifecycle Manager version 4.0, across operating systems. After restoring the file, datamigration to the system with IBM Security Key Lifecycle Manager V4.0 is complete.

Before you begin

• Ensure that you have the backup file of the IBM Security Key Lifecycle Manager version from which youwant to migrate the data, and ensure that you have the password that was used to create the backupfile.


Note: You must have the required IBM Security Key Lifecycle Manager user role to run the backup andrestore operations.

• Ensure that IBM Security Key Lifecycle Manager, V4.0 is installed on the system to which you want torestore the backed up file.

About this task

Before you start a restore task, isolate the system for maintenance. Take a backup of the existing system.You can later use this backup to bring the system back to original state if any issues occur during therestore process.

The directory names and .bat and .sh file names vary depending on the version of IBM Security KeyLifecycle Manager that you are restoring from.

IBM Security Key LifecycleManager version

Directory with restore utility(sklmv##)

Restore utility file name(restoreV##.bat/restoreV##.sh

3.0.1 sklmv301 • restoreV301.bat• restoreV301.sh

3.0 sklmv30 • restoreV30.bat• restoreV30.sh




Note: For greater security, change the IBM Security Key Lifecycle Manager User password soon after thedata migration process.

Procedure

1. Log in to the system where IBM Security Key Lifecycle Manager V4.0 is installed as the non-administrator or non-root user who is the owner of the Db2 and WebSphere Application Serverservices (For example, sklmdb40).

2. Copy the backup file from the system from which you want to migrate the data in the SKLM_DATAdirectory.You can copy the backup file to any directory in the SKLM_DATA directory as well. In the followingexample, the backup file for IBM Security Key Lifecycle Manager V2.5 is stored directly in theSKLM_DATA directory:

C:\Program Files\IBM\WebSphere\AppServer\products\sklm\data\sklm_v2.5.0.3_20170429013250-0400_migration_backup.jar

3. Restore the backup file by using any of the following methods:


a. Log in to the graphical user interface as an authorized user, for example, SKLMAdmin.b. On the Welcome page, click Administration > Backup and Restore.c. Click Browse to specify the backup file location under <SKLM_DATA> directory.


d. Click Display Backups to display the backup files that you want to restore.e. In the Backup and Restore table, select a backup file.f. Click Restore From Backup.g. On the Restore Backup page, specify the backup password that you used to create the backup

file.h. Click Restore Backup.i. Restart IBM Security Key Lifecycle Manager server.


Note: By using the graphical user interface, you cannot restore roles, users, and groups from IBMSecurity Key Lifecycle Manager backup file.




Windows


Linux


c. Run the tklmBackupRunRestore CLI command by specifying the parameters such as thebackup file name with its full path and backup password that you used to create the backup asshown in the following example.

print AdminTask.tklmBackupRunRestore ('[-backupFilePath <SKLM_DATA>/sklm_v2.5.0.3_20170429013250-0400_migration_backup.jar -password myBackupPwd]')

d. Restart IBM Security Key Lifecycle Manager server.

Note: By using the command-line interface, you cannot restore roles, users, and groups from IBMSecurity Key Lifecycle Manager backup file.

• REST interface

a. Open a REST client.b. Obtain a unique user authentication identifier to access IBM Security Key Lifecycle Manager

REST services.c. Run the Backup Run Restore REST Service. For example.

POST https://localhost:<port>/SKLM/rest/v1/ckms/restore{"backupFilePath":"<SKLM_DATA>/sklm_v2.5.0.3_20170429013250-0400_migration_backup.jar","password":"myBackupPwd"}

d. Restart IBM Security Key Lifecycle Manager server.

Note: By using the REST interface, you cannot restore roles, users, and groups from IBM SecurityKey Lifecycle Manager backup file.

• Migration restore script

a. Locate the IBM Security Key Lifecycle Manager restore utilities.Windows

<SKLM_INSTALL_HOME>\migration\utilities\sklmv##


For example: Default location of IBM Security Key Lifecycle Manager V2.5 is C:\ProgramFiles\IBM\SKLMV40\migration\utilities\sklmv25.

Linux<SKLM_INSTALL_HOME>/migration/utilities/sklmv##For example: Default location of IBM Security Key Lifecycle Manager V2.5 is /opt/IBM/SKLMV40/migration/utilities/sklmv25.

b. Edit the restore.properties file in the sklmv## directory to configure its properties.

Note: On Windows operating system, the restore.properties file that you use for restoreoperations must not contain the property keys and values with leading or trailing spaces.

The following example shows the updated file for IBM Security Key Lifecycle Manager V2.5:Windows

WAS_HOME=C:\\Program Files\\IBM\\WebSphere\\AppServerJAVA_HOME=C:\\Program Files\\IBM\\WebSphere\\AppServer\\java\8.0BACKUP_PASSWORD=passw0rd123DB_PASSWORD=db2_passwordRESTORE_FILE=<SKLM_DATA>\\sklm_v2.5.0.3_20170429013250-0400_migration_backup.jarWAS_USER_PWD=wasadmin_passwordRESTORE_USER_ROLES=y#pkcs11_config=C:\\luna.cfg

Linux

WAS_HOME=/opt/IBM/WebSphere/AppServerJAVA_HOME=/opt/IBM/WebSphere/AppServer/java/8.0BACKUP_PASSWORD=passw0rd123DB_PASSWORD=db2_passwordRESTORE_FILE=<SKLM_DATA>/sklm_v2.5.0.3_20170429013250-0400_migration_backup.jarWAS_USER_PWD=wasadmin_passwordRESTORE_USER_ROLES=y#pkcs11_config=/luna.cfg

Note:

– To log in to IBM Security Key Lifecycle Manager by using the user credentials that arespecified during product installation, set the RESTORE_USER_ROLES property as "n ". Settingthe property to "n " ensures that user ID and the password are not overwritten with the usercredentials of the earlier version.

– If IBM Security Key Lifecycle Manager is configured with HSM, uncomment the#pkcs11_config property and specify the correct path of luna.cfg file as the value.

– On Windows operating system, when you specify path in the properties file, use either "/ " or"\\ " as a path separator. The following example shows the path in IBM Security Key LifecycleManager V2.5 properties file:

C:\\sklmv25_restore

Or

C:/sklmv25_restore

c. Open a command prompt and run the restore utility.Windows

Go to the <SKLM_INSTALL_HOME>\migration\utilities\sklmv## directory and runthe following command:

restoreV##.bat

For example, for V2.5, run the following command:

restoreV25.bat


Linux

1) Go to the <SKLM_INSTALL_HOME>/migration/utilities/sklmv## directory.2) Check whether the restoreV##.sh file has executable permissions. If not, give

permissions by running the following command:

chmod 755 restoreV##.sh

For example, for IBM Security Key Lifecycle Manager v2.5:

chmod 755 restoreV25.sh

3) Run the following command:

restoreV##.sh

For example, for IBM Security Key Lifecycle Manager v2.5:

restoreV25.sh

d. Restart the IBM Security Key Lifecycle Manager server.

Note: By using the migration restore script, you can restore users, groups, and roles from IBMSecurity Key Lifecycle Manager backup file. Ensure that the value of the WAS_USER_PWD parameterfor WebSphere Application Server administrator password in the restore.properties iscorrectly specified. If the password value is incorrect, restore of users, groups, and roles fails.

Note: For greater security, change the IBM Security Key Lifecycle Manager User password soon afterthe data migration process.

Backing up data of an earlier version of IBM Security Key Lifecycle ManagerThe first step to migrate data from your existing IBM Security Key Lifecycle Manager version to V4.0 is toback up the data of the existing version. The next and final step is to restore this backup file to the systemwhere IBM Security Key Lifecycle Manager V4.0 is installed.

Before you begin

• Ensure that the system from which you want to migrate data and create backup has the minimumrequired level of IBM Security Key Lifecycle Manager version already installed.

Note: You must have the required IBM Security Key Lifecycle Manager user role to run the backup andrestore operations.

• Ensure that IBM Security Key Lifecycle Manager, V4.0 is installed on the system to which you want torestore the backed-up file.

About this task

Use the IBM Security Key Lifecycle Manager backup utility to create the backup file. The backup file isindependent of the operating system and directory structure of the server. You can restore this cross-platform-compatible backup file to a system with IBM Security Key Lifecycle Manager, version 4.0 acrossoperating systems.

IBM Security Key Lifecycle Manager stores the transactional data of keys that are served to clients in adatabase table. If the number of records in the table is equal to or greater than 100,000, IBM SecurityKey Lifecycle Manager automatically purges the database table and archives or stores the transactionaldata in a comma-separated values (CSV) file.

The CSV file and a checksum file are included in an archive (JAR) file that is saved in the SKLM_DATA\ServedDataListArchives folder.


Note: The archive file is not included in the cross-platform backup files. If you want the transactional dataof served keys to be backed up and restored, then select the inline migration method.

The directory names and .bat and .sh file names vary depending on the version of IBM Security KeyLifecycle Manager that you are backing up.

IBM Security Key LifecycleManager version

Directory with backup utility(sklmv##)

Backup utility file name(backupV##.bat/backupV##.sh

3.0.1 sklmv301 • backupV301.bat• backupV301.sh

3.0 sklmv30 • backupV30.bat• backupV30.sh




Procedure

1. Run the followings steps on the system where the IBM Security Key Lifecycle Manager version 4.0 isinstalled.

a. Log in to the system with your user credentials.b. Locate the backup utilities folder.

Windows<SKLM_INSTALL_HOME>\migration\utilities\sklmv##

Default location is C:\Program Files\IBM\.SKLMV40\migration\utilities\sklmv##

Linux<SKLM_INSTALL_HOME>/migration/utilities/sklmv##

Default location is /opt/IBM/SKLMV40/migration/utilities/sklmv##.2. Run the followings steps on the system where the earlier version of IBM Security Key Lifecycle

Manager, from where you want to migrate the data, is installed.

a. Log in to the system with your user credentials.b. Copy sklmv## folder from the system where IBM Security Key Lifecycle Manager, Version 4.0 is

installed to a local directory of your choice.c. Edit the backup.properties file in the sklmv## directory to configure the properties. You must

set values for all the properties, except for the BACKUP_DIR property (optional).

If you do not specify the value for BACKUP_DIR, the backup file is created in the backupsubdirectory under the same directory from where you run the backup utility.

Note: On Windows operating system, the backup.properties file that you use for backupoperations must not contain the property keys and values with leading or trailing spaces.

The content in the following examples is from the backup.properties file for IBM Security KeyLifecycle Manager V2.5 with sample password values:


Windows

WAS_HOME=C:\\Program Files (x86)\\IBM\\WebSphere\\AppServerBACKUP_PASSWORD=passw0rd123DB_PASSWORD=sklmdb2_passwordWAS_USER_PWD=wasadmin_passwordBACKUP_DIR=C:\\sklmv25_backup

Linux

WAS_HOME=/opt/IBM/WebSphere/AppServerBACKUP_PASSWORD=passw0rd123DB_PASSWORD=sklmdb2_passwordWAS_USER_PWD=wasadmin_passwordBACKUP_DIR=/sklmv25_backup

Note: On Windows operating system, when you specify path in the properties file, use either "/ " or"\\ " as path separator as shown in following example:

C:\\sklmv25_backup

Or

C:/sklmv25_backup

d. Open a command prompt and run the backup utility.Windows

Go to the sklmv## directory (see Step b) and run the following command:

backupV##.bat

For example: The command for IBM Security Key Lifecycle Manager V2.5:

backupV25.bat

Linux

1) Go to the sklmv## directory (see Step b).2) Check whether the backupV##.sh file has executable permissions. If not, give permissions

by running the following command:

chmod 755 backupV##.sh


chmod 755 backupV25.sh

3) Run the backup utility:

backupV##.sh


backupV25.sh

3. Complete the following verification tasks:

• Review the directory that contains backup files to ensure that the backup file exists. The backup filesare created in the location that you specified for BACKUP_DIR in the backup.properties file.

• Check the backup.log file for errors or exceptions. The backup.log file is created in the samedirectory where you run the backup utility. For a successful backup operation, ensure that there areno errors or exceptions in the log file.

• Retain the backup password for future use in case you restore the backup.• Do not edit a file in the backup archive. The file that you attempt to edit becomes unreadable.


Data objects and properties migrated from IBM Security Key LifecycleManager

Data objects and properties are migrated from earlier versions of IBM Security Key Lifecycle Manager,such as 2.5, 2.6, 2.7, and 3.0.Keystore

The keystore, including all certificates and metadata from earlier versions, are added to the IBMSecurity Key Lifecycle Manager, Version 4.0 database. The keystore is identified by theconfig.keystore.name property in the SKLMConfig.properties file.

DevicesAll the device information is read from the IBM Security Key Lifecycle Manager database.

Key groupsThe key group information is read from the IBM Security Key Lifecycle Manager database.

Rollover certificates and key groupsCertificates and key groups from the earlier versions might be marked for future 3592 tape driveadministration. The migration program detects and marks these rollovers for future administrationwith IBM Security Key Lifecycle Manager, Version 4.0.

MetadataAll the metadata information is migrated from earlier version database and made usable by the IBMSecurity Key Lifecycle Manager, Version 4.0 database.

PropertiesProperties in the SKLMConfig.properties file are migrated from the IBM Security Key LifecycleManager database. The datastore.properties file is migrated.

These properties are replaced in the version 4.0 SKLMConfig.properties file:

• ds8k.acceptUnknownDrives

The device.AutoPendingAutoDiscovery property replaces this property.• drive.acceptUnknownDrives

The device.AutoPendingAutoDiscovery attribute in the IBM Security Key Lifecycle Managerdatabase replaces this property.

These properties are migrated from the version 4.0 SKLMConfig.properties file to the IBM SecurityKey Lifecycle Manager database:

• drive.default.alias1• drive.default.alias2• symmetricKeySet (removed from the SKLMConfig.properties file and replaced with an entry for

the device group in the IBM Security Key Lifecycle Manager database)



Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer theproducts, services, or features discussed in this document in other countries. Consult your local IBMrepresentative for information on the products and services currently available in your area. Anyreference to an IBM product, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product, program, or service thatdoes not infringe any IBM intellectual property right may be used instead. However, it is the user'sresponsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not give you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785 US

For license inquiries regarding double-byte character set (DBCS) information, contact the IBM IntellectualProperty Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law :

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR APARTICULAR PURPOSE.

Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions,therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119

© Copyright IBM Corp. 2008, 2019 139

Armonk, NY 10504-1785US

Such information may be available, subject to appropriate terms and conditions, including in some casespayment of a fee.

The licensed program described in this document and all licensed material available for it are provided byIBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or anyequivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurement may have been estimatedthrough extrapolation. Actual results may vary. Users of this document should verify the applicable datafor their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©Copyright IBM Corp. _enter the year or years_.

If you are viewing this information in softcopy form, the photographs and color illustrations might not bedisplayed.

Terms and conditions for product documentationPermissions for the use of these publications are granted subject to the following terms and conditions.Applicability

These terms and conditions are in addition to any terms of use for the IBM website.


Personal useYou may reproduce these publications for your personal, noncommercial use provided that allproprietary notices are preserved. You may not distribute, display or make derivative work of thesepublications, or any portion thereof, without the express consent of IBM.

Commercial useYou may reproduce, distribute and display these publications solely within your enterprise providedthat all proprietary notices are preserved. You may not make derivative works of these publications,or reproduce, distribute or display these publications or any portion thereof outside your enterprise,without the express consent of IBM.

RightsExcept as expressly granted in this permission, no other permissions, licenses or rights are granted,either express or implied, to the publications or any information, data, software or other intellectualproperty contained therein.IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the useof the publications is detrimental to its interest or, as determined by IBM, the above instructions arenot being properly followed.You may not download, export or re-export this information except in full compliance with allapplicable laws and regulations, including all United States export laws and regulationsIBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONSARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the web at http://www.ibm.com/legal/copytrade.shtml.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered trademarks ortrademarks of Adobe Systems Incorporated in the United States, other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer and TelecommunicationsAgency which is now part of the Office of Government Commerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon,Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation orits subsidiaries in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

ITIL is a registered trademark, and a registered community trademark of the Office of GovernmentCommerce, and is registered in the U.S. Patent and Trademark Office.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/orits affiliates.

Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, othercountries, or both and is used under license therefrom.

Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. andQuantum in the U.S. and other countries.

Notices 141

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml


IBM®

Product Number:

Documents

IBM Security Key Lifecycle Manager : Scenarios · Use the IBM Security Key Lifecycle Manager installation program and repeat the same steps that you took on the primary computer