Custom SSL Certificates

You can use custom certificates with SUSE Manager and SUSE Manager Proxy.

This section covers how to use a third party SSL certificate authority with a new SUSE Manager installation, and replacing existing certificate with new custom certificates.

Before you begin, ensure you have:

A certificate authority (CA) SSL public certificate
An SSL server key
An SSL server certificate

Your key and certificate files must be in PEM format.

The host name of the SSL keys and certificates must match the fully qualified host name of the machine you deploy them on. You can set the host names in the X509v3 Subject Alternative Name section of the certificate. You can also list multiple host names if your environment requires it.

If you want to use intermediate certificates, you need to merge the intermediate and root CA certificates into one file. Ensure that the intermediate certificate comes first in the combined file.

Custom Certificates for New Installations

By default, SUSE Manager uses a self-signed certificate. After you have completed the initial setup, you can replace the default certificate with a custom certificate.

Procedure: Installing Custom Certificates on a New SUSE Manager Server

Install the SUSE Manager Server according to the instructions in installation:install-intro.adoc.
Complete the initial setup according to installation:server-setup.adoc.

At the command prompt, point the SSL environment variables to the custom certificate file locations:

export CA_CERT=<path_to_CA_certificate_file>
export SERVER_KEY=<path_to_web_server_key>
export SERVER_CERT=<path_to_web_server_certificate>

Complete SUSE Manager setup:
```
yast2 susemanagersetup
```
When you are prompted for certificate details during setup, fill in random values. The values will be overridden by the values you specified at the command prompt.

Execute the yast2 susemanagersetup command from the same shell you exported the environment variables from.

Custom Certificates for New Proxy Installations

By default, SUSE Manager Proxy uses a self-signed certificate. After you have completed the initial setup, you can replace the default certificate with a custom certificate.

Procedure: Installing Custom Certificates on a New SUSE Manager Proxy

Install the SUSE Manager Proxy according to the instructions in installation:install-intro.adoc.
Complete the initial setup according to installation:proxy-setup.adoc.
At the command prompt, run:
```
configure-proxy.sh
```
At the Do you want to import existing certificates? prompt, type y.
Follow the prompts to complete setup.

Re-Create Existing Server Certificates

If your existing custom certificates have expired or stopped working for any reason, you can generate a new server certificate from the existing CA.

Procedure: Re-Creating an Existing Server Certificate

On the SUSE Manager Server, at the command prompt, regenerate the server certificate:

rhn-ssl-tool --gen-server --dir="/root/ssl-build" --set-country="COUNTRY" \
--set-state="STATE" --set-city="CITY" --set-org="ORGANIZATION" \
--set-org-unit="ORGANIZATION UNIT" --set-email="name@example.com" \
--set-hostname="susemanager.example.top" --set-cname="example.com"

Ensure that the set-cname parameter is the fully-qualified domain name of your SUSE Manager Server. You can use the the set-cname parameter multiple times if you require multiple aliases.

Install the RPM that contains the newly generated certificate. Check that you have the latest version of the RPM before running this command. The version number is incremented every time you re-create the certificates.
```
rpm -Uhv /root/ssl-build/lnx0259a/rhn-org-httpd-ssl-key-pair-lnx0259a-1.0-2.noarch.rpm
```
Restart services to pick up the changes:
```
spacewalk-service restart
```

Create and Replace CA and Server Certificates

If you need to create entirely new certificates for an existing installation, you need to create a combined certificate first. Clients will authenticate to the certificate with both the old and new details. Then you can go ahead and remove the old details. This maintains the chain of trust.

Be careful with this procedure! It is possible to break the trust chain between the server and clients using this procedure. If that happens, you will need an administrative user to log in to every client and deploy the CA directly.

Procedure: Creating New Certificates

On the SUSE Manager Server, at the command prompt, move the old certificate directory to a new location:
```
mv /root/ssl-build /root/old-ssl-build
```

Generate a new CA certificate and create an RPM:

rhn-ssl-tool --gen-ca --dir="/root/ssl-build" --set-country="COUNTRY" \
--set-state="STATE" --set-city="CITY" --set-org="ORGANIZATION" \
--set-org-unit="ORGANIZATION UNIT" --set-common-name="SUSE Manager CA Certificate" \
--set-email="name@example.com"

Generate a new server certificate and create an RPM:
```
rhn-ssl-tool --gen-server --dir="/root/ssl-build" --set-country="COUNTRY" \
--set-state="STATE" --set-city="CITY" --set-org="ORGANIZATION" \
--set-org-unit="ORGANIZATION UNIT" --set-email="name@example.com" \
--set-hostname="susemanager.example.top" --set-cname="example.com"
```
Ensure that the set-cname parameter is the fully-qualified domain name of your SUSE Manager Server. You can use the the set-cname parameter multiple times if you require multiple aliases.

You will need to generate a server certificate RPM for each proxy, using their host names and cnames.

When you have new certificates, you can create the combined RPMs to authenticate the clients.

Procedure: Create Combined Certificate RPMs

Create a new CA file that combines the old and new certificate details, and generate a new RPM:

mkdir /root/combined-ssl-build
cp /root/old-ssl-build/RHN-ORG-TRUSTED-SSL-CERT /root/combined-ssl-build/
cat /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT >> /root/combined-ssl-build/RHN-ORG-TRUSTED-SSL-CERT
cp /root/old-ssl-build/*.rpm /root/combined-ssl-build/
rhn-ssl-tool --gen-ca --rpm-only --dir="/root/combined-ssl-build"

Deploy the CA certificate on the server:

/usr/bin/rhn-deploy-ca-cert.pl --source-dir /root/combined-ssl-build \
--target-dir /srv/www/htdocs/pub/ --trust-dir=/etc/pki/trust/anchors/

When you have the combined RPMs, you can deploy the combined CA certificates to your clients.

Procedure: Deploying Combined Certificates on Traditional Clients

On the client, create a new custom channel using these details:
- Name: SSL-CA-Channel
- Label: ssl-ca-channel
- Parent Channel: <choose the parent channel of a clients>
- Summary: SSL-CA-Channel
For more on creating custom channels, see administration:channel-management.adoc.

Upload the CA certificate RPM to the channel:

rhnpush -c ssl-ca-channel --nosig \
--ca-chain=/srv/www/htdocs/pub/RHN-ORG-TRUSTED-SSL-CERT \
/root/combined-ssl-build/rhn-org-trusted-ssl-cert-1.0-2.noarch.rpm

Subscribe all clients to the new SSL-CA-Channel channel.
Install the CA certificate RPM on all clients by updating the channel.

Procedure: Deploying Combined Certificates on Salt Clients

In the SUSE Manager Web UI, navigate to Systems Overview.
Check all your Salt Clients to add them to the System Set Manager (SSM).
Navigate to Systems System Set Manager Overview.
In the States field, click Apply to apply the system states.
In the Highstate page, click Apply Highstate to propagate the changes to the clients.

When you have every client trusting both the old and new certificates, you can go ahead and replace the server certificate on the SUSE Manager Server and Proxies.

Procedure: Replace Server Certificate on the Server

On the SUSE Manager Server, at the command prompt, install the RPM from the ssl-build directory:
```
rpm -Uhv ssl-build/susemanager/rhn-org-httpd-ssl-key-pair-susemanager-1.0-2.noarch.rpm
```
Restart services to pick the changes:
```
spacewalk-service restart
```

Procedure: Replace Server Certificate on the Proxy

On the SUSE Manager Proxy, at the command prompt, install the RPM from the ssl-build directory:

rpm -Uhv ssl-build/susemanager-proxy/rhn-org-httpd-ssl-key-pair-susemanager-proxy-1.0-2.noarch.rpm

Restart services to pick up the changes:
```
rhn-proxy restart
```
Test that all clients still operate as expected and can use SSL to reach the SUSE Manager Server and any proxies.

When you have replaced the server certificates on your server and any proxies, you need to update the certificate with only the new details on all the clients. This is done by adding it to the client channels you set up previously.

Procedure: Adding the New Certificates to the Client Channel

Copy the combined certificate RPM into the /root/ssl-build/ directory:
```
cp /root/combined-ssl-build/*.rpm /root/ssl-build/
```
Generate a new RPM with from the new certificates. Check the release number carefully to ensure you have the right certificate file:
```
rhn-ssl-tool --gen-ca --rpm-only --dir="/root/ssl-build"
```

Install the new local certificates on the SUSE Manager Server:

/usr/bin/rhn-deploy-ca-cert.pl --source-dir /root/ssl-build \
--target-dir /srv/www/htdocs/pub/ --trust-dir=/etc/pki/trust/anchors/

Restart services to pick up the changes:
```
spacewalk-service restart
```

Upload the new RPM into the channel:

rhnpush -c ssl-ca-channel --nosig \
--ca-chain=/srv/www/htdocs/pub/RHN-ORG-TRUSTED-SSL-CERT \
/root/ssl-build/rhn-org-trusted-ssl-cert-1.0-3.noarch.rpm

When you have the new certificate in the channel, you can use the SUSE Manager Web UI to update it on all clients and proxies, by synchronizing them with the channel. Alternatively, for Salt clients, you can use Salt Remote Commands, or apply the highstate.

You will also need to update your proxies to remove the copy of the certificate and the associated RPM. Your proxies must have the same certificate content as the server. Check the /srv/www/htdocs/pub/ directory and ensure it contains:

RHN-ORG-TRUSTED-SSL-CERT
rhn-org-trusted-ssl-cert-*.noarch.rpm

To complete the process, you need to update the database with this command:

/usr/bin/rhn-ssl-dbstore --ca-cert=/root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT

If you use bootstrap, remember to also update your bootstrap scripts to reflect the new certificate information.