Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add pkispawn EST deployment documentation #4866

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add pkispawn EST deployment documentation #4866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 46 additions & 93 deletions docs/installation/est/Installing_EST.md
View file
Open in desktop
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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's an issue with the commands in this section. There's no instruction how to set up the NSS database in nssdb folder. Should we just use the default NSS database in ~/.dogtag/nssdb and remove the -d nssdb -c 4me2Test from the doc?

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
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
----------------------------
Expand All @@ -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);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any advantage to pki-server that we want to continue providing it as an option?

Copy link
Contributor

@edewata edewata Sep 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general the pki-server tool provides more control over the installation process (i.e. fine-grained installation). If something fails, it can be fixed immediately, then the installation can resume from that point. With pkispawn it's all or nothing. pkispawn does many things at once so all params must be set correctly at the beginning. If something fails, usually you'd have to clean up the environment and start over from the beginning. This could be problematic if pkispawn leaves many orphan keys in HSM or starts replicating a huge database.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also for containers we don't want to do everything that pkispawn does, so pki-server tool provides a mechanism to do what's needed for containers.

I think for the primary EST doc we could suggest users to use pkispawn, but we should keep the EST doc using pki-server if they need more control over the installation process.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@edewata Thanks for the clarification. Yes I think we should keep both options available, but perhaps add the explanation to help with choices?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking the main EST install doc should just use pkispawn, but we also provide a link that says something like "Manual EST Installation" or "Advanced EST Installation" to another doc using pki-server. We can include the above explanation in that other doc. This way the user won't be forced to read, understand the differences, then make a choice before they can start the installation, but they can try pkispawn with the sample config files first (which is what most people want to do initially), then if it's not enough they can try pki-server. What do you think?


```
# 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 <<EOF
class=org.dogtagpki.est.DogtagRABackend
url=https://$(hostname):8443
profile=estServiceCert
username=est-ra-1
password=est4ever
EOF
```
## Verifying EST

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

The executable should exist and have the right permission. Here an example:
The following command will print the CA signing certificate obtained from the server:

```
# 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:
$ 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

```
# 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 <<EOF
class=com.netscape.cms.realm.PKIInMemoryRealm
username=alice
password=4me2Test
roles=estclient
EOF
```

Finally, restart the server:
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 commandss will perform the enrollment and print the final certificate::

```
# pki-server restart --wait
```
$ 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


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).
74 changes: 74 additions & 0 deletions docs/installation/est/Installing_EST_pki-server.md
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The $(hostname) might be confusing since IIUC we do not support command substitution like in shells, so I'd suggest to use something like <hostname> which indicates that it needs to be replaced with a real hostname, or just put a sample hostname (e.g. ca.example.com).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually this is a cat command and not the file so there is shell substitution so it is possible to cut&paste. If I change with <hostname> then it need to be edited.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes.

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
Comment on lines +63 to +64
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it possible to provide an example how to do an enrollment using these credentials? Also, I'd suggest using a different password to clarify that this is unrelated to est-ra-1 user.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verification is in the main document after the installation because the final test is independent of the installation path followed.

roles=estclient
EOF
```

Finally, restart the server:

```
# pki-server restart --wait
```

Loading
Loading