Allow use of secure LDAPS connection

- PKI TRAC Ticket #1144 - pkispawn needs option to specify ca cert for ldap

2 files changed, 78 insertions, 2 deletions

diff --git a/base/server/man/man5/pki_default.cfg.5 b/base/server/man/man5/pki_default.cfg.5
index a7706656b..1cf5c5134 100644
--- a/base/server/man/man5/pki_default.cfg.5
+++ b/base/server/man/man5/pki_default.cfg.5
@@ -169,6 +169,14 @@ Credentials to connect to the database during installation.  Directory Manager-l
 .IP
 Sets whether to require connections to the Directory Server using LDAPS.  This requires SSL to be set up on the Directory Server first.  Defaults to false.
 .PP
+.B pki_ds_secure_connection_ca_nickname
+.IP
+Once a Directory Server CA certificate has been imported into the PKI security databases (see \fBpki_ds_secure_connection_ca_pem_file\fP), \fBpki_ds_secure_connection_ca_nickname\fP will contain the nickname under which it is stored.  The \fBdefault.cfg\fP file contains a default value for this nickname.  This parameter is only utilized when \fBpki_ds_secure_connection\fP has been set to true.
+.PP
+.B pki_ds_secure_connection_ca_pem_file
+.IP
+The \fBpki_ds_secure_connection_ca_pem_file\fP parameter will consist of the fully-qualified path including the filename of a file which contains an exported copy of a Directory Server's CA certificate.  While this parameter is only utilized when \fBpki_ds_secure_connection\fP has been set to true, a valid value is required for this parameter whenever this condition exists.
+.PP
 .B pki_ds_remove_data
 .IP
 Sets whether to remove any data from the base DN before starting the installation.  Defaults to True.
diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
index fc50fd380..1d38b117a 100644
--- a/base/server/man/man8/pkispawn.8
+++ b/base/server/man/man8/pkispawn.8
@@ -136,8 +136,21 @@ setup the path where the admin certificate of this <subsystem> should be stored.
 \fIHostname:\fP
 Hostname of the directory server instance.  The default value is the hostname of the system.
 .TP
-\fIPort:\fP
-Port for the directory server instance. The default value is 389.
+\fIUse a secure LDAPS connection?\fP
+Answering yes to this question will cause prompts for \fISecure LDAPS Port:\fP and \fIDirectory Server CA certificate pem file:\fP.  Answering no to this question will cause a prompt for \fILDAP Port\fP.  The initial default value for this question is no.
+.TP
+\fISecure LDAPS Port:\fP
+Secure LDAPS port for the directory server instance. The default value is 636.
+.TP
+\fIDirectory Server CA certificate pem file:\fP
+The fully-qualified path including the filename of the file which contains an exported copy of the Directory Server's CA certificate (e. g. - /root/dscacert.pem).  This file must exist prior to \fBpkispawn\fP being able to utilize it.  For details on creation of this file see the
+.B EXAMPLES
+section below entitled
+.B Installing a CA connecting securely to a Directory Server via LDAPS.
+.
+.TP
+\fILDAP Port:\fP
+LDAP port for the directory server instance. The default value is 389.
 .TP
 \fIBase DN:\fP
 the Base DN to be used for the internal database for this subsystem. The default value is o=pki-tomcat-<subsystem>.
@@ -201,6 +214,7 @@ where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the follow
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -215,6 +229,7 @@ where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the follow
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -240,6 +255,7 @@ where \fImyconfig.txt\fP contains the following text:
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -267,6 +283,7 @@ where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the follow
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -294,6 +311,7 @@ where \fImyconfig.txt\fP contains the following text:
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -318,6 +336,7 @@ where \fImyconfig.txt\fP contains the following text:
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -346,6 +365,7 @@ In the first step, a certificate signing request (CSR) is generated for the sign
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -367,6 +387,7 @@ In the second step, the configuration file has been modified to install the issu
 .nf
 [DEFAULT]
 pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
 pki_client_pkcs12_password=\fIpassword123\fP
 pki_ds_password=\fIpassword123\fP
 pki_security_domain_password=\fIpassword123\fP
@@ -382,7 +403,54 @@ pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
 Then, the \fBpkispawn\fP command is run again:
 .PP
 .B pkispawn -s CA -f myconfig.txt
+.SS Installing a CA connecting securely to a Directory Server via LDAPS
+\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_database_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_ds_secure_connection=True
+pki_ds_secure_connection_ca_pem_file=\fI/root/dscacert.pem\fP
 
+[CA]
+pki_base_dn=\fIdc=example, dc=com\fP
+.fi
+.TP
+\fBImportant:\fP
+Although this example is specifically for a CA, the \fB[CA]\fP section may be replaced by the appropriate PKI subsystem (i. e. - \fb[KRA]\fP, \fb[OCSP]\fP, \fb[TKS]\fP, or \fb[TPS]\fP) being installed.  Additionally, if a KRA, OCSP, TKS, or TPS subsystem is being installed, they must also include the name/value pair \fBpki_security_domain_password=\fIpassword123\fP in the \fB[DEFAULT]\fP section.
+.PP
+Prior to running this command, a Directory Server instance must be configured to run securely over LDAPS using a self-signed certificate, and its self-signed CA certificate exported to a file so that it may be utilized by a PKI instance:
+.IP
+* \fBsetup-ds.pl\fP or \fBsetup-ds-admin.pl\fP
+.IP
+* \fB/usr/sbin/setupssl2.sh /etc/dirsrv/\fIslapd-pki\fP 389 636 \fIpassword123\fP
+.TP
+\fBNote:\fP
+The \fBsetupssl2.sh\fP script may be downloaded from \fBhttps://github.com/richm/scripts/blob/master/setupssl2.sh\fP.
+.IP
+* \fBsystemctl restart dirsrv.target\fP
+.IP
+* \fBcd /etc/dirsrv/\fIslapd-pki\fP
+.IP
+* \fB/usr/lib64/mozldap/ldapsearch -Z -h \fIpki.example.com\fP -p 636 -D 'cn=Directory Manager' -w \fIpassword123\fP -b \fI"dc=example, dc=com"\fP "objectclass=*"\fP
+.TP
+\fBNote:\fP
+The \fBmozldap ldapsearch\fP utility may be downloaded via running \fByum install mozldap-tools\fP.
+.IP
+* \fBcertutil -L -d /etc/dirsrv/\fIslapd-pki\fP -n "CA certificate" -a > \fI/root/dscacert.pem\fP
+.PP
+It should be noted that there are basically three scenarios in which a PKI subsystem (e. g. - a CA) needs to communicate securely via LDAPS with a directory server:
+.IP
+* A directory server exists which is already running LDAPS using a CA certificate that has been issued by some other CA.  For this scenario, the CA certificate must be made available via a PEM file during \fBpkispawn\fP installation/configuration such that the CA may be installed and configured to communicate with this directory server using LDAPS.
+.IP
+* A directory server exists which is currently running LDAP.  Once a CA has been created, there is a desire to use its CA certificate to issue an SSL certificate for this directory server so that this CA and this directory server can communicate via LDAPS.  For this scenario, since there is no need to communicate securely during the \fBpkispawn\fP installation/configuration, simply use \fBpkispawn\fP to install and configure the CA using the LDAP port of the directory server, issue an SSL certificate from this CA for the directory server, and then reconfigure the CA and directory server to communicate with each other via LDAPS.
+.IP
+* Similar to the previous scenario, a directory server exists which is currently running LDAP, and the desire is to create a CA and use it to establish LDAPS communications between this CA and this directory server.  However, for this scenario, there is a need for the CA and the directory server to communicate securely during \fBpkispawn\fP installation/configuration.  For this to succeed, the directory server must generate a temporary self-signed certificate for use during \fBpkispawn\fP installation/creation.  Once the CA has been created, swap things out to reconfigure the CA and directory server to utilize LDAPS through the desired certificates.  This example demonstrates the \fBpkispawn\fP portion of this particular scenario.
 .SS Execution management of a PKI instance (start, stop, status, etc.)
 .BR
 .PP