3.2. The RHN SSL Maintenance Tool

Red Hat Network provides a command line tool to ease management of your secure infrastructure: the RHN SSL Maintenance Tool, commonly known by its command rhn-ssl-tool. This tool, which resides in the rhns-certs-tools package within the software channels for the latest RHN Proxy Server and RHN Satellite Server, (as well as the Satellite ISO) enables you to generate your 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 though. It generates all 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, however. That is left to the administrator, or in many cases, automated by the RHN Satellite Server.

NOTE that the rhns-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 wish to manage their SSL infrastructure from their workstation or another system other than their RHN Server(s).

Here are the use cases for when you need to use the tool:

Here are the use cases for when you do not need to use the tool:

The installation procedures of both the RHN Satellite Server and the RHN 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 RHN Server. Refer to Section 3.3 Deploying the CA SSL Public Certificate to Clients for more information.

In short, if your organization's RHN infrastructure deploys the latest version of RHN Satellite Server as its top-level service, you will likely have little need to use the tool. Otherwise, you will have to be familiar with its usage.

3.2.1. SSL Generation Explained

The primary benefits of using the RHN SSL Maintenance Tool are security, flexibility, and portability. Security is achieved through the creation of distinct Web server SSL keys and certificates for each RHN server, all signed by a single Certificate Authority SSL key pair created by your organization. Flexibility is supplied by the tool's ability to work on any machine with the rhns-certs-tools package installed. Portability exists in a build structure that can be stored anywhere for safe keeping and then installed wherever the need arises.

Again, if your infrastructure's top-level RHN Server is the most current RHN Satellite Server, the most you may have to do is restore your ssl-build tree from archive to the /root directory and utilize the configuration tools provided within the RHN Satellite Server's website.

To make the best use of the RHN SSL Maintenance Tool, you should complete the following high-level tasks in this rough order. Refer to the remaining for the required details:

  1. Install the rhns-certs-tools package on a system within your organization, perhaps but not necessarily the RHN Satellite Server or RHN Proxy Server.

  2. Create a single Certificate Authority SSL key pair for your organization and install the resulting RPM or public certificate on all client systems.

  3. Create a Web server SSL key set for each of the Proxies and Satellites to be deployed and install the resulting RPMs on the RHN Servers, restarting the httpdservice afterwards:

    /sbin/service httpd restart
  4. Archive the SSL build tree - consisting of the primary build directory and all subdirectories and files - to removable media, such as a floppy disk. (Disk space requirements are insignificant.)

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

  6. Record and secure the CA password for future use.

  7. Delete the build tree from the build system for security purposes, but only once the entire RHN infrastructure is in place and configured.

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

3.2.2. RHN SSL Maintenance Tool Options

The RHN SSL Maintenance Tool offers a plethora of command line options for generating your Certificate Authority SSL key pair and managing your server SSL certificates and keys. The tool offers essentially three command line option help listings: rhn-ssl-tool --help (general), rhn-ssl-tool --gen-ca --help (Certificate Authority), and rhn-ssl-tool --gen-server --help (Web server). The manual page for rhn-ssl-tool is also quite detailed and available for assistance: man rhn-ssl-tool.

The two tables here break down the options by their related task, either CA or Web server SSL key set generation. The first set of options (CA) should be preceded by the --gen-ca argument, while the second set (Web server) should be preceded by the --gen-server argument.

OptionDescription
--gen-caGenerate a Certificate Authority (CA) key pair and public RPM. This must be issued with any of the remaining options in this table.
-h, --helpDisplay the help screen with a list of base options specific to generating and managing a Certificate Authority.
-f, --forceForcibly create a new CA private key and/or public certificate.
-p=, --password=PASSWORDThe CA password. You will be prompted for this if it's missing. Record it in a safe manner.
-d=, --dir=BUILD_DIRECTORYRequired for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build.
--ca-key=FILENAMEThe CA private key filename. The default is RHN-ORG-PRIVATE-SSL-KEY.
--ca-cert=FILENAMEThe CA public certificate filename. The default is RHN-ORG-TRUSTED-SSL-CERT.
--cert-expiration=CA_CERT_EXPIREThe expiration date of the public CA certificate. The default is the number of days until one year prior to epoch rollover (or 01-18-2038).
--set-country=COUNTRY_CODEThe two-letter country code. The default is US.
--set-state=STATE_OR_PROVINCEThe state or province of the CA. The default is null.
--set-city=CITY_OR_LOCALITYThe city or locality. The default is null.
--set-org=ORGANIZATIONThe company or organization. The default is Example Corp. Inc.
--set-org-unit=ORGANIZATIONAL_HURTThe organizational unit. The default is section.
--set-common-name=HOSTNAMENot typically set for the CA. - The common name, typically host plus domain name.
--set-email=EMAILNot typically set for the CA. - The email address.
--rpm-packager=PACKAGERPackager of the generated RPM, such as "RHN Admin ([email protected])."
--rpm-vendor=VENDORVendor of the generated RPM, such as "IS/IT Example Corp."
-v, --verboseDisplay verbose messaging. Accumulative - added "v"s result in increasing detail.
--ca-cert-rpm=CA_CERT_RPMRarely changed - RPM name that houses the CA certificate (the base filename, not filename-version-release.noarch.rpm).
--key-onlyRarely used - Generate only a CA private key. Review --gen-ca --key-only --help for more information.
--cert-onlyRarely used - Generate only a CA public certificate. Review --gen-ca --cert-only --help for more information.
--rpm-onlyRarely used - Generate only an RPM for deployment. Review --gen-ca --rpm-only --help for more information.
--no-rpmRarely used - Conduct all CA-related steps except RPM generation.

Table 3-1. SSL Certificate Authority (CA) Options (rhn-ssl-tool --gen-ca --help)

OptionDescription
--gen-serverGenerate the Web server's SSL key set, RPM and tar archive. This must be issued with any of the remaining options in this table.
-h, --helpDisplay the help screen with a list of base options specific to generating and managing a server key-pair.
-p=, --password=PASSWORDThe CA password. You will be prompted for this if it's missing. Record it in a safe manner.
-d=, --dir=BUILD_DIRECTORYRequired for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build.
--server-key=FILENAMEThe Web server's SSL private key filename. The default is server.key.
--server-cert-req=FILENAMEThe Web server's SSL certificate request filename. The default is server.csr.
--server-cert=FILENAMEThe Web server's SSL certificate filename. The default is server.crt.
--startdate=YYMMDDHHMMSSZThe start date for server certificate validity in the example format: year, month, date, hour, minute, second (two characters per value). Z stands for Zulu and is required. The default is one week before generation.
--cert-expiration=SERVER_CERT_EXPIREThe expiration date of the server certificate. The default is the number of days until one year prior to epoch rollover (or 01-18-2038).
--set-country=COUNTRY_CODEThe two-letter country code. The default is US.
--set-state=STATE_OR_PROVINCEThe state or province of the CA. The default is null.
--set-city=CITY_OR_LOCALITYThe city or locality. The default is null.
--set-org=ORGANIZATIONThe company or organization. The default is Example Corp. Inc.
--set-org-unit=ORGANIZATIONAL_HURTThe organizational unit. The default is section.
--set-common-name=HOSTNAMEThe common name, typically host plus domain name.
--set-hostname=HOSTNAMEThe hostname of the RHN Server to receive the key. The default is dynamically set to the build machine's hostname.
--set-email=EMAILThe email address of the certificate contact. The default is [email protected].
--rpm-packager=PACKAGERPackager of the generated RPM, such as "RHN Admin ([email protected])."
--rpm-vendor=VENDORVendor of the generated RPM, such as "IS/IT Example Corp."
-v, --verboseDisplay verbose messaging. Accumulative - added "v"s result in increasing detail.
--key-onlyRarely used - Generate only a server private key. Review --gen-server --key-only --help for more information.
--cert-req-onlyRarely used - Generate only a server certificate request. Review --gen-server --cert-req-only --help for more information.
--cert-onlyRarely used - Generate only a server certificate. Review --gen-server --cert-only --help for more information.
--rpm-onlyRarely used - Generate only an RPM for deployment. Review --gen-server --rpm-only --help for more information.
--no-rpmRarely used - Conduct all server-related steps except RPM generation.
--server-rpm=SERVER_RPMRarely changed - RPM name that houses the Web server's SSL key set (the base filename, not filename-version-release.noarch.rpm).
--server-tar=SERVER_TARRarely changed - Name of .tar archive of the Web server's SSL key set and CA public certificate that is used solely by the hosted RHN Proxy Server installation routines (the base filename, not filename-version-release.tar).

Table 3-2. SSL Web Server Options (rhn-ssl-tool --gen-server --help)

To use these options, insert the option and the appropriate value, if needed, after the rhn-ssl-tool command and base option, where the base option is either --gen-ca or --gen-server.

3.2.3. Generating the Certificate Authority SSL Key Pair

Before creating the SSL key set required by the Web server, you must have a Certificate Authority (CA) SSL key pair generated. A CA SSL public certificate gets distributed to client systems of the Satellite or Proxy. The RHN SSL Maintenance Tool allows you to generate a CA SSL key pair if needed and re-use it for all subsequent RHN server deployments.

The build process automatically creates the key pair and public RPM for distribution to clients. All CA components end up in the build directory specified at the command line, typically /root/ssl-build (or /etc/sysconfig/rhn/ssl for older Satellites and Proxies). To generate a CA SSL key pair, issue a command like this:

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"

Replace the example values with those appropriate for your organization. This will result in the following relevant files in the specified build directory:

Once finished, you're ready to distribute the RPM to client systems. Refer to Section 3.3 Deploying the CA SSL Public Certificate to Clients.

3.2.4. Generating Web Server SSL Key Sets

Although you must have a CA SSL key pair already generated, you will likely generate web server SSL key sets more frequently, especially if more than one Proxy or Satellite is deployed. Note that the value for --set-hostname is different for each server. In other words, a distinct set of SSL keys and certificates needs to be generated and installed for every distinct RHN server hostname.

The server certificate build process works much like CA SSL key pair generation with one exception: All server components end up in subdirectories of the build directory that reflect the build system's machine name, such as /root/ssl-build/MACHINE_NAME. To generate server certificates, issue a command like this:

rhn-ssl-tool --gen-server --password=MY_CA_PASSWORD --dir="/root/ssl-build" \
--set-state="North  Carolina" --set-city="Raleigh" --set-org="Example  Inc." \
--set-org-unit="IS/IT" --email="[email protected]" \
--set-hostname="rhnbox1.example.com

Replace the example values with those appropriate for your organization. This will result in the following relevant files in a machine-specific subdirectory of the build directory:

Once finished, you're ready to distribute and install the RPM on its respective RHN Server. Note that httpd service must be restarted after installation:

/sbin/service httpd restart