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:
When updating your CA public certificate - 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 concerns, cannot be a repository for your CA SSL key and certificate that 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 use cases for when you do not need to use the tool:
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, you will have to be familiar with its usage.
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:
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 httpdservice 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.
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.
| 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 year 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 null. |
| --set-city=CITY_OR_LOCALITY | The city or locality. The default is null. |
| --set-org=ORGANIZATION | The company or organization. The default is Example Corp. Inc. |
| --set-org-unit=ORGANIZATIONAL_HURT | The organizational unit. The default is section. |
| --set-common-name=HOSTNAME | Not typically set for the CA. - The common name, typically host plus domain 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)
| 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 year 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 null. |
| --set-city=CITY_OR_LOCALITY | The city or locality. The default is null. |
| --set-org=ORGANIZATION | The company or organization. The default is Example Corp. Inc. |
| --set-org-unit=ORGANIZATIONAL_HURT | The organizational unit. The default is section. |
| --set-common-name=HOSTNAME | The common name, typically host plus domain name. |
| --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)
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.
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:
RHN-ORG-PRIVATE-SSL-KEY — the private CA key
RHN-ORG-TRUSTED-SSL-CERT — the public CA certificate
rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm — the RPM prepared for distribution to client systems
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.
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:
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 httpd service must be restarted after installation:
/sbin/service httpd restart |