Certificate expiry and renewal

How to renew and replace TLS certificates in your VMware deployment.

The instructions in this topic apply only to the management, portal, and analytics subsystems. For gateway appliance-specific instructions, see Configuring the API Connect Gateway Service in the appropriate version of the DataPower documentation.

Note: The API invocation certificate (the certificate that is presented to callers of your APIs) is configured in the Cloud Manager UI when you register your gateway services. For more information about API invocation certificates, see Registering a gateway service and TLS profiles overview.

All ingress certificates in API Connect have a duration of 2 years. To avoid an outage when they expire, they must be manually renewed before expiration.

The ingress-ca CA certificate has a duration of 10 years and also requires manual steps to renew it before expiry.

Intra-subsystem certificates are renewed automatically.

Identifying expired certificates

From V10.0.5.7, to identify expired certificates, run:

apicup certs list <subsystem>

Any certificates that are expired or near to expiry are indicated in the Validation errors column.

Follow the step in Renewing certificates to renew expired or nearly expired certificates.

V10.0.5.6 and earlier releases: The apicup tool does not check certificate expiry. To check for expired certificates, you must login to your VMs and use the apicops tool:

Login to each subsystem VM:
```
ssh apicadm@<subsystem hostname>
```
Note: If you have a three replica deployment, login to only one of the VMs of each subsystem.
Switch to the root user:
```
sudo -i
```
Install the apicops tool: The API Connect operations tool: apicops:
1. Download the latest apicops-v10-linux executable file:
```
wget <URL of latest apicops-v10-linux>
```
  For example:
```
wget https://github.com/ibm-apiconnect/apicops/releases/download/<latest version>/apicops-v10-linux
```
2. Add execute permissions to apicops-v10-linux:
```
chmod a+x apicops-v10-linux
```
Run the apicops certs:validate command:
```
./apicops-v10-linux certs:validate -s <subsystem>
```
where <subsystem> is the subsystem you are running the command on, either: Management, portal, or analytics.
The apicops command reports any certificates that are expired or within 60 days of expiry.
You can ignore the message:
```
Cannot check who signed the certificate returned by ... as no ingress issuer was provided
```
this is expected on VMware deployments.
Renew any certificates that are expired or approaching expiry, except for the certificates that are listed under the heading Validating subsystem certificates for <subsystem name>, these are intra-subsystem certificates that are renewed automatically.
```
Validating subsystem certificates for abc-management
Good certificate: <subsystem name>-ca
Good certificate: <subsystem name>-client
Good certificate: <subsystem name>-server
```
Follow the step in Renewing certificates to renew expired or nearly expired certificates.

Renewing certificates

Use the apicup command to renew certificates.

Warning: Use these steps to renew only end-entity ingress certificates as defined here: ingress certificates. If you want to renew the ingress-ca certificate, then see Renewing ingress-ca.

Clear the existing certificate with the apicup certs clear command:
```
apicup certs set --clear <subsystem> <certificate name>
```
Repeat for all ingress certificates that you want to renew.
Generate new certificates for all the certificates that you cleared in step 1:
```
apicup certs generate <subsystem>
```
You do not need to specify the certificates with the apicup certs generate, the command identifies all empty (cleared) certificates in the subsystem and generates new ones.
Apply the updated certificates to the subsystem:
```
apicup subsys install <subsystem>
```

Renewing `ingress-ca`

Use the apicup command to renew ingress-ca, and then renew all the end-entity certificates the are signed by ingress-ca.

Clear the ingress-ca certificate:
```
apicup certs set --clear <management subsystem> ingress-ca
```
Although this command specifies <management subsystem>, because ingress-ca is a common certificate, it is cleared for all subsystems. You do not need to repeat this command for every portal or analytics subsystem that is managed from the same project directory.
Generate a new ingress-ca:
```
apicup certs generate <subsystem>
```
The generate command creates certificates for all previously cleared certificates, you do not need to specify ingress-ca in this command.
Clear all the ingress end-entity certificates that are signed by ingress-ca:
```
apicup certs set --clear <subsystem> <certificate name>
```
For a list of the ingress certificates, see Ingress certificates.
Generate new ingress end-entity certificates for each subsystem:
```
apicup certs generate <subsystem>
```
Apply the updated certificates to all subsystems:
```
apicup subsystem install <subsystem>
```