Setting custom certificates

Use the APICUP installer certs commands to set custom 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 set certificates for each subsystem during installation. If certificates are not explicitly set by using the apicup certs set command, then default certificates are generated by APICUP. The default certificates are self-signed, so they might not provide a level of trust suitable for external communication.

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.

Note: Once API Connect has been installed (meaning that the

apicup subsys install
SUBSYS

command has been executed) with a given set of certificates, only the certificates for the public ingress endpoints (portal-www, api-manager-ui, cloud-admin-ui, platform-api, consumer-api) can be modified. The TLS certificates involved in mutual authentication (portal-admin-ingress, portal-client, analytics-ingestion-ingress, analytics-ingestion-client) cannot be modified after the install command has been executed.

Procedure

Set up and validate the subsystem. Enter the settings for the subsystem using apicup subsys set <SUBSYS> and validate the subsystem settings using apicup subsys get <SUBSYS> --validate. The subsystem must pass validation before setting the certificates.
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 Deploying the Management virtual appliance
- 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] [KEY_FILE] [flags]

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.

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

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.
Repeat for additional custom certificates.
After setting the custom certificates, you can optionally generate the remaining default certificates prior to installation by entering the apicup certs generate command. The generate command generates any certificates that have not been set, so it will create default certificates for all remaining certificates. It will not overwrite any custom certificates you have set. You can review the certificates prior to installation.

List all certificates with apicup certs list SUBSYS. The results will include the generated default certificates and the custom certificates that you set.

Following is example output from the apicup certs list command:

Common certificates
===================

Name                        Summary                                                          Validation errors
----                        -------                                                          -----------------
analytics-ingestion-client  CN: analytics-ingestion-client                                   
                            SubjectKeyId: 27:60:BF:DF:6C:34:29:FE:8E:83:21:1B:C0:14:B2:9E    
                            AuthorityKeyId: 0B:37:61:5F:81:B3:67:5B:E0:F1:05:A6:6E:08:D5:8E  
ingress-ca                  CN: ingress-ca                                                   
                            SubjectKeyId: 0B:37:61:5F:81:B3:67:5B:E0:F1:05:A6:6E:08:D5:8E    
                            AuthorityKeyId: 5E:6D:5C:6E:2C:BE:50:F3:4E:EE:FD:02:76:86:6C:5A  
portal-client               CN: portal-client                                                
                            SubjectKeyId: 08:A8:57:A5:99:BC:79:FA:14:59:A4:98:6D:F7:43:C4    
                            AuthorityKeyId: 0B:37:61:5F:81:B3:67:5B:E0:F1:05:A6:6E:08:D5:8E  
root-ca                     CN: root-ca                                                      
                            SubjectKeyId: 5E:6D:5C:6E:2C:BE:50:F3:4E:EE:FD:02:76:86:6C:5A    
                            AuthorityKeyId:                                                  

Subsystem mgmt_subsys certificates
==================================

Name               Summary                                                          Validation errors
----               -------                                                          -----------------
api-manager-ui     CN: api-manager-ui
                   SubjectKeyId: F7:96:78:02:BE:01:83:C4:DF:42:A9:87:94:AB:1D:35
                   AuthorityKeyId: 6E:5A:6C:82:BA:F2:62:CF:B3:85:54:23:B6:26:9A:3F
cloud-admin-ui     CN: cloud-admin-ui
                   SubjectKeyId: AC:13:32:C2:6D:7B:46:6D:67:B5:41:6E:92:42:D3:4C
                   AuthorityKeyId: 6E:5A:6C:82:BA:F2:62:CF:B3:85:54:23:B6:26:9A:3F
consumer-api       CN: consumer-api
                   SubjectKeyId: DE:84:86:40:4F:1E:30:A6:16:0E:CD:5B:8E:0C:1A:46
                   AuthorityKeyId: 6E:5A:6C:82:BA:F2:62:CF:B3:85:54:23:B6:26:9A:3F
encryption-secret  A9:F3:28:0E:1E:AA:D9:5E:86:02:A4:95:69:83:94:30
k8s-ca             CN: k8s-ca                                                       
                   SubjectKeyId: 60:D9:B2:37:0B:17:FB:CD:FC:49:29:32:F6:A6:49:7C    
                   AuthorityKeyId:     
platform-api       CN: platform-api
                   SubjectKeyId: AC:EF:88:78:01:A1:4D:8E:95:95:7D:3E:C5:43:F9:48
                   AuthorityKeyId: 6E:5A:6C:82:BA:F2:62:CF:B3:85:54:23:B6:26:9A:3F

Install the subsystem with the certificates 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.
If necessary, you can replace custom certificates after installation is complete. See Replacing custom certificates.