Setting up a public key infrastructure
Configure keystores, truststores, passwords, and certificates to enable SSL communication, and web services security.
Before you begin
- For an overview of encryption and public key infrastructure (PKI), see Public key cryptography.
- Make sure that you understand the purpose of certificates, keystores, and truststores; see Digital certificates.
- Decide how you want to use the 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 each listener in an
integration node). Integration node listeners that do not have a PKI configured use the integration
node level PKI configuration.
If you use an integration node listener, you must specify a default queue manager for the integration node. For more information, see Interaction between IBM App Connect Enterprise and IBM MQ.
- Integration server level (one keystore and one truststore for each integration server). For integration servers under an integration node, if a PKI is not configured at the integration server level, the integration node level PKI configuration is used.
- Integration server listener level (one keystore and one truststore for each listener in an integration server). Integration server listeners that do not have a PKI configured use the integration server level PKI configuration. For integration servers under an integration node, if a PKI is not configured at either the integration server listener level or the integration server level, the integration node level PKI configuration is used.
Encryption strength
The IBM App Connect Enterprise 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.
IBM App Connect Enterprise currently supports up to 4096 bit keys. Larger keys require more CPU resources for encryption and decryption.
About this task
This topic uses the command line tool keytool to create and populate keystores and truststores. The keytool is a part of the Java Runtime Environment, which is supplied with IBM App Connect Enterprise and is located in the common/jdk/bin/keytool subdirectory of the installation directory.
The IBM App Connect Enterprise JVM also supplies a graphical tool, iKeyman. If IBM MQ
is installed the Global Secure Toolkit command gsk8capicmd_64
, can also be used.
Instructions for this are included in this document.
- Creating an empty keystore file or a truststore. When you use keytool, this step is not necessary but it is useful when you use GSKit.
- 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 an empty 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
Importing a certificate for production use
Import a personal certificate from a certificate authority for production use.
Procedure
keytool -importkeystore -srckeystore pkcs_file_name.p12 -srcstoretype pkcs12 -destkeystore keystore_name.jks -deststoretype jks [ -srcstorepass pw ] [ -deststorepass new_pw ]
For
example:keytool -importkeystore -srckeystore SOAPListenerCertificate.p12 -srcstoretype pkcs12 -destkeystore myBrokerKeystore.jks -deststoretype jks -deststorepass myBrokerKpass
When prompted, enter the keystore password.
Entry for alias Listener successfully imported.
Import command completed: 1 entries successfully imported, 0 entries failed or cancelled.
Viewing details of a certificate
View the details of a certificate to verify that they are correct and appropriate for your needs.
Procedure
keytool -v -list -keystore keystore_name.jks [-alias label]
keytool -v -list -keystore keystore_name.jks -alias mycert
When you are prompted, enter the keystore password. The output from the command is similar to the following example:
Alias name: mycert
Creation date: Sep 15, 2022
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=aceserver.ibm.com, O=IBM, OU=ISSW, L=Hursley, C=GB
Issuer: CN=aceserver.ibm.com, O=IBM, OU=ISSW, L=Hursley, C=GB
Serial number: 4cd1355a
Valid from: 9/15/22 2:01 PM until: 9/12/32 2:01 PM
Certificate fingerprints:
MD5: F8:D6:41:BC:71:66:AA:7B:48:70:5F:33:57:3C:8E:4B
SHA1: 24:1C:DD:25:2B:FE:8A:A7:DF:6B:B7:70:96:8D:08:06:74:D5:C6:54
SHA256: F1:D2:2C:BB:92:57:D5:E8:3F:0D:EC:F0:78:4B:9C:30:AE:02:54:7B:7C:57:5D:85:F5:5A:09:CD:CD:2C:81:DE
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.15 Criticality=false
KeyUsage [
DigitalSignature
Key_Encipherment
Data_Encipherment
Key_Agreement
]
#2: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: cb b0 39 f8 21 e2 73 70 2b b5 ea 78 6e 99 24 67 ..9...sp...xn..g
0010: 61 72 cf dc ar..
]
]
#3: ObjectId: 2.5.29.37 Criticality=false
ExtKeyUsage [
1.3.6.1.5.5.7.3.1 1.3.6.1.5.5.7.3.2]
#4: ObjectId: 2.5.29.17 Criticality=true
SubjectAlternativeName [
[DNSName: aceserver.ibm.com]]
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 (.pem). This format is convenient for inclusion in XML messages, and transmission over the Internet.
- Binary DER data (.der).
Procedure
keytool -exportcert -keystore keystore_name.jks -alias MyCert -rfc -file file_name.pem
keytool -exportcert -keystore keystore_name.jks -alias MyCert -rfc -file server.pem
When prompted, enter the keystore password.
notepad server.pem
-----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 a 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
keytool -import -trustcacerts -file file_name.pem -alias label -keystore truststore.jks -trustcacerts
keytool -import -file server.pem -alias aceserver -keystore truststore.jks -trustcacerts
- Enter keystore password:
- Re-enter new password:
Owner: CN=aceserver.ibm.com, O=IBM, OU=ISSW, L=Hursley, C=GB
Issuer: CN=aceserver.ibm.com, O=IBM, OU=ISSW, L=Hursley, C=GB
Serial number: 4cd1355a
Valid from: 9/15/22 2:01 PM until: 9/12/32 2:01 PM
Certificate fingerprints:
MD5: F8:D6:41:BC:71:66:AA:7B:48:70:5F:33:57:3C:8E:4B
SHA1: 24:1C:DD:25:2B:FE:8A:A7:DF:6B:B7:70:96:8D:08:06:74:D5:C6:54
SHA256: F1:D2:2C:BB:92:57:D5:E8:3F:0D:EC:F0:78:4B:9C:30:AE:02:54:7B:7C:57:5D:85:F5:5A:09:CD:CD:2C:81:DE
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.15 Criticality=false
KeyUsage [
DigitalSignature
Key_Encipherment
Data_Encipherment
Key_Agreement
]
#2: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: cb b0 39 f8 21 e2 73 70 2b b5 ea 78 6e 99 24 67 ..9...sp...xn..g
0010: 61 72 cf dc ar..
]
]
#3: ObjectId: 2.5.29.37 Criticality=false
ExtKeyUsage [
1.3.6.1.5.5.7.3.1 1.3.6.1.5.5.7.3.2]
#4: ObjectId: 2.5.29.17 Criticality=true
SubjectAlternativeName [
[DNSName: aceserver.ibm.com]]
Trust this certificate? [no]: yes
Certificate was added to keystore
Listing all certificates in a keystore
Procedure
keytool -list -keystore keystore_name.jks
keytool -list -keystore truststore.jks
When you are prompted, enter the keystore password.
Keystore type: jks
Keystore provider: IBMJCE
Your keystore contains 1 entry
aceserver, Sep 15, 2022, trustedCertEntry,
Certificate fingerprint (SHA1): 24:1C:DD:25:2B:FE:8A:A7:DF:6B:B7:70:96:8D:08:06:74:D5:C6:54
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 NodeHttpListener -o HTTPSConnector -a
- Set the keystore
property.
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -n keystoreFile -v install_dir\MyBrokerKeystore.jks
- Set the truststore
property.
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -n truststoreFile -v install_dir\MyBrokerTruststore.jks
- Set the password for the
keystore.
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -n keystorePass -v keystore_pass
- Set the password for the
truststore.
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -n TruststorePassword -v truststore_pass
- Display and verify the integration node listener
properties.
mqsireportproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -a
Configuring PKI at an integration server level
Define the properties for the integration server HTTP listener to identify the location, name, and password of the keystore and truststore files.
About this task
If you enable SSL for the integration server HTTP listener but do not set the following properties, then the integration node-level settings are applied, see Configuring PKI at integration node level.
- 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 brokerKeystore::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 brokerTruststore::password
- 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 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.