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.

Use this procedure for new SUSE Manager Server installations only. The setup step will reset any customization you have added.

Procedure: Installing Custom Certificates on a New SUSE Manager Server
  1. Install the SUSE Manager Server according to the instructions in installation:install-intro.adoc.

  2. Complete the initial setup according to installation:server-setup.adoc.

  3. 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>
  4. Complete SUSE Manager setup:

    yast2 susemanager_setup

    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 susemanager_setup 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.

Use this procedure for new SUSE Manager Proxy installations only. The setup step will reset any customization you have added.

Procedure: Installing Custom Certificates on a New SUSE Manager Proxy
  1. Install the SUSE Manager Proxy according to the instructions in installation:install-intro.adoc.

  2. Complete the initial setup according to installation:proxy-setup.adoc.

  3. At the command prompt, run:

    configure-proxy.sh
  4. At the Do you want to import existing certificates? prompt, type y.

  5. 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
  1. 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.

  2. 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
  3. 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
  1. 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
  2. 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"
  3. 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
  1. 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"
  2. 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
  1. On the SUSE Manager Server, 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.

  2. 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
  3. Subscribe all clients to the new SSL-CA-Channel channel.

  4. Install the CA certificate RPM on all clients by updating the channel.

Procedure: Deploying Combined Certificates on Salt Clients
  1. In the SUSE Manager Web UI, navigate to Systems  Overview.

  2. Check all your Salt Clients to add them to the System Set Manager (SSM).

  3. Navigate to Systems  System Set Manager  Overview.

  4. In the States field, click Apply to apply the system states.

  5. 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
  1. 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
  2. Restart services to pick the changes:

    spacewalk-service restart
Procedure: Replace Server Certificate on the Proxy
  1. 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
  2. Restart services to pick up the changes:

    rhn-proxy restart
  3. 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
  1. Copy the combined certificate RPM into the /root/ssl-build/ directory:

    cp /root/combined-ssl-build/*.rpm /root/ssl-build/
  2. 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"
  3. 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/
  4. Restart services to pick up the changes:

    spacewalk-service restart
  5. 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.