Re: [Pki-devel] [Patch] Add HSM information

[John Magne]

Tried it out the man pages, looks good.

ACK



- Original Message -
> From: "Matthew Harmsen" <mharm...@redhat.com>
> To: "pki-devel" <pki-devel@redhat.com>
> Sent: Friday, July 1, 2016 1:52:02 PM
> Subject: [Pki-devel] [Patch] Add HSM information
> 
> Please review the attached patch which addresses the following ticket:
> 
> 
> * PKI TRAC Ticket #1405 - [MAN] Add additional HSM details to
> 'pki_default.cfg' & 'pkispawn' man pages
> 
> 
> This ticket adds text to the pki_default.cfg.5 and pkispawn.8 man pages to
> more adequatey describe the
> use of hardware security modules (HSM) with PKI subsystems.
> 
> ___
> Pki-devel mailing list
> Pki-devel@redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel

___
Pki-devel mailing list
Pki-devel@redhat.com
https://www.redhat.com/mailman/listinfo/pki-devel

[Pki-devel] [Patch] Add HSM information

[Matthew Harmsen]

Please review the attached patch which addresses the following ticket:

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

This ticket adds text to the pki_default.cfg.5 and pkispawn.8 man pages 
to more adequatey describe the

use of hardware security modules (HSM) with PKI subsystems.

From 4d7daa7ba5116ceb19c1df71ce749c3db7944f49 Mon Sep 17 00:00:00 2001
From: Matthew Harmsen 
Date: Fri, 1 Jul 2016 14:45:57 -0600
Subject: [PATCH] Add HSM information

- PKI TRAC Ticket #1405 - Add additional HSM details to 'pki_default.cfg' &
  'pkispawn' man pages
---
 base/server/man/man5/pki_default.cfg.5 |   8 +-
 base/server/man/man8/pkispawn.8| 173 +
 2 files changed, 180 insertions(+), 1 deletion(-)

diff --git a/base/server/man/man5/pki_default.cfg.5 b/base/server/man/man5/pki_default.cfg.5
index 550e2aa..aaf7b53 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//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//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 3ad6fdb..3678cff 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=
+pki_hsm_modulename=
+pki_token_name=
+pki_token_password=
+# Provide PKI-specific HSM token names
+pki_audit_signing_token=
+pki_ssl_server_token=
+pki_subsystem_token=
+[CA]
+# Provide CA-specific HSM token names
+pki_ca_signing_token=
+pki_ocsp_signing_token=
+.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