-
Notifications
You must be signed in to change notification settings - Fork 139
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add pkispawn EST deployment documentation
- Loading branch information
Showing
4 changed files
with
527 additions
and
152 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| <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" | ||
| --------------------------- | ||
| 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://<EST_HOSTNAME>:<EST_PORT>/.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://<EST_HOSTNAME>:<EST_PORT>/.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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <<EOF | ||
| class=org.dogtagpki.est.DogtagRABackend | ||
| url=https://$(hostname):8443 | ||
| profile=estServiceCert | ||
| username=est-ra-1 | ||
| password=est4ever | ||
| 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/local/libexec/estauthz | ||
| EOF | ||
| ``` | ||
|
|
||
| The executable should exist and have the right permission. Here an example: | ||
|
|
||
| ``` | ||
| # 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 | ||
| ``` | ||
|
|
||
| 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: | ||
|
|
||
| ``` | ||
| # 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 | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| Verifying EST | ||
| ----------------------------- | ||
|
|
||
| Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*. | ||
|
|
||
|
|
||
| ``` | ||
| $ 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). | ||
| This page has been converted/moved to [Installing_EST.adoc](../est/Installing_EST.adoc) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <<EOF | ||
| class=org.dogtagpki.est.DogtagRABackend | ||
| url=https://$(hostname):8443 | ||
| profile=estServiceCert | ||
| username=est-ra-1 | ||
| password=password4ESTUser | ||
| EOF | ||
| ``` | ||
|
|
||
| Note: to use TLS mutual authentication instead of _username/password_, one needs to: | ||
|
|
||
| * get issuance for a TLS client certificate from the CA, using the EST | ||
| instance’s crypto token for generating keys and CSR in the instance | ||
| alias directory; | ||
| * import the certificate into the EST instance’s crypto token; | ||
| * assign the nickname to the parameter _nickname_ (leave out _username_ and _password_); | ||
| * in addition, add the certificate to the EST RA user account on the CA. | ||
| An example on how to get the certificate and configure EST with TLS | ||
| mutual configuration is provided in the `pkispawn` installation guide | ||
| xref:../est/Installing_EST_pkispawn.adoc#installation-on-separate-instance-with-certificates[here]. | ||
|
|
||
| Configure request authorization. The class | ||
| `org.dogtagpki.est.ExternalProcessRequestAuthorizer` allows to | ||
| delegate the authorization to an external process configured with the | ||
| parameter *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 in this example performs a simple check of the user role and it | ||
| is available link:/base/est/bin/estauthz[here]. It can be replaced if a | ||
| more sophisticated authorization framework has to be adopted. | ||
|
|
||
|
|
||
| Deploy the EST application: | ||
|
|
||
| ``` | ||
| # pki-server est-deploy | ||
| ``` | ||
|
|
||
| Configure the authentication. The authentication allows one 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 | ||
| ``` | ||
|
|
Oops, something went wrong.