MQSCO (TLS configuration options) on IBM i

The MQSCO structure (with the TLS fields in the MQCD structure) allows an application running as an IBM MQ MQI client to specify configuration options that control the use of TLS for the client connection when the channel protocol is TCP/IP.

Overview

Purpose: The structure is an input parameter on the MQCONNX call.

If the channel protocol for the client channel is not TCP/IP, the MQSCO structure is ignored.

Character set and encoding: Data in MQSCO must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT.

• Fields
• Initial values
• RPG declaration

Fields

The MQSCO structure contains the following fields; the fields are described in alphabetical order:

SCAIC (10-digit signed integer)

This is the number of authentication information (MQAIR) records addressed by the SCAIP or SCAIO fields. For more information, seeMQAIR (Authentication information record) on IBM i. The value must be zero or greater. If the value is not valid, the call fails with reason code RC2383.

This is an input field. The initial value of this field is 0.

SCAIO (10-digit signed integer)

This is the offset in bytes of the first authentication information record from the start of the MQSCO structure. The offset can be positive or negative. The field is ignored if SCAIC is zero.

We can use either SCAIO or SCAIP to specify the MQAIR records, but not both; see the description of the SCAIP field for details.

This is an input field. The initial value of this field is 0.

SCAIP (10-digit signed integer)

This is the address of the first authentication information record. The field is ignored if SCAIC is zero.

We can provide the array of MQAIR records in one of two ways:

• By using the pointer field SCAIP

  In this case, the application can declare an array of MQAIR records that is separate from the MQSCO structure, and set SCAIP to the address of the array.

  Consider using SCAIP for programming languages that support the pointer data type in a fashion that is portable to different environments (for example, the C programming language).

• By using the offset field SCAIO

  In this case, the application must declare a compound structure containing an MQSCO followed by the array of MQAIR records, and set SCAIO to the offset of the first record in the array from the start of the MQSCO structure. Ensure that this value is correct, and has a value that can be accommodated within an MQLONG (the most restrictive programming language is COBOL, for which the valid range is -999 999 999 through +999 999 999).

  Consider using SCAIO for programming languages that do not support the pointer data type, or that implement the pointer data type in a fashion that is not portable to different environments (for example, the COBOL programming language).

Whatever technique you choose, only one of SCAIP and SCAIO can be used; the call fails with reason code RC2384 if both are nonzero.

This is an input field. The initial value of this field is the null pointer in those programming languages that support pointers, and an all-null byte string otherwise.

Note: On platforms where the programming language does not support the pointer data type, this field is declared as a byte string of the appropriate length.

SCCERLBL (10-digit signed integer)

This field gives details of the certificate label being used.

IBM MQ initializes the value for the SCCERLBL field as blanks. Either enter the required value, or accept the default value.

ibmwebspheremquser_id is a valid value for this field for all versions of the product, and for MQSCO versions less than 5.0 it is the only valid value. Therefore the value of this field is interpreted at run time, and changed if necessary. If you specify an MQSCO version less than 5.0, or accept the default value of blanks for the SCCERLBL field, the system uses the value ibmwebspheremquser_id.

This is an input field.

SCCERTVPOL (10-digit signed integer)

This field specifies what type of certificate validation policy is used. The field can be set to one of the following values:

MQ_CERT_VAL_POLICY_ANY

Apply each of the certificate validation policies supported by the secure sockets library. Accept the certificate chain if any of the policies considers the certificate chain valid.

MQ_CERT_VAL_POLICY_RFC5280

Apply only the RFC5280 compliant certificate validation policy. This setting provides stricter validation than the ANY setting, but rejects some older digital certificates.

The initial value of this field is MQ_CERT_VAL_POLICY_ANY

SCCH (10-digit signed integer)

This field gives configuration details for cryptographic hardware connected to the client system.

Set the field to a string in the following format, or leave it blank or null:

GSK_PKCS11=the PKCS #11 driver path and file name;the PKCS #11
token label;the PKCS #11 token password;symmetric cipher setting>;

To use cryptographic hardware which conforms to the PKCS11 interface, for example, the IBM 4960 or IBM 4963, specify the PKCS11 driver path, PKCS11 token label, and PKCS11 token password strings, each terminated by a semi-colon.

The PKCS #11 driver path is an absolute path to the shared library providing support for the PKCS #11 card. The PKCS #11 driver file name is the name of the shared library. An example of the value required for the PKCS #11 path and file name is:

/usr/lib/pkcs11/PKCS11_API.so

The PKCS #11 token label must be entirely in lowercase. If we have configured your hardware with a mixed case or uppercase token label, reconfigure it with this lowercase label.

If no cryptographic hardware configuration is required, set the field to blank or null.

If the value is shorter than the length of the field, terminate the value with a null character, or pad it with blanks to the length of the field. If the value is not valid, or leads to a failure when used to configure the cryptographic hardware, the call fails with reason code RC2382.

This is an input field. The length of this field is given by LNSSCH. The initial value of this field is blank characters.

SCEPSUITEB (10-digit signed integer)

This field Specifies whether Suite B compliant cryptography is used and what level of strength is employed. The value can be one or more of:

• SCEPSUITEB0

  Suite B compliant cryptography is not used.

• SCEPSUITEB1

  Suite B 128-bit strength security is used.

• SCEPSUITEB2

  Suite B 192-bit strength security is used.

Note: Using SCEPSUITEB0 with any other value in this field is invalid.

SCFR (10-digit signed integer)

IBM MQ can be configured with cryptographic hardware so that the cryptography modules used are those provided by the hardware product; these can be FIPS-certified to a particular level depending on the cryptographic hardware product in use.

Use this field to specify that only FIPS-certified algorithms are used if the cryptography is provided in IBM MQ-provided software.

When IBM MQ is installed an implementation of TLS cryptography is also installed which provides some FIPS-certified modules.

The values can be:

MQSSL_FIPS_NO

This is the default value. When set to this value:

• Any CipherSpec supported on a particular platform can be used.
• If run without use of cryptographic hardware, the following CipherSpecs run using FIPS 140-2 certified cryptography on the IBM MQ platforms:
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA

MQSSL_FIPS_YES

When set to this value, unless you are using cryptographic hardware to perform the cryptography, we can be sure that

• Only FIPS-certified cryptographic algorithms can be used in the CipherSpec applying to this client connection.
• Inbound and outbound TLS channel connections only succeed if one of the following Cipher Specs are used:
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA

Notes:

1. CipherSpec TLS_RSA_WITH_3DES_EDE_CBC_SHA is deprecated.
2. Where possible, if FIPS-only CipherSpecs is configured then the MQI client rejects connections which specify a non-FIPS CipherSpec withRC2393. IBM MQ does not guarantee to reject all such connections and it is your responsibility to determine whether your IBM MQ configuration is FIPS-compliant.

SCKR (10-digit signed integer)

This field is relevant only for IBM MQ MQI clients running on UNIX and Windows systems. It specifies the location of the key database file in which keys and certificates are stored. The key database file must have a file name of the form zzz.kdb, where zzz is user-selectable. The SCKR field contains the path to this file, along with the file name stem (all characters in the file name up to but not including the final .kdb). The .kdb file suffix is added automatically.

Each key database file has an associated password stash file. This holds encrypted passwords that are used to allow programmatic access to the key database. The password stash file must reside in the same directory and have the same file stem as the key database, and must end with the suffix .sth.

For example, if the SCKR field has the value /xxx/yyy/key, the key database file must be /xxx/yyy/key.kdb, and the password stash file must be /xxx/yyy/key.sth, where xxx and yyy represent directory names.

If the value is shorter than the length of the field, terminate the value with a null character, or pad it with blanks to the length of the field. The value is not checked; if there is an error in accessing the key repository, the call fails with reason code RC2381.

To run a TLS connection from an IBM MQ MQI client, set SCKR to a valid key database file name.

This is an input field. The length of this field is given by LNSSKR. The initial value of this field is a blank character.

SCSID (10-digit signed integer)

This is the structure identifier; the value must be:

SCSIDV

Identifier for TLS configuration options structure.

This is always an input field. The initial value of this field is SCSIDV.

SCVER (10-digit signed integer)

This is the structure version number; the value must be:

SCVER1

Version-1 TLS configuration options structure.

SCVER2

Version-2 TLS configuration options structure.

The following constant specifies the version number of the current version:

SCVERC

Current version of TLS configuration options structure.

This is always an input field. The initial value of this field is SCVER2

Initial values

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQSCO Structure
     D*
     D* Structure identifier
     D  SCSID                  1      4    INZ('SCO ')
     D* Structure version number
     D  SCVER                  5      8I 0 INZ(1)
     D* Location of TLS key repository
     D  SCKR                   9    264    INZ
     D* Cryptographic hardware configuration string
     D  SCCH                 265    520    INZ
     D* Number of MQAIR records present
     D  SCAIC                521    524I 0 INZ(0)
     D* Offset of first MQAIR record from start of MQSCO structure
     D  SCAIO                525    528I 0 INZ(0)
     D* Address of first MQAIR record
     D SCAIP                 529    544*   INZ(*NULL)
     D* Ver:1 **
     D* Number of unencrypted bytes sent/received before secret key is
     D* reset
     D SCKRC                 545    548I 0 INZ(0)
     D* Using FIPS-certified algorithms
     D SCFR                  549    552I 0 INZ(0)
     D* Ver:2 **
     * Use only Suite B cryptographic algorithms
     D SCEPSUITEB0
     D SCEPSUITEB1           553    556I 0 INZ(1)
     D SCEPSUITEB2           557    560I 0 INZ(0)
     D SCEPSUITEB3           561    564I 0 INZ(0)
     D SCEPSUITEB4           565    568I 0 INZ(0)
     D SCEPSUITEB                    10I 0 DIM(4) OVERLAY(SCEPSUITEB0)
     D* Ver:3 **
     D* Certificate validation policy
     D SCCERTVPOL            569    572I 0 INZ(0)
     D* Ver:4 **