From 2b53465eb36f2c464a109a8907031f2716da36a2 Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata@redhat.com>
Date: Wed, 23 Apr 2014 01:23:46 -0400
Subject: [PATCH] Converted TPS connector docs into man page.

The TPS connector docs in the CS.cfg have been converted into
pki-tps-connector manual page. The build scripts have been updated
accordingly.

Ticket #890, #950.
---
 base/tps-tomcat/CMakeLists.txt                     |  12 ++
 .../tps-tomcat/man/man5/pki-tps-connector-config.5 | 217 +++++++++++++++++++++
 base/tps-tomcat/shared/conf/CS.cfg.in              |  81 --------
 specs/pki-core.spec                                |   1 +
 4 files changed, 230 insertions(+), 81 deletions(-)
 create mode 100644 base/tps-tomcat/man/man5/pki-tps-connector-config.5

diff --git a/base/tps-tomcat/CMakeLists.txt b/base/tps-tomcat/CMakeLists.txt
index 58304db068640afc77a75f69dfb0ca3dc2e6ed7f..c953d8adf3fd4156ed4059ed041ee06de10171ae 100644
--- a/base/tps-tomcat/CMakeLists.txt
+++ b/base/tps-tomcat/CMakeLists.txt
@@ -6,6 +6,18 @@ add_subdirectory(src)
 add_subdirectory(setup)
 add_subdirectory(shared/conf)
 
+# install manual pages
+install(
+    DIRECTORY
+        man/
+    DESTINATION
+        ${MAN_INSTALL_DIR}
+    FILE_PERMISSIONS
+        OWNER_READ OWNER_WRITE
+        GROUP_READ
+        WORLD_READ
+)
+
 # install systemd scripts
 install(
     FILES
diff --git a/base/tps-tomcat/man/man5/pki-tps-connector-config.5 b/base/tps-tomcat/man/man5/pki-tps-connector-config.5
new file mode 100644
index 0000000000000000000000000000000000000000..85b6792d6af58cf51df133ceb83f74c6b7dd7ccb
--- /dev/null
+++ b/base/tps-tomcat/man/man5/pki-tps-connector-config.5
@@ -0,0 +1,217 @@
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH pki-tps-connector 5 "April 22, 2014" "version 10.2" "PKI TPS Connector Configuration" Dogtag Team
+.\" Please adjust this date whenever revising the man page.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for man page specific macros, see man(7)
+.SH NAME
+PKI TPS Connector Configuration
+
+.SH LOCATION
+/var/lib/pki/<instance>/conf/tps/CS.cfg
+
+.SH DESCRIPTION
+
+TPS connector provides a mechanism for TPS to communicate with other PKI subsystems.
+There are three supported connector types: CA, KRA, and TKS. The connectors are
+defined using properties in the TPS configuration file.
+
+.SH CA CONNECTOR
+
+A CA connector is defined using properties that begin with tps.connector.ca<n> where
+n is a positive integer indicating the ID of the CA connector.
+
+.SS tps.connector.ca<n>.enable
+
+This property contains a boolean value indicating whether the connector is enabled.
+
+.SS tps.connector.ca<n>.host
+
+In no-failover configuration, the property contains the hostname of the CA.
+
+In failover configuration, the property contains a list of hostnames and port numbers
+of the CA subsystems. The format is hostname:port separated by spaces.
+
+.SS tps.connector.ca<n>.port
+
+In no-failover configuration, the property contains the port number of the CA.
+
+.SS tps.connector.ca<n>.nickName
+
+This property contains the nickname of the TPS subsystem certificate for SSL client
+authentication to the CA.
+
+.SS tps.connector.ca<n>.minHttpConns
+
+This property contains the minimum number of HTTP connections.
+
+.SS tps.connector.ca<n>.maxHttpConns
+
+This property contains the maximum number of HTTP connections.
+
+.SS tps.connector.ca<n>.uri.<op>
+
+This property contains the URI to contact CA for the operation <op>.
+Example ops: enrollment, renewal, revoke, unrevoke.
+
+.SS tps.connector.ca<n>.timeout
+
+This property contains the connection timeout.
+
+.SH KRA CONNECTOR
+
+A KRA connector is defined using properties that begin with tps.connector.kra<n> where
+n is a positive integer indicating the ID of the KRA connector.
+
+.SS tps.connector.kra<n>.enable
+
+This property contains a boolean value indicating whether the connector is enabled.
+
+.SS tps.connector.kra<n>.host
+
+In no-failover configuration, the property contains the hostname of the KRA.
+
+In failover configuration, the property contains a list of hostnames and port numbers
+of the KRA subsystems. The format is hostname:port separated by spaces.
+
+.SS tps.connector.kra<n>.port
+
+In no-failover configuration, the property contains the port number of the KRA.
+
+.SS tps.connector.kra<n>.nickName
+
+This property contains the nickname of the TPS subsystem certificate for SSL client
+authentication to the KRA.
+
+.SS tps.connector.kra<n>.minHttpConns
+
+This property contains the minimum number of HTTP connections.
+
+.SS tps.connector.kra<n>.maxHttpConns
+
+This property contains the maximum number of HTTP connections.
+
+.SS tps.connector.kra<n>.uri.<op>
+
+This property contains the URI to contact KRA for the operation <op>.
+Example ops: GenerateKeyPair, TokenKeyRecovery.
+
+.SS tps.connector.kra<n>.timeout
+
+This property contains the connection timeout.
+
+.SH TKS CONNECTOR
+
+A TKS connector is defined using properties that begin with tps.connector.tks<n> where
+n is a positive integer indicating the ID of the TKS connector.
+
+.SS tps.connector.tks<n>.enable
+
+This property contains a boolean value indicating whether the connector is enabled.
+
+.SS tps.connector.tks<n>.host
+
+In no-failover configuration, the property contains the hostname of the TKS.
+
+In failover configuration, the property contains a list of hostnames and port numbers
+of the TKS subsystems. The format is hostname:port separated by spaces.
+
+.SS tps.connector.tks<n>.port
+
+In no-failover configuration, the property contains the port number of the TKS.
+
+.SS tps.connector.tks<n>.nickName
+
+This property contains the nickname of the TPS subsystem certificate for SSL client
+authentication to the TKS.
+
+.SS tps.connector.tks<n>.minHttpConns
+
+This property contains the minimum number of HTTP connections.
+
+.SS tps.connector.tks<n>.maxHttpConns
+
+This property contains the maximum number of HTTP connections.
+
+.SS tps.connector.tks<n>.uri.<op>
+
+This property contains the URI to contact TKS for the operation <op>.
+Example ops: computeRandomData, computeSessionKey, createKeySetData, encryptData.
+
+.SS tps.connector.tks<n>.timeout
+
+This property contains the connection timeout.
+
+.SS tps.connector.tks<n>.generateHostChallenge
+
+This property contains a boolean value indicating whether to generate host challenge.
+
+.SS tps.connector.tks<n>.serverKeygen
+
+This property contains a boolean value indicating whether to generate keys on server side.
+
+.SS tps.connector.tks<n>.keySet
+
+This property contains the key set to be used on TKS.
+
+.SS tps.connector.tks<n>.tksSharedSymKeyName
+
+This property contains the shared secret key name.
+
+.SH EXAMPLE
+
+.nf
+tps.connector.ca1.enable=true
+tps.connector.ca1.host=server.example.com
+tps.connector.ca1.port=8443
+tps.connector.ca1.minHttpConns=1
+tps.connector.ca1.maxHttpConns=15
+tps.connector.ca1.nickName=subsystemCert cert-pki-tomcat TPS
+tps.connector.ca1.timeout=30
+tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient
+tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient
+tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke
+tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke
+
+tps.connector.kra1.enable=true
+tps.connector.kra1.host=server.example.com
+tps.connector.kra1.port=8443
+tps.connector.kra1.minHttpConns=1
+tps.connector.kra1.maxHttpConns=15
+tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat TPS
+tps.connector.kra1.timeout=30
+tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair
+tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
+
+tps.connector.tks1.enable=true
+tps.connector.tks1.host=server.example.com
+tps.connector.tks1.port=8443
+tps.connector.tks1.minHttpConns=1
+tps.connector.tks1.maxHttpConns=15
+tps.connector.tks1.nickName=subsystemCert cert-pki-tomcat TPS
+tps.connector.tks1.timeout=30
+tps.connector.tks1.generateHostChallenge=true
+tps.connector.tks1.serverKeygen=false
+tps.connector.tks1.keySet=defKeySet
+tps.connector.tks1.tksSharedSymKeyName=sharedSecret
+tps.connector.tks1.uri.computeRandomData=/tks/agent/tks/computeRandomData
+tps.connector.tks1.uri.computeSessionKey=/tks/agent/tks/computeSessionKey
+tps.connector.tks1.uri.createKeySetData=/tks/agent/tks/createKeySetData
+tps.connector.tks1.uri.encryptData=/tks/agent/tks/encryptData
+.fi
+
+.SH AUTHORS
+Dogtag Team <pki-devel@redhat.com>.
+
+.SH COPYRIGHT
+Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
diff --git a/base/tps-tomcat/shared/conf/CS.cfg.in b/base/tps-tomcat/shared/conf/CS.cfg.in
index 3898e989c45582d32355fe6f5836fc3a5d0725ab..b9b97c8a22bd85a38a018fd44004ebfd420f9661 100644
--- a/base/tps-tomcat/shared/conf/CS.cfg.in
+++ b/base/tps-tomcat/shared/conf/CS.cfg.in
@@ -1483,30 +1483,6 @@ tps.cert.audit_signing.nickname=[HSM_LABEL][NICKNAME]
 tps.cert.list=sslserver,subsystem,audit_signing
 tps.cert.sslserver.certusage=SSLServer
 tps.cert.subsystem.certusage=SSLClient
-tps.connector.ca1._001=#########################################
-tps.connector.ca1._002=# CA connector
-tps.connector.ca1._003=#
-tps.connector.ca1._004=# tps.connector.ca<n>.enable:
-tps.connector.ca1._005=#   - enable this connector or not
-tps.connector.ca1._006=# tps.connector.ca<n>.host:
-tps.connector.ca1._007=#   - for no Failover, host name of the CA
-tps.connector.ca1._008=#   - for Failover setup, host name and port number
-tps.connector.ca1._009=#     of your CA, format is host:port separated by a space
-tps.connector.ca1._010=# tps.connector.ca<n>.port:
-tps.connector.ca1._011=#   - for no Failover, port number of the CA
-tps.connector.ca1._012=# tps.connector.ca<n>.nickName:
-tps.connector.ca1._013=#   - nickname of the TPS subsystem certificate for
-tps.connector.ca1._014=#     SSL client authentication to the CA
-tps.connector.ca1._015=# tps.connector.ca<n>.minHttpConns:
-tps.connector.ca1._016=#   - minimum HTTP connections
-tps.connector.ca1._017=# tps.connector.ca<n>.maxHttpConns:
-tps.connector.ca1._018=#   - maximum HTTP connections
-tps.connector.ca1._019=# tps.connector.ca<n>.uri.<op>:
-tps.connector.ca1._020=#   - uri to contact CA for the operation <op>
-tps.connector.ca1._021=#   - example ops: enrollment, renewal, revoke, unrevoke
-tps.connector.ca1._022=# tps.connector.ca<n>.timeout:
-tps.connector.ca1._023=#   - connection timeout
-tps.connector.ca1._024=#########################################
 tps.connector.ca1.enable=false
 tps.connector.ca1.host=[PKI_CA_HOSTNAME]
 tps.connector.ca1.port=[PKI_CA_PORT]
@@ -1518,30 +1494,6 @@ tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient
 tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient
 tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke
 tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke
-tps.connector.kra1._001=#########################################
-tps.connector.kra1._002=# KRA connector
-tps.connector.kra1._003=#
-tps.connector.kra1._004=# tps.connector.kra<n>.enable:
-tps.connector.kra1._005=#   - enable this connector or not
-tps.connector.kra1._006=# tps.connector.kra<n>.host:
-tps.connector.kra1._007=#   - for no Failover, host name of the KRA
-tps.connector.kra1._008=#   - for Failover setup, host name and port number
-tps.connector.kra1._009=#     of your KRA, format is host:port separated by a space
-tps.connector.kra1._010=# tps.connector.kra<n>.port:
-tps.connector.kra1._011=#   - for no Failover, port number of the KRA
-tps.connector.kra1._012=# tps.connector.kra<n>.nickName:
-tps.connector.kra1._013=#   - nickname of the TPS subsystem certificate for
-tps.connector.kra1._014=#     SSL client authentication to the KRA
-tps.connector.kra1._015=# tps.connector.kra<n>.minHttpConns:
-tps.connector.kra1._016=#   - minimum HTTP connections
-tps.connector.kra1._017=# tps.connector.kra<n>.maxHttpConns:
-tps.connector.kra1._018=#   - maximum HTTP connections
-tps.connector.kra1._019=# tps.connector.kra<n>.uri.<op>:
-tps.connector.kra1._020=#   - uri to contact KRA for the operation <op>
-tps.connector.kra1._021=#   - example ops: GenerateKeyPair, TokenKeyRecovery
-tps.connector.kra1._022=# tps.connector.kra<n>.timeout:
-tps.connector.kra1._023=#   - connection timeout
-tps.connector.kra1._024=#########################################
 tps.connector.kra1.enable=false
 tps.connector.kra1.host=[DRM_HOST]
 tps.connector.kra1.port=[DRM_PORT]
@@ -1551,39 +1503,6 @@ tps.connector.kra1.nickName=[HSM_LABEL]:[NICKNAME]
 tps.connector.kra1.timeout=30
 tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair
 tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
-tps.connector.tks1._001=#########################################
-tps.connector.tks1._002=# TKS connector
-tps.connector.tks1._003=#
-tps.connector.tks1._004=# tps.connector.tks<n>.enable:
-tps.connector.tks1._005=#   - enable this connector or not
-tps.connector.tks1._006=# tps.connector.tks<n>.host:
-tps.connector.tks1._007=#   - for no Failover, host name of the TKS
-tps.connector.tks1._008=#   - for Failover setup, host name and port number
-tps.connector.tks1._009=#     of your TKS, format is host:port separated by a space
-tps.connector.tks1._010=# tps.connector.tks<n>.port:
-tps.connector.tks1._011=#   - for no Failover, port number of the TKS
-tps.connector.tks1._012=# tps.connector.tks<n>.nickName:
-tps.connector.tks1._013=#   - nickname of the TPS subsystem certificate for
-tps.connector.tks1._014=#     SSL client authentication to the TKS
-tps.connector.tks1._015=# tps.connector.tks<n>.minHttpConns:
-tps.connector.tks1._016=#   - minimum HTTP connections
-tps.connector.tks1._017=# tps.connector.tks<n>.maxHttpConns:
-tps.connector.tks1._018=#   - maximum HTTP connections
-tps.connector.tks1._019=# tps.connector.tks<n>.uri.<op>:
-tps.connector.tks1._020=#   - uri to contact TKS for the operation <op>
-tps.connector.tks1._021=#   - example ops: computeRandomData, computeSessionKey,
-tps.connector.tks1._022=#                  createKeySetData, encryptData
-tps.connector.tks1._023=# tps.connector.tks<n>.timeout:
-tps.connector.tks1._024=#   - connection timeout
-tps.connector.tks1._025=# tps.connector.tks<n>.generateHostChallenge:
-tps.connector.tks1._026=#   - generate host challenge or not
-tps.connector.tks1._027=# tps.connector.tks<n>.serverKeygen:
-tps.connector.tks1._028=#   - generate keys on server side or not
-tps.connector.tks1._029=# tps.connector.tks<n>.keySet:
-tps.connector.tks1._030=#   - keySet to be used on tks
-tps.connector.tks1._031=# tps.connector.tks<n>.tksSharedSymKeyName
-tps.connector.tks1._032=#   - shared secret key name
-tps.connector.tks1._033=#########################################
 tps.connector.tks1.enable=false
 tps.connector.tks1.host=[TKS_HOST]
 tps.connector.tks1.port=[TKS_PORT]
diff --git a/specs/pki-core.spec b/specs/pki-core.spec
index 65a15425371c7a2160d2c8be1d405cabc6f6097c..7b5950cbf534941dfd447f08f5a678661759e0bf 100644
--- a/specs/pki-core.spec
+++ b/specs/pki-core.spec
@@ -1001,6 +1001,7 @@ fi
 %{_datadir}/pki/tps/conf/
 %{_datadir}/pki/tps/setup/
 %{_datadir}/pki/tps/webapps/
+%{_mandir}/man5/pki-tps-connector-config.5.gz
 
 %if %{with javadoc}
 %files -n pki-javadoc
-- 
1.8.4.2

