Replacing custom certificates

Use the APICUP installer certs commands to replace existing certificates.

About this task

Important:

Customization of public certificates and public user-facing certificates is recommended. Customization of internal certificates is strongly discouraged.
To view a list of public, public user-facing, and internal certificates, see Certificate management: Read This First. For details on each certificate, see Certificate reference.

The APICUP installer can be used to update certificates for each subsystem after installation.

Requirements for custom certificates:

Extended Key Usage (EKU), either serverAuth or clientAuth depending upon the type of certificate. Certificates of type Server must have an Extended Key Usage with serverAuth purpose. Certificates of type Client must have an Extended Key Usage with clientAuth purpose.
Subject Alternative Name (SAN) for the required hosts
Any custom common certificates that are being used must be set prior to setting any custom certificates for a subsystem.

See Certificate Reference to view the list of common certificates and to determine whether an EKU is needed for a certificate and which type of EKU (serverAuth or clientAuth).

Certificates and identical endpoints:

The Management subsystem has four public endpoints: api-manager-ui, cloud-admin-ui, platform-api, and consumer-api. Distinct TLS certificates can be set for each endpoint. However, if any two endpoints are identical, only one TLS certificate will be effective. When 2 or more endpoints are set to the same host, the secrets associated with the endpoints should be the same or contain the same certificate files.

Procedure

Generate the custom certificate with the appropriate EKU and SAN. You will need to obtain the private key, public certificate, and CA certificates in non-password-protected PEM format for the custom certificate. Following is an example for how to generate a certificate (platform-api-example) with an EKU serverAuth and SAN using openssl:
```
openssl x509 -req -days 360 -in platform-api-example.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -out platform-api-cert -sha256  
-extfile <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:fqdn.myserver.com\nextendedKeyUsage=serverAuth")) 
-extensions SAN
```
where
- DNS:fqdn.myserver.com is the fully qualified domain name of the endpoint the certificate applies to. This matches the endpoints entered in the APICUP installer. See Installing the Management subsystem into a Kubernetes environment
- platform-api-example.csr is the file name for the certificate signing request
Following is an example for how to generate a certificate (portal-client) with an EKU clientAuth and SAN using openssl:
```
openssl x509 -req -days 360 -in portal-client-example.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -out portal-client-cert  
-sha256 -extfile <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nkeyUsage=critical, digitalSignature,keyEncipherment\nextendedKeyUsage = clientAuth\nbasicConstraints=critical, 
CA:FALSE\nsubjectKeyIdentifier=hash\n")) -extensions SAN
```
Once the certificate has been created, set the certificate by entering the following command:

apicup certs set SUBSYS CERT_NAME [CERT_FILE KEY_FILE CA_FILE]

You can find definitions for commands at the following location: Command reference

If the certificate is signed by an intermediate CA, the CA_File argument must point to a file that concatenates the intermediate CA, followed by the root CA, in that order.

If the certificate was generated with an EKU serverAuth, it must be assigned to a server certificate. If the certificate was generated with an EKU clientAuth, it must be assigned to a client certificate.
Install the subsystem with the new certificate using apicup subsys install SUBSYS. Any missing certificates will be generated. The installation will not proceed if there are any validation issues with the certificates.
See Validation reference.
Repeat for other subsystems requiring new certificates.