Red Hat Training

A Red Hat training course is available for Red Hat Satellite

3.2. The Red Hat Satellite SSL Maintenance Tool

Red Hat Satellite provides a command line tool to ease the management of the organization's secure infrastructure: the Red Hat Satellite SSL Tool, commonly known by its command rhn-ssl-tool. This tool is available as part of the spacewalk-certs-tools package. This package can be found within the software channels for the latest Red Hat Proxy Server and Red Hat Satellite Server (as well as the Red Hat Satellite Server ISO). The Red Hat Satellite SSL Tool enables organizations to generate their own Certificate Authority SSL key pair, as well as Web server SSL key sets (sometimes called key pairs).
This tool is only a build tool. It generates all of the SSL keys and certificates that are required. It also packages the files in RPM format for quick distribution and installation on all client machines. It does not deploy them. That is left to the administrator, or in many cases, automated by the Red Hat Satellite Server.

Note

The spacewalk-certs-tools, which contains rhn-ssl-tool, can be installed and run on any current Red Hat Enterprise Linux system with minimal requirements. This is offered as a convenience for administrators who want to manage their SSL infrastructure from their workstation or another system other than their Satellite or Proxy servers.
The Red Hat Satellite SSL Tool is required in the following situations:
  • When updating the Certificate Authority (CA) public certificate.
  • When installing a Red Hat Proxy Server 3.6 or later that connects to the central Red Hat Satellite Servers as its top-level service. The hosted service, for security reasons, cannot be a repository for the CA SSL key and certificate, which is private to the organization.
  • When reconfiguring the Satellite or Proxy infrastructure to use SSL where it previously did not.
  • When adding multiple Red Hat Satellite Servers to the Red Hat Satellite infrastructure. Consult with a Red Hat representative for instructions regarding this.
The Red Hat Satellite SSL Tool is not required in the following situations:
  • During installation of a Red Hat Satellite Server. All SSL settings are configured during the installation process. The SSL keys and certificate are built and deployed automatically.
  • During installation of a Red Hat Proxy Server 3.6 or later if connected to a Red Hat Satellite Server 3.6 or later as its top-level service. The Red Hat Satellite Server contains all of the SSL information needed to configure, build and deploy the Red Hat Proxy Server's SSL keys and certificates.
The installation procedures for both the Red Hat Satellite Server and the Red Hat Proxy Server ensure the CA SSL public certificate is deployed to the /pub directory of each server. This public certificate is used by the client systems to connect to the Red Hat Satellite Server. See Section 3.3, “Deploying the CA SSL Public Certificate to Clients” for more information.
In summary, if the organization's Satellite or Proxy infrastructure deploys the latest version of Red Hat Satellite Server as its top-level service, there should be little need to use the Red Hat Satellite SSL Tool.

3.2.1. Generating SSL Certificates

The primary benefits of using the Red Hat Satellite SSL Maintenance Tool are security, flexibility, and portability. Security is achieved through the creation of distinct Web server SSL keys and certificates for each Red Hat Satellite server, all signed by a single Certificate Authority SSL key pair created by the organization. Flexibility is supplied by the tool's ability to work on any machine that has the spacewalk-certs-tools package installed. Portability exists in a build structure that can be stored anywhere for safe keeping and then installed whenever the need arises.
If the organization infrastructure's top-level Server is the most current Red Hat Satellite Server, the most that may be required is to restore the ssl-build tree from an archive to the /root directory and utilize the configuration tools provided within the Red Hat Satellite Server's website.
To make the best use of the Red Hat Satellite SSL Maintenance Tool, complete the following high-level tasks in the following order. See the remaining sections for the required details:
  1. Install the spacewalk-certs-tools package on a system within the organization, perhaps but not necessarily the Red Hat Satellite Server or Red Hat Proxy Server.
  2. Create a single Certificate Authority SSL key pair for the organization and install the resulting RPM or public certificate on all client systems. See Section 3.2.3, “Generating the Certificate Authority SSL Key Pair” for more information.
  3. Create a Web server SSL key set for each of the Proxy and Satellite servers to be deployed and install the resulting RPM files on the Red Hat Satellite servers.
  4. Restart the httpd service:
    # service httpd restart 
  5. Back up the SSL build tree - consisting of the primary build directory and all subdirectories and files - to removable media, such as a CD or DVD. (Disk space requirements are insignificant.)
  6. Verify and then store that archive in a safe location, such as the one described for backups in the Additional Requirements sections of either the Proxy or Satellite installation guide.
  7. Record and secure the CA password for future use.
  8. Delete the build tree from the build system for security purposes, but only after the entire Satellite infrastructure is in place and configured.

    Note

    When additional Web server SSL key sets are needed, restore the build tree on a system running the Red Hat Satellite SSL Maintenance Tool and repeat steps 3 through 7.

3.2.2. Red Hat Satellite SSL Maintenance Tool Options

The Red Hat Satellite SSL Maintenance Tool offers numerous command line options for generating Certificate Authority SSL key pair and managing your server SSL certificates and keys. The following command-line help options are available:
  • rhn-ssl-tool --help: for general help.
  • rhn-ssl-tool --gen-ca --help: for Certificate Authority help.
  • rhn-ssl-tool --gen-server --help: for Web server help.
See the manual page (man rhn-ssl-tool) for more information.

3.2.3. Generating the Certificate Authority SSL Key Pair

Before creating the SSL key set required by the Web server, generate a Certificate Authority (CA) SSL key pair. A CA SSL public certificate is distributed to client systems of the Satellite or Proxy. The Red Hat Satellite SSL Maintenance Tool allows you to generate a CA SSL key pair if needed and reuse it for all subsequent Red Hat Satellite server deployments.
The build process automatically creates the key pair and public RPM for distribution to clients. All CA components are created in the build directory specified at the command line, typically /root/ssl-build (or /etc/sysconfig/rhn/ssl for older Satellite and Proxy servers). To generate a CA SSL key pair, run the following command.

Important

Replace the example values with those appropriate for your organization.
# rhn-ssl-tool --gen-ca \
  --password=MY_CA_PASSWORD \
  --dir="/root/ssl-build" \
  --set-state="North Carolina" \
  --set-city="Raleigh" \
  --set-org="Example Inc." \
  --set-org-unit="SSL CA Unit"
This command generates the following relevant files in the specified build directory:
  • RHN-ORG-PRIVATE-SSL-KEY: the CA SSL private key.
  • RHN-ORG-TRUSTED-SSL-CERT: the CA SSL public certificate.
  • rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm: the RPM prepared for distribution to client systems.
    This file contains the CA SSL public certificate (above) and installs it as /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
  • rhn-ca-openssl.cnf: the SSL CA configuration file.
  • latest.txt: lists the latest versions of the relevant files.
When this process is complete, distribute the RPM file to the client systems. See Section 3.3, “Deploying the CA SSL Public Certificate to Clients” for more information.

3.2.4. Generating Web Server SSL Key Sets

At this point, a CA SSL key pair should already be generated. However there is a likelihood of generating web server SSL key sets more frequently, especially if more than one Proxy or Satellite is deployed. A distinct set of SSL keys and certificates must be generated and installed for every distinct Satellite or Proxy server host name. The value for --set-hostname is therefore different for each server.
The server certificate build process works in a similar fashion to CA SSL key pair generation, with one exception: All server components are saved in subdirectories of the build directory. These subdirectories reflect the build system's machine name, such as /root/ssl-build/MACHINE_NAME. To generate a server certificate, run the following command.

Important

Replace the example values with those appropriate for your organization.
The following is a single command. Ensure you enter it all on one line.
# rhn-ssl-tool --gen-server \
  --password=MY_CA_PASSWORD \
  --dir="/root/ssl-build" \
  --set-state="MY_STATE" \
  --set-city="MY_CITY"
  --set-org="Example Inc." \
  --set-org-unit="MY_ORG_UNIT" \
  --set-email="admin@example.com" \
  --set-hostname="machinename.example.com"
This command generates the following relevant files in a machine-specific subdirectory of the build directory:
  • server.key: the Web server's SSL private server key.
  • server.csr: the Web server's SSL certificate request.
  • server.crt: the web server's SSL public certificate.
  • rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm: the RPM prepared for distribution to Satellite and Proxy Servers. Its associated src.rpm file is also generated.
    This RPM file contains the server.key, server.csr, and server.crt files. These files are installed in the following directories:
    • /etc/httpd/conf/ssl.key/server.key
    • /etc/httpd/conf/ssl.csr/server.csr
    • /etc/httpd/conf/ssl.crt/server.crt
  • rhn-server-openssl.cnf: the Web server's SSL configuration file.
  • latest.txt: lists the latest versions of the relevant files.
When this process is complete, distribute and install the RPM file on its respective Satellite or Proxy Server, and then restart the httpd service.
# service httpd restart