diff --git a/docs/installation/est/Installing_EST.adoc b/docs/installation/est/Installing_EST.adoc new file mode 100644 index 00000000000..b5cd50b1e05 --- /dev/null +++ b/docs/installation/est/Installing_EST.adoc @@ -0,0 +1,118 @@ +// this asciidoc file is converted from Installing_EST.md with needed modifications +// + += Installing EST = + +== Overview == + +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 == + +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 on the same host with +the default port and the nssdb is located in `~/.dogtag/nssdb`. To +point to a CA on a different host or with a different port use the options `-h +`, `-p ` or `-U `. + +``` +# pki -n caadmin ca-group-add "EST RA Agents" +--------------------------- +Added group "EST RA Agents" +--------------------------- + Group ID: EST RA Agents + +# pki -n caadmin ca-user-add \ + 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 -n caadmin ca-group-member-add "EST RA Agents" est-ra-1 +----------------------------- + Added group member "est-ra-1" +----------------------------- + User: est-ra-1 +``` + +Add and enable the EST enrollment profile `estServiceCert.cfg` (it is +available in `/usr/share/pki/ca/profiles/ca` if the *dogtag-pki-ca* +package is installed): + +``` +# pki -n caadmin ca-profile-add --raw /usr/share/pki/ca/profiles/ca/estServiceCert.cfg +---------------------------- +Added profile estServiceCert +---------------------------- +# pki -n caadmin ca-profile-enable estServiceCert +-------------------------------- +Enabled profile "estServiceCert" +-------------------------------- +``` + +Note: before enabling the profile verify if the options satisfy the requirement for the deployment. + + +## EST Subsystem Installation + +There are two options for the installation: + + * Basic installation with `pkispawn` + xref:../est/Installing_EST_pkispawn.adoc[Installing_EST_pkispawn]; + + * Advanced installation with `pki-server` + xref:../est/Installing_EST_pki-server.adoc[Installing_EST_pki-server], + which requires more manual configuration but provides more + control over the installation process since each step can be + verified and eventually customised and repeated. + + + +== Verifying EST == + +Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*. + +The following command will print the CA signing certificate obtained from the server: + +``` +$ curl --cacert ./ca_signing.crt https://:/.well-known/est/cacerts | openssl base64 -d | 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). + + +To test the enrollment using curl, generate a CSR and submit using a +user from the EST user DB associated with the realm. The following +commands will perform the enrollment and print the final certificate: + +``` +$ 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 + +$ 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 + +``` +Note: the `testServer.p10` file is a base64 encoded pkcs10 DER without header/footer. diff --git a/docs/installation/est/Installing_EST.md b/docs/installation/est/Installing_EST.md index 33d3e97c6de..de3bdfeac90 100644 --- a/docs/installation/est/Installing_EST.md +++ b/docs/installation/est/Installing_EST.md @@ -1,152 +1 @@ -Installing EST -============== - -Overview --------- - -This page describes the process to install a *EST subsystem*. - - -Prerequisite --------------------------- - -Create a Dogtag 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. - -``` -# pki -n caadmin ca-group-add "EST RA Agents" ---------------------------- -Added group "EST RA Agents" ---------------------------- - Group ID: EST RA Agents - -# pki -n caadmin ca-user-add \ - est-ra-1 --fullName "EST RA 1" --password ************ ---------------------- -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 ------------------------------ - 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`): - -``` -# pki -d nssdb -c 4me2Test -n caadmin ca-profile-add --raw estServerCert.cfg ----------------------------- -Added profile estServiceCert ----------------------------- -# pki -n caadmin ca-profile-enable estServiceCert --------------------------------- -Enabled profile "estServiceCert" --------------------------------- -``` - - -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**. - - -``` -# 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 < - -``` -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). +This page has been converted/moved to [Installing_EST.adoc](../est/Installing_EST.adoc) diff --git a/docs/installation/est/Installing_EST_pki-server.adoc b/docs/installation/est/Installing_EST_pki-server.adoc new file mode 100644 index 00000000000..598495289be --- /dev/null +++ b/docs/installation/est/Installing_EST_pki-server.adoc @@ -0,0 +1,92 @@ += EST installation using `pki-server` = + +After the prerequisite in xref:../est/Installing_EST.adoc[Installing EST], it is +possible to install *EST*. + +A PKI Tomcat instance has to be already available, if it is not present then it +is possible to create a new one with `pki-server create` (see more details +link:https://github.com/dogtagpki/pki/wiki/PKI-Server-Create-CLI[here]). + + +Create the _EST subsystem_ inside the pki server instance: + +``` +# pki-server est-create +``` + +Configure the issuance backend. The class +`org.dogtagpki.est.DogtagRABackend` is used for the EST instance to +communicate with the CA. This requires: + +* the _url_ parameter pointing to the CA subsystem; +* credentials of an EST RA account using either of the following methods that authorizes the account to request certificate issuance using the configured enrollment profile: + ** _username_ and _password_ if the EST RA account; + ** _TLS client certificate_ that belongs to the EST RA account. +* the enrollment _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 `pkispawn` installation configuration is provided in +`/usr/share/pki/server/examples/installation/est.cfg` with the following content: + +``` +[DEFAULT] +pki_server_database_password=Secret.123 +pki_admin_setup=False + +[EST] +est_realm_type=ds +est_realm_url=ldap://localhost.localdomain:389 +est_realm_bind_password=Secret.123 +est_ca_user_name=est-ra-1 +est_ca_user_password=Secret.est +pki_sslserver_nickname=sslserver +``` + +The following commands will install an EST subsystem on a PKI server +instance that already has a CA subsystem in it. By default the PKI +server instance is called `pki-tomcat` and it will use HTTP port `8080` +and HTTPS port `8443`. To use a different instance name or port numbers +please refer to the command's manual page. + +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:389 \ + -v +``` + +Note that 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 path to the executable +responsible for verifying the authorization. The default script +`estauthz` is a simple authorization example that checks only that the +user has the role _estclient_. + +The `est_realm_*` options allow one to customize 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 === + +EST can also be installed on a tomcat instance that’s separate from +the CA. + +In addition to the configuration above, installing EST in a separate instance +requires some extra steps to configure the certificates. + +Note: the commands below assumes that the CA is running on the same host with +the default port and the nssdb is located in `~/.dogtag/nssdb`. To +point to a CA on a different host or with a different port use the options `-h +`, `-p ` or `-U `. + +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 matches with +the nickname used by EST. For the 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 +request a server certificate for EST from the CA (and later the +RA user certificate) and then export them as exemplified below: + +``` +# 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 RA user (est-ra-1) previously configured in the CA, and add in the same +PKCS12 of the SSL server certificate: + +``` +# pki nss-cert-request --csr est-ra-1.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 est-ra-1.csr \ + --profile caSubsystemCert \ + --output-file est-ra-1.crt + +# pki nss-cert-import --cert est-ra-1.crt "est-ra-1" + +# pki -n caadmin ca-user-cert-add est-ra-1 --input est-ra-1.crt + +# pki pkcs12-cert-import "est-ra-1" --pkcs12-file $SHARED/est_server.p12 --pkcs12-password Secret.123 --append +``` + +Using the generated PKCS#12 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:389 \ + -D pki_ca_uri=https://ca.example.com:8443 \ + -D est_ca_user_password= \ + -D est_ca_user_certificate=est-ra-1 \ + -D pki_server_pkcs12_path=est_server.p12 \ + -D pki_server_pkcs12_password=Secret.123 \ + -v +``` + + +=== Installation on separate instance without certificates === + +If the PKCS#12 bundle certificates are not provided to `pkispawn`, +during the installation, the EST server cert will be issued +automatically. The connection with the CA uses the credentials +(_username/password_) provided in the configuration file and the +released certificate will be generated with the profile configured +for EST. In such a case the CA signing certificate is +needed. Retrieving the certificate can be done in the CA server with +the command: + +``` +# pki-server cert-export ca_signing --cert-file ca_signing.crt +``` + +It is possible to install EST with the following command: + +``` +# pkispawn \ + -f /usr/share/pki/server/examples/installation/est.cfg \ + -s EST \ + -D est_realm_url=ldap://estds.example.com:389 \ + -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 server +certificates with a new server certificate using a different +profile. Additionally, a certificate for TLS authentication could be +added in the EST nssdb and configured in the file +`/var/lib/pki/pki-tomcat/conf/est/backend.conf`. + +== Removing EST == + +To remove the EST subsystem it is possible to use the `pkidestroy` command as follow: + +``` +# pkidestroy -s EST -v +``` + +Note: the configuration and log folders are not removed. To remove +everything add the the options: `--remove-conf` `--remove-logs`.