Update quickstart and enrollment workflow docs

Author: oliwel

doc/index.rst

@@ -44,7 +44,7 @@ Setup and Configuration
    reference/configuration/workflows/certrequest
    reference/configuration/workflows/certrevocation
    reference/configuration/workflows/crlissuance
-   reference/configuration/workflows/scep
+   reference/configuration/workflows/enroll
    reference/configuration/workflows/smartcard
    reference/tools/openxpkiadm
    reference/tools/openxpkictl

doc/quickstart.rst

@@ -3,6 +3,12 @@
 Quickstart guide
 ================
 
+OpenXPKI is an easy-to-deploy and easy-to-use RA/CA software that makes
+handling of certificates easy but nevertheless you should **really**
+have some basic knownledge on what a PKI is. If you just want to see
+"OpenXPKI in action" for a first impression of the tool, use the
+public demo at https://demo.openxpki.org.
+
 Support
 -------
 
@@ -15,13 +21,14 @@ Vagrant
 
 We have a vagrant setup for debian buster. If you have vagrant you can just
 checkout the git repo, go to vagrant/debian and run "vagrant up test". Provisioning takes some
-minutes and will give you a ready to run OXI install available at http://localhost:8080/openxpki/.
+minutes and will give you a ready to run OXI install available at https://localhost:8443/openxpki/.
 
 Docker
 ------
 
-We also provide a docker image based on the debian packages as well as a docker-compose file, see
-https://github.com/openxpki/openxpki-docker.
+We also provide a docker image based on the debian packages as well as a
+docker-compose file, see https://github.com/openxpki/openxpki-docker.
+**Please read the hints in the README if you try this on Windows!**
 
 Debian Builds
 -------------
@@ -31,8 +38,8 @@ those running a v2 version we still maintain security and major bug fixes for th
 
 **Packages are for Debian 10 (Buster) / 64bit (arch amd64). The en_US.utf8 locale must be
 installed as the translation system will crash otherwise! The packages do NOT work
-on Ubuntu or 32bit systems. Community packages for Ubuntu have been
-discontinued due to packaging/dependancy problems.**
+on Ubuntu or 32bit systems. Packages for SLES/CentOS/RHEL/Ubuntu are available
+via subscription**
 
 Start with a debian minimal install, we recommend to add "SSH Server" and "Web Server" in the package selection menu, as this will speed up the install later.
 
@@ -50,6 +57,8 @@ Add the repository to your source list (buster)::
     echo "deb http://packages.openxpki.org/v3/debian/ buster release" > /etc/apt/sources.list.d/openxpki.list
     apt update
 
+Please do not disable the installation of "recommend" packages as this will very likely leave you with an unusable system.
+
 As the init script uses mysql as default, but does not force it as a dependency, it is crucial that you have the mysql server and the perl mysql binding installed before you pull the OpenXPKI package::
 
     apt install default-mysql-server libdbd-mysql-perl
@@ -62,16 +71,10 @@ Note, fastcgi module should be enabled explicitly, otherwise, .fcgi file will be
 
     a2enmod fcgid
 
-Some people reported that a2enmod is not available on their system, in this case try to install the apache2.2-common package.
-
 Now install the OpenXPKI core package, session driver and the translation package::
 
     apt install libopenxpki-perl openxpki-cgi-session-driver openxpki-i18n
 
-You should now restart the apache server to activate the new config::
-
-    service apache2 restart
-
 use the openxpkiadm command to verify if the system was installed correctly::
 
     openxpkiadm version
@@ -97,7 +100,7 @@ Now, create an empty database and assign a database user::
 
 
 Please create the empty database schema from the provided schema file. mysql and postgresql
-should work out of the box, the oracle schema is goo for testing but needs some extra indices
+should work out of the box, the oracle schema is good for testing but needs some extra indices
 to perform properly.
 
 Example call when debian packages are installed::
@@ -125,6 +128,9 @@ Here is what you need to do if you *dont* use the sampleconfig script.
 #. Create a key/certificate for the internal datavault (ca = false, can be below the ca but can also be self-signed).
 #. Create a key/certificate for the scep service (ca = false, can be below the ca but can also be self-signed or from other ca).
 
+OpenXPKI supports NIST and Brainpool ECC curves (as supported by openssl) for the CA certificates, as the Datavault
+certificate is used for data encryption it **MUST** use an RSA key!
+
 **Starting with release 3.6 the default config uses the database to store the issuing ca and SCEP tokens -
 if you upgrade from an older config version check the new settings in systems/crypto.yaml.**
 
@@ -243,12 +249,28 @@ An easy check to see if the signer token is working is to create a CRL::
 Adding the Webclient
 ^^^^^^^^^^^^^^^^^^^^
 
-The webclient is included in the core packages. Just open your browser and navigate to *https://yourhost/openxpki/*. You should see the main authentication page. If you get an internal server error, make sure you have the *en_US.utf8* locale installed (``locale -a | grep en_US``)!
+The package installs a default configuration for apache but requires that you
+provide a tls certificate for the WebUI by yourself. So before you can start
+the Webserver you **must** create a TLS certificate, place the key to
+`/etc/openxpki/tls/private/openxpki.pem` and the certificate to `/etc/openxpki/tls/endentity/openxpki.crt`.
+
+The default configuration also offers TLS client authentication. Place a copy of
+your root certificate in `/etc/openxpki/tls/chain/` and run `c_rehash /etc/openxpki/tls/chain/`
+to make it available for chain construction in apache.
+
+You should now be able to start the apache server::
+
+    $ service apache2 restart
+
+Navigate your browser to *https://yourhost/openxpki/*. If your browser asks you to present a certificate
+for authentication, skip it. You should now see the main authentication page.
 
-You can log in as user with any username/password combination, the operator login has two preconfigured operator accounts raop and raop2 with password openxpki.
+You can log in as user with any username/password combination, the operator login has two preconfigured
+operator accounts raop and raop2 with password openxpki.
 
-If you only get the "Open Source Trustcenter" banner without a login prompt, check that fcgid is enabled as described above with
-(``a2enmod fcgid; service apache2 restart``).
+If you only get the "Open Source Trustcenter" banner without a login prompt, check that fcgid is enabled
+as described above with (``a2enmod fcgid; service apache2 restart``). If you get an internal server error,
+make sure you have the *en_US.utf8* locale installed (``locale -a | grep en_US``)!
 
 Testdrive
 ^^^^^^^^^

doc/reference/configuration/workflows/scep.rst doc/reference/configuration/workflows/enroll.rst

@@ -1,9 +1,9 @@
-SCEP Workflow
-=============
+Enrollment Workflow
+====================
 
-Before you can use the SCEP subsystem, you need to enable the SCEP Server
-in the general configuration. This section explains the business logic and
-options for the enrollment workflow.
+The enrollment workflow is used by the SCEP, EST and RPC interface. The
+details how to connect the workflow to the API differ but the general
+configuration and operational modes are the same for all three subsystems.
 
 Operational Modes
 -----------------
@@ -23,6 +23,8 @@ match the subject of the signer certificate (which is a self-signed
 certificate in this case). Especially Ciso ASA fails here as the certificate
 subject does not match the request subject.
 
+For EST and RPC this is equal to an unauthenticated/unsigned TLS request.
+
 Renewal
 +++++++
 
@@ -35,6 +37,12 @@ request from the old certificate to ensure the subjects match. Please note
 that reuse of keys is not supported, you must generate a new key for each new
 request.
 
+As you can not use a TLS server certificate to authenticate as client the
+workflow supports an approach names "surrogate certifcates" which requires
+that you create a look-alike self-signed certificate with the proper key
+usage. Have a look at the perldoc of the EvaluateSignerTrust activity for
+more details.
+
 Enrollment On Behalf
 ++++++++++++++++++++
 
@@ -45,6 +53,9 @@ always choosen if the subject of request and signer do not match, so it is
 often hit by accident when Renewal or Initial Enrollment are made with
 "wrong" subjects.
 
+For SCEP the signature on the SCEP PKCS7 container is the TTP, for EST/RPC
+the TTP is the TLS client certificate used to make the connection.
+
 Workflow Logic
 --------------
 
@@ -83,25 +94,20 @@ approval point:
 Sample Configuration
 --------------------
 
-The workflow fetches all information from the configuration system at ``scep.<servername>`` where the servername is taken from the scep wrapper configuration.
+The workflow fetches all information from the configuration system at
+``<subsystem>.<servername>`` where the servername is taken from the wrapper
+configuration.
 
-Here is a complete sample configuration (found in `scep/generic.yaml`)::
+Here is a complete sample configuration (found in `scep/generic.yaml`). The
+sections `token`, `workflow` and `response` are only used by SCEP, the
+`export_certificate` is only applicable to the RPC output. The remainder
+of the configuration is the same for all subsystems::
 
     # By default, all scep endpoints wll use the default token defined
     # by the scep token group, if you pass a name here, it is considered
     # a group name from the alias table
     #token: ca-one-special-scep
 
-    # A renewal request is only accpeted if the used certificate will
-    # expire within this period of time.
-    renewal_period: 000060
-
-    # If the request was a replacement, optionally revoke the replaced
-    # certificate after a grace period
-    revoke_on_replace:
-        reason_code: keyCompromise
-        delay_revocation_time: +000014
-
     workflow:
         type: certificate_enroll
         param:
@@ -114,6 +120,35 @@ Here is a complete sample configuration (found in `scep/generic.yaml`)::
             _url_params: url_params
             #_pkcs7: pkcs7
 
+    response:
+        # The scep standard is a bit unclear if the root should be in the chain
+        # or not. We consider it a security risk (trust should be always set
+        # by hand) but as most clients seem to expect it, we include the root
+        # by default.
+        # The getca response contains the certificate of the SCEP server itself
+        # and of the current active issuer (which can but need not to be the same!)
+        # You can define weather to have only the certificate itself (endentity),
+        # the chain without the root (chain)  or the chain including the root
+        # (fullchain).
+        # Note: The response is cached internally in the datapool so changes
+        # will not show up immediately - to list the cached items use
+        # openxpkicli list_data_pool_entries  --arg namespace=scep.cache.getca
+        # You can delete by setting the empty string as value with
+        # set_data_pool_entry (value="" force=1)
+        getca:
+            ra:     fullchain
+            issuer: fullchain
+
+    # A renewal request is only accpeted if the used certificate will
+    # expire within this period of time.
+    renewal_period: 000060
+
+    # If the request was a replacement, optionally revoke the replaced
+    # certificate after a grace period
+    revoke_on_replace:
+        reason_code: keyCompromise
+        delay_revocation_time: +000014
+
     authorized_signer:
         rule1:
             # Full DN
@@ -165,25 +200,11 @@ Here is a complete sample configuration (found in `scep/generic.yaml`)::
         # This substitutes the "replace_window" from the OpenXPKI v1 config
         allow_replace: 1
 
-    response:
-        # The scep standard is a bit unclear if the root should be in the chain
-        # or not. We consider it a security risk (trust should be always set
-        # by hand) but as most clients seem to expect it, we include the root
-        # by default.
-        # The getca response contains the certificate of the SCEP server itself
-        # and of the current active issuer (which can but need not to be the same!)
-        # You can define weather to have only the certificate itself (endentity),
-        # the chain without the root (chain)  or the chain including the root
-        # (fullchain).
-        # Note: The response is cached internally in the datapool so changes
-        # will not show up immediately - to list the cached items use
-        # openxpkicli list_data_pool_entries  --arg namespace=scep.cache.getca
-        # You can delete by setting the empty string as value with
-        # set_data_pool_entry (value="" force=1)
-        getca:
-            ra:     fullchain
-            issuer: fullchain
-
+        # by default only the certificate identifier is written to the workflow
+        # set to a true value to get the PEM encoded certificate in the context,
+        # set to "chain" to get the issuer certificate and "fullchain" to get
+        # the chain including the root certificate (key chain).
+        export_certificate: chain
 
     profile:
       cert_profile: tls_server
@@ -277,6 +298,21 @@ in the workflow.
 Workflow Configuration
 ----------------------
 
+Test-Drive (INSECURE)
++++++++++++++++++++++
+
+If you need a server that *just creates certificates*, use the following
+policy section::
+
+    policy:
+        allow_anon_enroll: 1
+        approval_points: 0
+        max_active_certs: 0
+        allow_replace: 0
+        export_certificate: chain
+
+**This will issue any certificate for any request - so do not use this in production**
+
 Authentication
 ++++++++++++++