The TLS sample program

AMQSSSLC is a sample C program that demonstrates how to use the MQCNO and MQSCO structures to supply TLS client connection information on the MQCONNX call. This enables a client MQI application to provide the definition of its client connection channel and TLS settings at run time without a client channel definition table (CCDT).

If a connection name is supplied, the program constructs a client connection channel definition in an MQCD structure.

If the stem name of the key repository file is supplied, the program constructs an MQSCO structure; if an OCSP responder URL is also supplied, the program constructs an authentication information record MQAIR structure.

The program then connects to the queue manager using MQCONNX. It inquires and prints out the name of the queue manager to which it connected.

This program is intended to be linked as an MQI client application. However, it can be linked as a regular MQI application, in which case it simply connects to a local queue manager and ignores the client connection information.

If the passphrase to access the key repository is not stashed to a file, you must supply the passphrase to amqssslc when the application runs. You can supply the passphrase either by:

Requesting amqssslc to prompt for the passphrase, or
Using the MQKEYRPWD environment variable, or
Using the SSLKeyRepositoryPassword attribute in the client configuration file

For more information about supplying the key repository password to IBM® MQ MQI client applications, see Supplying the key repository password for an IBM MQ MQI client on AIX®, Linux®, and Windows.

amqssslc accepts the following parameters, all of which are optional:

-m QmgrName: Name of the queue manager to connect to
-c ChannelName: Name of the channel to use
-x ConnName: Server connection name

TLS parameters:

-k KeyReposFileName

The name of the key repository file. If the file extension is not supplied, it is assumed to be .kdb. For example:

/home/user/client.kdb
C:\User\client.p12

-s CipherSpec

The TLS channel CipherSpec string corresponding to the SSLCIPH on the SVRCONN channel definition on the queue manager.

-f

Specifies that only FIPS 140-2 certified algorithms must be used.

-b VALUE1[,VALUE2...]

Specifies that only Suite B compliant algorithms must be used. This parameter is a comma-separated list of one or more of the following values: NONE,128_BIT,192_BIT. These values have the same meaning as those for the MQSUITEB environment variable, and the equivalent EncryptionPolicySuiteB setting in the client configuration file SSL stanza.

-p Policy

Specifies the certificate validation policy to be used. This can be one of the following values:

ANY: Apply each of the certificate validation policies supported by the secure sockets library and accept the certificate chain if any of the policies considers the certificate chain valid. This setting can be used for maximum backwards compatibility with older digital certificates which do not comply with the modern certificate standards.
RFC5280: Apply only the RFC 5280 compliant certificate validation policy. This setting provides stricter validation than the ANY setting, but rejects some older digital certificates.

The default value is ANY.

-l CertLabel

The certificate label to use for the secure connection.

Note: You must specify the value using lowercase characters.

-w

Specifies that amqssslc prompts for the key repository passphrase to be supplied.

-i

Specifies that amqssslc prompts for the initial key used to encrypt the key repository passphrase to be supplied.

Specify this option if an initial key file was specified when the key repository passphrase was encrypted using the runmqicred utility.

OCSP certificate revocation parameter:

-o URL: The OCSP Responder URL

You can also set one of the following environment variables to supply credentials that are used to authenticate with the queue manager:

MQSAMP_USER_ID: Set to the user ID to be used for connection authentication, if you want use a user ID and a password to authenticate with the queue manager. The program prompts for the password to accompany the user ID.
MQSAMP_TOKEN: Set to a non-blank value if you want to supply an authentication token to authenticate with the queue manager. The program prompts for the authentication token.