IBM Support

Secure Communication Setting in IIB over SSL/TLS

How To


Summary

IBM Integration Bus (IIB) provides several interfaces for connecting to/from other endpoints. This "How To" guide provides step-by-step instructions for configuring several of these interfaces for secure connections to/from using SSL/TLS.

Objective

IIB uses Java Secure Sockets Extension (JSSE) for secure connections and requires the use of JKS or PKCS12 keystores.
Note the difference between "keystore" and "truststore".
  • A keystore is used to hold certificates to be provided to other endpoints (eg. when IIB acts as a webservice and provides a server certificate, or when IIB acts as a client during two-way authentication).
  • A truststore is used to hold "signer certificates" from endpoints that IIB should trust (eg. when IIB acts as a web client and receives a server certificate, or when IIB acts as a server during two-way authentication).
These instructions detail how to configure keystores and truststores, as well as other optional settings, such as port numbers, cipher lists, or protocol restrictions.

Steps

The exact steps you will need depend on the interface you are attempting to secure:

Securing the IIB Web User Interface

The Web User Interface (WebUI) is a web-based administration portal provided as an alternative to the command line interface. Use these instructions to secure browser connections to the WebUI.
Note that these steps are also covered (and expanded on) in IIBv10 Self-study Lab 10: WebAdministration Interface and File-based Security.

  1. Verify the current configuration

    mqsireportproperties IIBNODE -b webadmin -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  algorithm='Platform Default'
  clientAuth='Platform Default'
  keystoreFile=''
  keystorePass=''
  keystoreType='Platform Default'
  truststoreFile=''
  truststorePass=''
  truststoreType='Platform Default'
  sslProtocol='Platform Default'
  ciphers='Platform Default'
  keyAlias='Platform Default'
  keypass=''
  sessionCacheSize=''
  crlFile='Platform Default'
  address=''
  port=''
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests=''
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay=''
  enableLookups='false'
  serverName=''
  accessLog=''
  accessLogPattern=''

  2. Check to see whether SSL is enabled or not

    mqsireportproperties IIBNODE -b webadmin -o server -a
server=''
  uuid='server'
  enabled='true'
  ldapAuthenticationUri=''
  sessionMaxInactiveAgeSecs=''
  enableSSL=''

  3. Enable SSL if needed

    mqsichangeproperties IIBNode -b webadmin -o server -n enabled,enableSSL -v true,true

  4. Configure the keyststore type

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n keystoreType -v JKS

    If using a keystore with a .p12 extension, set the type to PKCS12.

  5. Configure the truststore type

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n truststoreType -v JKS

    If using a truststore with a .p12 extension, set the type to PKCS12.

  6. (OPTIONAL) Configure the connection port number to be used

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n port -v 1077

    You can use any unclaimed port, avoid the first 1000 (usually OS reserved). Use netstat -an to see in use ports. By default, all webuis will use the same port (4414), which results in a failure for all but the first to start. Use unique ports for each node.

  7. Configure the SSL protocol to be used

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n sslProtocol -v TLSv1.2

    Valid protocols are: TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, SSL_TLSv2, SSL, SSLv3

    Protocol Value used Notes
    TLS TLS v1.0 Default. If you use the Java option com.ibm.jsse2.overrideDefaultTLS=true, the value is all TLS versions (v1.0, v1.1, and v1.2).
    TLSv1 TLS v1.0
    TLSv1.1 TLS v1.1 No fallback to TLS v1.0.
    TLSv1.2 TLS v1.2 No fallback to TLS v1.0 or v1.1.
    SSL_TLS TLS v1.0, SSL v3 No fallback to SSL v2
    SSL_TLSv2 TLS v1.0, TLS v1.1, TLS v1.2, SSL v3 No fallback to SSL v2.
    SSL TLS v1.0, TLS v1.1, TLS v1.2 Despite the name, this is for all TLS versions, not SSL.
    SSLv3 SSL v3 Fallback to SSL v2 allowed. Disabled unless you set the Java option com.ibm.jsse2.disableSSLv3=false. If you use the Java option com.ibm.jsse2.convertSSLv3=true, the value is SSL v3 and all TLS versions (v1.0, v1.1, and v1.2).

  8. Set the path to the keystore file

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n keystoreFile -v /var/mqsi/SSL/keystore.jks

    Use the absolute path to the keystore, make sure the IIB user id has read permissions at least. There is a default value, but do not use it.

  9. Set the path to the truststore file

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n truststoreFile -v /var/mqsi/SSL/truststore.jks

    Use the absolute path to the truststore, make sure the IIB user id has read permissions at least. The default is <IIB_Install_path>/common/jdk/jre/lib/security/cacerts which has many common signer certificates prepopulated. You can add to this, import it into your own, or ignore it. If you use the default, keep in mind it will change with each fix pack and version, so you may want to point this property explicitly to the default if you decide to use it so you can be sure which copy is in use.

  10. Configure the keystore password

    mqsisetdbparms IIBNODE -n brokerKeystore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n keystorePass -v brokerKeystore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerKeystore::, for example: brokerKeystore::webuipassword. Changing the first part may have unexpected results

  11. Configure the truststore password

    mqsisetdbparms IIBNODE -n brokerTruststore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n truststorePass -v brokerTruststore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerTruststore::, for example: brokerTruststore::webuipassword. Changing the first part may have unexpected results

    The password for the default truststore is changeit

  12. (OPTIONAL) Set client authentication

    mqsichangeproperties IIBNODE -b webadmin -o HTTPSConnector -n clientAuth -v true

    Required only for two-way SSL or mutual authentication setup, where the client certificate is required . Do not set this to true if you are doing one-way SSL, server only certificates.

  13. Verify your configuration

    mqsireportproperties IIBNODE -b webadmin -o server -a
server=''
  uuid='server'
  enabled='true'
  ldapAuthenticationUri=''
  sessionMaxInactiveAgeSecs=''
  enableSSL='true'
  
mqsireportproperties IIBNODE -b webadmin -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  algorithm='Platform Default'
  clientAuth='true'
  keystoreFile='/var/mqsi/SSL/keystore.jks'
  keystorePass='brokerKeystore::password'
  keystoreType='JKS'
  truststoreFile='/var/mqsi/SSL/truststore.jks'
  truststorePass='brokerTruststore::password'
  truststoreType='JKS'
  sslProtocol='TLSv1.2'
  ciphers='Platform Default'
  keyAlias='Platform Default'
  keypass=''
  sessionCacheSize=''
  crlFile='Platform Default'
  address=''
  port='1077'
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests=''
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay=''
  enableLookups='false'
  serverName=''
  accessLog=''
  accessLogPattern=''

  14. Stop and restart the broker

    mqsistop IIBNODE
mqsistart IIBNODE

    mqsireload will not work, a full restart is needed.

Securing outbound requests from a message flow via Integration Server JVM

IIB request nodes do not make use of listener settings. In order to configure request nodes (such as HTTPRequest or SOAPRequest) for secure connections, use these steps.
Note that these steps are also covered in the IIB KnowledgeCenter articles:
- Configuring PKI at an integration server level
- Viewing and setting keystore and truststore runtime properties at integration server level

  1. Verify the current configuration

    mqsireportproperties IIBNODE -e IS -o ComIbmJVMManager -a
ComIbmJVMManager
  uuid='ComIbmJVMManager'
  userTraceLevel='none'
  traceLevel='none'
  userTraceFilter='none'
  traceFilter='none'
  vrmfIntroducedAt='7.0.0.0'
  resourceStatsReportingOn='inactive'
  resourceStatsMeasurements='       '
  activityLogSupported='no'
  jvmVerboseOption='none'
  jvmDisableClassGC='false'
  jvmShareClasses='false'
  jvmNativeStackSize='-1'
  jvmJavaOSStackSize='-1'
  jvmMinHeapSize='-1'
  jvmMaxHeapSize='-1'
  jvmDebugPort='0'
  jvmSystemProperty=''
  keystoreType=''
  keystoreFile=''
  keystorePass=''
  truststoreType=''
  truststoreFile=''
  truststorePass=''
  crlFileList=''
  enableCRLDP=''
  allowSSLv3=''
  allowSNI=''
  kerberosConfigFile=''
  kerberosKeytabFile=''

  2. Configure the keyststore type

    mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n keystoreType -v JKS

    If using a keystore with a .p12 extension, set the type to PKCS12.

  3. Configure the truststore type

    mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n truststoreType -v JKS

    If using a truststore with a .p12 extension, set the type to PKCS12.

  4. Set the path to the keystore file

    mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n keystoreFile -v /var/mqsi/SSL/keystore.jks

    Use the absolute path to the keystore, make sure the IIB user id has read permissions at least. There is a default value, but do not use it.

  5. Set the path to the truststore file

    mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n truststoreFile -v /var/mqsi/SSL/truststore.jks

    Use the absolute path to the truststore, make sure the IIB user id has read permissions at least. The default is <IIB_Install_path>/common/jdk/jre/lib/security/cacerts which has many common signer certificates prepopulated. You can add to this, import it into your own, or ignore it. If you use the default, keep in mind it will change with each fix pack and version, so you may want to point this property explicitly to the default if you decide to use it so you can be sure which copy is in use.

  6. Configure the keystore password

    mqsisetdbparms IIBNODE -n brokerKeystore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n keystorePass -v brokerKeystore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerKeystore::, for example: brokerKeystore::IS1Password. Changing the first part may have unexpected results

  7. Configure the truststore password

    mqsisetdbparms IIBNODE -n brokerTruststore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -e IS -o ComIbmJVMManager -n truststorePass -v brokerTruststore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerTruststore::, for example: brokerTruststore::IS1Password. Changing the first part may have unexpected results

    The password for the default truststore is changeit

  8. Verify your configuration

    mqsireportproperties IIBNODE -e IS -o ComIbmJVMManager -a
ComIbmJVMManager
  uuid='ComIbmJVMManager'
  userTraceLevel='none'
  traceLevel='none'
  userTraceFilter='none'
  traceFilter='none'
  vrmfIntroducedAt='7.0.0.0'
  resourceStatsReportingOn='inactive'
  resourceStatsMeasurements='       '
  activityLogSupported='no'
  jvmVerboseOption='none'
  jvmDisableClassGC='false'
  jvmShareClasses='false'
  jvmNativeStackSize='-1'
  jvmJavaOSStackSize='-1'
  jvmMinHeapSize='-1'
  jvmMaxHeapSize='-1'
  jvmDebugPort='0'
  jvmSystemProperty=''
  keystoreType='JKS'
  keystoreFile='/var/mqsi/SSL/keystore.jks'
  keystorePass='brokerKeystore::password'
  truststoreType='JKS'
  truststoreFile='/var/mqsi/SSL/truststore.jks'
  truststorePass='brokerTruststore::password'
  crlFileList=''
  enableCRLDP=''
  allowSSLv3=''
  allowSNI=''
  kerberosConfigFile=''
  kerberosKeytabFile=''

  9. Stop and restart the broker

    mqsistop IIBNODE
mqsistart IIBNODE

    mqsireload will not work, a full restart is needed.

Securing inbound requests to an Integration Server's embedded HTTP Listener

IIB message flow input nodes can be configured to use an HTTP Listener at the Integration Node level or one embedded within the Integration Server it is deployed to.
By default, the Integration Server embedded listener will use the security settings set at the server's JVM level (see the section above this one).
Use these steps to override an Integration Server's JVM settings for inbound connections.
(Note that this allows for the use of separate keystore/truststore files for inbound and outbound connections.)

  1. Verify the current configuration

    mqsireportproperties IIBNODE -e IS -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  userTraceLevel='none'
  traceLevel='none'
  userTraceFilter='none'
  traceFilter='none'
  port='0'
  address=''
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests='0'
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay='true'
  explicitlySetPortNumber=''
  enableLookups=''
  enableMQListener=''
  shutdownDelay=''
  allowCrossConnectorPolling=''
  autoRespondHTTPHEADRequests=''
  integratedWindowsAuthentication=''
  iwaTimeoutSeconds='300'
  serverName=''
  corsEnabled='false'
  corsAllowOrigins='*'
  corsAllowCredentials='false'
  corsExposeHeaders='Content-Type'
  corsMaxAge='-1'
  corsAllowMethods='GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
  corsAllowHeaders='Accept,Accept-Language,Content-Language,Content-Type'
  disableHttpMethods=''
  algorithm=''
  clientAuth=''
  keystoreFile=''
  keystorePass=''
  keystoreType=''
  truststoreFile=''
  truststorePass=''
  truststoreType=''
  sslProtocol=''
  ciphers=''
  keypass=''
  keyAlias=''
  sslSessionTimeout=''
  crlFile=''
  propagateClientCert=''
  sessionCacheSize=''

  2. Configure the keyststore type

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n keystoreType -v JKS

    If using a keystore with a .p12 extension, set the type to PKCS12.

  3. Configure the truststore type

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n truststoreType -v JKS

    If using a truststore with a .p12 extension, set the type to PKCS12.

  4. (OPTIONAL) Configure the connection port number to be used

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n explicitlySetPortNumber -v 8542

    You can use any unclaimed port, avoid the first 1000 (usually OS reserved). Use netstat -an to see in use ports. By default, all webuis will use the same port, which results in a failure for all but the first to start. Use unique ports for each node.

    The port property is read-only, showing the port actually being used if the listener is started. I.e. a value of 0 indicates the listener is not running.

  5. Configure the SSL protocol to be used

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n sslProtocol -v TLSv1.2

    Valid protocols are: TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, SSL_TLSv2, SSL, SSLv3

    Protocol Value used Notes
    TLS TLS v1.0 Default. If you use the Java option com.ibm.jsse2.overrideDefaultTLS=true, the value is all TLS versions (v1.0, v1.1, and v1.2).
    TLSv1 TLS v1.0
    TLSv1.1 TLS v1.1 No fallback to TLS v1.0.
    TLSv1.2 TLS v1.2 No fallback to TLS v1.0 or v1.1.
    SSL_TLS TLS v1.0, SSL v3 No fallback to SSL v2
    SSL_TLSv2 TLS v1.0, TLS v1.1, TLS v1.2, SSL v3 No fallback to SSL v2.
    SSL TLS v1.0, TLS v1.1, TLS v1.2 Despite the name, this is for all TLS versions, not SSL.
    SSLv3 SSL v3 Fallback to SSL v2 allowed. Disabled unless you set the Java option com.ibm.jsse2.disableSSLv3=false. If you use the Java option com.ibm.jsse2.convertSSLv3=true, the value is SSL v3 and all TLS versions (v1.0, v1.1, and v1.2).

  6. Set the path to the keystore file

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n keystoreFile -v /var/mqsi/SSL/keystore.jks

    Use the absolute path to the keystore, make sure the IIB user id has read permissions at least. There is a default value, but do not use it.

  7. Set the path to the truststore file

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n truststoreFile -v /var/mqsi/SSL/truststore.jks

    Use the absolute path to the truststore, make sure the IIB user id has read permissions at least. The default is <IIB_Install_path>/common/jdk/jre/lib/security/cacerts which has many common signer certificates prepopulated. You can add to this, import it into your own, or ignore it. If you use the default, keep in mind it will change with each fix pack and version, so you may want to point this property explicitly to the default if you decide to use it so you can be sure which copy is in use.

  8. Configure the keystore password

    mqsisetdbparms IIBNODE -n brokerKeystore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n keystorePass -v brokerKeystore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerKeystore::, for example: brokerKeystore::IS1Password. Changing the first part may have unexpected results

  9. Configure the truststore password

    mqsisetdbparms IIBNODE -n brokerTruststore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n truststorePass -v brokerTruststore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerTruststore::, for example: brokerTruststore::IS1Password. Changing the first part may have unexpected results

    The password for the default truststore is changeit

  10. (OPTIONAL) Set client authentication

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n clientAuth -v true

    Required only for two-way SSL or mutual authentication setup, where the client certificate is required . Do not set this to true if you are doing one-way SSL, server only certificates.

  11. (OPTIONAL) Specify the alias that the keystore server certificate is to use

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n keyAlias -v certificateKeyAlias

    By default, IIB will use the first personal certificate available in the keystore. If you have multiple personal certificates in the keystore, and the one to be used is not on the top of the list, set this parameter to ensure that IIB uses the correct certificate.

  12. (OPTIONAL) Specify the cipher(s) to be use for the connnection

    mqsichangeproperties IIBNODE -e IS -o HTTPSConnector -n ciphers -v 
\"SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_AES_256_CBC_SHA,
SSL_ECDH_ECDSA_WITH_AES_256_CBC_SHA,SSL_ECDH_RSA_WITH_AES_256_CBC_SHA,SSL_DHE_RSA_WITH_AES_256_CBC_SHA,
SSL_DHE_DSS_WITH_AES_256_CBC_SHA\"

    It is possible that the cipher required for the connection is not in the default list provided by IIB. In such case, you can override the default list by configuring the a single cipher or custom list of ciphers to be used. It is also important to confirm from the IBM cipher list page Cipher suites that the cipher(s) you configure are not disabled by default or require(s) TLSv1.2 or higher to be functional. In case the ciphers are disable by default, you can re-enable them by editing the line jdk.tls.disabledAlgorithms in the java.security file located in the IIB installation directory. You can also re-enable disabled cipher by running an mqsi command.

    For example: to re-enable SSL_RSA_WITH_3DES_EDE_CBC_SHA cipher, you run

    mqsichangeproperties IIBNODE -o BrokerRegistry -n reenabledCertificateAlgorithms -v 3DES_EDE_CBC

    Any cipher you specify on the IS HTTPS listener using the mqsi command only affects inbound connections. If you need to override a cipher or SSL protocol for outbound connection, you must do so on the request node before building the flow bar file.

  13. Verify your configuration

    mqsireportproperties IIBNODE -e IS -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  userTraceLevel='none'
  traceLevel='none'
  userTraceFilter='none'
  traceFilter='none'
  port='0'
  address=''
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests='0'
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay='true'
  explicitlySetPortNumber=''
  enableLookups=''
  enableMQListener=''
  shutdownDelay=''
  allowCrossConnectorPolling=''
  autoRespondHTTPHEADRequests=''
  integratedWindowsAuthentication=''
  iwaTimeoutSeconds='300'
  serverName=''
  corsEnabled='false'
  corsAllowOrigins='*'
  corsAllowCredentials='false'
  corsExposeHeaders='Content-Type'
  corsMaxAge='-1'
  corsAllowMethods='GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
  corsAllowHeaders='Accept,Accept-Language,Content-Language,Content-Type'
  disableHttpMethods=''
  algorithm=''
  clientAuth=''
  keystoreFile='/var/mqsi/SSL/keystore.jks'
  keystorePass='brokerKeystore::password'
  keystoreType='JKS'
  truststoreFile='/var/mqsi/SSL/truststore.jks'
  truststorePass='brokerTruststore::password'
  truststoreType='JKS'
  sslProtocol='TLSv1.2'
  ciphers=''
  keypass=''
  keyAlias=''
  sslSessionTimeout=''
  crlFile=''
  propagateClientCert=''
  sessionCacheSize=''

  14. Stop and restart the broker

    mqsistop IIBNODE
mqsistart IIBNODE

    mqsireload will not work, a full restart is needed.

Securing inbound requests to an Integration Node's HTTP Listener

IIB message flow input nodes can be configured to use an HTTP Listener at the Integration Node level or one embedded within the Integration Server it is deployed to.
Use these steps to configure the HTTPSConnector for the Integration Node level HTTP listener for secure inbound connections.
Note that these steps are covered in the IIB KnowledgeCenter articles:
- Configuring PKI for the broker-wide HTTP listener

  1. Verify the current configuration

    mqsireportproperties IIBNODE -b httplistener -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  algorithm='Platform Default'
  clientAuth='Platform Default'
  keystoreFile='Platform Default'
  keystorePass=''
  keystoreType='Platform Default'
  truststoreFile='Platform Default'
  truststorePass=''
  truststoreType='Platform Default'
  sslProtocol='TLS'
  ciphers='Platform Default'
  keyAlias=''
  keypass=''
  keyAlias='Platform Default'
  sessionCacheSize=''
  crlFile='Platform Default'
  propagateClientCert='Platform Default'
  address=''
  port='7083'
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests='0'
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay='true'
  enableLookups='false'
  serverName=''
  accessLog=''
  accessLogPattern=''
  corsEnabled='false'
  corsAllowOrigins='*'
  corsAllowCredentials='false'
  corsExposeHeaders='Content-Type'
  corsMaxAge='-1'
  corsAllowMethods='GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
  corsAllowHeaders='Accept,Accept-Language,Content-Language,Content-Type'
  disableHttpMethods=''

  2. Configure the keyststore type

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n keystoreType -v JKS

    If using a keystore with a .p12 extension, set the type to PKCS12.

  3. Configure the truststore type

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n truststoreType -v JKS

    If using a truststore with a .p12 extension, set the type to PKCS12.

  4. (OPTIONAL) Configure the connection port number to be used

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n port -v 6895

    You can use any unclaimed port, avoid the first 1000 (usually OS reserved). Use netstat -an to see in use ports. By default, all webuis will use the same port, which results in a failure for all but the first to start. Use unique ports for each node.

  5. Configure the SSL protocol to be used

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n sslProtocol -v TLSv1.2

    Valid protocols are: TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, SSL_TLSv2, SSL, SSLv3

    Protocol Value used Notes
    TLS TLS v1.0 Default. If you use the Java option com.ibm.jsse2.overrideDefaultTLS=true, the value is all TLS versions (v1.0, v1.1, and v1.2).
    TLSv1 TLS v1.0
    TLSv1.1 TLS v1.1 No fallback to TLS v1.0.
    TLSv1.2 TLS v1.2 No fallback to TLS v1.0 or v1.1.
    SSL_TLS TLS v1.0, SSL v3 No fallback to SSL v2
    SSL_TLSv2 TLS v1.0, TLS v1.1, TLS v1.2, SSL v3 No fallback to SSL v2.
    SSL TLS v1.0, TLS v1.1, TLS v1.2 Despite the name, this is for all TLS versions, not SSL.
    SSLv3 SSL v3 Fallback to SSL v2 allowed. Disabled unless you set the Java option com.ibm.jsse2.disableSSLv3=false. If you use the Java option com.ibm.jsse2.convertSSLv3=true, the value is SSL v3 and all TLS versions (v1.0, v1.1, and v1.2).

  6. Set the path to the keystore file

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n keystoreFile -v /var/mqsi/SSL/keystore.jks

    Use the absolute path to the keystore, make sure the IIB user id has read permissions at least. There is a default value, but do not use it.

  7. Set the path to the truststore file

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n truststoreFile -v /var/mqsi/SSL/truststore.jks

    Use the absolute path to the truststore, make sure the IIB user id has read permissions at least. The default is <IIB_Install_path>/common/jdk/jre/lib/security/cacerts which has many common signer certificates prepopulated. You can add to this, import it into your own, or ignore it. If you use the default, keep in mind it will change with each fix pack and version, so you may want to point this property explicitly to the default if you decide to use it so you can be sure which copy is in use.

  8. Configure the keystore password

    mqsisetdbparms IIBNODE -n brokerKeystore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n keystorePass -v brokerKeystore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerKeystore::, for example: brokerKeystore::IS1Password. Changing the first part may have unexpected results

  9. Configure the truststore password

    mqsisetdbparms IIBNODE -n brokerTruststore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n truststorePass -v brokerTruststore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerTruststore::, for example: brokerTruststore::IS1Password. Changing the first part may have unexpected results

    The password for the default truststore is changeit

  10. (OPTIONAL) Set client authentication

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n clientAuth -v true

    Required only for two-way SSL or mutual authentication setup, where the client certificate is required . Do not set this to true if you are doing one-way SSL, server only certificates.

  11. (OPTIONAL) Specify the alias that the keystore server certificate is to use

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -n keyAlias -v certificateKeyAlias

    By default, IIB will use the first personal certificate available in the keystore. If you have multiple personal certificates in the keystore, and the one to be used is not on the top of the list, set this parameter to ensure that IIB uses the correct certificate.

  12. (OPTIONAL) Specify the cipher(s) to be use for the connnection

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -o HTTPSConnector -n ciphers -v 
\"SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,SSL_ECDHE_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_AES_256_CBC_SHA,
SSL_ECDH_ECDSA_WITH_AES_256_CBC_SHA,SSL_ECDH_RSA_WITH_AES_256_CBC_SHA,SSL_DHE_RSA_WITH_AES_256_CBC_SHA,
SSL_DHE_DSS_WITH_AES_256_CBC_SHA\"

    It is possible that the cipher required for the connection is not in the default list provided by IIB. In such case, you can override the default list by configuring the a single cipher or custom list of ciphers to be used. It is also important to confirm from the IBM cipher list page Cipher suites that the cipher(s) you configure are not disabled by default or require(s) TLSv1.2 or higher to be functional. In case the ciphers are disable by default, you can re-enable them by editing the line jdk.tls.disabledAlgorithms in the java.security file located in the IIB installation directory. You can also re-enable disabled cipher by running an mqsi command.

    For example: to re-enable SSL_RSA_WITH_3DES_EDE_CBC_SHA cipher, you run

    mqsichangeproperties IIBNODE -o BrokerRegistry -n reenabledCertificateAlgorithms -v 3DES_EDE_CBC

    Any cipher you specify on the Node HTTPS listener using the mqsi command only affects inbound connections. If you need to override a cipher or SSL protocol for outbound connection, you must do so on the request node before building the flow bar file.

  13. Verify your configuration

    mqsichangeproperties IIBNODE -b httplistener -o HTTPSConnector -a
HTTPSConnector
  uuid='HTTPSConnector'
  algorithm='Platform Default'
  clientAuth='Platform Default'
  keystoreFile='/var/mqsi/SSL/keystore.jks'
  keystorePass='brokerKeystore::password'
  keystoreType='JKS'
  truststoreFile='/var/mqsi/SSL/truststore.jks'
  truststorePass='brokerTruststore::password'
  truststoreType='JKS'
  sslProtocol='TLSv1.2'
  ciphers='Platform Default'
  keyAlias=''
  keypass=''
  keyAlias='Platform Default'
  sessionCacheSize=''
  crlFile='Platform Default'
  propagateClientCert='Platform Default'
  address=''
  port='7083'
  maxPostSize=''
  acceptCount=''
  compressableMimeTypes=''
  compression=''
  connectionLinger=''
  connectionTimeout=''
  maxHttpHeaderSize=''
  maxKeepAliveRequests='0'
  maxThreads=''
  minSpareThreads=''
  noCompressionUserAgents=''
  restrictedUserAgents=''
  socketBuffer=''
  tcpNoDelay='true'
  enableLookups='false'
  serverName=''
  accessLog=''
  accessLogPattern=''
  corsEnabled='false'
  corsAllowOrigins='*'
  corsAllowCredentials='false'
  corsExposeHeaders='Content-Type'
  corsMaxAge='-1'
  corsAllowMethods='GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
  corsAllowHeaders='Accept,Accept-Language,Content-Language,Content-Type'
  disableHttpMethods=''

  14. Stop and restart the broker

    mqsistop IIBNODE
mqsistart IIBNODE

    mqsireload will not work, a full restart is needed.

Creating a "default" security configuration via the Integration Node Registry

It is possible to create a generic, or "default", configuration for all assets managed by an Integration Node.
This configuration is used when there are no explicit settings for the particular listener or Integration Server in use.
Note that these steps are also covered in the IIB KnowledgeCenter articles:
- Configuring PKI at broker level
- Viewing and setting keystore and truststore runtime properties at integration node level

  1. Verify the current configuration

    mqsireportproperties IIBNODE -o BrokerRegistry -a
BrokerRegistry
  uuid='BrokerRegistry'
  brokerKeystoreType='JKS'
  brokerKeystoreFile=''
  brokerKeystorePass='brokerKeystore::password'
  brokerTruststoreType='JKS'
  brokerTruststoreFile=''
  brokerTruststorePass='brokerTruststore::password'
  brokerCRLFileList=''
  httpConnectorPortRange=''
  httpsConnectorPortRange=''
  brokerKerberosConfigFile=''
  brokerKerberosKeytabFile=''
  allowSSLv3=''
  allowSNI=''
  reenableTransportAlgorithms=''
  reenableCertificateAlgorithms=''
  mqCCDT=''
  modeExtensions=''
  operationMode='advanced'
  adminMessageLogging=''
  productFunctionality=''
  mqKeyRepository=''
  dataCapturePolicyUri='/apiv1/policy/DataCapture/default'
  shortDesc=''
  longDesc=''

  2. Configure the keyststore type

    mqsichangeproperties IIBNODE -o BrokerRegistry -n brokerKeystoreType -v JKS

    If using a keystore with a .p12 extension, set the type to PKCS12.

  3. Configure the truststore type

    mqsichangeproperties IIBNODE -o BrokerRegistry -n brokerTruststoreType -v JKS

    If using a truststore with a .p12 extension, set the type to PKCS12.

  4. Set the path to the keystore file

    mqsichangeproperties IIBNODE -o BrokerRegistry -n brokerKeystoreFile -v /var/mqsi/SSL/keystore.jks

    Use the absolute path to the keystore, make sure the IIB user id has read permissions at least. There is a default value, but do not use it.

  5. Set the path to the truststore file

    mqsichangeproperties TESTNODE_kb -o BrokerRegistry -n brokerTruststoreFile -v /var/mqsi/SSL/truststore.jks

    Use the absolute path to the truststore, make sure the IIB user id has read permissions at least. The default is <IIB_Install_path>/common/jdk/jre/lib/security/cacerts which has many common signer certificates prepopulated. You can add to this, import it into your own, or ignore it. If you use the default, keep in mind it will change with each fix pack and version, so you may want to point this property explicitly to the default if you decide to use it so you can be sure which copy is in use.

  6. Configure the keystore password

    mqsisetdbparms IIBNODE -n brokerKeystore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -o BrokerRegistry -n brokerKeystorePass -v brokerKeystore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerKeystore::, for example: brokerKeystore::Node1Password. Changing the first part may have unexpected results

  7. Configure the truststore password

    mqsisetdbparms IIBNODE -n brokerTruststore::password -u ignore -p 'P@ssw0rd!'
mqsichangeproperties IIBNODE -o BrokerRegistry -n brokerTruststorePass -v brokerTruststore::password

    Linux & AIX: passwords with special characters need to be in single quotes.

    Windows: passwords with special characters need to be in double quotes.

    If you want to use a unique identifier, change the part after brokerTruststore::, for example: brokerTruststore::Node1Password. Changing the first part may have unexpected results

    The password for the default truststore is changeit

  8. Verify your configuration

    mqsireportproperties IIBNODE -o BrokerRegistry -a
BrokerRegistry
  uuid='BrokerRegistry'
  brokerKeystoreType='JKS'
  brokerKeystoreFile='/var/mqsi/SSL/keystore.jks'
  brokerKeystorePass='brokerKeystore::password'
  brokerTruststoreType='JKS'
  brokerTruststoreFile='/var/mqsi/SSL/truststore.jks'
  brokerTruststorePass='brokerTruststore::password'
  brokerCRLFileList=''
  httpConnectorPortRange=''
  httpsConnectorPortRange=''
  brokerKerberosConfigFile=''
  brokerKerberosKeytabFile=''
  allowSSLv3=''
  allowSNI=''
  reenableTransportAlgorithms=''
  reenableCertificateAlgorithms=''
  mqCCDT=''
  modeExtensions=''
  operationMode='advanced'
  adminMessageLogging=''
  productFunctionality=''
  mqKeyRepository=''
  dataCapturePolicyUri='/apiv1/policy/DataCapture/default'
  shortDesc=''
  longDesc=''

  9. Stop and restart the broker

    mqsistop IIBNODE

mqsistart IIBNODE

    mqsireload will not work, a full restart is needed.

Troubleshooting Secure Connections in IIB

SSL Issues MustGather: Collecting a JSSE Trace on UNIX
SSL Issues MustGather: Collecting a JSSE Trace on Windows

Collecting SSL (JSSE) trace to Troubleshooting Secure Communication in IIB

A JSSE, Java Secure Socket Extension, trace is built on the underlying Java SSL libraries. IIB uses the JSSE for all its SSL actions. As such, all JSSE related actions including tracing follows the same guidelines as other Java programs. In order to take a trace, you enable the debugging mode using the Java option: -Djavax.net.debug=true Note that there are other values you can set for this, such as all, ssl, record (optional plaintext and packet when record is used), handshake, keygen, session, defaultctx, sslctx, sessioncache, keymanager, trustmanager, data, verbose, and help. Using true is similar to 'all' but is IBM JSSE compatible. This is the recommended option for most SSL issues. Other options may be useful if you are interested in specific aspects only. For instance, if you want to see what data went across the wire, you can use 'record'. Please see this page for information on what each option collects: Debugging Utilities

Multiple options are supported using commas or colons as separators. IIB offers two ways of setting this JVM parameter. Our documented approach is through an environment variable, IBM_JAVA_OPTIONS. This will enable SSL on all Integration Nodes and Servers that are restarted while the variable is set. Because of this, you may generate extra traces for applications that do not need to be debugged. It also requires a complete Integration Node restart to be picked up. The other option is through the Integration Server's JVM overrides. The Integration Server has a property called jvmSystemProperty which takes any JVM parameter and applies it to just that Integration Server. This is much more useful as only the Integration Server needs to be restarted to pick up the change and only the Server in question will be traced.

Note for Solaris Solaris is a bit different than the other systems. The key difference is that the IBM_JAVA_OPTIONS variable does not work. You can instead use _JAVA_OPTIONS (no proceeding IBM) or use the jvmSystemProperty.

Locating the JSSE Trace Output on the Filesystem

The trace would write to the console. IIB redirects this output. The outputs are in the following locations depending on the OS and listener used.

Your flow is using Integration Server listener

Windows: \MQSI_WORKPATH>\components\IIBNODE\IS_UUID\console.txt
Linux|Unix|Z|Solaris: /MQSI_WORKPATH/components/IIBNODE/IS_UUID/stdout

Your flow is using Integration wide listener

Windows: \MQSI_WORKPATH>\components\IIBNODE\httplistener\console.txt
Linux|Unix|Z|Solaris: /MQSI_WORKPATH/components/IIBNODE/httplistener/stdout

For the Integration Node Web Interface

Windows: \MQSI_WORKPATH>\components\IIBNODE\console.txt
Linux|Unix|Z|Solaris: /MQSI_WORKPATH/components/IIBNODE/stdout

List of Common Errors

This text is revealed when the collapsible item is expanded.

Document Location

Worldwide

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSNQK6","label":"IBM Integration Bus"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"10.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
29 May 2020

UID

ibm10958803

Page Feedback