From 93350484f9c3337bec738d51f400a689c3037a65 Mon Sep 17 00:00:00 2001 From: Marco Fargetta 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 +`, `-p ` or `-U `. + ``` # 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 </var/lib/pki/pki-tomcat/conf/est/authorizer.conf </usr/local/libexec/estauthz </var/lib/pki/pki-tomcat/conf/est/realm.conf <:/.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://:/.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 </var/lib/pki/pki-tomcat/conf/est/authorizer.conf </var/lib/pki/pki-tomcat/conf/est/realm.conf <');" 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 +``` + +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`.