Setting up a public key infrastructure
Configure keystores, truststores, passwords, and certificates to enable SSL communication, and web services security.
Before you begin
- Make sure you understand the purpose of certificates, keystores and truststores; see Digital certificates.
- Decide how you will use the public key infrastructure (PKI). You
can configure keystores and truststores at the following
levels:
- integration node level (one keystore, and one truststore for each integration node).
- integration node listener level (one keystore and one truststore for the integration node listener in an integration node).Integration node listeners that do not have a PKI configured use the integration node level PKI configuration.
- integration server level (one keystore and one truststore for each integration server). Integration servers that do not have a PKI configured use the integration node level PKI configuration.
- embedded listener level (one keystore and one truststore for the embedded listener in an integration server). Embedded listeners that do not have a PKI configured use the integration server level PKI configuration. If there is no integration server level PKI configuration, then the embedded listener uses the integration node 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.
For information about how to update your security JAR files, see Downloading and installing the unrestricted JCE policy files.
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 integration node.
IBM Integration Bus currently supports up to 4096 bit keys. Larger keys require more CPU resources for encryption and decryption.
About this task
- A command-line tool, keytool.
- A graphical tool, iKeyman.
- Creating a keystore file or a truststore
- Either Creating a self-signed certificate for test use or 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 integration node level
- Configuring PKI for the integration node 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 integration node 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.
Procedure
Creating a self-signed certificate for test use
Use self-signed certificates only for testing SSL, not in production.
Procedure
gsk7cmd -cert -create
-db keystore_name
[-pw password]
-label cert_label
-dn "distinguished_name"
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.
Procedure
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).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
Procedure
gsk7cmd -cert -details
-db keystore_name
[-pw password]
-label label
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.
About this task
- Base64-encoded ASCII data (.arm). This format is convenient for inclusion in XML messages, and transmission over the Internet.
- Binary DER data (.der).
Procedure
gsk7cmd -cert -extract
-db keystore_name
-pw keystore_passwd
-label label
-target file_name
[-format ascii | binary]
gsk7cmd -cert -extract
-db myBrokerKeystore.jks
-pw myKeyPass
-label MyCert
-target MyCert.arm
-format ascii
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 an integration node or integration server.
About this task
The following steps show how to add an extracted certificate as signer certificate to the truststore file. Adding the integration node self-signed certificate to an integration node 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 integration node or integration server.
Procedure
gsk7cmd -cert -add
-db truststore_name
[-pw password]
-label label
-file file_name
-format [ascii | binary]
gsk7cmd -cert -add
-db myBrokerTruststore.jks
-label CACert
-file TRUSTEDPublicCerticate.arm
-format ascii
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
Procedure
gsk7cmd -cert -list
-db keystore_name
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 integration node level
Define the integration node registry properties that identify the location, name, and password of the keystore and truststore files.
About this task
- Start the integration node:
mqsistart integrationNodeName
- Display the current settings of the integration node registry
properties:
mqsireportproperties integrationNodeName -o BrokerRegistry -r
- Set the keystore property:
mqsichangeproperties integrationNodeName -o BrokerRegistry -n brokerKeystoreFile -v install_dir\MyBrokerKeystore.jks
- Set the truststore property:
mqsichangeproperties integrationNodeName -o BrokerRegistry -n brokerTruststoreFile -v install_dir\MyBrokerTruststore.jks
- Stop the integration node:
mqsistop integrationNodeName
- Set the password for the keystore:
mqsisetdbparms integrationNodeName -n brokerKeystore::password -u ignore -p keystore_pass
- Set the password for the truststore:
mqsisetdbparms integrationNodeName -n brokerTruststore::password -u ignore -p truststore_pass
- Start the integration node:
mqsistart integrationNodeName
- Display and verify the integration node registry properties:
mqsireportproperties integrationNodeName -o BrokerRegistry -r
Configuring PKI for the integration node HTTP listener
Define the properties for the integration node HTTP listener to identify the location, name, and password of the keystore and truststore files.
About this task
- Start the integration node.
mqsistart integrationNodeName
- Display the current settings of the integration node listener
properties.
mqsireportproperties integrationNodeName -b httplistener -o HTTPSConnector -a
- Set the keystore property.
mqsichangeproperties integrationNodeName -b httplistener -o HTTPSConnector -n keystoreFile -v install_dir\MyBrokerKeystore.jks
- Set the truststore property.
mqsichangeproperties integrationNodeName -b httplistener -o HTTPSConnector -n truststoreFile -v install_dir\MyBrokerTruststore.jks
- Set the password for the keystore.
mqsichangeproperties integrationNodeName -b httplistener -o HTTPSConnector -n keystorePass -v keystore_pass
- Set the password for the truststore.
mqsichangeproperties integrationNodeName -b httplistener -o HTTPSConnector -n truststorePass -v truststore_pass
- Display and verify the integration node listener properties.
mqsireportproperties integrationNodeName -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.
About this task
- Start the integration node.
mqsistart integrationNodeName
- Display the current settings of the ComIbmJVMManager properties.
mqsireportproperties integrationNodeName -e exec_grp_name -o ComIbmJVMManager -r
- Set the keystore property.
mqsichangeproperties integrationNodeName -e exec_grp_name -o ComIbmJVMManager -n keystoreFile -v install_dir\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 integrationNodeName -e exec_grp_name -o ComIbmJVMManager -n keystorePass -v exec_grp_nameKeystore::password
- Set the truststore property.
mqsichangeproperties integrationNodeName -e exec_grp_name -o ComIbmJVMManager -n truststoreFile -v install_dir\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 integrationNodeName -e exec_grp_name -o ComIbmJVMManager -n truststorePass -v exec_grp_nameTruststore::password
- Stop the integration node.
mqsistop integrationNodeName
- Set the password for the keystore.
mqsisetdbparms integrationNodeName -n exec_grp_nameKeystore::password -u ignore -p keystore_pass
- Set the password for the truststore.
mqsisetdbparms integrationNodeName -n exec_grp_nameTruststore::password -u ignore -p truststore_pass
- Start the integration node.
mqsistart integrationNodeName
- Display and verify the ComIbmJVMManager properties.
mqsireportproperties integrationNodeName -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.