diff --git a/docs/installation/est/Installing_EST.md b/docs/installation/est/Installing_EST.md index 33d3e97c6de..5df12ec7cc6 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 + 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 `estServiceCert.cfg` (it is available in `/usr/share/pki/ca/profiles/ca` if the *dogtag-pki-ca* package is installed): ``` -# pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg +# pki -n caadmin ca-profile-add --raw /usr/share/pki/ca/profiles/ca/estServiceCert.cfg ---------------------------- Added profile estServiceCert ---------------------------- @@ -48,105 +58,48 @@ 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 -``` +## EST Subsystem Installation -Create the *EST subsytem* inside the pki server instance: +There are two options for the installation: +- Basic installation with `pkispawn` [here](./Installing_EST_pkispawn.md); -``` -# pki-server est-create -``` - -Configure the issuance backend. The class `org.dogtagpki.est.DogtagRABackend` is used for the *Dogtag CA*. This requires: +- 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. -- 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 </usr/local/libexec/estauthz <:/.well-known/est/cacerts | openssl base64 -d | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout ``` -# pki-server est-deploy -``` +Replace `$EST_HOSTNAME` and `$EST_PORT` with the hostname and port of the *EST subsystem*, respectively. -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: +If successful, the server CA certificate chain will be printed on standard output and the command will exit with status 0 (success). -``` -# cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <:/.well-known/est/simpleenroll - -Verifying EST ------------------------------ - -Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*. - +$ openssl base64 -d -in newCert.p7 | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout ``` -$ 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 - -<...certificate base64…> - -``` -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. + +Additionally, java driver for PostgreSQL need to be installed in the EST server and linked into library folder of pki: + +``` +# dnf install -y postgresql-jdbc +# ln -s /usr/share/java/postgresql-jdbc/postgresql.jar /usr/share/pki/server/common/lib +# ln -s /usr/share/java/ongres-scram/client.jar /usr/share/pki/server/common/lib +# ln -s /usr/share/java/ongres-scram/common.jar /usr/share/pki/server/common/lib +# ln -s /usr/share/java/ongres-stringprep/saslprep.jar /usr/share/pki/server/common/lib/ +# ln -s /usr/share/java/ongres-stringprep/stringprep.jar /usr/share/pki/server/common/lib/ +``` + +## 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 with certificates + +In addition to the above, installating EST in a separate instance +requires some extra steps to configure the certificates. + +The EST server cert (and a subsystem certificate to connect with the +CA) has to be pre-issued and provided 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. + +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 +``` + +Similarly, to generate a subsystem certificate for EST, associate to +the EST user previously configured in the CA, and add in the same +PKCS12 of the SSL server certificate: + +``` +# pki nss-cert-request --csr estUser.csr \ + --ext /usr/share/pki/server/certs/admin.conf \ + --subject 'CN=EST Subsystem Certificate,OU=pki-tomcat,O=EXAMPLE' + +# pki -n caadmin -cert-issue \ + --csr-file estUser.csr \ + --profile caSubsystemCert \ + --output-file estUser.crt + +# pki nss-cert-import --cert estUser.crt "EST subsystem cert" + +# pki -n caadmin ca-user-cert-add est-ra-1 --input estUser.crt + +# pki pkcs12-cert-import "EST subsystem cert" --pkcs12-file $SHARED/est_server.p12 --pkcs12-password Secret.123 --append +``` + + +Using the generate bundle, the command to deploy EST 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 +``` + + +### Installation on separate instance without certificates + +If the bundle certificates is not provided to `pkispawn`, during the installation, +the EST server cert will be issued like the certificates for EST clients using the configured profile. +In this case, beside the CA URL, it is needed only the CA signing certificate for the installation. +Retrieving the certificate can be done in the CA server with the command: + +``` +# pki-server cert-export ca_signing --cert-file ca_signing.crt +``` + +After moving the CA signing certificate to the EST server, it is possible to install EST with: + +``` +# 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 +``` + +After the installation it is recommended to update the EST nssdb certificates using proper profile. + +## 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`.