mgr-ssl-tool

1 Version 1.0.1

`mgr-ssl-tool`

Generate and maintain SSL keys, certificates and deployment RPMs.

            mgr-ssl-tool
            options ...
            --help

            mgr-ssl-tool --gen-ca -dBUILD_DIR -pCA_PASSWORD
            options ...

            mgr-ssl-tool --gen-server -dBUILD_DIR -pCA_PASSWORD
            options ...

## Help

- `mgr-ssl-tool --help`
- `mgr-ssl-tool --gen-ca --help`
- `mgr-ssl-tool --gen-server --help`
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- (advanced) `mgr-ssl-tool --gen-ca --key-only --help`
- (advanced) `mgr-ssl-tool --gen-ca --cert-only --help`
- (advanced) `mgr-ssl-tool --gen-ca --rpm-only --help`
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- (advanced) `mgr-ssl-tool --gen-server --key-only --help`
- (advanced) `mgr-ssl-tool --gen-server --cert-req-only --help`
- (advanced) `mgr-ssl-tool --gen-server --cert-only --help`

## Description

The &RHNSSLTOOL; (`mgr-ssl-tool`) is used to generate and maintain SUSE Manager 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 SUSE Manager context, but can be useful outside of SUSE Manager.

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 SUSE Manager: securing web applications.

The SUSE Manager context of this document is in support of SUSE Manager server, but all holds true for SUSE Manager Proxy as well, so keep that in mind. SUSE Manager Servers and Proxies use /root/ssl-build as the default build directory.

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:

- `mgr-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 (SUSE Manager Server/Proxy).

  In the SUSE Manager Server/Proxy context, the organization acts as their own Certificate Authority, but these steps can be skipped if intending to use of an outside authority.

  The CA private key remains private.

  The CA certificate is used by client software (zypper 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 archive:

- `mgr-ssl-tool --gen-server --dir `BUILD_DIR` [ options `...` ]`

  This step is done more frequently (generally), especially if more than one SUSE Manager 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 SUSE Manager Proxy or 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 SUSE Manager server (SUSE Manager Server or Proxy). This is generally done by making the RPM available in the /srv/www/htdocs/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 SUSE Manager Server or SUSE Manager 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 discrete 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 CA SSL public RPM using a custom CA certificate from the given file: `--gen-ca --rpm-only --from-ca-cert=`FILE``

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

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.

-p`PASSWORD` | --password=`PASSWORD`

- CA password. Will prompt if option is missing.

-d `BUILD_DIR` | --dir=`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). Use capital letters only!

--set-state=`STATE_OR_PROVINCE`

- state or province, such as "Frankonia" (default: "")

--set-city=`CITY_OR_LOCALITY`

- city or locality, such as "Nuremberg" (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 "SUSE Manager 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:

  -p`PASSWORD` | --password=`PASSWORD`

- CA password. Will prompt if option is missing. MUST MATCH PASSWORD OF CA!!!

-d `BUILD_DIR` | --dir=`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). Use capital letters only!

--set-state=`STATE_OR_PROVINCE`

- state or province (default: "Frankonia")

--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 SUSE Manager Server or SUSE Manager Proxy (default: build machine's hostname).

--set-cname=`HOSTNAME`

- set the cname alias (FQDN: fully qualified domain name) of the SUSE Manager Server or SUSE Manager Proxy. This will generate certificate with multiple hostnames. Can be specified multiple times.

--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-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 SUSE Manager installation routines (the base filename, not filename-version-release.tar).

-h | --help

- help message.

## Examples

- `mgr-ssl-tool --help`
- `mgr-ssl-tool --gen-ca --help`
- `mgr-ssl-tool --gen-server --help`
- `mgr-ssl-tool --gen-ca -pMY_CA_PASSWORD --set-state="Frankonia" --set-city=Nuremberg --set-org="Example Inc." --set-org-unit="SSL CA Unit" --dir=/etc/sysconfig/rhn/ssl`
- `mgr-ssl-tool --gen-server -pMY_CA_PASSWORD --set-state="Frankonia" --set-city=Nuremberg --set-org="Example Inc." --set-org-unit="IS/IT" --email="taw@example.com" --set-hostname="rhnbox1.example.com" --set-cname="rhnbox1.localnet" --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-archive-MACHINE_NAME-VER-REL.tar

## See Also

- openssl(1)
- rpm(8)

## Author

- Todd Warner taw@redhat.com