[Pki-devel] [PATCH] 634 Updated man pages with TPS info.
Endi Sukma Dewata
edewata at redhat.com
Fri Jul 17 23:37:23 UTC 2015
On 7/17/2015 11:36 AM, Christina Fu wrote:
> 1. I don't think we should assume that the installer is root. I suggest
> you change the following line from
> setup the path where the admin certificate of this <subsystem> should be
> stored. The default value is
> /root/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.
> to something like
> setup the path where the admin certificate of this <subsystem> should be
> stored. The default value is
> $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.
> If there are other places like this in this man pages or any other
> documentation, we should make sure we do this correct.y
This is fixed in patch #635 (ACKed by alee).
> 2. I do not find any mentioning of the need to set up the shared secret
> between TKS and TPS after pkispawn if one were to install TKS and TPS on
> separate tomcat instances. Please add that as a note and point to
> wherever the detail is at(possibly another tps-specific man page). Can
> also mention that in the case of shared tomcat instance, pkispawn takes
> cared of it.
Please take a look at the new patch #634-2. I added references to the
instruction provided by jmagne.
> 3. probably no action needed from you now, but I need to write a man
> page for TPS externalReg feature.
>
> We can discuss more on irc if needed.
> thanks,
> Christina
--
Endi S. Dewata
-------------- next part --------------
>From 9d6969d02d5fc2c72baf6968ecc6f4718ce2ce40 Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata at redhat.com>
Date: Wed, 24 Jun 2015 12:07:47 -0400
Subject: [PATCH] Updated man pages with TPS info.
The man pages for pkispawn and pki_default.cfg have been updated
to include TPS deployment parameters.
https://fedorahosted.org/pki/ticket/1277
---
base/server/man/man5/pki_default.cfg.5 | 67 +++++++++++--
base/server/man/man8/pkispawn.8 | 111 +++++++++++++++++----
.../python/pki/server/deployment/pkiparser.py | 4 +-
3 files changed, 152 insertions(+), 30 deletions(-)
diff --git a/base/server/man/man5/pki_default.cfg.5 b/base/server/man/man5/pki_default.cfg.5
index 6623ce6fd5d5cf425bd93e73eb450d31b4f788bb..df4f944287a02285c03b85c87c832aaff2e396b2 100644
--- a/base/server/man/man5/pki_default.cfg.5
+++ b/base/server/man/man5/pki_default.cfg.5
@@ -24,7 +24,13 @@ pki_default.cfg \- Certificate Server instance default config file.
This file contains the default settings for a Certificate Server instance created using \fBpkispawn\fP. This file should not be edited, as it can be modified when the Certificate Server packages are updated. Rather, when setting up a Certificate Server instance, a user-provided configuration file can provide overrides to the defaults in /etc/pki/default.cfg. See \fBpkispawn(8)\fR for details.
.SH SECTIONS
-\fIdefault.cfg\fP is divided into subsystem-based sections ([DEFAULT] for general configuration and subsystem-type sections such as [CA] and [KRA]). These sections are stacked, so that parameters read in earlier sections can be overwritten by parameters in later sections. For the Java subsystems (CA, KRA, OCSP, and TKS), the sections read are [DEFAULT], [Tomcat] and the subsystem type section -- [CA], [KRA], [OCSP], and [TKS] -- in that order. This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and subsystem-specific upgrades in the other sections.
+\fIdefault.cfg\fP contains parameters that are grouped into sections.
+These sections are stacked, so that parameters defined in earlier sections can
+be overwritten by parameters defined in later sections. The sections are read
+in the following order: [DEFAULT], [Tomcat], and the subsystem section ([CA],
+[KRA], [OCSP], [TKS], or [TPS]). This allows the ability to specify parameters
+to be shared by all subsystems in [DEFAULT] or [Tomcat], and subsystem-specific
+customization.
.PP
There are a small number of bootstrap parameters which are passed in the configuration file by \fBpkispawn\fP. Other parameter's values can be interpolated tokens rather than explicit values. For example:
.PP
@@ -134,7 +140,7 @@ Nickname for the administrator certificate.
.IP
Set to True to import an existing admin certificate for the admin user, rather than generating a new one. A subsystem-specific administrator will still be created within the subsystem's LDAP tree. This is useful to allow multiple subsystems within the same instance to be more easily administered from the same browser by using a single certificate.
-By default, this is set to False for CA subsystems and true for KRA, OCSP, and TKS subsystems. In this case, the admin certificate is read from the file ca_admin.cert in \fBpki_client_dir\fP.
+By default, this is set to False for CA subsystems and true for KRA, OCSP, TKS, and TPS subsystems. In this case, the admin certificate is read from the file ca_admin.cert in \fBpki_client_dir\fP.
Note that cloned subsystems do not create a new administrative user. The administrative user of the master subsystem is used instead, and the details of this master user are replicated during the install.
.TP
@@ -237,11 +243,11 @@ The security domain is a component that facilitates communication between subsys
.TP
.B pki_security_domain_hostname, pki_security_domain_https_port
.IP
-Location of the security domain. Required for KRA, OCSP, and TKS subsystems and for CA subsystems joining a security domain. Defaults to the location of the CA subsystem within the same instance.
+Location of the security domain. Required for KRA, OCSP, TKS, and TPS subsystems and for CA subsystems joining a security domain. Defaults to the location of the CA subsystem within the same instance.
.TP
.B pki_security_domain_user, pki_security_domain_password
.IP
-Administrative user of the security domain. Required for KRA, OCSP, and TKS subsystems, and for CA subsystems joining a security domain. Defaults to the administrative user for the CA subsystem within the same instance (caadmin).
+Administrative user of the security domain. Required for KRA, OCSP, TKS, and TPS subsystems, and for CA subsystems joining a security domain. Defaults to the administrative user for the CA subsystem within the same instance (caadmin).
.TP
.B pki_security_domain_name
.IP
@@ -308,7 +314,7 @@ Set to \fBTrue\fP if the subordinate CA will host its own security domain. Defa
Used when \fBpki_subordinate_create_security_domain\fP is set to \fBTrue\fP. Specifies the name of the security domain to be hosted on the subordinate CA.
.SS STANDALONE PKI PARAMETERS
-A stand-alone PKI subsystem is defined as a non-CA PKI subsystem that does not contain a CA as a part of its deployment, and functions as its own security domain. Currently, only stand-alone DRMs are supported.
+A stand-alone PKI subsystem is defined as a non-CA PKI subsystem that does not contain a CA as a part of its deployment, and functions as its own security domain. Currently, only stand-alone KRAs are supported.
.TP
.B pki_standalone
.IP
@@ -328,7 +334,7 @@ Will be generated by the first step of a stand-alone PKI process. This is the l
.PP
.B pki_external_storage_csr_path
.IP
-[DRM ONLY] Will be generated by the first step of a stand-alone DRM process. This is the location of the file containing the storage CSR (which will be presented to the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_storage.csr'.
+[KRA ONLY] Will be generated by the first step of a stand-alone KRA process. This is the location of the file containing the storage CSR (which will be presented to the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_storage.csr'.
.PP
.B pki_external_subsystem_csr_path
.IP
@@ -336,7 +342,7 @@ Will be generated by the first step of a stand-alone PKI process. This is the l
.PP
.B pki_external_transport_csr_path
.IP
-[DRM ONLY] Will be generated by the first step of a stand-alone DRM process. This is the location of the file containing the transport CSR (which will be presented to the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_transport.csr'.
+[KRA ONLY] Will be generated by the first step of a stand-alone KRA process. This is the location of the file containing the transport CSR (which will be presented to the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_transport.csr'.
.PP
.B pki_external_step_two
.IP
@@ -364,7 +370,7 @@ Required for the second step of a stand-alone PKI process. This is the location
.PP
.B pki_external_storage_cert_path
.IP
-[DRM ONLY] Required for the second step of a stand-alone DRM process. This is the location of the file containing the storage certificate (as issued by the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_storage.cert'.
+[KRA ONLY] Required for the second step of a stand-alone KRA process. This is the location of the file containing the storage certificate (as issued by the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_storage.cert'.
.PP
.B pki_external_subsystem_cert_path
.IP
@@ -372,7 +378,50 @@ Required for the second step of a stand-alone PKI process. This is the location
.PP
.B pki_external_transport_cert_path
.IP
-[DRM ONLY] Required for the second step of a stand-alone DRM process. This is the location of the file containing the transport certificate (as issued by the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_transport.cert'.
+[KRA ONLY] Required for the second step of a stand-alone KRA process. This is the location of the file containing the transport certificate (as issued by the external CA). Defaults to '%(pki_instance_configuration_path)s/kra_transport.cert'.
+
+.SS TPS PARAMETERS
+.BR
+.TP
+.B pki_authdb_basedn
+.IP
+Specifies the base DN of TPS authentication database.
+.TP
+.B pki_authdb_hostname
+.IP
+Specifies the hostname of TPS authentication database. Defaults to localhost.
+.TP
+.B pki_authdb_port
+.IP
+Specifies the port number of TPS authentication database. Defaults to 389.
+.TP
+.B pki_authdb_secure_conn
+.IP
+Specifies whether to use a secure connection to TPS authentication database.
+Defaults to False.
+.TP
+.B pki_enable_server_side_keygen
+.IP
+Specifies whether to enable server-side key generation. Defaults to False.
+The location of the KRA instance should be specified in the \fBpki_kra_uri\fP
+parameter.
+.TP
+.B pki_ca_uri
+.IP
+Specifies the URI of the CA instance used by TPS to create and revoke user
+certificates. Defaults to the instance in which the TPS is running.
+.TP
+.B pki_kra_uri
+.IP
+Specifies the URI of the KRA instance used by TPS to archive and recover
+keys. Required if server-side key generation is enabled using the
+\fBpki_enable_server_side_keygen\fP parameter. Defaults to the instance in
+which the TPS is running.
+.TP
+.B pki_tks_uri
+.IP
+Specifies the URI of the TKS instance used by TPS to generate symmetric keys.
+Defaults to the instance in which the TPS is running.
.SH AUTHORS
Ade Lee <alee at redhat.com>. \fBpkispawn\fP was written by the Dogtag project.
diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
index d475d9524aced59e53ec28bdf3b466ccc4593f7f..9970da8259fa4793262ad33d6e2340e601845fb5 100644
--- a/base/server/man/man8/pkispawn.8
+++ b/base/server/man/man8/pkispawn.8
@@ -21,7 +21,8 @@ pkispawn \- Sets up an instance of Certificate Server.
pkispawn \-s <subsystem> \-f <config_file> [\-h] [\-v] [\-p <prefix>]
.SH DESCRIPTION
-Sets up an instance of Certificate Server. This utility creates any of the Java-based Certificate Server subsystems (CA, KRA, OCSP, and TKS).
+Sets up a Certificate Server subsystem (CA, KRA, OCSP, TKS, or TPS) in a
+Tomcat instance.
.TP
\fBNote:\fP
A 389 Directory Server instance must be configured and running before this script can be run. Certificate Server requires an internal directory database. The default configuration assumes a Directory Server instance running on the same machine on port 389. For more information on creating a Directory Server instance, see
@@ -35,7 +36,14 @@ respectively.
.PP
The instances are created based on values for configuration parameters in the default configuration (/etc/pki/default.cfg) and the user-provided configuration file. The user-provided configuration file is read after the default configuration file, so any parameters defined in that file will override parameters in the default configuration file. In general, most users will store only those parameters which are different from the default configuration in their user-provided configuration file.
.PP
-This configuration file contains directives that are divided into sections for different subsystem types (such as [DEFAULT], [CA], and [KRA]). These sections are stacked, so that parameters read in earlier sections can be overwritten by parameters in later sections. For the Java subsystems (CA, KRA, OCSP and TKS), the sections read are [DEFAULT], [Tomcat] and the subsystem-type section ([CA], [KRA], [OCSP], or [TKS]), in that order. This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and system-specific upgrades in the [CA], [KRA], and other sections.
+This configuration file contains parameters that are grouped into sections.
+These sections are stacked, so that parameters defined in earlier sections can
+be overwritten by parameters defined in later sections. The sections are read
+in the following order: [DEFAULT], [Tomcat], and the subsystem section ([CA],
+[KRA], [OCSP], [TKS], or [TPS]). This allows the ability to specify parameters
+to be shared by all subsystems in [DEFAULT] or [Tomcat], and system-specific
+customization.
+
.TP
\fBNote:\fP
Any non-password related parameter values in the configuration file that needs to contain a \fB%\fP character must be properly escaped. For example, a value of \fBfoo%bar\fP would be specified as \fBfoo%%bar\fP in the configuration file.
@@ -68,7 +76,7 @@ Previously, as an alternative to using \fBpkisilent\fP to perform a non-interact
.SH OPTIONS
.TP
.B -s <subsystem>
-Specifies the subsystem to be installed and configured, where <subsystem> is CA, KRA, OCSP, or TKS.
+Specifies the subsystem to be installed and configured, where <subsystem> is CA, KRA, OCSP, TKS, or TPS.
.TP
.B -f <config_file>
Specifies the path to the user-defined configuration file. This file contains differences between the default configuration and the custom configuration.
@@ -83,10 +91,16 @@ for details.
.SH INTERACTIVE MODE
.PP
-If no options are specified, pkispawn will provide an interactive menu to collect the parameters needed to install
-the Certificate Server instance. Note that only the most basic installation options are provided. This includes root CAs,
-KRAs, OCSPs and TKS, connecting to the LDAP port of a directory server. More complicated setups such as: cloned subsystems, subordinate or externally signed CAs, subsystems that connect to the directory server using LDAPS, and subsystems that are customized beyond the options described below - require the use of a configuration file with the
-\-f option.
+If no options are specified, pkispawn will provide an interactive menu to
+collect the parameters needed to install the Certificate Server instance.
+Note that only the most basic installation options are provided. This
+includes root CA, KRA, OCSP, TKS, and TPS connecting to an existing
+directory server. More advanced setups such as cloned subsystems,
+subordinate or externally signed CA, subsystems that connect to the
+directory server using LDAPS, and subsystems that are customized beyond
+the options described below require the use of a configuration file with
+the \-f option.
+
.PP
The interactive option is most useful for those users getting familiar with Certificate Server. The parameters collected are
written to the installation file of the subsystem, which can be found at \fB/etc/sysconfig/pki/tomcat/<instance name>/<subsystem>/deployment.cfg.\fP
@@ -95,7 +109,7 @@ The following parameters are queried interactively during the installation proce
.PP
\fBSubsystem Type\fP
.TP
-\fISubsystem (CA/KRA/OCSP/TKS):\fP
+\fISubsystem (CA/KRA/OCSP/TKS/TPS):\fP
the type of subsystem to be installed. Prompted when the \-s option is not specified. The default value chosen is CA.
.PP
\fBInstance Specific Parameters\fP
@@ -103,7 +117,7 @@ the type of subsystem to be installed. Prompted when the \-s option is not speci
\fIInstance name:\fP
the name of the tomcat instance in which the subsystem is to be installed. The default value is pki-tomcat.
.br
-\fBNote:\fP Only one subsystem of a given type (CA, KRA, OCSP, TKS) can exist within a given instance.
+\fBNote:\fP Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can exist within a given instance.
.TP
\fIHTTP port:\fP
the HTTP port of the Tomcat instance. The default value is 8080.
@@ -122,7 +136,7 @@ the management port of the Tomcat instance. The default value is 8005.
\fBAdministrative User Parameters\fP
.TP
\fIUsername:\fP
-the username of the administrator of this subsystem. The default value is <ca/kra/tks/ocsp>admin.
+the username of the administrator of this subsystem. The default value is <ca/kra/ocsp/tks/tps>admin.
.TP
\fIPassword:\fP
password for the administrator user.
@@ -131,7 +145,7 @@ password for the administrator user.
An optional parameter that can be used to import an already available CA admin certificate into this instance.
.TP
\fIExport certificate:\fP
-setup the path where the admin certificate of this <subsystem> should be stored. The default value is $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks>_admin.cert.
+setup the path where the admin certificate of this <subsystem> should be stored. The default value is $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.
.PP
\fBDirectory Server Parameters\fP
.TP
@@ -281,17 +295,18 @@ Additionally, for a CA subsystem, both the CA and OCSP Signing key algorithm, ke
\fBNote:\fP
For all PKI subsystems including the CA, ECC is not supported for the corresponding Audit Signing parameters. Similarly, for KRA subsystems, ECC is not supported for either of the corresponding Storage or Transport parameters.
-.SS Installing a KRA, OCSP, or TKS in a shared instance
+.SS Installing a KRA, OCSP, TKS, or TPS in a shared instance
.BR
.PP
-To install a KRA, OCSP, or TKS in the same instance used by the CA execute
+To install a KRA, OCSP, TKS, or TPS in the same instance used by the CA execute
+
the following command:
.IP
\x'-1'\fBpkispawn \-s <subsystem> \-f myconfig.txt\fR
.PP
-where subsystem is KRA, OCSP, or TKS and \fImyconfig.txt\fP contains the
+where subsystem is KRA, OCSP, TKS, or TPS, and \fImyconfig.txt\fP contains the
following text:
.IP
@@ -314,17 +329,47 @@ with a single administrator certificate. To access the new subsystem's
functionality, simply point the browser to https://<hostname>:8443 and click
the relevant top-level links.
-.SS Installing a KRA, OCSP, or TKS in a separate instance
+.PP
+To install TPS in a shared instance the following section must be added to
+\fImyconfig.txt\fP:
+
+.IP
+.nf
+[TPS]
+pki_authdb_basedn=\fIdc=example,dc=com\fP
+.fi
+
+TPS requires an authentication database. The \fBpki_authdb_basedn\fP
+specifies the base DN of the authentication database.
+
+.PP
+TPS also requires that a CA and a TKS subsystems are already installed
+in the same instance. Since they are in the same instance, a shared
+secret key will automatically be generated in TKS and imported into TPS.
+
+.PP
+Optionally, server-side key generation can be enabled in TPS by adding the
+following parameter in [TPS]:
+
+.IP
+.nf
+pki_enable_server_side_keygen=\fITrue\fP
+.fi
+
+.PP
+The server-side key generation requires a KRA subsystem to be installed already.
+
+.SS Installing a KRA, OCSP, TKS, or TPS in a separate instance
.BR
.PP
-To install a KRA, OCSP, or TKS with a remote a CA execute the following
+To install a KRA, OCSP, TKS, or TPS with a remote a CA execute the following
command:
.IP
\x'-1'\fBpkispawn \-s <subsystem> \-f myconfig.txt\fR
.PP
-where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the
+where subsystem is KRA, OCSP, TKS, or TPS, and \fImyconfig.txt\fP contains the
following text:
.IP
@@ -340,7 +385,7 @@ pki_security_domain_https_port=<ca_https_port>
pki_security_domain_user=caadmin
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
-[KRA/OCSP/TKS]
+[KRA/OCSP/TKS/TPS]
pki_import_admin_cert=False
.fi
@@ -352,7 +397,7 @@ and the information about the security domain (the trusted collection of
subsystems within an instance).
.PP
-The subsystem section is [KRA], [OCSP], or [TKS]. This example assumes
+The subsystem section is [KRA], [OCSP], [TKS], or [TPS]. This example assumes
that the specified CA hosts the security domain. The CA must be running and
accessible.
@@ -360,6 +405,34 @@ accessible.
A new administrator certificate is generated for the new subsystem and stored
in a PKCS #12 file in \fI$HOME/.dogtag/pki-tomcat\fP.
+.PP
+As in a shared instance, to install TPS in a separate instance the
+authentication database must be specified in the [TPS] section, and optionally
+the server-side key generation can be enabled. If the CA, KRA, or TKS
+subsystems required by TPS are running on a remote instance the following
+parameters must be added into the [TPS] section to specify their locations:
+
+.IP
+.nf
+pki_ca_uri=\fIhttps://<ca_hostname>:<ca_https_port>\fP
+pki_kra_uri=\fIhttps://<kra_hostname>:<kra_https_port>\fP
+pki_tks_uri=\fIhttps://<tks_hostname>:<tks_https_port>\fP
+.fi
+
+.PP
+If TPS and TKS are installed on separate instances the shared secret key needs
+to be generated manually on TKS, then manually imported into TPS. Follow this
+document starting from step 18 to generate a shared secret key in TKS:
+
+.PP
+https://access.redhat.com/documentation/en-US/Red_Hat_Certificate_System/8.1/html/Deploy_and_Install_Guide/tms-install.html#install-tks
+
+.PP
+Follow this document starting from step 24 to import the shared secret key into TPS:
+
+.PP
+https://access.redhat.com/documentation/en-US/Red_Hat_Certificate_System/8.1/html/Deploy_and_Install_Guide/pkicreate-tps.html
+
.SS Installing a CA clone
.BR
.PP
diff --git a/base/server/python/pki/server/deployment/pkiparser.py b/base/server/python/pki/server/deployment/pkiparser.py
index 4b3dabb927f138fa7d7e5977951380692a60debc..c1b6be3954d250450c7a3ad035aaf7b4b69c24ad 100644
--- a/base/server/python/pki/server/deployment/pkiparser.py
+++ b/base/server/python/pki/server/deployment/pkiparser.py
@@ -71,7 +71,7 @@ class PKIConfigParser:
nargs=1, choices=config.PKI_SUBSYSTEMS,
metavar='<subsystem>',
help='where <subsystem> is '
- 'CA, KRA, OCSP, RA, TKS, or TPS')
+ 'CA, KRA, OCSP, TKS, or TPS')
self.optional.add_argument(
'-h', '--help',
dest='help', action='help',
@@ -1178,7 +1178,7 @@ class PKIConfigParser:
elif (config.pki_subsystem != "CA" or\
config.str2bool(self.mdict['pki_clone']) or\
config.str2bool(self.mdict['pki_subordinate'])):
- # PKI KRA, PKI OCSP, PKI RA, PKI TKS, PKI TPS,
+ # PKI KRA, PKI OCSP, PKI TKS, PKI TPS,
# CA Clone, KRA Clone, OCSP Clone, TKS Clone, TPS Clone
# Subordinate CA
self.mdict['pki_security_domain_type'] = "existing"
--
1.9.3
More information about the Pki-devel
mailing list