setamschl (set AMS channel)

Set up MCA interception on a specific server-connection channel on a queue manager previously configured with AMS.

Purpose

You can use the setamschl command to set up MCA interception on a particular server-connection channel on a specified queue manager. You can also use setamschl to delete existing MCA interceptions.

You can use OCSP or CRL to check on the validity of the certificates used in your MCA interception. You can specify properties for either method using the setamschl command.

Syntax

Parameters

-m QMgrName: Specifies the name of the queue manager for which the MCA interception is required.; The queue manager must exist.
-n channel_name: Specifies the name of the server-connection channel for which the MCA interception is required.
-c certificate_label: Specifies the certificate used for the queue manager. The certificate is identified by its label.
-k property: Optionally specify an OCSP or CRL property to set. See Table 1 and Table 2 for lists of available properties.
-v value: Specify the value of an OCSP or CRL property. See Table 1 and Table 2 for guidance.
-d: Specify this option to delete the specified MCA interception.
You can also specify this option with the -k option to delete the specified property.

Table 1. OCSP properties and values
Option	Description
`ocsp.enable=off`	Enable the OCSP checking if the certificate being checked has an Authority Info Access (AIA) Extension with an PKIX_AD_OCSP access method containing a URI of where the OCSP Responder is located. Possible values: `on` or `off`.
`ocsp.url=responder_URL`	The URL address of OCSP responder. If this option is omitted then non-AIA OCSP checking is disabled.
`ocsp.http.proxy.host=OCSP_proxy`	The URL address of the OCSP proxy server. If this option is omitted then a proxy is not used for non-AIA online certificate checks.
`ocsp.http.proxy.port=port_number`	The OCSP proxy server's port number. If this option is omitted then the default port of 8080 is used.
`ocsp.nonce.generation=on/off`	Generate nonce when querying OCSP. The default value is `off`.
`ocsp.nonce.check=on/off`	Check nonce after receiving a response from OCSP. The default value is `off`.
`ocsp.nonce.size=8`	Nonce size in bytes.
`ocsp.http.get=on/off`	Specify HTTP GET as your request method. If this option is set to `off`, HTTP POST is used. The default value is `off`.
`ocsp.max_response_size=20480`	Maximum size of response from the OCSP responder provided in bytes.
`ocsp.cache_size=100`	Enable internal OCSP response caching and set the limit for the number of cache entries.
`ocsp.timeout=30`	Waiting time for a server response, in seconds, after which Advanced Message Security times-out.
`ocsp.unknown=ACCEPT`	Defines the behavior when an OCSP server cannot be reached within a timeout period. Possible values: `ACCEPT` Allows the certificate `WARN` Allows the certificate and logs a warning `REJECT` Prevents the certificate from being used and logs an error

Table 2. CRL properties and values
Option	Description
`crl.ldap.host=host_name`	LDAP server host name.
`crl.ldap.port=port_number`	LDAP server port number. Each AMS native interceptor supports only one LDAP CRL server.
`crl.cdp=off`	Use this option to check or use CRLDistributionPoints extensions in certificates.
`crl.ldap.version=3`	LDAP protocol version number. Possible values: 2 or 3.
`crl.ldap.user=cn=username`	Log in to the LDAP server. If this value is not specified, CRL attributes in LDAP must be world-readable
`crl.ldap.pass=password`	Password for the LDAP server. This is encrypted by the appliance. If you do not want to enter the password in plain text on the command line, omit the `-v value` option, and you are prompted to enter the password interactively.
`crl.ldap.cache_lifetime=0`	LDAP cache lifetime in seconds. Possible values: 0-86400.
`crl.ldap.cache_size=50`	LDAP cache size. This option can be specified only if the `crl.ldap.cache_lifetime` value is larger than `0`.
`crl.http.proxy.host=some.host.com`	HTTP proxy server port for CDP CRL retrieval.
`crl.http.proxy.port=8080`	HTTP proxy server port number.
`crl.http.max_response_size=204800`	The maximum size of CRL, in bytes, that can be retrieved from an HTTP server that is accepted by IBM® Global Security Kit (GSKit).
`crl.http.timeout=30`	Waiting time for a server response, in seconds, after which AMS times outs.
`crl.http.cache_size=0`	HTTP cache size, in bytes.
`crl.unknown=ACCEPT`	Defines the behavior when a CRL server cannot be reached within a timeout period. Possible values: `ACCEPT` Allows the certificate `WARN` Allows the certificate and logs a warning `REJECT` Prevents the certificate from being used and logs an error

Usage notes

This command must be run from the IBM MQ administration mode. If the system is in the IBM MQ administration mode the prompt includes mq. To enter the IBM MQ administration mode, enter mqcli on the command line. To exit the IBM MQ administration mode, enter exit on the command line.
MCA interception requires that the required certificates and keys are held in the queue manager key repository. The key repository is created automatically with the queue manager and managed with the certificate commands.

Examples

The following command creates an MCA interception for the server-connection channel SC1 on queue manager QM1:
```
setamschl -m QM1 -n SC1 -c cert1
```

The following command sets the LDAP server host name for CRL checking:

setamschl -m QM1 -k crl.ldap.host -v myhost.mydomain
MCA interception key crl.ldap.host set for queue manager QM1.

The following command deletes the LDAP server host name setting:
```
setamschl -m QM1 -k crl.ldap.host -d
```