MQCSP - Security parameters

The IBM® MQ connection security parameter structure is used by applications to flow authentication information on an MQCONNX call to the queue manager. You can also use it to provide the initial key that is used with the IBM MQ password protection system that encrypts sensitive data.

Set AuthenticationType to MQCSP_AUTH_USER_ID_AND_PWD to include the user ID and password from version 1.

When you provide initial key information at version 2, the AuthenticationType defaults to MQCSP_AUTH_NONE.

[MQ 9.4.0 Jun 2024]From IBM MQ 9.3.4, use AuthenticationType to include authentication token information.

[MQ 9.4.0 Jun 2024]You can use MQCSP_AUTH_USER_ID_AND_PWD or MQCSP_AUTH_ID_TOKEN, but not both.

Warning: In some cases, the password or authentication token in an MQCSP structure for a client application is sent over the network in plain text. To ensure that client application passwords and authentication tokens are protected appropriately, see MQCSP password protection.

Availability

The MQCSP structure is available on all supported IBM MQ platforms.

Version

The header, COPY, and INCLUDE files provided for the supported programming languages contain the most-recent version of MQCSP, but with the initial value of the Version field set to MQCSP_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 MQCSP must be in the character set and encoding of the local queue manager, these are given by the CodedCharSetId queue manager attribute and MQENC_NATIVE, respectively.

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically.
Table 1. Fields in MQCSP for MQCSP
Field name and description Name of constant Initial value (if any) of constant
StrucId (structure identifier) MQCSP_STRUC_ID 'CSP¬'
Version (structure version number) MQCSP_VERSION_1 1
AuthenticationType (type of authentication) None MQCSP_AUTH_NONE
Reserved1 (required for pointer alignment on IBM i) None Null string or blanks
CSPUserIdPtr (address of user ID) None Null pointer or null bytes
CSPUserIdOffset (offset of user ID) None 0
CSPUserIdLength (length of user ID) None 0
Reserved2 (required for pointer alignment on IBM i) None Null string or blanks
CSPPasswordPtr (address of password) None Null pointer or null bytes
CSPPasswordOffset (offset of password) None 0
CSPPasswordLength (length of password) None 0
Note: The remaining fields are ignored if Version is less than MQCSP_VERSION_2.
Reserved3 (required for pointer alignment on IBM i) None Null string or blanks
InitialKeyPtr None Null pointer or blanks
InitialKeyOffset (offset of initial key for the password protection system) None 0
InitialKeyLength (length of initial key for the password protection system) None 0
Note: The remaining fields are ignored if Version is less than MQCSP_VERSION_3.
[MQ 9.4.0 Jun 2024]Reserved4 (required for pointer alignment on IBM i) None Null string or blanks
[MQ 9.4.0 Jun 2024]TokenPtr (address of authentication token) None Null pointer or blanks
[MQ 9.4.0 Jun 2024]TokenKeyOffset (offset of authentication token) None 0
[MQ 9.4.0 Jun 2024]TokenLength (length of authentication token) None 0
Notes:
  1. The symbol ¬ represents a single blank character.
  2. In the C programming language, the macro variable MQCSP_DEFAULT contains the values that are listed in the table. It can be used in the following way to provide initial values for the fields in the structure: 
    MQCSP MyCSP = {MQCSP_DEFAULT};

Language declarations

C declaration for MQCSP

typedef struct tagMQCSP MQCSP;
struct tagMQCSP {
  MQCHAR4    StrucId;            /* Structure identifier */
  MQLONG     Version;            /* Structure version number */
  MQLONG     AuthenticationType; /* Type of authentication */
  MQBYTE4    Reserved1;          /* Required for IBM i pointer alignment */
  MQPTR      CSPUserIdPtr;       /* Address of user ID */
  MQLONG     CSPUserIdOffset;    /* Offset of user ID */
  MQLONG     CSPUserIdLength;    /* Length of user ID */
  MQBYTE8    Reserved2;          /* Required for IBM i pointer alignment */
  MQPTR      CSPPasswordPtr;     /* Address of password */
  MQLONG     CSPPasswordOffset;  /* Offset of password */
  MQLONG     CSPPasswordLength;  /* Length of password */
/* Ver:1 */

  MQBYTE8    Reserved3;          /* Required for IBM i pointer alignment */
  MQPTR      InitialKeyPtr;      /* Address of initial key */
  MQLONG     InitialKeyOffset;   /* Offset of initial key */
  MQLONG     InitialKeyLength;   /* Length of initial key */
/* Ver:2 */
  };
[MQ 9.4.0 Jun 2024]

typedef struct tagMQCSP MQCSP;
struct tagMQCSP {
  MQCHAR4    StrucId;            /* Structure identifier */
  MQLONG     Version;            /* Structure version number */
  MQLONG     AuthenticationType; /* Type of authentication */
  MQBYTE4    Reserved1;          /* Required for IBM i pointer alignment */
  MQPTR      CSPUserIdPtr;       /* Address of user ID */
  MQLONG     CSPUserIdOffset;    /* Offset of user ID */
  MQLONG     CSPUserIdLength;    /* Length of user ID */
  MQBYTE8    Reserved2;          /* Required for IBM i pointer alignment */
  MQPTR      CSPPasswordPtr;     /* Address of password */
  MQLONG     CSPPasswordOffset;  /* Offset of password */
  MQLONG     CSPPasswordLength;  /* Length of password */
/* Ver:1 */

  MQBYTE8    Reserved3;          /* Required for IBM i pointer alignment */
  MQPTR      InitialKeyPtr;      /* Address of initial key */
  MQLONG     InitialKeyOffset;   /* Offset of initial key */
  MQLONG     InitialKeyLength;   /* Length of initial key */
/* Ver:2 */

  MQBYTE8    Reserved4;          /* Required for IBM i pointer alignment */
  MQPTR      TokenPtr;           /* Address of token */
  MQLONG     TokenOffset;        /* Offset of token */
  MQLONG     TokenLength;        /* Length of token */
/* Ver:3 */
  };

COBOL declaration for MQCSP

**   MQCSP structure
  10 MQCSP.
**    Structure identifier
   15 MQCSP-STRUCID           PIC X(4).
**    Structure version number
   15 MQCSP-VERSION           PIC S9(9) BINARY.
**    Type of authentication
   15 MQCSP-AUTHENTICATIONTYPE PIC S9(9) BINARY.
**    Required for IBM i pointer alignment
   15 MQCSP-RESERVED1         PIC X(4).
**    Address of user ID
   15 MQCSP-CSPUSERIDPTR      POINTER.
**    Offset of user ID
   15 MQCSP-CSPUSERIDOFFSET   PIC S9(9) BINARY.
**    Length of user ID
   15 MQCSP-CSPUSERIDLENGTH   PIC S9(9) BINARY.
**    Required for IBM i pointer alignment
   15 MQCSP-RESERVED2         PIC X(4).
**    Address of password
   15 MQCSP-CSPPASSWORDPTR    POINTER.
**    Offset of password
   15 MQCSP-CSPPASSWORDOFFSET PIC S9(9) BINARY.
**    Length of password
   15 MQCSP-CSPPASSWORDLENGTH PIC S9(9) BINARY.
** Ver:1 **

**    Reserved
   15 MQCSP-RESERVED3         PIC X(8).
**    Address of initial key
   15 MQCSP-INITIALKEYPTR     POINTER.
**    Offset of initial key
   15 MQCSP-INITIALKEYOFFSET  PIC S9(9) BINARY.
**    Length of initial key
   15 MQCSP-INITIALKEYLENGTH  PIC S9(9) BINARY.
** Ver:2 **
[MQ 9.4.0 Jun 2024]

**   MQCSP structure
  10 MQCSP.
**    Structure identifier
   15 MQCSP-STRUCID           PIC X(4).
**    Structure version number
   15 MQCSP-VERSION           PIC S9(9) BINARY.
**    Type of authentication
   15 MQCSP-AUTHENTICATIONTYPE PIC S9(9) BINARY.
**    Required for IBM i pointer alignment
   15 MQCSP-RESERVED1         PIC X(4).
**    Address of user ID
   15 MQCSP-CSPUSERIDPTR      POINTER.
**    Offset of user ID
   15 MQCSP-CSPUSERIDOFFSET   PIC S9(9) BINARY.
**    Length of user ID
   15 MQCSP-CSPUSERIDLENGTH   PIC S9(9) BINARY.
**    Required for IBM i pointer alignment
   15 MQCSP-RESERVED2         PIC X(4).
**    Address of password
   15 MQCSP-CSPPASSWORDPTR    POINTER.
**    Offset of password
   15 MQCSP-CSPPASSWORDOFFSET PIC S9(9) BINARY.
**    Length of password
   15 MQCSP-CSPPASSWORDLENGTH PIC S9(9) BINARY.
** Ver:1 **

**    Reserved
   15 MQCSP-RESERVED3         PIC X(8).
**    Address of initial key
   15 MQCSP-INITIALKEYPTR     POINTER.
**    Offset of initial key
   15 MQCSP-INITIALKEYOFFSET  PIC S9(9) BINARY.
**    Length of initial key
   15 MQCSP-INITIALKEYLENGTH  PIC S9(9) BINARY.
** Ver:2 **

**    Reserved
   15 MQCSP-RESERVED4         PIC X(8).
**    Address of token
   15 MQCSP-TOKENPTR     POINTER.
**    Offset of token
   15 MQCSP-TOKENOFFSET  PIC S9(9) BINARY.
**    Length of token
   15 MQCSP-TOKENLENGTH  PIC S9(9) BINARY.
** Ver:3 **

PL/I declaration for MQCSP

dcl
 1 MQCSP based,
  3 StrucId           char(4),       /* Structure identifier */
  3 Version           fixed bin(31), /* Structure version number */
  3 AuthenticationType fixed bin(31),  /* Type of authentication */
  3 Reserved1         char(4),       /* Required for IBM i pointer
                                        alignment */
  3 CSPUserIdPtr      pointer,       /* Address of user ID */
  3 CSPUserIdOffset   fixed bin(31), /* Offset of user ID */
  3 CSPUserIdLength   fixed bin(31), /* Length of user ID */
  3 Reserved2         char(8),       /* Required for IBM i pointer
                                        alignment */
  3 CSPPasswordPtr    pointer,       /* Address of password */
  3 CSPPasswordOffset fixed bin(31), /* Offset of user ID */
  3 CSPPasswordLength fixed bin(31), /* Length of user ID */
/* Version 1 */                                                     

  3 Reserved3         char(8),       /* Reserved */              
  3 InitialKeyPtr     pointer,       /* Address of initial key */
  3 InitialKeyOffset  fixed bin(31), /* Offset of initial key */ 
  3 InitialKeyLength  fixed bin(31); /* Length of initial key */ 
/* Version 2 */
[MQ 9.4.0 Jun 2024]

dcl
 1 MQCSP based,
  3 StrucId           char(4),       /* Structure identifier */
  3 Version           fixed bin(31), /* Structure version number */
  3 AuthenticationType fixed bin(31),  /* Type of authentication */
  3 Reserved1         char(4),       /* Required for IBM i pointer
                                        alignment */
  3 CSPUserIdPtr      pointer,       /* Address of user ID */
  3 CSPUserIdOffset   fixed bin(31), /* Offset of user ID */
  3 CSPUserIdLength   fixed bin(31), /* Length of user ID */
  3 Reserved2         char(8),       /* Required for IBM i pointer
                                        alignment */
  3 CSPPasswordPtr    pointer,       /* Address of password */
  3 CSPPasswordOffset fixed bin(31), /* Offset of user ID */
  3 CSPPasswordLength fixed bin(31), /* Length of user ID */
/* Version 1 */                                                     

  3 Reserved3         char(8),       /* Reserved */              
  3 InitialKeyPtr     pointer,       /* Address of initial key */
  3 InitialKeyOffset  fixed bin(31), /* Offset of initial key */ 
  3 InitialKeyLength  fixed bin(31); /* Length of initial key */ 
/* Version 2 */

  3 Reserved4         char(8),       /* Reserved */              
  3 TokenPtr          pointer,       /* Address of Token */
  3 TokenOffset       fixed bin(31), /* Offset of Token */ 
  3 TokenLength       fixed bin(31); /* Length of Token */ 
/* Version 3 */

Visual Basic declaration for MQCSP

Type MQCSP
  StrucId           As String*4   'Structure identifier'
  Version           As Long       'Structure version number'
  AuthenticationType As Long      'Type of authentication'
  Reserved1         As MQBYTE4    'Required for IBM i pointer'
                                  'alignment'
  CSPUserIdPtr      As MQPTR      'Address of user ID'
  CSPUserIdOffset   As Long       'Offset of user ID'
  CSPUserIdLength   As Long       'Length of user ID'
  Reserved2         As MQBYTE8    'Required for IBM i pointer'
                                  'alignment'
  CSPPasswordPtr    As MQPTR      'Address of password'
  CSPPasswordOffset As Long       'Offset of password'
  CSPPasswordLength As Long       'Length of password'
End Type