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 is available as part of the rhns-certs-tools package. This package can be found within the software channels for the the latest RHN Proxy Server and RHN Satellite Server (as well as the RHN Satellite Server ISO). RHN SSL Maintenance Tool 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. 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, however. That is left to the administrator, or in many cases, automated by the RHN Satellite Server.
 | Note |
|---|---|
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 cases in which the tool is required:
When updating your CA public certificate - this is rare.
When installing an RHN Proxy Server version 3.6 or later that connects to the central RHN Servers as its top-level service - the hosted service, for security reasons, cannot be a repository for your CA SSL key and certificate, which is private to your organization.
When reconfiguring your RHN infrastructure to use SSL where it previously did not.
When adding RHN Proxy Servers of versions prior to 3.6 into your RHN infrastructure.
When adding multiple RHN Satellite Servers to your RHN infrastructure - consult with a Red Hat representative for instructions regarding this.
Here are the cases in which the tool is not required:
During installation of an RHN Satellite Server - all SSL settings are configured during the installation process. The SSL keys and certificate are built and deployed automatically.
During installation of an RHN Proxy Server version 3.6 or later if connected to an RHN Satellite Server version 3.6 or later as its top-level service - the RHN Satellite Server contains all of the SSL information needed to configure, build and deploy the RHN Proxy Server's SSL keys and certificates.
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, become 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 that has 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 an 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, complete the following high-level tasks in roughly this order. Refer to the remaining sections for the required details:
Install the rhns-certs-tools package on a system within your organization, perhaps but not necessarily the RHN Satellite Server or RHN Proxy Server.
Create a single Certificate Authority SSL key pair for your organization and install the resulting RPM or public certificate on all client systems.
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 httpd service afterwards:
/sbin/service httpd restart
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.)
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.
Record and secure the CA password for future use.
Delete the build tree from the build system for security purposes, but only once the entire RHN infrastructure is in place and configured.
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 to assist: man rhn-ssl-tool.
The two tables below break down the options by their related task, either CA or Web server SSL key set generation.
This set of options must be preceded by the --gen-ca argument:
| Option | Description |
|---|---|
| --gen-ca | Generate a Certificate Authority (CA) key pair and public RPM. This must be issued with any of the remaining options in this table. |
| -h, --help | Display the help screen with a list of base options specific to generating and managing a Certificate Authority. |
| -f, --force | Forcibly create a new CA private key and/or public certificate. |
| -p=, --password=PASSWORD | The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
| -d=, --dir=BUILD_DIRECTORY | Required for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build. |
| --ca-key=FILENAME | The CA private key filename. The default is RHN-ORG-PRIVATE-SSL-KEY. |
| --ca-cert=FILENAME | The CA public certificate filename. The default is RHN-ORG-TRUSTED-SSL-CERT. |
| --cert-expiration=CA_CERT_EXPIRE | The expiration date of the public CA certificate. The default is the number of days until one day prior to epoch rollover (or 01-18-2038). |
| --set-country=COUNTRY_CODE | The two-letter country code. The default is US. |
| --set-state=STATE_OR_PROVINCE | The state or province of the CA. The default is ''. |
| --set-city=CITY_OR_LOCALITY | The city or locality. The default is ''. |
| --set-org=ORGANIZATION | The company or organization, such as Red Hat. The default is Example Corp. Inc. |
| --set-org-unit=SET_ORG_UNIT | The organizational unit, such as RHN. The default is ''. |
| --set-common-name=HOSTNAME | Not typically set for the CA. - The common name. |
| --set-email=EMAIL | Not typically set for the CA. - The email address. |
| --rpm-packager=PACKAGER | Packager of the generated RPM, such as "RHN Admin ([email protected])." |
| --rpm-vendor=VENDOR | Vendor of the generated RPM, such as "IS/IT Example Corp." |
| -v, --verbose | Display verbose messaging. Accumulative - added "v"s result in increasing detail. |
| --ca-cert-rpm=CA_CERT_RPM | Rarely changed - RPM name that houses the CA certificate (the base filename, not filename-version-release.noarch.rpm). |
| --key-only | Rarely used - Generate only a CA private key. Review --gen-ca --key-only --help for more information. |
| --cert-only | Rarely used - Generate only a CA public certificate. Review --gen-ca --cert-only --help for more information. |
| --rpm-only | Rarely used - Generate only an RPM for deployment. Review --gen-ca --rpm-only --help for more information. |
| --no-rpm | Rarely used - Conduct all CA-related steps except RPM generation. |
Table 3-1. SSL Certificate Authority (CA) Options (rhn-ssl-tool --gen-ca --help)
The following set of options must be preceded by the --gen-server argument:
| Option | Description |
|---|---|
| --gen-server | Generate 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, --help | Display the help screen with a list of base options specific to generating and managing a server key-pair. |
| -p=, --password=PASSWORD | The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
| -d=, --dir=BUILD_DIRECTORY | Required for most commands - The directory where certificates and RPMs are built. The default is ./ssl-build. |
| --server-key=FILENAME | The Web server's SSL private key filename. The default is server.key. |
| --server-cert-req=FILENAME | The Web server's SSL certificate request filename. The default is server.csr. |
| --server-cert=FILENAME | The Web server's SSL certificate filename. The default is server.crt. |
| --startdate=YYMMDDHHMMSSZ | The 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_EXPIRE | The expiration date of the server certificate. The default is the number of days until one day prior to epoch rollover (or 01-18-2038). |
| --set-country=COUNTRY_CODE | The two-letter country code. The default is US. |
| --set-state=STATE_OR_PROVINCE | The state or province. The default is North Carolina. |
| --set-city=CITY_OR_LOCALITY | The city or locality. The default is Raleigh. |
| --set-org=ORGANIZATION | The company or organization, such as Red Hat. The default is Example Corp. Inc. |
| --set-org-unit=SET_ORG_UNIT | The organizational unit, such as RHN. The default is unit. |
| --set-hostname=HOSTNAME | The hostname of the RHN Server to receive the key. The default is dynamically set to the build machine's hostname. |
| --set-email=EMAIL | The email address of the certificate contact. The default is [email protected]. |
| --rpm-packager=PACKAGER | Packager of the generated RPM, such as "RHN Admin ([email protected])." |
| --rpm-vendor=VENDOR | Vendor of the generated RPM, such as "IS/IT Example Corp." |
| -v, --verbose | Display verbose messaging. Accumulative - added "v"s result in increasing detail. |
| --key-only | Rarely used - Generate only a server private key. Review --gen-server --key-only --help for more information. |
| --cert-req-only | Rarely used - Generate only a server certificate request. Review --gen-server --cert-req-only --help for more information. |
| --cert-only | Rarely used - Generate only a server certificate. Review --gen-server --cert-only --help for more information. |
| --rpm-only | Rarely used - Generate only an RPM for deployment. Review --gen-server --rpm-only --help for more information. |
| --no-rpm | Rarely used - Conduct all server-related steps except RPM generation. |
| --server-rpm=SERVER_RPM | Rarely changed - RPM name that houses the Web server's SSL key set (the base filename, not filename-version-release.noarch.rpm). |
| --server-tar=SERVER_TAR | Rarely 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)
3.2.3. Generating the Certificate Authority SSL Key Pair
Before creating the SSL key set required by the Web server, you must generate a Certificate Authority (CA) SSL key pair. A CA SSL public certificate is 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:
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. It contains the CA SSL public certificate (above) and installs it in this location: /usr/share/rhn/RHN-ORG-TRUSTED-SSL-CERT
rhn-ca-openssl.cnf — the SSL CA configuration file
latest.txt — always lists the latest versions of the relevant files.
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 must 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:
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 RHN Servers. Its associated src.rpm file is also generated. This RPM contains the above three files. It will install them in these locations:
/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 — always lists the latest versions of the relevant files.
Once finished, you're ready to distribute and install the RPM on its respective RHN Server. Note that the httpd service must be restarted after installation:
/sbin/service httpd restart |