rhn-ssl-tool

Langue: en

Version: 07 October 2010 (fedora - 01/12/10)

Section: 1 (Commandes utilisateur)

Sommaire

NAME

rhn-ssl-tool - Generate and maintain SSL keys, certificates and deployment RPMs.

SYNOPSIS

     
 
 rhn-ssl-tool [ options ... ] --help
 
     
 
 rhn-ssl-tool --gen-ca -dBUILD_DIR -pCA_PASSWORD [ options ... ] 
 
     
 
 rhn-ssl-tool --gen-server -dBUILD_DIR -pCA_PASSWORD [ options ... ]

HELP

rhn-ssl-tool --help

rhn-ssl-tool --gen-ca --help

rhn-ssl-tool --gen-server --help

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

(advanced) rhn-ssl-tool --gen-ca --key-only --help

(advanced) rhn-ssl-tool --gen-ca --cert-only --help

(advanced) rhn-ssl-tool --gen-ca --rpm-only --help

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

(advanced) rhn-ssl-tool --gen-server --key-only --help

(advanced) rhn-ssl-tool --gen-server --cert-req-only --help

(advanced) rhn-ssl-tool --gen-server --cert-only --help

(advanced) rhn-ssl-tool --gen-server --rpm-only --help

DESCRIPTION

The RHN SSL Maintenance Tool (rhn-ssl-tool) is used to generate and maintain RHN SSL keys and certificates. It also will generate RPMs for use in deploying these keys and certificates. The tool is geared for use in an RHN context, but can be useful outside of RHN.

Working with openssl directly can be tedious and trying. This tool aims to make the process relatively simple. We limit the scope of using openssl to how we use it in RHN: securing web applications.

The RHN context of this document is in support of RHN Satellite, but all holds true for RHN Proxy as well, so keep that in mind. The most current RHN Satellite Servers use /root/ssl-build as the default build directory. Older RHN Satellites and Proxies used the /etc/sysconfig/rhn/ssl directory, and *very* old installations used /etc/sysconfig/rhn.

The basic process of SSL key/certificate/RPM generation using this tool: (step 1) generate a CA SSL key pair(set) and public RPM, (step 2) create web server SSL key pair(set) and RPM (and tar archive).

Build directory structure: --dir BUILD_DIR is used with nearly all commandline options. BUILD_DIR marks the top of the build tree; all CA files and RPMs land there. Server SSL key pairs(sets) are FQDN specific and so we build them in BUILD_DIR/MACHINE_NAME.

STEP 1: Generate a CA key pair(set) and public RPM:

rhn-ssl-tool --gen-ca --dir BUILD_DIR [ options ... ]

This step should ideally never need to be repeated unless the CA password is lost or forgotten (DON'T DO THAT!). The default validity window for the CA is from now until 2038. The CA public certificate is what get's distributed to clients of the web-app (RHN Satellite/Proxy).

In the RHN Satellite/Proxy context, the organization acts as their own Certificate Authority, but these steps can be skipped if intending to use of an outside authority (This is not officially supported by Red Hat).

The CA private key remains private.

The CA certificate is used by client software (up2date for example), and is generally deployed via an RPM or the raw file.

STEP 2: Generate a web server SSL key pair(set), RPM and tar

rhn-ssl-tool --gen-server --dir BUILD_DIR [ options ... ]

This step is done more frequently (generally), especially if more than one RHN server is being deployed (--set-hostname is different for each server). The default validity window for the CA is from now until 2038. All clients using the CA SSL public certificate that signed the new web server SSL certificate will work as expected with all web server key pairs(set) generated.

The web server SSL key and certificate are used solely by the web application server (apache on an RHN Proxy or Satellite Server for example).

A note about generated RPMs:
The --gen-ca process generates an RPM that contains the public CA certificate. It needs to be deployed to any clients making SSL connections to an RHN server (RHN Satellite or Proxy). This is generally done by making the RPM available in the /var/www/html/pub directory. It is also a good idea to copy the CA certificate itself in that directory: RHN-ORG-TRUSTED-CA-CERT.

The --gen-server process generates an RPM that contains the server.key and server.crt files needed to secure your RHN server (RHN Satellite or RHN Proxy). It needs to be installed on the appropriate server. That server then needs to have it's httpd processes restarted /sbin/service httpd restart.

IMPORTANT:
Time and date need to be correctly set on systems establishing SSL connections. It is highly recommended that all client and server systems have the ntpd service installed, configured and running.
Advanced options (rarely used discete steps):

generate a CA SSL private key: --gen-ca --key-only ...

generate a CA SSL public certificate: --gen-ca --cert-only ...

generate a CA SSL public RPM: --gen-ca --rpm-only ...

generate a web server's SSL private key: --gen-server --key-only ...

generate a web server's SSL certificate request: --gen-server --cert-req-only ...

generate/sign a web server's SSL certificate: --gen-server --cert-only ...

generate a web server's private RPM (and tar archive used for RHN Proxy installations): --gen-server --rpm-only ...

Using a 3rd party CA (rarely done in the RHN context):

CA public certficate: In the "3rd party CA" case, simply copy the certificate authorities public certificate to the SSL build directory; renaming it to RHN-ORG-TRUSTED-SSL-CERT; and then run --gen-ca --dir BUILD_DIR --rpm-only to package that certificate in an expected manner ready for client deployment. NOTE: this has not been tested by RHN personnell. See further instructions in step 2.

Web server's SSL key pair(set): Usually, one creates the web server's SSL private key, certificate-request and certificate in one step. If using a 3rd party CA though, create a web server's SSL private key and certificate-request via --gen-server --key-only --dir BUILD_DIR and --gen-server --cert-req-only --dir BUILD_DIR. Have the 3rd party sign server.csr which will generate a server.crt file. Copy that server.crt file into the BUILD_DIR/MACHINE_NAME directory (where the server.key file was generated). And then create your deployable RPM with --gen-server --rpm-only --dir BUILD_DIR.

NOTE: each step (--gen-* or --gen-* --*-only) has its own --help information.

ALL OPTIONS

-h | --help
Display the help screen with a list of base options (--gen-*).
--gen-ca
Generate a Certificate Authority (CA) key pair and public RPM:
-f | --force
forcibly create a new CA private key and/or public certificate.
-pPASSWORD |
CA password. Will prompt if option is missing.
-d BUILD_DIR |
build directory (default: ./ssl-build).
--ca-key=FILENAME
CA private key filename(default is dynamically set).
--ca-cert=FILENAME
CA public certificate filename (default is dynamically set).
--cert-expiration=CA_CERT_EXP
expiration of public CA certificate (default is # days until 1 day prior to epoch rollover (or 01-19-2038)).
--set-country=COUNTRY_CODE
two letter country code (default: US).
--set-state=STATE_OR_PROVINCE
state or province, such as "North Carolina" (default: "")
--set-city=CITY_OR_LOCALITY
city or locality, such as "Raleigh" (default: "").
--set-org=ORGANIZATION
organization or company name (default: "Example Corp. Inc").
--set-org-unit=ORGANIZATIONAL_UNIT
organizational unit (default: unit).
--set-common-name=HOSTNAME
not generally set for the CA certificate. The common name.
--set-email=EMAIL
email address. Not generally set for the CA certificate.
-v | --verbose
be verbose (accumulative: -vvv means "be *really* verbose).
--key-only
(rarely used) only generate a CA private key. Try --gen-ca --key-only --help for more information.
--cert-only
(rarely used) only generate a CA public certificate. Try --gen-ca --cert-only --help for more information.
--ca-cert-rpm
(rarely changed) RPM name that houses the CA SSL public certificate (the base filename, not filename-version-release.noarch.rpm).
--rpm-packager
(rarely used) packager of the generated RPM, such as "RHN Admin <rhn-admin@example.com>".
--rpm-vendor
(rarely used) vendor of the generated RPM, such as "IS/IT Example Corp.".
--rpm-only
(rarely used) only generate a deployable RPM. Try --gen-ca --rpm-only --help for more information.
--no-rpm
(rarely used) do everything *except* generate an RPM.
-h | --help
help message.
--gen-server
Generate a web server's SSL key pair(set), RPM and tar archive:
-pPASSWORD |
CA password. Will prompt if option is missing. MUST MATCH PASSWORD OF CA!!!
-d BUILD_DIR |
build directory (default: ./ssl-build).
--server-key=FILENAME
web server's SSL private key filename (default: server.key).
--server-cert-req=FILENAME
web server's SSL certificate request filename (default: server.csr).
--server-cert=FILENAME
web server's SSL certificate filename (default: server.crt).
--startdate=YYMMDDHHMMSSZ
start date for web server's SSL certificate validity in the above format (Z is a letter; default is 1 week ago).
--cert-expiration=EXPIRATION
expiration of the web server's SSL certificate (default is # days until 1 day prior to epoch rollover (or 01-19-2038)).
--set-country=COUNTRY_CODE
two letter country code (default: US).
--set-state=STATE_OR_PROVINCE
state or province (default: "North Carolina")
--set-city=CITY_OR_LOCALITY
city or locality (default: Raleigh).
--set-org=ORGANIZATION
organization or company name (default: "Example Corp. Inc").
--set-org-unit=ORGANIZATIONAL_UNIT
organizational unit, such as "Marketing" (default: unit).
--set-hostname=HOSTNAME
set the hostname (FQDN: fully qualified domain name) of the RHN Satellite or RHN Proxy (default: build machine's hostname).
--set-email=EMAIL
email address (default: admin@example.com)
-v | --verbose
be verbose (accumulative: -vvv means "be *really* verbose).
--key-only
(rarely used) only generate a web server's SSL private key. Try --gen-server --key-only --help for more information.
--cert-req-only
(rarely used) only generate a web server's SSL certificate request. Try --gen-server --cert-req-only --help for more information.
--cert-only
(rarely used) only generate a web server's SSL certificate. Try --gen-server --cert-only --help for more information.
--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
(rarely changed) name of archive (tarball) of the web server's SSL key set and CA SSL public certificate that is used solely by the hosted RHN Proxy installation routines (the base filename, not filename-version-release.tar).
--rpm-packager
(rarely used) packager of the generated RPM, such as "RHN Admin <rhn-admin@example.com>".
--rpm-vendor
(rarely used) vendor of the generated RPM, such as "IS/IT Example Corp.".
--rpm-only
(rarely used) only generate a deployable RPM. Try --gen-server --rpm-only --help for more information.
--no-rpm
(rarely used) do everything *except* generate an RPM.
-h | --help
help message.

EXAMPLES

rhn-ssl-tool --help

rhn-ssl-tool --gen-ca --help

rhn-ssl-tool --gen-server --help

rhn-ssl-tool --gen-ca -pMY_CA_PASSWORD --set-state="North Carolina" --set-city=Raleigh --set-org="Example Inc." --set-org-unit="SSL CA Unit" --dir=/etc/sysconfig/rhn/ssl

rhn-ssl-tool --gen-server -pMY_CA_PASSWORD --set-state="North Carolina" --set-city=Raleigh --set-org="Example Inc." --set-org-unit="IS/IT" --email="taw@example.com" --set-hostname="rhnbox1.example.com" --dir=/etc/sysconfig/rhn/ssl

FILES

BUILD_DIR/rhn-ca-openssl.cnf

BUILD_DIR/RHN-ORG-PRIVATE-SSL-KEY

BUILD_DIR/RHN-ORG-TRUSTED-SSL-CERT

BUILD_DIR/serial

BUILD_DIR/index.txt

BUILD_DIR/latest.txt

BUILD_DIR/rhn-org-trusted-ssl-cert-VER-REL.src.rpm

BUILD_DIR/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm

BUILD_DIR/MACHINE_NAME/latest.txt

BUILD_DIR/MACHINE_NAME/rhn-server-openssl.cnf

BUILD_DIR/MACHINE_NAME/server.key

BUILD_DIR/MACHINE_NAME/server.csr

BUILD_DIR/MACHINE_NAME/server.crt

BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.src.rpm

BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-REL.noarch.rpm

BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-archive-MACHINE_NAME-VER-REL.tar

SEE ALSO

openssl(1)

rpm(8)

AUTHOR

Todd Warner <taw@redhat.com>