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 clients:

AIX®
HP-UX
IBM i
Linux®
Solaris
Windows

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

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically. The child topics follow the same sequence.

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

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 */

  };

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 **

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 */

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