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

Add pkispawn EST deployment documentation #4866

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+458 −152
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
110 changes: 110 additions & 0 deletions docs/installation/est/Installing_EST.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
// 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`
link:../est/Installing_EST_pkispawn.adoc[Installing_EST_pkispawn];

* Advanced installation with `pki-server`
link:../est/Installing_EST_pki-server.adoc[Installing_EST_pki-server],
which require 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 to the realm. The following commandss 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

```
153 changes: 1 addition & 152 deletions docs/installation/est/Installing_EST.md
View file
Open in desktop
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)
74 changes: 74 additions & 0 deletions docs/installation/est/Installing_EST_pki-server.adoc
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 link:../est/Installing_EST.adoc[Installing EST], 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
link:https://github.com/dogtagpki/pki/wiki/PKI-Server-Create-CLI[here].


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;
** it 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 link:/base/est/bin/estauthz[here]. 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
Loading