MQSCO - SSL/TLS configuration options

The MQSCO structure, in conjunction 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. The structure is an input parameter on the MQCONNX call.

Availability

The MQSCO structure is available on the following operating systems:

AIX®
IBM i
Linux®
Windows

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

Version

The header, COPY, and INCLUDE files that are provided for the supported programming languages contain the most recent version of MQSCO, but with the initial value of the Version field set to MQSCO_VERSION_1. To use fields that are not present in the version-1 structure, the application must set the Version field to the version number that is required.

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 MQENC_NATIVE.

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically.

Table 1. Fields in `MQSCO`
Field name and description	Name of constant	Initial value (if any) of constant
StrucId (structure identifier)	`MQSCO_STRUC_ID`	`'SCO¬'`
Version (structure version number)	`MQSCO_CURRENT_VERSION`	1
KeyRepository (location of key repository)	None	Null string or blanks
CryptoHardware (details of cryptographic hardware)	None	Null string or blanks
AuthInfoRecCount (number of MQAIR records present)	None	`0`
AuthInfoRecOffset (offset of first MQAIR record from start of MQSCO)	None	`0`
AuthInfoRecPtr (address of first MQAIR record)	None	Null pointer or null bytes
Note: The following two fields are ignored if `Version` is less than `MQSCO_VERSION_2`.
KeyResetCount (TLS secret key reset count)	`MQSCO_RESET_COUNT_DEFAULT`	`0`
FipsRequired (MQLONG) (use FIPS certified cryptographic algorithms in IBM MQ)	`MQSSL_FIPS_NO`	`0`
Note: The following two fields are ignored if `Version` is less than `MQSCO_VERSION_3`.
EncryptionPolicySuiteB (use only Suite B cryptographic algorithms)	`MQ_SUITE_B_NONE, MQ_SUITE_B_NOT_AVAILABLE, MQ_SUITE_B_NOT_AVAILABLE, MQ_SUITE_B_NOT_AVAILABLE`	`1, 0, 0, 0`
Note: The following two fields are ignored if `Version` is less than `MQSCO_VERSION_4`.
CertificateValPolicy (certificate validation policy)	`MQ_CERT_VAL_POLICY_DEFAULT`	`0`
Note: The following two fields are ignored if `Version` is less than `MQSCO_VERSION_5`.
CertificateLabel (details the certificate label that is being used)	None	Null string or blanks
Note: The following three fields are ignored if `Version` is less than `MQSCO_VERSION_6`.
KeyRepoPasswordPtr (address of TLS key repository password)	None	Null pointer or null bytes
KeyRepoPasswordOffset (offset of TLS key repository password)	None	`0`
KeyRepoPasswordLength (length of TLS key repository password)	None	`0`
Note: The following five fields are ignored if `Version` is less than `MQSCO_VERSION_7`.
HTTPSKeyStorePtr (address of HTTPSKeyStore string)	none	null pointer
HTTPSKeyStoreOffset (offset of HTTPSKeyStore string) from start of MQSCO	none	`0`
HTTPSKeyStoreLength (length of HTTPSKeyStore string)	none	`0`
HTTPSCertValidation (level of certificate validation required. `MQ_HTTPSCERTVAL_DEFAULT` means the setting in the mqclient.ini file is used, if it exists)	`MQ_HTTPSCERTVAL_DEFAULT MQ_HTTPSCERTVAL_ANY MQ_HTTPSCERTVAL_NONE MQ_HTTPSCERTVAL_HOSTNAMECN`	`0 1 2 3`
HTTPSCertRevocation (level of certificate revocation checking required. `MQ_HTTPSCERTREV_DEFAULT` means the setting in the mqclient.ini file is used, if it exists)	`MQ_HTTPSCERTREV_DEFAULT MQ_HTTPSCERTREV_REQUIRED MQ_HTTPSCERTREV_DISABLED MQ_HTTPSCERTREV_OPTIONAL`	`0 1 2 3`

Notes:

The symbol ¬ represents a single blank character.
In the C programming language, the macro variable MQSCO_DEFAULT contains the values listed in the table. Use it in the following way to provide initial values for the fields in the structure:
```
MQSCO MySCO = {MQSCO_DEFAULT};
```

Language declarations

C declaration for MQSCO

typedef struct tagMQSCO MQSCO;
struct tagMQSCO {
   MQCHAR4    StrucId;                    /* Structure identifier */
   MQLONG     Version;                    /* Structure version number */
   MQCHAR256  KeyRepository;              /* Location of TLS key */
                                          /* repository */
   MQCHAR256  CryptoHardware;             /* Cryptographic hardware */
                                          /* configuration string */
   MQLONG     AuthInfoRecCount;           /* Number of MQAIR records */
                                          /* present */
   MQLONG     AuthInfoRecOffset;          /* Offset of first MQAIR */
                                          /* record from start of */
                                          /* MQSCO structure */
   PMQAIR     AuthInfoRecPtr;             /* Address of first MQAIR */
                                          /* record */
/* Ver:1 */
   MQLONG     KeyResetCount;              /* Number of unencrypted */
                                          /* bytes sent/received */
                                          /* before secret key is */
                                          /* reset */
   MQLONG     FipsRequired;               /* Using FIPS certified */
/* Ver:2 */
                                          /* algorithms */
   MQLONG     EncryptionPolicySuiteB[4];  /* Use only Suite B */
/* Ver:3 */
                                          /* cryptographic algorithms */
   MQLONG     CertificateValPolicy;       /* Certificate validation */
                                          /* policy */
/* Ver:4 */
   MQCHAR64   CertificateLabel;           /* Certificate label */
/* Ver:5 */
   MQPTR      KeyRepoPasswordPtr;         /* Address of key */
                                          /* repository password */
   MQLONG     KeyRepoPasswordOffset;      /* Offset of key repository */
                                          /* password */
   MQLONG     KeyRepoPasswordLength;      /* Length of key repository */
                                          /* password */
/* Ver:6 */
   MQLONG     HTTPSCertValidation;        /* HTTPS certificate */
                                          /* validation level */
   MQLONG     HTTPSCertRevocation;        /* HTTPS certificate */
                                          /* revocation level */
   MQPTR      HTTPSKeyStorePtr;           /* Address of HTTPS */
                                          /* Keystore */
   MQLONG     HTTPSKeyStoreOffset;        /* Offset of HTTPS Keystore */
   MQLONG     HTTPSKeyStoreLength;        /* Length of HTTPS keystore */
/* Ver:7 */
  };

COBOL declaration for MQSCO

**   MQSCO structure
  10 MQSCO.
**    Structure identifier
   15 MQSCO-STRUCID                  PIC X(4).
**    Structure version number
   15 MQSCO-VERSION                  PIC S9(9) BINARY.
**    Location of TLS key repository
   15 MQSCO-KEYREPOSITORY            PIC X(256).
**    Cryptographic hardware configuration string
   15 MQSCO-CRYPTOHARDWARE           PIC X(256).
**    Number of MQAIR records present
   15 MQSCO-AUTHINFORECCOUNT         PIC S9(9) BINARY.
**    Offset of first MQAIR record from start of MQSCO structure
   15 MQSCO-AUTHINFORECOFFSET        PIC S9(9) BINARY.
**    Address of first MQAIR record
   15 MQSCO-AUTHINFORECPTR           POINTER.
** Version 1 **
**    Number of unencrypted bytes sent/received before secret key is
**    reset
   15 MQSCO-KEYRESETCOUNT            PIC S9(9) BINARY.
**    Using FIPS certified algorithms
   15 MQSCO-FIPSREQUIRED             PIC S9(9) BINARY.
** Version 2 **
**    Use only Suite B cryptographic algorithms
   15 MQSCO-ENCRYPTIONPOLICYSUITEB   PIC S9(9) BINARY OCCURS 4.
** Version 3 **
**    Certificate validation policy setting
   15 MQSCO-CERTIFICATEVALPOLICY     PIC S9(9) BINARY.
** Version 4 **
**    SSL/TLS certificate label
   15 MQSCO-CERTIFICATELABEL         PIC X(64).
** Version 5 **
**    Add padding to ensure that pointers start on correct
**    boundaries
   15 FILLER                         PIC S9(9) BINARY VALUE 0.
**   Address of key repository password
   15 MQSCO-KEYREPOPASSWORDPTR       POINTER.
**   Offset of key repository password
   15 MQSCO-KEYREPOPASSWORDOFFSET    PIC S9(9) BINARY.
**   Length of key repository password
   15 MQSCO-KEYREPOPASSWORDLENGTH    PIC S9(9) BINARY.
** Version 6 **** HTTPS certificate validation level
   15 MQSCO-HTTPSCERTVALIDATION      PIC S9(9) BINARY VALUE 0.
** HTTPS certificate revocation level
   15 MQSCO-HTTPSCERTREVOCATION      PIC S9(9) BINARY VALUE 0.
** Address of HTTPS Keystore
   15 MQSCO-HTTPSKEYSTOREPTR         POINTER VALUE NULL.
** Offset of HTTPS Keystore
   15 MQSCO-HTTPSKEYSTOREOFFSET      PIC S9(9) BINARY VALUE 0.
** Length of HTTPS keystore
   15 MQSCO-HTTPSKEYSTORELENGTH      PIC S9(9) BINARY VALUE 0.
** Ver:7 **

PL/I declaration for MQSCO

dcl
 1 MQSCO based,
  3 StrucId                    char(4),       /* Structure identifier */
  3 Version                    fixed bin(31), /* Structure version number */
  3 KeyRepository              char(256),     /* Location of TLS key
                                                 repository */
  3 CryptoHardware             char(256),     /* Cryptographic hardware
                                                 configuration string */
  3 AuthInfoRecCount           fixed bin(31), /* Number of MQAIR records
                                                 present */
  3 AuthInfoRecOffset          fixed bin(31), /* Offset of first MQAIR record
                                                 from start of MQSCO structure */
  3 AuthInfoRecPtr             pointer,       /* Address of first MQAIR record */
  3 KeyResetCount              fixed bin(31), /* Key reset count */
/* Version 1 */
  3 FipsRequired               fixed bin(31), /* FIPS required */
/* Version 2 */
  3 EncryptionPolicySuiteB (4) fixed bin(31), /* Suite B encryption policy */
/* Version 3 */
  3 CertificateValPolicy       fixed bin(31), /* Certificate validation policy */
/* Version 4 */
  3 CertificateLabel           char(64),      /* SSL/TLS certificate label */ 
/* Version 5 */
  3 KeyRepoPasswordPtr         pointer,       /* Address of key repository 
                                                 password */
  3 KeyRepoPasswordOffset      fixed bin(31), /* Offset of key repository
                                                 password */
  3 KeyRepoPasswordLength      fixed bin(31); /* Length of key repository
                                                 password */
/* Version 6 */
  3 HTTPSCertValidation        fixed bin(31), /* HTTPS certificate */
                                                 validation level */
  3 HTTPSCertRevocation        fixed bin(31), /* HTTPS certificate */
                                                 revocation level */
  3 HTTPSKeyStorePtr           pointer,       /* Address of HTTPS Keystore */
  3 HTTPSKeyStoreOffset        fixed bin(31), /* Offset of HTTPS Keystore */
  3 HTTPSKeyStoreLength        fixed bin(31); /* Length of HTTPS keystore */
/* Version 7 */

Visual Basic declaration for MQSCO

Type MQSCO
  StrucId           As String*4   'Structure identifier'
  Version           As Long       'Structure version number'
  KeyRepository     As String*256 'Location of TLS key repository'
  CryptoHardware    As String*256 'Cryptographic hardware configuration'
                                  'string'
  AuthInfoRecCount  As Long       'Number of MQAIR records present'
  AuthInfoRecOffset As Long       'Offset of first MQAIR record from'
                                  'start of MQSCO structure'
  AuthInfoRecPtr    As MQPTR      'Address of first MQAIR record'
  KeyResetCount     As Long       'Number of unencrypted bytes sent/received before secret key is reset'
'Version 1'
  FipsRequired      As Long       'Mandatory FIPS CipherSpecs?'
'Version 2'
End Type