Add HSM information

- PKI TRAC Ticket #1405 - Add additional HSM details to 'pki_default.cfg' &
  'pkispawn' man pages

2 files changed, 180 insertions, 1 deletions

diff --git a/base/server/man/man5/pki_default.cfg.5 b/base/server/man/man5/pki_default.cfg.5
index 550e2aa9c..aaf7b53d6 100644
--- a/base/server/man/man5/pki_default.cfg.5
+++ b/base/server/man/man5/pki_default.cfg.5
@@ -184,7 +184,10 @@ Location for the PKCS #12 file containing the administrative user's certificate
 .B pki_backup_keys, pki_backup_password
 .IP
 Set to True to back up the subsystem certificates and keys to a PKCS #12 file.  This file will be located in \fI/var/lib/pki/<instance_name>/alias\fP.  pki_backup_password is the password of the PKCS#12 file.
-  
+.TP
+\fBImportant:\fP
+Since HSM keys are stored in the HSM (hardware), they cannot be backed up to a PKCS #12 file (software).  Therefore, if \fBpki_hsm_enable\fP is set to True, \fBpki_backup_keys\fP should be set to False and \fBpki_backup_password\fP should be left unset (the default values in \fB/etc/pki/default.cfg\fP).  Failure to do so will result in \fBpkispawn\fP reporting this error and exiting.
+
 .SS CLIENT DIRECTORY PARAMETERS
 .TP
 .B pki_client_dir
@@ -295,6 +298,9 @@ Installs a clone, rather than original, subsystem.
 .IP
 Location and password of the PKCS #12 file containing the system certificates for the master subsystem being cloned.  This file should be readable by the user that the Certificate Server is running as (default of pkiuser), and have the correct selinux context (pki_tomcat_cert_t).  This can be achieved by placing the file in \fI/var/lib/pki/<instance_name>/alias\fP.
 .TP
+\fBImportant:\fP
+Since HSM keys are stored in the HSM (hardware), they cannot be copied to a PKCS #12 file (software).  For the case of clones using an HSM, this means that the HSM keys must be shared between the master and its clones.  Therefore, if \fBpki_hsm_enable\fP is set to True, both \fBpki_clone_pkcs12_path\fP and \fBpki_clone_pkcs12_password\fP should be left unset (the default values in \fB/etc/pki/default.cfg\fP).  Failure to do so will result in \fBpkispawn\fP reporting this error and exiting.
+.TP
 .B pki_clone_setup_replication
 .IP
 Defaults to True.  If set to False, the installer does not set up replication agreements from the master to the clone as part of the subsystem configuration.  In this case, it is expected that the top level suffix already exists, and that the data has already been replicated.  This option is useful if you want to use other tools to create and manage your replication topology, or if the baseDN is already replicated as part of a top-level suffix.
diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
index 3ad6fdb6d..3678cffa6 100644
--- a/base/server/man/man8/pkispawn.8
+++ b/base/server/man/man8/pkispawn.8
@@ -756,6 +756,179 @@ conn.tks1.tksSharedSymKeyName=sharedSecret
 .PP
 Finally, restart the TPS instance.
 
+.SS Installing a CA, KRA, OCSP, TKS, or TPS using a Hardware Security Module (HSM)
+.BR
+.PP
+This section provides sample \fBmyconfig.txt\fP files when an HSM is being utilized in a shared PKI instance.
+
+.PP
+For this example, assume that a new CA instance has been installed by
+executing the following command:
+.IP
+\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fISecret123\fP
+pki_client_pkcs12_password=\fISecret123\fP
+pki_ds_password=\fISecret123\fP
+# Optionally keep client databases
+pki_client_database_purge=False
+# Provide HSM parameters
+pki_hsm_enable=True
+pki_hsm_libfile=<hsm_libfile>
+pki_hsm_modulename=<hsm_modulename>
+pki_token_name=<hsm_token_name>
+pki_token_password=<pki_token_password>
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=<hsm_token_name>
+pki_ssl_server_token=<hsm_token_name>
+pki_subsystem_token=<hsm_token_name>
+[CA]
+# Provide CA-specific HSM token names
+pki_ca_signing_token=<hsm_token_name>
+pki_ocsp_signing_token=<hsm_token_name>
+.if
+
+.PP
+To install a shared KRA in the same instance used by the CA execute
+the following command:
+.IP
+\x'-1'\fBpkispawn \-s KRA \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fISecret123\fP
+pki_client_database_password=\fISecret123\fP
+pki_client_pkcs12_password=\fISecret123\fP
+pki_ds_password=\fISecret123\fP
+pki_security_domain_password=\fISecret123\fP
+# Provide HSM parameters
+pki_hsm_enable=True
+pki_hsm_libfile=<hsm_libfile>
+pki_hsm_modulename=<hsm_modulename>
+pki_token_name=<hsm_token_name>
+pki_token_password=<pki_token_password>
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=<hsm_token_name>
+pki_ssl_server_token=<hsm_token_name>
+pki_subsystem_token=<hsm_token_name>
+[KRA]
+# Provide KRA-specific HSM token names
+pki_storage_token=<hsm_token_name>
+pki_transport_token=<hsm_token_name>
+.if
+
+.PP
+To install a shared OCSP in the same instance used by the CA execute
+the following command:
+.IP
+\x'-1'\fBpkispawn \-s OCSP \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fISecret123\fP
+pki_client_database_password=\fISecret123\fP
+pki_client_pkcs12_password=\fISecret123\fP
+pki_ds_password=\fISecret123\fP
+pki_security_domain_password=\fISecret123\fP
+# Provide HSM parameters
+pki_hsm_enable=True
+pki_hsm_libfile=<hsm_libfile>
+pki_hsm_modulename=<hsm_modulename>
+pki_token_name=<hsm_token_name>
+pki_token_password=<pki_token_password>
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=<hsm_token_name>
+pki_ssl_server_token=<hsm_token_name>
+pki_subsystem_token=<hsm_token_name>
+[OCSP]
+# Provide OCSP-specific HSM token names
+pki_ocsp_signing_token=<hsm_token_name>
+.if
+
+.PP
+To install a shared TKS in the same instance used by the CA execute
+the following command:
+.IP
+\x'-1'\fBpkispawn \-s TKS \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fISecret123\fP
+pki_client_database_password=\fISecret123\fP
+pki_client_pkcs12_password=\fISecret123\fP
+pki_ds_password=\fISecret123\fP
+pki_security_domain_password=\fISecret123\fP
+# Provide HSM parameters
+pki_hsm_enable=True
+pki_hsm_libfile=<hsm_libfile>
+pki_hsm_modulename=<hsm_modulename>
+pki_token_name=<hsm_token_name>
+pki_token_password=<pki_token_password>
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=<hsm_token_name>
+pki_ssl_server_token=<hsm_token_name>
+pki_subsystem_token=<hsm_token_name>
+.if
+
+.PP
+To install a shared TPS in the same instance used by the CA execute
+the following command:
+.IP
+\x'-1'\fBpkispawn \-s TPS \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fISecret123\fP
+pki_client_database_password=\fISecret123\fP
+pki_client_pkcs12_password=\fISecret123\fP
+pki_ds_password=\fISecret123\fP
+pki_security_domain_password=\fISecret123\fP
+# Provide HSM parameters
+pki_hsm_enable=True
+pki_hsm_libfile=<hsm_libfile>
+pki_hsm_modulename=<hsm_modulename>
+pki_token_name=<hsm_token_name>
+pki_token_password=<pki_token_password>
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=<hsm_token_name>
+pki_ssl_server_token=<hsm_token_name>
+pki_subsystem_token=<hsm_token_name>
+[TPS]
+# Shared TPS instances optionally utilize their shared KRA
+# for server-side keygen
+pki_enable_server_side_keygen=True
+pki_authdb_basedn=\fIdc=example,dc=com\fP
+.if
+
+.TP
+\fBImportant:\fP
+Since HSM keys are stored in the HSM (hardware), they cannot be
+backed up, moved, or copied to a PKCS #12 file (software).
+For example, if \fBpki_hsm_enable\fP is set to True,
+\fBpki_backup_keys\fP should be set to False and
+\fBpki_backup_password\fP should be left unset (the default
+values in \fB/etc/pki/default.cfg\fP).  Similarly, for the case
+of clones using an HSM, this means that the HSM keys must be
+shared between the master and its clones.  Therefore, if
+\fBpki_hsm_enable\fP is set to True, both
+\fBpki_clone_pkcs12_path\fP and \fBpki_clone_pkcs12_password\fP
+should be left unset (the default values in
+\fB/etc/pki/default.cfg\fP).  Failure to comply with these rules
+will result in \fBpkispawn\fP reporting an appropriate error and
+exiting.
+
 .SS Installing a CA clone
 .BR
 .PP