Using Custom Certificates

This guide describes how to use and update certificates on orcharhino Server and orcharhino Proxy Servers. If you want to use custom SSL/TLS certificates, you can add them during the installation process or replace the orcharhino default certificates at a later stage. For more information, see main installation steps in Installing orcharhino Server.

In general, you can change the SSL certificates of orcharhino, for example, if you want to use your own CA or a third party non self-signed CA. You can change the katello-server-ca, but you must not change the katello-default-ca.

Ensure to carry out the following procedure with absolute caution. Aborting the procedure will irreparably damage orcharhino. Ensure to create a backup to which you can revert to.

If you use AlmaLinux 9, Oracle Linux 9, Red Hat Enterprise Linux 9, and Rocky Linux 9 systems connecting to orcharhino, do not use SSL certificates that rely on SHA-1 as signature algorithm. By default, AlmaLinux 9, Oracle Linux 9, Red Hat Enterprise Linux 9, and Rocky Linux 9 do not trust those SSL certificates.

If you have to use SSL certificates that rely on SHA-1 as signature algorithm, you have to update the crypto policies on AlmaLinux 9, Oracle Linux 9, Red Hat Enterprise Linux 9, and Rocky Linux 9 systems connecting to orcharhino to allow SHA-1 usage.

After this procedure, you must reconnect all orcharhino Proxy Servers and all managed hosts.

Prerequisites

You have successfully installed orcharhino Server with self-signed certificates. Installing orcharhino automatically creates self-signed certificates to ensure a secure connection from your local machine to your orcharhino Server.

For more information, see Installing orcharhino Server Using the install_orcharhino.sh Script in Installing orcharhino Server.
The hostname of your orcharhino Server matches the hostname that the certificates are issued for. For more information, see Setting the Host Name in Installing orcharhino Server.

Migrating to Non Self-Signed Certificates

You can migrate from self-signed certificates to non self-signed certificates. This allows you to use your own CA and certificates. With this procedure, you overwrite active SSL certificates on your orcharhino Server.

Prerequisites

The certificate my_crt.pem, the server key my_key.pem, and the CA my_ca.pem must be available in PEM format in /root/or_ssl/ on your orcharhino Server.

Procedure

On your orcharhino Server, stop all orcharhino services:
```
$ orcharhino-maintain service stop
```

Update the certificates on your orcharhino Server:

$ orcharhino-installer \
--certs-server-ca-cert /root/or_ssl/my_ca.pem \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server \
--certs-update-server-ca

Start all orcharhino services to enable new certificates:
```
$ orcharhino-maintain service start
```
If you use orcharhino Proxy Servers: Transfer the certificates to your orcharhino Proxy Servers. Create the certificates for orcharhino Proxy Servers on your orcharhino Server:
```
$ foreman-proxy-certs-generate \
--certs-tar "/root/$FOREMAN_PROXY-certs.tar" \
--foreman-proxy-fqdn "$FOREMAN_PROXY"
```
Replace $FOREMAN_PROXY with the FQDN of your orcharhino Proxy Server. Transfer the certs.tar archive to your orcharhino Proxy Server by following the instructions from the output of the previous command.

You must update the certificates on all your orcharhino Proxy Servers.

Reconnect managed hosts because the katello-server-ca has been updated. Delete the previously used certificates, install katello-ca-consumer-latest.noarch.rpm, and reregister your managed hosts:

$ rpm -e katello-ca-consumer-orcharhino.example.com
$ subscription-manager clean
$ rpm -ivh https://orcharhino.example.com/pub/katello-ca-consumer-latest.noarch.rpm
$ subscription-manager register --org="$ORG" --activationkey="$ACTIVATIONKEY"

Updating Custom Certificates on orcharhino Server

You can update your custom certificates on orcharhino Server.

Procedure

On your orcharhino Server, stop all orcharhino services:
```
$ orcharhino-maintain service stop
```
If your CA certificate file has not changed, update the certificate as follows:
```
$ orcharhino-installer \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server
```
This procedure only updates the certificates to access the management UI and for interprocess communication. It does not update katello-ca-consumer-latest.noarch.rpm or katello-rhsm-consumer. There are no changes on your managed hosts necessary.
If your non self-signed .ca file has changed, update the certificates as follows:
```
$ orcharhino-installer \
--certs-server-ca-cert /root/or_ssl/my_ca.pem \
--certs-server-cert /root/or_ssl/my_crt.pem \
--certs-server-key /root/or_ssl/my_key.pem \
--certs-update-server \
--certs-update-server-ca
```
This procedure also updates katello-ca-consumer-latest.noarch.rpm and katello-rhsm-consumer. You need to deploy this package to all managed hosts and reregister them to orcharhino Server as described in reconnect clients.
Restart all orcharhino services:
```
$ orcharhino-maintain service start
```
If you use orcharhino Proxy Servers: Follow the output of orcharhino-installer to update the certificates on your orcharhino Proxy Servers. For more information, see updating custom certificates on orcharhino Proxy Server.

You must update the certificates on all your orcharhino Proxy Servers.

Updating Custom Certificates on orcharhino Proxy Server

Procedure

On your orcharhino Server, create a backup of ssl-build:

$ mkdir /root/ssl-build_backup/
$ cp -r /root/ssl-build /root/ssl-build_backup

Remove the old certificates for the orcharhino Proxy Server:

Ensure you have a backup before deleting files in /root/ssl-build/. If you delete more than the folder for the orcharhino Proxy Server, you need to rebuild all certificates, including all self-signed ones which results in a change where you need to re-register all managed hosts.

$ rm -fr /root/ssl-build/orcharhino-proxy.network2.example.com

On your orcharhino Server, generate the certificates:

$ foreman-proxy-certs-generate \
--certs-tar "/root/orcharhino-proxy.network2.example.com-certs.tar" \
--foreman-proxy-fqdn "orcharhino-proxy.network2.example.com" \
--server-ca-cert /root/certs/orcharhino-proxy.ca \
--server-cert /root/certs/orcharhino-proxy.cert \
--server-cert-req /root/certs/orcharhino-proxy.csr \
--server-key /root/certs/orcharhino-proxy.key

Copy the archive to your orcharhino Proxy Server:

$ scp /root/orcharhino-proxy.network2.example.com-certs.tar root@orcharhino-proxy.network2.example.com:root/

Update the certificates on your orcharhino Proxy Server:

$ orcharhino-installer \
--certs-tar-file "/root/orcharhino-proxy.network2.example.com-certs.tar" \
--certs-update-server