Add pkispawn EST deployment documentation #4866

fmarco76 · 2024-09-30T13:48:23Z

The documentation is updated to match the configuration in the new CI workflow for EST using pkispawn.

Almost all operation are performed by pkispawn but the user and profile for EST need to be created in advance.

edewata

Please see my comments below. My main concern is that sometimes we introduce a new information (e.g. estUser) without explaining how to set it up, so it might be difficult for users to follow, but if you prefer we can address that in a separate PR later. Or if the doc still requires a lot of development, we can write it in the wiki first, then when it's ready we can just import it into the source repository.

edewata · 2024-09-30T14:11:16Z

docs/installation/est/Installing_EST.md


-Overview
--------
+## Overview

 This page describes the process to install a *EST subsystem*.


I'd suggest changing this to an EST.

@edewata did you just mean to correct the 'a' before "EST subsystem" (so it reads "an EST subsystem"), or did you mean to correct the 'a' AND suggest to remove the word "subsystem" too (so it reads "an EST")? I think we have called other subsystems with the word "subsystem" at many places.

Yes, I meant an EST subsystem.

edewata · 2024-09-30T14:17:49Z

docs/installation/est/Installing_EST.md

-EST Subsystem Installation
--------------------------
-Install the *EST subsystem* via dnf command.
+Finally, install the *EST subsystem* via dnf command.

 ```
 # dnf install dogtag-pki-est


Generally package installations should be done first before creating/configuring the instances since these tasks might be done by different people with different roles.

The operation above are not related to the EST instance itself but to the CA. In any case I moved this before so it will be the first operation.

edewata · 2024-09-30T14:23:48Z

docs/installation/est/Installing_EST.md


 This page describes the process to install a *EST subsystem*.


-Prerequisite
--------------------------
+## Prerequisite


There's an issue with the commands in this section. There's no instruction how to set up the NSS database in nssdb folder. Should we just use the default NSS database in ~/.dogtag/nssdb and remove the -d nssdb -c 4me2Test from the doc?

edewata · 2024-09-30T14:26:08Z

docs/installation/est/Installing_EST_pki-server.md

+# EST installation using `pki-server`
+
+After the prerequisite in [Installing
+EST](Installing_EST.md), it is possible to installa **EST**.


Typo: installa

edewata · 2024-09-30T14:33:08Z

docs/installation/est/Installing_EST_pki-server.md

+```
+# cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF
+class=org.dogtagpki.est.DogtagRABackend
+url=https://$(hostname):8443


The $(hostname) might be confusing since IIUC we do not support command substitution like in shells, so I'd suggest to use something like <hostname> which indicates that it needs to be replaced with a real hostname, or just put a sample hostname (e.g. ca.example.com).

Actually this is a cat command and not the file so there is shell substitution so it is possible to cut&paste. If I change with <hostname> then it need to be edited.

edewata · 2024-09-30T14:48:38Z

docs/installation/est/Installing_EST_pkispawn.md

+## REALM user DB
+
+
+**EST** subsystem has its own realm authtnetication with a separate


Typo: authtnetication

edewata · 2024-09-30T14:51:08Z

docs/installation/est/Installing_EST_pkispawn.md

+$ pkispawn \
+ -f /usr/share/pki/server/examples/installation/est.cfg \
+ -s EST \
+ -D est_realm_url=ldap://ds.example.com:3389 \


Should this be estds.example.com?

edewata · 2024-09-30T14:58:18Z

docs/installation/est/Installing_EST_pkispawn.md

+To remove the EST subsystem it is possible to use the `pkidestroy` command as follow:
+
+```
+pkidestroy -i pki-tomcat -s CA -v


Should this be pkidestroy -s EST? The -i and -v are optional, but it's ok to include.

the -v is in all commands. I am removing the -i

edewata · 2024-09-30T15:00:44Z

docs/installation/est/Installing_EST_pkispawn.md

+ -D est_ca_user_certificate=estUser \
+ -D pki_server_pkcs12_path=$SHARED/est_server.p12 \
+ -D pki_server_pkcs12_password=Secret.123 \


We probably should explain how to create the estUser and est_server.p12, maybe in a separate section or a separate doc. The $SHARED should not be included since it's only available in the CI.

I am adding a note but if it is not clear then it is better to move and add just a link

edewata · 2024-09-30T15:02:13Z

docs/installation/est/Installing_EST_pkispawn.md

+ -D pki_cert_chain_path=ca_signing.crt \
+ -D pki_cert_chain_nickname=caSigning \


We probably should explain how to get the ca_signing.crt.

ladycfu · 2024-09-30T16:10:41Z

docs/installation/est/Installing_EST.md


 This page describes the process to install a *EST subsystem*.


-Prerequisite
--------------------------
+## Prerequisite

 Create a Dogtag user group for EST RA accounts (**EST RA Agents**), and an EST RA


To avoid confusion, I'd start with "On the CA," so it reads "On the CA, create a Dogtag user group for the EST RA accounts ..."

Also, for the pki commands below, it's best not to assume the defaults on user's command line, because if they happen to use something different, it might frustrate them to have to dig up the information on their own. Perhaps add a note at the top that says something like "The commands below assumes that the default host and port number of the CA are the local host and 8443 (correct me if I'm wrong). To specify a different host and port number, use -h and -p respectively. It is also assumed that the nssdb is under ~/.dogtag/nssdb (to reflect @edewata 's suggestion above). To specify a different nssdb path, use -d"

Also (sorry I can't seem to add comment to the exact line below) for the EST profile, estServerCert.cfg already exists in the CA, so we just need to enable it (maybe with some edits, such as AIA), isn't it?

@ladycfu I think you are right although in all the tests I have done I always add the profile and do not get any warning like "The profile already exist!". I'll remove the add and double check with the CI.

@ladycfu I did a test and it is not included in the default profile available with the CA so it need to be added explicitly. At least using the master branch and I think it should be the same for other branches so I am leaving this step.

ladycfu · 2024-09-30T17:03:00Z

docs/installation/est/Installing_EST.md

-password=est4ever
-EOF
-```
+There are two options for the installation:


Is there any advantage to pki-server that we want to continue providing it as an option?

In general the pki-server tool provides more control over the installation process (i.e. fine-grained installation). If something fails, it can be fixed immediately, then the installation can resume from that point. With pkispawn it's all or nothing. pkispawn does many things at once so all params must be set correctly at the beginning. If something fails, usually you'd have to clean up the environment and start over from the beginning. This could be problematic if pkispawn leaves many orphan keys in HSM or starts replicating a huge database.

Also for containers we don't want to do everything that pkispawn does, so pki-server tool provides a mechanism to do what's needed for containers.

I think for the primary EST doc we could suggest users to use pkispawn, but we should keep the EST doc using pki-server if they need more control over the installation process.

@edewata Thanks for the clarification. Yes I think we should keep both options available, but perhaps add the explanation to help with choices?

I was thinking the main EST install doc should just use pkispawn, but we also provide a link that says something like "Manual EST Installation" or "Advanced EST Installation" to another doc using pki-server. We can include the above explanation in that other doc. This way the user won't be forced to read, understand the differences, then make a choice before they can start the installation, but they can try pkispawn with the sample config files first (which is what most people want to do initially), then if it's not enough they can try pki-server. What do you think?

ladycfu · 2024-09-30T17:40:30Z

docs/installation/est/Installing_EST_pkispawn.md

+
+
+**EST** subsystem has its own realm authtnetication with a separate
+user DB. Out of the box *LDAP*, *PostreSQL* and file based DB are


I jumped directly from "Using pkispawn here", I don't see any mention for an ldap instance to be created. Did I miss a step in the jump?

It is in the subsection. Should I move it?

@fmarco76 which subsection?

I was thinking the one below from line 14. But reading again your comment maybe you want the DS installation steps, not just the how the ldap tree should be populated. Should I include the step to create the instance? (And the same for postegresql?)

before you can do line 14 and on, you want to mention that a DS instance needs to be created. I think there already is a page for that which you can link to. See an example from the 2nd paragraph of Overview here : https://github.com/dogtagpki/pki/blob/master/docs/installation/ca/Installing_CA.md

ladycfu · 2024-09-30T21:25:27Z

docs/installation/est/Installing_EST_pkispawn.md

+provided in order to retrieve the user information from the DB.
+
+
+## Installation


Is this section supposed to be for installing on the same instance, or does it contain something that shared with the installation on separate instance? It is currently one level above ### Installation on separate instance.

The content of this section applies to both cases: same or separate instance. However, in the second case there are a couple of additional steps to get the CA and SSL certificates.

ladycfu · 2024-09-30T21:56:05Z

docs/installation/est/Installing_EST_pkispawn.md

+pki-server cert-export ca_signing --cert-file ca_signing.crt
+```
+
+EST will get the SSL server certificate through the EST provided user


I'm reading this comment a few times and have to make a guess. Please verify my understanding. This paragraph is saying that without the two pkcs12 related parameters, pkispawn will get the EST's server cert automatically issued by using the estServerCert (the default name, which is hard-coded?) profile. And if one wishes to use a pre-generated server cert/keys, then supply its p12 and passwd as stated in the pkcs12 params.

@ladycfu your guess is correct. If it is not provided with a p12 then it will try to get a certificate using the EST credentials and profile which are not hard-coded but they are parameter (est_ca_profile and est_ca_user_*). Currently we do not support multiple profiles although the specification allows to include a label in a request which could be used to select different CAs (or profiles I think).

@fmarco76 got it! In that case, I suggest a little clarification. Maybe something like "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 could be pre-issued prior to pkispawn with its full chain in PKCS#12 bundle supplied via the pki_server_pkcs12_ parameters on the pkispawn command line as exemplified below. It is important tha tthe certificate aliases ..."

ladycfu

See comments. I skipped over the pki-server installation method.

ladycfu

one more comment

ladycfu · 2024-10-01T16:27:23Z

docs/installation/est/Installing_EST_pkispawn.md

+ -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 \


@fmarco76 looks like you updated while I was typing up the following: Just realized that I missed the "(and the user certificate if it is needed to connect to the CA)" part in my suggestion clarification. So the est_ca_user_* are for client cert talking to the CA then? Which profile is it using (which parameter in pkispawn cfg?)? As for it's alternative, I see in the example below, est_ca_user_password and est_ca_user_certificate are supplied, but it doesn't seem to point to any p12. How does it work?

So the est_ca_user_* are for client cert talking to the CA then?

These parameter are to configure the CA user for EST communication. This is created in the prerequisite described in the main installation document and added here.

Which profile is it using (which parameter in pkispawn cfg?)

The profile is defined with the option est_ca_profile (line 107) and default it is estServiceCert.

As for it's alternative, I see in the example below, est_ca_user_password and est_ca_user_certificate are supplied, but it doesn't seem to point to any p12. How does it work?

est_ca_user_certificate is the name of the certificate to use inside the nssdb of the instance. est_ca_user_password is empty to be sure it is not used but if both are provided I think the certificate has precedence but it is in the EST code so I should verify.

@fmarco76 sorry I'm still a bit lost. Sounds like you are saying that the EST server cert and the EST client cert (the one to be associated with the est user in the CA agent group) are using the same enrollment profile (I hope not), estServerCert? Oh wait, you said estServiceCert. So there are two profiles, one being estServerCert (the one for server) and the other being estServiceCert (the one for client)? I could see how the EST server cert is being issued, either via the default set in est_ca_profile=, or by pkispawn command line -D pki_server_pkcs12_*, but I still don't get how the EST client cert (for talking to the ca) got issued. Unless I missed it, I do not see it being instructed to be issued in the prerequisite section. Could you please point to me where that is?

sonarcloud · 2024-10-01T16:39:30Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

ladycfu · 2024-10-01T17:34:42Z

docs/installation/est/Installing_EST.md


 ```
-# pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg
+# pki -n caadmin ca-profile-add --raw estServerCert.cfg


this says "estServerCert.cfg"

ladycfu · 2024-10-01T17:35:31Z

docs/installation/est/Installing_EST.md


 ```
-# 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
 ----------------------------


and this is estServiceCert". So that's two profiles?

fmarco76 requested review from edewata and ladycfu September 30, 2024 13:48

edewata reviewed Sep 30, 2024

View reviewed changes

ladycfu reviewed Sep 30, 2024

View reviewed changes

fmarco76 force-pushed the EST_doc branch from b1135e3 to 0acfdc8 Compare September 30, 2024 19:10

ladycfu reviewed Sep 30, 2024

View reviewed changes

fmarco76 force-pushed the EST_doc branch 2 times, most recently from 6c8d214 to 98cf1e5 Compare October 1, 2024 10:05

fmarco76 requested review from edewata and ladycfu October 1, 2024 10:06

fmarco76 force-pushed the EST_doc branch from 98cf1e5 to 9335048 Compare October 1, 2024 16:24

ladycfu reviewed Oct 1, 2024

View reviewed changes

Add pkispawn EST deployment documentation

4c45118

fmarco76 force-pushed the EST_doc branch from 9335048 to 4c45118 Compare October 3, 2024 14:18

		## REALM user DB


		EST subsystem has its own realm authtnetication with a separate

		-D pki_cert_chain_path=ca_signing.crt \
		-D pki_cert_chain_nickname=caSigning \



		EST subsystem has its own realm authtnetication with a separate
		user DB. Out of the box LDAP, PostreSQL and file based DB are

		provided in order to retrieve the user information from the DB.


		## Installation

Add pkispawn EST deployment documentation #4866

Are you sure you want to change the base?

Add pkispawn EST deployment documentation #4866

Conversation

fmarco76 commented Sep 30, 2024

edewata left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

edewata Sep 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ladycfu left a comment

Choose a reason for hiding this comment

ladycfu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fmarco76 Oct 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sonarcloud bot commented Oct 1, 2024

Quality Gate passed

Choose a reason for hiding this comment

Choose a reason for hiding this comment

edewata Sep 30, 2024 •

edited

Loading

fmarco76 Oct 1, 2024 •

edited

Loading