[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Pki-devel] [PATCH] 634 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

--
Endi S. Dewata
From 7a595832ff93b2b4e24d8d9c0f5b2e3dec2ca66a Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata 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                    | 94 +++++++++++++++++-----
 .../python/pki/server/deployment/pkiparser.py      |  4 +-
 3 files changed, 135 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..8d117f4dd905330e1aa28bb36a72fd0b4cda222a 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], and [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 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 9517b527c848f7e57f536a13696cb29095a0a4f7..54de11c8f712f9b0bb3394e0e6f5267632f13a10 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 /root/.dogtag/pki-tomcat/<ca/kra/tks/ocsp>_admin.cert.
+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.
 .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,44 @@ 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
+
+.PP
+TPS requires a TKS subsystem to be installed already in addition to a CA, and
+also an authentication database. The \fBpki_authdb_basedn\fP specifies the
+base DN of the authentication database.
+
+.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 +382,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 +394,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 +402,20 @@ 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
+
 .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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]