The software described in this documentation is either no longer supported or is in extended support.
Oracle recommends that you upgrade to a current supported release.

Chapter 3 Replacing SSL Certificates on Spacewalk Servers or Spacewalk Proxies

When you install a Spacewalk server or Spacewalk proxy, you create a self-signed SSL certificate that you can use with Spacewalk clients. This section describes how to replace self-signed certificates or expired CA-signed certificates with certificates that have been signed by a Certificate Authority (CA).

You can use certificates for individual Spacewalk servers or Spacewalk proxies, or wildcard certificates for all Spacewalk servers or Spacewalk proxies in the domains that the wildcard certificates cover.

To replace the existing certificate on a Spacewalk server or Spacewalk proxy:

Create a backup of the system's existing SSL configuration, for example:

# tar -cvf SSLconfig.tar \ 
  /etc/httpd/conf/ssl.* \
  /etc/pki/spacewalk/jabberd/server.pem \
  /root/ssl-build \
  /var/www/html/pub

Obtain a server certificate from a CA and install this certificate in the SSL build hierarchy on the system:
1. Send the Certificate Signing Request (CSR) file /root/ssl-build/swksvr/server.csr to the CA.
  Note
  swksvr is the name of the Spacewalk server or Spacewalk proxy that you used to set up the existing SSL configuration with the domain name removed.
  After validating your request, the CA returns a signed server certificate file.
2. Create a backup of the signed server certificate file.
3. If necessary, convert the certificate to PEM format.
  A PEM-format certificate file is a text file that contains a base64-encoded certificate section between begin and end markers, for example:
```
-----BEGIN CERTIFICATE-----
MIIF7DCCBNSgAwIBAgIQbsx6pacDIAm4zrz06VLUkTANBgkqhkiG9w0BAQUFADCB
...
Rs/iGAZeqa6ogZpHFt4MKGwlJ7net4RYxh84HqTEy2Y=
-----END CERTIFICATE-----
```
  A PEM-format certificate file usually has a file extension of .crt or .pem. However, binary DER-format certificate files are also sometimes given a .crt extension.
  A DER-format certificate file is a binary file that usually has a file extension of .cer or .der, but can also have the extension .cert or .crt.
  You can use the following command to test if a certificate file is in DER format:
```
# openssl x509 -inform der -text -in certificate_file
```
4. If a certificate file is in DER format, convert the file to a PEM-format certificate file, for example:
```
# openssl x509 -inform der -in server.cer -out server.pem
```
5. If a PEM-format certificate file was not generated on a UNIX or Linux system, it might contain ^M carriage return characters. You can use either of the following commands to remove these characters:
```
# sed -i -e 's/\r//' server.pem
-or-
# dos2unix server.pem
```
  The dos2unix command is available in the dos2unix package.
6. Copy the PEM-format server certificate file to /root/ssl-build/swksvr/server.crt, overwriting the original file.
```
# cp server.pem /root/ssl-build/swksvr/server.crt
```
Add the CA public certificate to the /root/ssl-build directory as the file RHN-ORG-TRUSTED-SSL-CERT, overwriting the original file:
- If available, obtain the CA chain certificate from the CA that issued the server certificate. Copy this certificate file to /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT, for example:
```
# cp ca_chain.pem /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
```
- If the CA chain certificate is not available from the issuing CA, create the CA chain certificate yourself:
  1. Obtain the root CA public certificate and the intermediate CA public certificates from the issuing CA.
  2. Concatenate the chain of CA public certificate files starting with the public certificate file of the CA that issued your server certificate down to the public certificate file of the root CA to /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT, for example:
    # cat intermediate_ca.pem root_ca.pem > /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
    In this example, intermediate_ca.pem is the public certificate file of the intermediate CA that signed your server certificate, and root_ca.pem is the public certificate file of the root CA that signed the intermediate certificate.
    Note
    The order of the public certificates in a CA chain certificate file is critical. The CA chain certificate does not work if its component certificates are not in the correct order.
- If a root CA signed your server certificate directly (which is unlikely nowadays), only the public certificate of the root CA is required. Copy the root CA public certificate file to /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT, for example:
```
# cp root_ca.pem /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
```
Use the following command to validate the server certificate against the CA public certificate:
```
# openssl verify -CAfile /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT \
  /root/ssl-build/swksvr/server.crt
/root/ssl-build/swksvr/server.crt: OK
```
If this command returns an error, verify that you have created RHN-ORG-TRUSTED-SSL-CERT correctly and that the date and time configured on the server are correct.
Store the CA public certificate in the Spacewalk database so that it is available for use in provisioning client systems.
```
# rhn-ssl-dbstore -v --ca-cert=/root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
Public CA SSL certificate:  /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
```
If the command returns an error, enter the command again, specifying a higher level of debugging such as -vvv to gather more information about the problem.

Generate and install the web server SSL package:

Generate the web server SSL package.

# rhn-ssl-tool --gen-server --rpm-only --dir /root/ssl-build

...working...

Generating web server's SSL key pair/set RPM:
    /root/ssl-build/swksvr/rhn-org-httpd-ssl-key-pair-swksvr-1.0-rev.src.rpm
    /root/ssl-build/swksvr/rhn-org-httpd-ssl-key-pair-swksvr-1.0-rev.noarch.rpm

The most current Spacewalk Proxy Server installation process against RHN hosted
requires the upload of an SSL tar archive that contains the CA SSL public
certificate and the web server's key set.

Generating the web server's SSL key set and CA SSL public certificate archive:
    /root/ssl-build/swksvr/rhn-org-httpd-ssl-archive-swksvr-1.0-rev.tar

Deploy the server's SSL key pair/set RPM:
    (NOTE: the Red Hat Satellite or Proxy installers may do this step for you.)
    The "noarch" RPM needs to be deployed to the machine working as a
    web server, or Red Hat Satellite, or Spacewalk Proxy.
    Presumably 'swksvr.mydom.com'.

You can use rpm to list the files that the packages install.

# rpm -qlp /root/ssl-build/swksvr/rhn-org-httpd-ssl-key-pair-swksvr-1.0-rev.src.rpm
rhn-org-httpd-ssl-key-pair-swksvr-1.0.tar.gz
rhn-org-httpd-ssl-key-pair-swksvr.spec
# rpm -qlp /root/ssl-build/swksvr/rhn-org-httpd-ssl-key-pair-swksvr-1.0-rev.noarch.rpm
/etc/httpd/conf/ssl.crt/server.crt
/etc/httpd/conf/ssl.csr/server.csr
/etc/httpd/conf/ssl.key/server.key
/etc/pki/spacewalk/jabberd/server.pem

Install the web server SSL noarch package.

# rpm -Uhv /root/ssl-build/swksvr/rhn-org-httpd-ssl-key-pair-swksvr-1.0-rev.noarch.rpm
Preparing...                ########################################### [100%]
   1:rhn-org-httpd-ssl-key-p########################################### [100%]

Generate the public CA certificate package and make both the package and the CA public certificate file available to clients:

Generate the public CA certificate package.

# rhn-ssl-tool --gen-ca --dir=/root/ssl-build --rpm-only

...working...
Generating CA public certificate RPM:
    /root/ssl-build/rhn-org-trusted-ssl-cert-1.0-rev.src.rpm
    /root/ssl-build/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm

Make the public CA certificate publicly available:
    (NOTE: the Red Hat Satellite or Proxy installers may do this step for you.)
    The "noarch" RPM and raw CA certificate can be made publicly accessible
    by copying it to the /var/www/html/pub directory of your Red Hat Satellite or
    Proxy server.

You can use rpm to list the files that the packages install.

# rpm -qlp /root/ssl-build/rhn-org-trusted-ssl-cert-1.0-rev.src.rpm
rhn-org-trusted-ssl-cert-1.0.tar.gz
rhn-org-trusted-ssl-cert.spec
# rpm -qlp /root/ssl-build/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm 
/usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT

If a Spacewalk server or Spacewalk proxy is also configured as a client, install the public CA certificate noarch package on this system.

# rpm -Uhv /root/ssl-build/pub/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm
Preparing...                ########################################### [100%]
   1:rhn-org-trusted-ssl-cer########################################### [100%]

The public CA certificate is installed as /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT.

Copy the rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm package and CA public certificate file to /var/www/html/pub for access by clients.

# cp /root/ssl-build/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm /var/www/html/pub
# cp /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT /var/www/html/pub

Note

If you do not copy the updated RHN-ORG-TRUSTED-SSL-CERT to /var/www/html/pub, the osa-dispatcher service fails to start.

To verify that the installed copies of RHN-ORG-TRUSTED-SSL-CERT are identical, compare their digest values, for example:

# sha1sum /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT \
  /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT \
  /var/www/html/pub/RHN-ORG-TRUSTED-SSL-CERT
74380a372bfa55d8ab7579bf01502c874b8aae84
                      /root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT
74380a372bfa55d8ab7579bf01502c874b8aae84
                      /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
74380a372bfa55d8ab7579bf01502c874b8aae84
                      /var/www/html/pub/RHN-ORG-TRUSTED-SSL-CERT

The rhn-org-trusted-ssl-cert-1.0-rev.src.rpm package is usually not made available to clients.

On a Spacewalk server, stop the Spacewalk services, clear the jabberd database, and restart Spacewalk.
```
# /usr/sbin/spacewalk-service stop
# rm -Rf /var/lib/jabberd/db/*
# /usr/sbin/spacewalk-service start
```
On a Spacewalk proxy, restart the Spacewalk proxy services:
```
# /usr/sbin/rhn-proxy restart
```

On the remaining Spacewalk clients, download and install the public CA certificate package, for example:

# wget https://swksvr.mydom.com/pub/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm
--2015-06-05 15:15:44--  https://swksvr.mydom.com/pub/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm
Resolving swksvr.mydom.com... 192.168.1.3
Connecting to swksvr.mydom.com|192.168.1.3|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 4840 (4.7K) [application/x-rpm]
Saving to: “rhn-org-trusted-ssl-cert-1.0-2.noarch.rpm”

100%[======================================>] 4,840       --.-K/s   in 0s      

2015-06-05 15:15:44 (57.5 MB/s) - “rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm” saved [4840/4840]

# rpm -Uhv /root/ssl-build/pub/rhn-org-trusted-ssl-cert-1.0-rev.noarch.rpm
Preparing...                ########################################### [100%]
   1:rhn-org-trusted-ssl-cer########################################### [100%]

Note

If you subsequently replace the server certificate because it is revoked or it expires, you do not need to update the public CA certificate on the clients unless you change the CA that signs the server certificate.