Configuring certificates for the REST management interface

You can configure the REST management interface to use certificates that you supply.

About this task

You use the appliance command line interface to configure the REST management interface to use your certificates.

To set up secure communication between a REST client and the REST management interface and to handle certificates, you create a TLS server profile on the appliance. You import the required certificates and key file to the appliance, and create definition objects for them. The definition objects are used when you create an ID credentials (idcred) object for the appliance. The idcred is in turn used when you configure the TLS server profile. Finally, the TLS server profile is associated with your web management profile.

If you want to configure client validation, you import the certificates of the clients that are going to be allowed to connect. You then create definition objects for the certificates, which are used when you create a validation credential (valcred) object. The valcred object is in turn used when you configure the TLS server profile.

The example in this topic assumes that you have a signed certificate for the appliance. When you make certificate requests for an appliance, the CN part of the distinguished name must be the URL that you type to connect to the REST API. For example, myappliance1.ourcompany.com. If you want to set up the profile to validate connecting clients, you also require the relevant client certificates.

By default the REST management service listens on all of the appliance ports (local address set to 0.0.0.0). However, you can configure the service so that it listens on an IP address or host alias of a specific port (and so limit access to the REST management interface).

Procedure

To upload certificates to your appliance:
1. Ensure that you have the following items:
  - A private key to access the appliance certificate.
  - The appliance certificate.
  - Client certificates (optional).
2. Connect to the IBM® MQ Appliance as described in Command line access.
3. Log in as a user in the administrators group.
4. Type the following command to enter configuration mode:
```
config
```
5. Upload the key and certificates to the appliance by using the copy command, for example:
```
copy scp://username@otherserver//home/username/myappliance1key.pem cert:
copy scp://username@otherserver//home/username/myappliance1.cer cert:
copy scp://username@otherserver//home/username/client1.cer cert:
copy scp://username@otherserver//home/username/client2.cer cert:
copy scp://username@otherserver//home/username/client3.cer cert:
```
You can also copy the certificates to your appliance by using the IBM MQ Appliance web UI, see Uploading certificates to the appliance.
To create definition objects for the appliance certificate and key:
1. From configuration mode, type crypto to enter crypto configuration mode.
2. Create a crypto key definition for the private key that is used for generating the appliance certificate:
```
key key_alias cert:///keyfile
```
  For example:
```
key WebUiKey01 cert:///myappliance1key.pem
```
3. Create a crypto certificate definition for the appliance:
```
certificate cert_alias cert:///certfile
```
  For example:
```
certificate RESTmgmt cert:///myappliance1.cer
```
4. Create a crypto credential definition for the appliance:
```
idcred credential_name key_alias cert_alias 
```
  For example:
```
idcred RESTmgtCred01 RESTmgtKey01 RESTmgtCert01 
```
To create a crypto valcred definition for validating clients (this step is optional):
1. From the crypto configuration mode, create a certificate definition object for each of the client certificates that you have imported:
```
certificate cert_alias cert:///certfile
```
  For example:
```
certificate RESTClientCert01 cert:///client1.cer
certificate RESTClientCert02 cert:///client2.cer
certificate RESTClientCert03 cert:///client3.cer
```
2. Create a crypto valcred definition, specifying the certificate definitions for the client certificates:
```
valcred valcred_name
certificate cert_alias 
```
  Repeat the certificate command to specify the certificate definition for every client certificate that you have uploaded. For example:
```
valcred RESTcred01
certificate RESTClientCert01
certificate RESTClientCert02
certificate RESTClientCert03 
```

To create an TLS server profile for the appliance:

From the crypto configuration mode, enter the following commands:

ssl-server TLS_Svr_Profile_name
admin-state enabled
idcred IDCred_name
protocols TLSv1d2

If you are specifying client validation, also enter:


valcred ValCred_name
request-client-auth on
require-client-auth on
send-client-auth-ca-list on

For example:

ssl-server myappliance1
admin-state enabled
idcred RESTmgtCred01
protocols TLSv1d2
valcred RESTcred01
request-client-auth on
require-client-auth on
send-client-auth-ca-list on

To save all the changes that you have made in crypto configuration mode:
1. Type exit to leave crypto configuration mode.
2. Type write mem to save your configuration changes.
To associate the TLS server profile with the REST management interface:
1. From configuration mode, type rest-mgmt to enter REST management interface configuration mode.
2. Enter the following command:
```
ssl-server SSL_Svr_Profile_name
```
  For example:
```
ssl-server myappliance1
```
To save your REST management interface configuration:
1. Type exit to leave rest-mgmt configuration mode.
2. Type write mem to save your configuration changes.
3. Type exit again to leave configuration mode.