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

Merged
merged 1 commit into from
Dec 23, 2024
Merged

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
118 changes: 118 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,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.
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)
92 changes: 92 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,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
```

Loading
Loading