Contents
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.
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. |
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 |
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.
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:
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.
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 Servers to
be deployed and install the resulting RPMs on the SUSE Manager Servers,
restarting the httpd
service afterwards:
rcapache2 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 SUSE Manager 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 SUSE Manager infrastructure is in place and configured.
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.
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=
| The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
-d= ,
--dir=
| Required for
most commands - The directory where
certificates and RPMs are built. The default is
./ssl-build . |
--ca-key=
| The CA private key filename. The default is
RHN-ORG-PRIVATE-SSL-KEY . |
--ca-cert=
| The CA public certificate filename. The
default is
RHN-ORG-TRUSTED-SSL-CERT . |
--cert-expiration=
| 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=
| The two-letter country code. The default is US. |
--set-state=
| The state or province of the CA. The default is ''. |
--set-city=
| The city or locality. The default is ''. |
--set-org=
| The company or organization, such as SUSE. The default is Example Corp. Inc. |
--set-org-unit=
| The organizational unit. The default is ''. |
--set-common-name=
| Not typically set for the CA. - The common name. |
--set-email=
| Not typically set for the CA. - The email address. |
--rpm-packager=
| Packager of the generated RPM, such as "SUSE Admin (suse-admin@example.com)." |
--rpm-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=
| 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=
| The CA password. You will be prompted for this if it's missing. Record it in a safe manner. |
-d= ,
--dir=
| Required for
most commands - The directory where
certificates and RPMs are built. The default is
./ssl-build . |
--server-key=
| The Web server's SSL private key filename.
The default is server.key . |
--server-cert-req=
| The Web server's SSL certificate request
filename. The default is server.csr . |
--server-cert=
| The Web server's SSL certificate filename.
The default is server.crt . |
--startdate=
| 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=
| 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=
| The two-letter country code. The default is US. |
--set-state=
| The state or province. The default is North Carolina. |
--set-city=
| The city or locality. . |
--set-org=
| The company or organization, such as SUSE. The default is Example Corp. Inc. |
--set-org-unit=
| The organizational unit. The default is unit. |
--set-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=
| The email address of the certificate contact. The default is admin@example.corp. |
--rpm-packager=
| Packager of the generated RPM, such as "SUSE Admin (suse-admin@example.com)." |
--rpm-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=
| 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 .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). |
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-
— the RPM prepared for distribution to client systems. It contains
the CA SSL public certificate (above) and installs it in this
location: VER-REL
.noarch.rpm/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”.
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-
— 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:
MACHINE_NAME-VER-REL
.noarch.rpm
/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
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.
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.