## Chapter 3. SSL Infrastructure¶

For SUSE Manager customers, security concerns are of the utmost importance. One of the strengths of SUSE Manager is its ability to process every single request over Secure Sockets Layer, or SSL. To maintain this level of security, customers installing SUSE Manager within their infrastructures must generate custom SSL keys and certificates.

Manual creation and deployment of SSL keys and certificates can be quite involved. Both the SUSE Manager Proxy Server and the SUSE Manager Server allow you to build your own SSL keys and certificates based on your own private Certificate Authority (CA) during installation. In addition, a separate command line utility, the SUSE Manager SSL Maintenance Tool, exists for this purpose. Regardless, these keys and certificates must then be deployed to all systems within your managed infrastructure. In many cases, deployment of these SSL keys and certificates is automated for you. This chapter describes efficient methods for conducting all of these tasks.

Please note that this chapter does not explain SSL in depth. The SUSE Manager SSL Maintenance Tool was designed to hide much of the complexity involved in setting up and maintaining this public-key infrastructure (PKI). For more information, please consult some of the many good references available at your nearest bookstore.

## 3.1. A Brief Introduction To SSL¶

SSL, or Secure Sockets Layer, is a protocol that enables client-server applications to pass information securely. SSL uses a system of public and private key pairs to encrypt communication passed between clients and servers. Public certificates can be left accessible, while private keys must be secured. It's the mathematical relationship (a digital signature) between a private key and its paired public certificate that makes this system work. Through this relationship, a connection of trust is established.

Throughout this document we discuss SSL private keys and public certificates. Technically both can be referred to as keys (public and private keys). But it is convention, when discussing SSL, to refer to the public half of an SSL key pair (or key set) as the SSL public certificate.

An organization's SSL infrastructure is generally made up of these SSL keys and certificates:

- Certificate Authority (CA) SSL private key and public certificate — only one set per organization generally generated. The public certificate is digitally signed by its private key. The public certificate is distributed to every system.

- Web server SSL private key and public certificate — one set per application server. The public certificate is digitally signed by both its private key and the CA SSL private key. We often refer to a Web server's key set; this is because there is an intermediary SSL certificate request that is generated. The details of what this is used for are not important to this discussion. All three are deployed to an SUSE Manager Server.

Here's a scenario: If you have one SUSE Manager Server and five SUSE Manager Proxy Servers, you will generate one CA SSL key pair and six Web server SSL key sets. The CA SSL public certificate is distributed to all systems and used by all clients to establish a connection to their respective upstream servers. Each server has its own SSL key set that is specifically tied to that server's hostname and generated using its own SSL private key and the CA SSL private key in combination. This establishes a digitally verifiable association between the Web server's SSL public certificate and the CA SSL key pair and server's private key. The Web server's key set cannot be shared with other web servers.

The most critical portion of this system is the CA SSL key pair. From that private key and public certificate an administrator can regenerate any Web server's SSL key set. This CA SSL key pair must be secured. It is highly recommended that once the entire SUSE Manager infrastructure of servers is set up and running, you archive the SSL build directory generated by this tool and/or the installers onto separate media, write down the CA password, and secure the media and password in a safe place.

## 3.2. The SUSE Manager SSL Maintenance Tool¶

SUSE Manager provides a command line tool to ease management of your secure infrastructure: the SSL Maintenance Tool, commonly known by its command mgr-ssl-tool . This tool is available as part of the `spacewalk-certs-tools` package. This package can be found within the software channels for the the latest SUSE Manager Proxy Server and SUSE Manager Server (as well as the SUSE Manager Server ISO). 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 SUSE Manager Server.

The `spacewalk-certs-tools`, which contains mgr-ssl-tool , can be installed and run on any current SUSE Linux Enterprise Server 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 SUSE Linux Enterprise Server.

Here are the cases in which the tool is required:

- When updating your CA public certificate - this is rare.

- When installing an SUSE Manager Proxy Server version 1.2 or later that connects to the central SUSE Manager 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 SUSE Manager infrastructure to use SSL where it previously did not.

- When adding SUSE Manager Proxy Servers of versions prior to 1.2 into your SUSE Manager infrastructure.

- When adding multiple SUSE Manager Servers to your SUSE Manager infrastructure.

Here are the cases in which the tool is not required:

- During installation of a SUSE Manager Server - all SSL settings are configured during the installation process. The SSL keys and certificate are built and deployed automatically.

- During installation of an SUSE Manager Proxy Server version 1.2 or later if connected to an SUSE Manager Server version 1.2 or later as its top-level service - the SUSE Manager Server contains all of the SSL information needed to configure, build and deploy the SUSE Manager Proxy Server's SSL keys and certificates.

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

In short, if your organization's SUSE Manager infrastructure deploys the latest version of SUSE Manager 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 SSL Maintenance Tool are security, flexibility, and portability. Security is achieved through the creation of distinct Web server SSL keys and certificates for each SUSE Manager 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 `spacewalk-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 server is the most current SUSE Manager 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 SUSE Manager Server's website.

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

1. Install the `spacewalk-certs-tools` package on a system within your organization, perhaps but not necessarily the SUSE Manager Server or SUSE Manager 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 Servers to be deployed and install the resulting RPMs on the SUSE Manager Servers, restarting the `httpd` service afterwards:

       rcapache2 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 SUSE Manager 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 SUSE Manager 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 SSL Maintenance Tool and repeat steps 3 through 7.

### 3.2.2. SSL Maintenance Tool Options¶

The 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: mgr-ssl-tool --help (general), mgr-ssl-tool --gen-ca --help (Certificate Authority), and mgr-ssl-tool --gen-server --help (Web server). The manual page for mgr-ssl-tool is also quite detailed and available to assist: man mgr-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:

Table 3.1. SSL Certificate Authority (CA) Options (mgr-ssl-tool --gen-ca --help)

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 SUSE. The default is Example Corp. Inc.
`--set-org-unit=`SET_ORG_UNIT`` | The organizational unit. 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 "SUSE Admin (suse-admin@example.com)."
`--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.

The following set of options must be preceded by the `--gen-server` argument:

Table 3.2. SSL Web Server Options ( mgr-ssl-tool --gen-server --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 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. .
`--set-org=`ORGANIZATION`` | The company or organization, such as SUSE. The default is Example Corp. Inc.
`--set-org-unit=`SET_ORG_UNIT`` | The organizational unit. The default is unit.
`--set-hostname=`HOSTNAME`` | The hostname of the SUSE Manager 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 admin@example.corp.
`--rpm-packager=`PACKAGER`` | Packager of the generated RPM, such as "SUSE Admin (suse-admin@example.com)."
`--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 SUSE Manager Proxy Server installation routines (the base filename, not filename-version-release.tar).

### 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 SUSE Manager or SUSE Manager Proxy. The SSL Maintenance Tool allows you to generate a CA SSL key pair if needed and re-use it for all subsequent SUSE Manager 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 SUSE Manager and Proxies). To generate a CA SSL key pair, issue a command like this:

    mgr-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 SUSE Manager 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 SUSE Manager 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:

    mgr-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" --set-email="admin@example.com" \
    --set-hostname="mgrbox1.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 SUSE Manager 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 SUSE Manager Server. Note that the `httpd` service must be restarted after installation:

    rcapache2 restart

## 3.3. Deploying the CA SSL Public Certificate to Clients¶

Both the SUSE Manager Proxy Server and SUSE Manager Server installation processes make client deployment relatively easy by generating a CA SSL public certificate and RPM. These installation processes make those publicly available by placing a copy of one or both into the `/srv/www/htdocs/pub/` directory of the SUSE Manager Server.

This public directory can be inspected easily by simply browsing to it via any web browser: http://proxy-or-susemgr.example.com/pub/.

The CA SSL public certificate in that directory can be downloaded to a client system using wget or curl. For example:

    curl -O http://proxy-or-susemgr.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT
    wget http://proxy-or-susemgr.example.com/pub/RHN-ORG-TRUSTED-SSL-CERT

Alternatively, if the CA SSL public certificate RPM resides in the `/pub` directory, it can be installed on a client system directly:

    rpm -Uvh \
    http://proxy-or-susemgr.example.com/pub/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm

Confirm the actual name of the certificate or RPM before running these commands.

## 3.4. Configuring Client Systems¶

Once the RPM or raw certificate has been deployed to a client system, the administrator of that system must then alter the configuration files of the Update Agent / Online Updater to use the new CA SSL public certificate file and connect to the appropriate SUSE Manager Proxy Server or SUSE Manager Server. The generally accepted location for that CA SSL public certificate is in the `/usr/share/rhn` directory.

The SUSE Manager Proxy Server and SUSE Manager Server both have mgr_bootstrap installed by default, which can greatly reduce these repetitive steps and simplify the process of registering and configuring client systems. Please refer Chapter 5, Using Bootstrap for details.