IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Setting up a public key infrastructure

Configure keystores, truststores, passwords, and certificates to enable SSL communication, and Web Services Security.

Decide how you will use the public key infrastructure (PKI). You can configure keystores and truststores at either broker level (one keystore, one truststore, and one personal certificate for each broker) or at integration server level (one keystore, one truststore, and one personal certificate for each integration server). Integration servers that do not have PKI configured use the broker-level PKI configuration.

Encryption strength

The IBM® Integration Bus Java™ runtime environment (JRE) is provided with strong but limited strength encryption. If you cannot import keys into keystores, limited strength encryption might be the cause. Either start ikeyman by using the strmqikm command, or download unrestricted jurisdiction policy files from IBM developer kits: Security information.

Important: Your country of origin might have restrictions on the import, possession, use, or re-export to another country, of encryption software. Before you download or use the unrestricted policy files, you must check the laws of your country. Check its regulations and its policies on the import, possession, use, and re-export of encryption software, to determine whether it is permitted. Note that when you apply a fix pack to an existing IBM Integration Bus installation, the JVM is overwritten, including any updated policy set files. These policy set files must be restored before you restart the broker.

IBM Integration Bus currently supports up to 4096 bit keys. Larger keys require more CPU resources for encryption and decryption.

This topic uses the command line tool, gsk7cmd, to create and populate keystores and truststores. The gsk7cmd tool is a part of the Global Secure Toolkit, supplied with WebSphere® MQ. Other options, which are supplied with the IBM Integration Bus JVM, include the following:

A command-line tool, keytool.
A graphical tool, iKeyman.

To create the infrastructure, complete the following tasks:

Creating a keystore file or a truststore
Creating a self-signed certificate for test use
Importing a certificate for production use
Viewing details of a certificate
Extracting a certificate
Adding a signer certificate to the truststore
Listing all certificates in a keystore
Configuring PKI at broker level
Configuring PKI for the broker-wide HTTP listener
Configuring PKI at an integration server level

Creating a keystore file or a truststore

The keystore file contains the personal certificate for the broker or for the integration server. You can have only one personal certificate in the keystore. You can store signer certificates in the same file, or create a separate file, which is known as a truststore.

Set the JAVA_HOME environment variable. For example,
```
set JAVA_HOME=install_dir\MQSI\9.0\jre17
```

Issue the following command:

gsk7cmd -keydb -create
  -db keystore_name
  [-pw password]
  -type jks

The password argument is optional. If you omit it, you are prompted to enter a password. For example:

gsk7cmd -keydb -create
  -db myBrokerKeystore.jks
  -type jks
A password is required to access this key database.
Please enter a password:

Creating a self-signed certificate for test use

Use self-signed certificates only for testing SSL, not in production.

Enter the following command:

gsk7cmd -cert -create
  -db keystore_name
  [-pw password] 
  -label cert_label
  -dn "distinguished_name"

For example:

gsk7cmd -cert -create
  -db myBrokerKeystore.jks
  -label MyCert
  -dn "CN=MyBroker.Server,O=IBM,OU=ISSW,L=Hursley,C=GB"
A password is required to access this key database.
Please enter a password:

Importing a certificate for production use

Import a personal certificate from a certificate authority for production use.

Issue the following command:

gsk7cmd -cert -import
  -db pkcs12_file_name
  [-pw pkcs12_password]
  -label label 
  -type pkcs12
  -target keystore_name
  [-target_pw keystore_password]

If you are going to use the keystore for inbound https connections, then ensure that you always specify a target_pw, and that it matches the password required to access the key database (keystore). For example:

gsk7cmd -cert -import
  -db SOAPListenerCertificate.p12
  -label soaplistener
  -type pkcs12 
  -target myBrokerKeystore.jks
  -target_pw  myBrokerKpass
A password is required to access this key database.
Please enter a password:

Viewing details of a certificate

Issue the following command:

gsk7cmd -cert -details
  -db keystore_name
  [-pw password]
  -label label

For example:

gsk7cmd -cert -details
  -db myKeyStore.jks
  -label MyCert
A password is required to access this key database.
Please enter a password:

Label: MyCert
Key Size: 1024
Version: X509 V3
Serial Number: 4A D7 39 1F
Issued By: MyBroker.Server
ISSW
IBM
Hursley, GB
Subject: MyBroker.Server
ISSW
IBM
Hursley, GB
Valid From: 15 October 2009 16:00:47 o'clock BST To: 15 October 2010 16:00:47 o'
clock BST
Fingerprint: 98:5D:C4:70:A0:28:84:72:FB:F6:3A:D2:D2:F5:EE:8D:30:33:87:82
Signature Algorithm: 1.2.840.113549.1.1.4
Trust Status: enabled

Extracting a certificate

Generate a copy of a self-signed certificate that you can import as a trusted (or signer certificate) into a truststore file. Use this procedure only for testing, not production.

Certificates can be extracted in two formats:

Base64-encoded ASCII data (.arm). This format is convenient for inclusion in XML messages, and transmission over the Internet.
Binary DER data (.der).

Issue the following command:

gsk7cmd -cert -extract
  -db keystore_name
  -pw keystore_passwd
  -label label
  -target file_name
  [-format ascii | binary]

For example:

gsk7cmd -cert -extract
  -db myBrokerKeystore.jks
  -pw myKeyPass
  -label MyCert 
  -target MyCert.arm
  -format ascii

You can then view the certificate in a text editor, such as Notepad:

notepad MyCert.arm
-----BEGIN CERTIFICATE-----
MIICIzCCAYygAwIBAgIEStc5HzANBgkqhkiG9w0BAQQFADBWMQswCQYDVQQGEwJHQjEQMA4GA1UE
BxMHSHVyc2xleTEMMAoGA1UEChMDSUJNMQ0wCwYDVQQLEwRJU1NXMRgwFgYDVQQDEw9NeUJyb2tl
ci5TZXJ2ZXIwHhcNMDkxMDE1MTUwMDQ3WhcNMTAxMDE1MTUwMDQ3WjBWMQswCQYDVQQGEwJHQjEQ
MA4GA1UEBxMHSHVyc2xleTEMMAoGA1UEChMDSUJNMQ0wCwYDVQQLEwRJU1NXMRgwFgYDVQQDEw9N
eUJyb2tlci5TZXJ2ZXIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMwkK5kFLwC29YsHLXlf
hd0CgqFeytHlI0sZesdi8hEPXKsOzs3OQta2b0GZyUbBkh4tNeUHNWE9o7Hx2/SfziPQRKUw908R
F/6FPaHGezRkkaLJGX3uEhjt/2+n5tOJGytnKWaWJTpzdmZ79c0XjFvO83q3yXPYjKzq8rS1iVBf
AgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAQEjpvZkjRcg3AHqY4RWbSMtXVWFFyoHSbjymR8IdURoQ
DCGZ2jsv3kxQLADaCXOBYgohGJAHS7PzkQoHUCiHR0kusyuAt1MNYbhEcs+BYAzvsSz1ay4oiqCw
Qs3aeNLVOb9c1RyzbuKYZl0uX59GAfGVLvyk6vQ/g7wPVL4TVgc=
-----END CERTIFICATE-----

Adding a signer certificate to the truststore

Add a signer certificate to the truststore of a broker or integration server.

The following steps show how to add an extracted certificate as signer certificate to the truststore file. Adding the broker self-signed certificate to a broker or integration server truststore enables request nodes (HTTP or SOAP) to send test messages to input nodes (HTTP or SOAP) when the flows are running on the broker or integration server.

Issue the following command:

gsk7cmd -cert -add
  -db truststore_name
  [-pw password]
  -label label 
  -file file_name
  -format [ascii | binary]

For example:

gsk7cmd -cert -add
  -db myBrokerTruststore.jks
  -label CACert 
  -file TRUSTEDPublicCerticate.arm
  -format ascii

You can view details of the certificate:

gsk7cmd -cert -details -db myBrokerTruststore.jks -label CACert
A password is required to access this key database.
Please enter a password:

Label: CACert
Key Size: 1024
Version: X509 V3
Serial Number: 49 49 23 1B
Issued By: VSR1BK
ISSW
IBM
GB
Subject: VSR1BK
ISSW
IBM
GB
Valid From: 17 December 2008 16:04:43 o'clock GMT To: 17 December 2009 16:04:43
o'clock GMT
Fingerprint: CB:39:E7:D8:1D:C0:00:A1:3D:B1:97:69:7A:A7:77:19:6D:09:C2:A7
Signature Algorithm: 1.2.840.113549.1.1.4
Trust Status: enabled

Listing all certificates in a keystore

Issue the following command:

gsk7cmd -cert -list
  -db keystore_name

For example:

gsk7cmd -cert -list
  -db myBrokerKeystore.jks
A password is required to access this key database.
Please enter a password:

Certificates in database: myBrokerKeystore.jks
    verisign class 1 public primary certification authority - g3
    verisign class 4 public primary certification authority - g3
    verisign class 1 public primary certification authority - g2
    verisign class 4 public primary certification authority - g2
    verisign class 2 public primary certification authority
    entrust.net global client certification authority
    rsa secure server certification authority
    verisign class 2 public primary certification authority - g3
    verisign class 2 public primary certification authority - g2
    verisign class 3 secure server ca
    verisign class 3 public primary certification authority
    verisign class 3 public primary certification authority - g3
    verisign class 3 public primary certification authority - g2
    thawte premium server ca
    verisign class 1 public primary certification authority
    entrust.net global secure server certification authority
    thawte personal basic ca
    thawte personal premium ca
    thawte personal freemail ca
    verisign international server ca - class 3
    thawte server ca
    entrust.net certification authority (2048)
    cacert
    entrust.net client certification authority
    entrust.net secure server certification authority
    soaplistener
    mycert

Configuring PKI at broker level

Define the broker registry properties that identify the location, name, and password of the keystore and truststore files.

These settings are used as the default settings for the broker-wide HTTP listener and all embedded HTTP listeners in integration servers on the broker. These settings can be overridden for the broker-wide HTTP listener (see Configuring PKI for the broker-wide HTTP listener) and for individual embedded HTTP listeners (see Configuring PKI at an integration server level).

Start the broker:
```
mqsistart broker_name
```

Display the current settings of the broker registry properties:

mqsireportproperties broker_name 
  -o BrokerRegistry
  –r

Set the keystore property:

mqsichangeproperties broker_name
  -o BrokerRegistry
  -n brokerKeystoreFile
  -v install_dir\MQSI\9.0\MyBrokerKeystore.jks

Set the truststore property:

mqsichangeproperties broker_name
  -o BrokerRegistry
  -n brokerTruststoreFile
  -v install_dir\MQSI\9.0\MyBrokerTruststore.jks

Stop the broker:
```
mqsistop broker_name
```

Set the password for the keystore:

mqsisetdbparms broker_name
  -n brokerKeystore::password
  -u ignore
  -p keystore_pass

Set the password for the truststore:

mqsisetdbparms broker_name
  -n brokerTruststore::password
  -u ignore
  -p truststore_pass

Start the broker:
```
mqsistart broker_name
```

Display and verify the broker registry properties:

mqsireportproperties broker_name
  -o BrokerRegistry 
  –r

Configuring PKI for the broker-wide HTTP listener

Define the properties for the broker-wide HTTP listener to identify the location, name, and password of the keystore and truststore files.

These settings override any PKI configuration that is set at the broker level. If you enable SSL on the broker-wide HTTP listener but do not set the following properties, then the broker-level settings are applied, see Configuring PKI at broker level.

Start the broker.
```
mqsistart broker_name
```

Display the current settings of the broker-wide listener properties.

mqsireportproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -a

Set the keystore property.

mqsichangeproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -n keystoreFile 
  -v install_dir\MQSI\9.0\MyBrokerKeystore.jks

Set the truststore property.

mqsichangeproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -n truststoreFile 
  -v install_dir\MQSI\9.0\MyBrokerTruststore.jks

Set the password for the keystore.

mqsichangeproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -n keystorePass 
  -v keystore_pass

Set the password for the truststore.

mqsichangeproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -n truststorePass 
  -v truststore_pass

Display and verify the broker-wide listener properties.

mqsireportproperties broker_name 
  -b httplistener 
  -o HTTPSConnector 
  -a

Configuring PKI at an integration server level

Define the ComIbmJVMManager properties for the required integration server to identify the location, name, and password of the keystore and truststore files.

These settings override any PKI configuration that is set at the broker level. If you enable SSL on an embedded HTTP listener but do not set the following properties, then the broker-level settings are applied, see Configuring PKI at broker level.

Start the broker.
```
mqsistart broker_name
```

Display the current settings of the ComIbmJVMManager properties.

mqsireportproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager 
  -r

Set the keystore property.

mqsichangeproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager
  -n keystoreFile 
  -v install_dir\MQSI\9.0\MyExecGrpKeystore.jks

Set the keystore password key property. The value for this property is in the format any_prefix_name::password. This value is used to correlate the password that is defined in the mqsisetdbparms command.
```
mqsichangeproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager
  -n keystorePass
  -v exec_grp_nameKeystore::password
```

Set the truststore property.

mqsichangeproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager
  -n truststoreFile 
  -v install_dir\MQSI\9.0\MyExecGrpTruststore.jks

Set the truststore password key property. The value for this property is in the format any_prefix_name::password. This value is used to correlate the password that is defined in the mqsisetdbparms command.
```
mqsichangeproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager
  -n truststorePass
  -v exec_grp_nameTruststore::password
```
Stop the broker.
```
mqsistop broker_name
```

Set the password for the keystore.

mqsisetdbparms broker_name
  -n exec_grp_nameKeystore::password
  -u ignore
  -p keystore_pass

Set the password for the truststore.

mqsisetdbparms broker_name
  -n exec_grp_nameTruststore::password
  -u ignore
  -p truststore_pass

Start the broker.
```
mqsistart broker_name
```

Display and verify the ComIbmJVMManager properties.

mqsireportproperties broker_name
  -e exec_grp_name
  -o ComIbmJVMManager 
  -r

For information about cipher-suite requirements (such as the cryptographic algorithm and corresponding key lengths), see the Java Secure Socket Extension (JSSE) IBMJSSE2 Provider reference guide.

ap34020_.htm |

Last updated Friday, 21 July 2017

Setting up a public key infrastructure

Subtopics

Creating a keystore file or a truststore

Creating a self-signed certificate for test use

Importing a certificate for production use

Viewing details of a certificate

Extracting a certificate

Adding a signer certificate to the truststore

Listing all certificates in a keystore

Configuring PKI at broker level

Configuring PKI for the broker-wide HTTP listener

Configuring PKI at an integration server level