Skip to content

Commit

Permalink
Add pkispawn EST deployment documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@fmarco76
fmarco76 committed Oct 1, 2024
1 parent eddb83b commit 9335048
Show file tree
Hide file tree
Showing 3 changed files with 346 additions and 93 deletions.
138 changes: 45 additions & 93 deletions docs/installation/est/Installing_EST.md
View file
Original file line number Diff line number Diff line change
@@ -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
<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"
---------------------------
Expand All @@ -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
----------------------------
Expand All @@ -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 <<EOF
class=org.dogtagpki.est.DogtagRABackend
url=https://$(hostname):8443
profile=estServiceCert
username=est-ra-1
password=est4ever
EOF
```
- 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.

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:
## Verifying EST

```
# 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
```
Use `curl` to verify that the *EST subsystem* is deployed and is able to communicate with the *CA subsystem*.

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:
The following command will print the CA signing certificate obtained from the server:

```
# cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <<EOF
class=com.netscape.cms.realm.PKIInMemoryRealm
username=alice
password=4me2Test
roles=estclient
EOF
```
$ 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
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://<EST_HOSTNAME>:<EST_PORT>/.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).
74 changes: 74 additions & 0 deletions docs/installation/est/Installing_EST_pki-server.md
View file
Original file line number Diff line number Diff line change
@@ -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 <<EOF
class=org.dogtagpki.est.DogtagRABackend
url=https://$(hostname):8443
profile=estServiceCert
username=est-ra-1
password=password4ESTUser
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/share/pki/est/bin/estauthz
EOF
```

The executable script perform a simple check of the user role and it
is available [here](/base/est/bin/estauthz). It can be replaced if
more complex authorization framework has to be adopted.


Deploy the EST application:

```
# pki-server est-deploy
```

Configure the authentication. The authentication 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
```

Loading

0 comments on commit 9335048

Please sign in to comment.