From 93350484f9c3337bec738d51f400a689c3037a65 Mon Sep 17 00:00:00 2001
From: Marco Fargetta <mfargett@redhat.com>
Date: Mon, 30 Sep 2024 12:05:15 +0200
Subject: [PATCH] Add pkispawn EST deployment documentation

---
 docs/installation/est/Installing_EST.md       | 138 ++++-------
 .../est/Installing_EST_pki-server.md          |  74 ++++++
 .../est/Installing_EST_pkispawn.md            | 227 ++++++++++++++++++
 3 files changed, 346 insertions(+), 93 deletions(-)
 create mode 100644 docs/installation/est/Installing_EST_pki-server.md
 create mode 100644 docs/installation/est/Installing_EST_pkispawn.md

diff --git a/docs/installation/est/Installing_EST.md b/docs/installation/est/Installing_EST.md
index 33d3e97c6de..a7acf26cd07 100644
--- a/docs/installation/est/Installing_EST.md
+++ b/docs/installation/est/Installing_EST.md
@@ -1,19 +1,29 @@
-Installing EST
-==============
+# Installing EST
 
-Overview
---------
+## Overview
 
-This page describes the process to install a *EST subsystem*.
+This page describes the process to install an *EST subsystem*.
+
+The *EST subsystem* requires the package `dogtag-pki-est` installed in the server which will run the instance:
+
+```
+# dnf install dogtag-pki-est
+```
 
 
-Prerequisite
---------------------------
 
-Create a Dogtag user group for EST RA accounts (**EST RA Agents**), and an EST RA
+## Prerequisite
+
+On the CA, create a user group for EST RA accounts (**EST RA Agents**), and an EST RA
 account (**est-ra-1**). The EST subsystem will use this account to authenticate to
 the CA subsystem and issue certificates on behalf of EST clients.
 
+Note: the commands below assumes that the CA is running in the same host on
+the default port and the nssdb is located in `~/.dogtag/nssdb`. To
+point to a CA in a different host or with a different port use the options `-h
+<hostname>`, `-p <port_number>` or `-U <CA_uri`. To use a different
+nssdb use the option `-d <nssdb_path>`.
+
 ```
 # pki -n caadmin ca-group-add "EST RA Agents"
 ---------------------------
@@ -22,23 +32,23 @@ Added group "EST RA Agents"
   Group ID: EST RA Agents
 
 # pki -n caadmin ca-user-add \
-      est-ra-1 --fullName "EST RA 1" --password ************
+      est-ra-1 --fullName "EST RA 1" --password password4ESTUser
 ---------------------
 Added user "est-ra-1"
 ---------------------
   User ID: est-ra-1
   Full name: EST RA 1
-# pki -d nssdb -c 4me2Test -n caadmin ca-group-member-add "EST RA Agents" est-ra-1
+# pki -n caadmin ca-group-member-add "EST RA Agents" est-ra-1
 -----------------------------
   Added group member "est-ra-1"
 -----------------------------
   User: est-ra-1	    
 ```
 
-Add the EST profile `estServerCert.cfg` (it is available in `/usr/share/pki/ca/profiles/ca`):
+Add and enable the EST profile `estServerCert.cfg` (it is available in `/usr/share/pki/ca/profiles/ca`):
 
 ```
-# pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg
+# pki -n caadmin ca-profile-add --raw estServerCert.cfg
 ----------------------------
 Added profile estServiceCert
 ----------------------------
@@ -48,105 +58,47 @@ Enabled profile "estServiceCert"
 --------------------------------
 ```
 
+Note: before enable the profile verify if the options satisfy the requirement for the deployment.
 
-EST Subsystem Installation
---------------------------
-Install the *EST subsystem* via dnf command.
-
-```
-# dnf install dogtag-pki-est
-```
-
-Create the *EST subsytem* inside the pki server instance:
-
-```
-# pki-server est-create
-```
-
-Configure the issuance backend. The class `org.dogtagpki.est.DogtagRABackend` is used for the *Dogtag CA*. This requires:
 
-- the **url** parameter pointing to the CA subsystem;
-- credentials of an RA account, **username** and **password**, that is authorised to issue certificates using the configured profile;
-  - is also possible to use TLS client certificate authentication to authenticate to the CA subsystem.
-- the **profile**.
+## EST Subsystem Installation
 
+There are two options for the installation:
+- Basic installation with `pkispawn` [here](./Installing_EST_pkispawn.md);
 
-```
-# cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF
-class=org.dogtagpki.est.DogtagRABackend
-url=https://$(hostname):8443
-profile=estServiceCert
-username=est-ra-1
-password=est4ever
-EOF
-```
+- Advanced installation with `pki-server`
+  [here](./Installing_EST_pki-server.md), which require more manual
+  configuration but provides more control over the installation
+  process since each step can be verified and eventually customised
+  and repeated.
 
-Configure request authorization. The class `org.dogtagpki.est.ExternalProcessRequestAuthorizer` allows to delegate the authorization to an external process configured with the paramter **executable**:
 
-```
-# cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF
-class=org.dogtagpki.est.ExternalProcessRequestAuthorizer
-executable=/usr/local/libexec/estauthz
-EOF
-```
 
-The executable should exist and have the right permission. Here an example:
+## Verifying EST
 
-```
-# cat >/usr/local/libexec/estauthz <<EOF
-#!/usr/bin/python3
-import json, sys
-ALLOWED_ROLE = 'estclient'
-obj = json.loads(sys.stdin.read())
-if not ALLOWED_ROLE in obj['authzData']['principal']['roles']:
-    print(f'Principal does not have required role {ALLOWED_ROLE!r}')
-    sys.exit(1)
-EOF
-# chmod +x /usr/local/libexec/estauthz
-	
-```
-
-Deploy the EST application:
-
-```
-# pki-server est-deploy
-```
+Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*.
 
-Configure the authentication. The authentication is build on `com.netscape.cms.tomcat.ProxyRealm` class which allows to use realms from *tomcat* or developed for dogtag. As an example we use an in memory realm:
+The following command will print the CA signing certificate obtained from the server:
 
 ```
-# cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <<EOF
-class=com.netscape.cms.realm.PKIInMemoryRealm
-username=alice
-password=4me2Test
-roles=estclient
-EOF
-```
+$ curl --cacert ./ca_signing.crt  https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/cacerts | openssl base64 -d | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
 
-Finally, restart the server:
-
-```
-# pki-server restart --wait
 ```
+Replace `$EST_HOSTNAME` and `$EST_PORT` with the hostname and port of the *EST subsystem*, respectively.
 
+If successful, the server CA certificate chain will be printed on standard output and the command will exit with status 0 (success).
 
 
-Verifying EST
------------------------------
-
-Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*.
-
+To test the enrollment using curl, generate a CSR and submit using a user from the EST user DB associated to the realm. The following command will perform the enrollment and print the final certificate::
 
 ```
-$ curl https://$EST_HOSTNAME:$EST_PORT/.well-known/est/cacerts
-HTTP/1.1 200
-Content-Type: application/pkcs7-mime
-Transfer-Encoding: chunked
-Date: Tue, 26 Jul 2022 05:47:49 GMT
+$ pki nss-cert-request --csr testServer.csr \
+    --ext /usr/share/pki/server/certs/sslserver.conf --subject 'CN=test.example.com'
+$ openssl req -in testServer.csr -outform der | openssl base64 -out testServer.p10
 
-<...certificate base64…>
+$ curl --cacert ./ca_signing.crt --anyauth -u est-test-user:Secret.123 \
+    --data-binary @testServer.p10 -H "Content-Type: application/pkcs10" \
+    -o newCert.p7 https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/simpleenroll
+$ openssl base64 -d -in newCert.p7 | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
 
 ```
-Replace `$EST_HOSTNAME` and `$EST_PORT` with the hostname and port of the *EST subsystem*, respectively.
-
-If successful, the server CA certificate chain will be printed on standard output and the command will exit with status 0 (success).
diff --git a/docs/installation/est/Installing_EST_pki-server.md b/docs/installation/est/Installing_EST_pki-server.md
new file mode 100644
index 00000000000..4517aa9b104
--- /dev/null
+++ b/docs/installation/est/Installing_EST_pki-server.md
@@ -0,0 +1,74 @@
+# EST installation using `pki-server`
+
+After the prerequisite in [Installing EST](Installing_EST.md), it is
+possible to install **EST**.
+
+An instance has to be already available, if it is not present then it
+is possible to create a new one with `pki-server create`, more details
+[here](https://github.com/dogtagpki/pki/wiki/PKI-Server-Create-CLI).
+
+
+Create the *EST subsytem* inside the pki server instance:
+
+```
+# pki-server est-create
+```
+
+Configure the issuance backend. The class `org.dogtagpki.est.DogtagRABackend` is used for the *Dogtag CA*. This requires:
+
+- the **url** parameter pointing to the CA subsystem;
+- credentials of an RA account, **username** and **password**, that is authorised to issue certificates using the configured profile;
+  - is also possible to use TLS client certificate authentication to authenticate to the CA subsystem.
+- the **profile**.
+
+
+```
+# cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF
+class=org.dogtagpki.est.DogtagRABackend
+url=https://$(hostname):8443
+profile=estServiceCert
+username=est-ra-1
+password=password4ESTUser
+EOF
+```
+
+Configure request authorization. The class
+`org.dogtagpki.est.ExternalProcessRequestAuthorizer` allows to
+delegate the authorization to an external process configured with the
+paramter **executable**:
+
+```
+# cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF
+class=org.dogtagpki.est.ExternalProcessRequestAuthorizer
+executable=/usr/share/pki/est/bin/estauthz
+EOF
+```
+
+The executable script perform a simple check of the user role and it
+is available [here](/base/est/bin/estauthz). It can be replaced if
+more complex authorization framework has to be adopted.
+
+
+Deploy the EST application:
+
+```
+# pki-server est-deploy
+```
+
+Configure the authentication. The authentication allows to use realms from *tomcat* or developed for dogtag. As an example we use an in memory realm:
+
+```
+# cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <<EOF
+class=com.netscape.cms.realm.PKIInMemoryRealm
+username=alice
+password=4me2Test
+roles=estclient
+EOF
+```
+
+Finally, restart the server:
+
+```
+# pki-server restart --wait
+```
+
diff --git a/docs/installation/est/Installing_EST_pkispawn.md b/docs/installation/est/Installing_EST_pkispawn.md
new file mode 100644
index 00000000000..1121dbb3eda
--- /dev/null
+++ b/docs/installation/est/Installing_EST_pkispawn.md
@@ -0,0 +1,227 @@
+# EST installation using `pkispawn`
+
+After the prerequisite in [Installing
+EST](Installing_EST.md), it is possible to install **EST**.
+
+## REALM user DB
+
+
+**EST** subsystem has its own realm authentication with a separate
+user DB. Out of the box *LDAP*, *PostreSQL* and file based DB are
+supported. User management is currently not performed by the subsystem
+so the DB has to be prepared in advance.
+
+### LDAP based DB
+
+Before adding users, please ensure that you have configured the
+directory server and added base entries. The step is described
+[here](https://github.com/dogtagpki/pki/wiki/DS-Installation).
+
+The user DB requires a node containing the users (*inetOrgPerson*) and
+a node containing the groups (*groupOfUniqueNames*). Therefore, if
+the base dn is like `dc=pki,dc=example,dc=com` it is possible create a
+tree with a user using the command:
+
+```
+ldapadd -x -H ldap://estds.example.com:3389 \
+    -D "cn=Directory Manager"  -w Secret.123 << EOF
+dn: dc=est,dc=pki,dc=example,dc=com
+objectClass: domain
+dc: est 
+          
+dn: ou=people,dc=est,dc=pki,dc=example,dc=com
+ou: people
+objectClass: top
+objectClass: organizationalUnit
+          
+dn: ou=groups,dc=est,dc=pki,dc=example,dc=com
+ou: groups
+objectClass: top
+objectClass: organizationalUnit
+          
+dn: uid=est-test-user,ou=people,dc=est,dc=pki,dc=example,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+uid: est-test-user
+sn: EST TEST USER
+cn: EST TEST USER
+userPassword: Secret.123
+
+dn: cn=estclient,ou=groups,dc=est,dc=pki,dc=example,dc=com
+objectClass: top
+objectClass: groupOfUniqueNames
+cn: estclient
+uniqueMember: uid=est-test-user,ou=People,dc=est,dc=pki,dc=example,dc=com
+EOF
+```
+
+### PostgreSQL based DB
+
+First, prepare a database (e.g. est) and a user (e.g. est) to access
+the database. Verify the database connection with the following
+command:
+
+To use the *PostreSQL* DB the user tables should be created with the
+sql file provided in
+`/usr/share/pki/est/conf/realm/postgresql/create.sql` and then filled
+with the user information. The tables can be created with the command:
+```
+$ psql -U est -t -A -f /tmp/create.sql est
+```
+Then fill the tables with the commands:
+```
+$ psql -U est -t -A -c "INSERT INTO users VALUES ('est-test-user', 'EST TEST USER', '<tomcat_digest>');"  est 
+$ psql -U est -t -A -c "INSERT INTO groups VALUES ('estclient', 'EST TEST USERS');"  est 
+$ psql -U est -t -A -c "INSERT INTO group_members VALUES ('estclient', 'est-test-user');"  est 
+```
+
+Note: the tomcat digest for the password can be obtained with the command:
+```
+$ tomcat-digest <user_password>
+```
+
+It is possible to use different schemas but in this case a custom
+`statements.conf` file (provided in the same folder) has to be
+provided in order to retrieve the user information from the DB.
+
+
+## Installation
+
+An example installation configuration is provided in
+`/usr/share/pki/server/examples/installation/est.cfg`. To install EST
+in the same instance of the CA and with the DS realm run the command:
+
+```
+# pkispawn \
+    -f /usr/share/pki/server/examples/installation/est.cfg \
+    -s EST \
+    -D est_realm_url=ldap://estds.example.com:3389 \
+    -v
+```
+
+The `est_realm_url` points to the user DB. The other configurations that could be modified according to the deployment are:
+
+```
+est_ca_profile=estServiceCert
+est_ca_user_name=
+est_ca_user_password=
+est_ca_user_password_file=
+est_ca_user_certificate=
+est_realm_type=
+est_realm_custom=
+est_realm_url=
+est_realm_auth_type=BasicAuth
+est_realm_bind_dn=cn=Directory Manager
+est_realm_bind_password=
+est_realm_nickname=
+est_realm_user=
+est_realm_username=
+est_realm_password=
+est_realm_users_dn=ou=people,dc=est,dc=pki,dc=example,dc=com
+est_realm_groups_dn=ou=groups,dc=est,dc=pki,dc=example,dc=com
+est_realm_statements=/usr/share/pki/est/conf/realm/postgresql/statements.conf
+est_authorizer_exec_path=/usr/share/pki/est/bin/estauthz
+```
+
+The `est_ca_*` provides information related to the user and profile
+configured in the CA for the EST subsystem.
+
+The `est_authorizer_exec_path` is the executable responsible to verify
+the authorisation. The provided script checks only that the user has
+the role *estclient*.
+
+The `est_realm_*` options allow to customise the realm. Possible types
+are: ds, postgresql and in-memory. As an example, to install EST with
+PostgreSQL the command will be
+
+```
+# pkispawn \
+    -f /usr/share/pki/server/examples/installation/est.cfg \
+    -s EST \
+    -D est_realm_url="jdbc:postgresql://postgresql.example.com:5432/est?ssl=true&sslmode=require" \
+    -D est_realm_type=postgresql \
+    -D est_realm_user=est \
+    -D est_realm_password=mysecretpassword \
+    -v
+```
+
+The `est_realm_custom` is a path to a custom realm configuration for
+tomcat and if provided it will overwrite all other realm related
+configurations.
+
+### Installation on separate instance
+
+When installed on a separate instance the CA URL and the signing
+certificate has to be provided. This is done with the command:
+
+```
+# pkispawn \
+    -f /usr/share/pki/server/examples/installation/est.cfg \
+    -s EST \
+    -D est_realm_url=ldap://estds.example.com:3389 \
+    -D pki_ca_uri=https://ca.example.com:8443 \
+    -D pki_cert_chain_path=ca_signing.crt \
+    -D pki_cert_chain_nickname=caSigning \
+    -v
+```
+
+Note: the CA signing certificate can be obtained with the following command in the CA server:
+```
+# pki-server cert-export ca_signing --cert-file ca_signing.crt
+```
+
+By default, the EST server cert will be issued based on the
+information provided via the `pkispawn` parameters `est_ca_profile`
+and `est_ca_user_*`.  Alternatively, the EST server cert (and the user
+certificate if it is needed to connect to the CA) could be pre-issued
+prior to `pkispawn` with its full chain in a **PKCS#12** bundle supplied
+via the `pki_server_pkcs12_*` parameters on the `pkispawn` command
+line as exemplified below. It is important that the certificate
+aliases in the PKCS#12 match with the nickname used by EST. For SSL
+certificate the nickname configured in `est.cfg` is `sslserver` but
+can be modified. The command to deploy with the certificate bundle is:
+
+```
+# pkispawn \
+    -f /usr/share/pki/server/examples/installation/est.cfg \
+    -s EST \
+    -D est_realm_url=ldap://estds.example.com:3389 \
+    -D pki_ca_uri=https://ca.example.com:8443 \
+    -D est_ca_user_password= \
+    -D est_ca_user_certificate=estUser \
+    -D pki_server_pkcs12_path=est_server.p12 \
+    -D pki_server_pkcs12_password=Secret.123 \
+    -v
+```
+
+Note: to create the PKCS12 with the certificate it is possible to
+generate a server certificate for EST in the CA (end eventually the
+user certificate) and then export them as in the following example:
+
+```
+# pki nss-cert-request --csr estSSLServer.csr \
+    --ext /usr/share/pki/server/certs/sslserver.conf --subject 'CN=est.example.com'
+
+# pki -n caadmin \
+    ca-cert-issue \
+    --csr-file estSSLServer.csr \
+    --profile caServerCert \
+    --output-file estSSLServer.crt
+
+# pki nss-cert-import --cert estSSLServer.crt sslserver
+
+# pki pkcs12-cert-import sslserver --pkcs12-file $SHARED/est_server.p12 --pkcs12-password Secret.123
+```
+
+## Removing EST
+
+To remove the EST subsystem it is possible to use the `pkidestroy` command as follow:
+
+```
+# pkidestroy -s CA -v
+```
+
+Note: the configuration and log folders are not removed. To remove
+everything add the the options: `--remove-conf` `--remove-logs`.