Rework documentation to include OpenSSL CA backend and examples

warden_ra/README

@@ -36,7 +36,6 @@ Dependencies
     Python 2.7+
     Apache 2.2+
     mod_wsgi 3.3+
-    EJBCA_ 3.9+
 
 
 Registration process
@@ -78,10 +77,6 @@ the Warden RA web service, where it obtains the new complete certificate.
 Installation
 ------------
 
-As for now, correctly configured and running EJBCA_ PKI is necessary. PKI part
-of the RA is however pluggable, so simple openssl backend is also planned.
-
-
 This depends heavily on your distribution and Apache configuration.
 Basically you need to create and include apache.conf:
 
@@ -103,6 +98,8 @@ Also, for warden_server.wsgi, you can use warden_server.wsgi.dist as
 a template. You will possibly need to change at least configuration
 file path.
 
+ * Now install and/or configure RA backend (see README.openssl or README.ejbca)
+
  * Configure Warden RA (see next chapter)
 
  * Reload Apache
@@ -133,7 +130,7 @@ Sections and their "type" objects can be:
 
     Log: FileLogger, SysLogger
     Auth: OptionalAuthenticator
-    Registry: EjbcaRegistry
+    Registry: EjbcaRegistry, OpenSSLRegistry
     Handler: CertHandler
 
 "type" keyword is not mandatory, if not specified, first implementation
@@ -156,21 +153,14 @@ Object function and configuration keys are as follows:
 
     CertHandler: the main certificate requestor implementation
 
-    EjbcaRegistry: EJBCA connector configuration
-        url: EJBCA API URL, for example "https://ejbca.example.org/ejbca/ejbcaws/ejbcaws?wsdl"
-        cert: certificate for authentication to EJBCA, defaults to "warden_ra.cert.pem"
-        key: key for authentication to EJBCA, defaults to "warden_ra.key.pem"
-        ca_name: name of the CA, dedicated for Warden, defaults to "Example CA"
-        certificate_profile_name: name of the EJBCA certificate profile, defaults to "Example"
-        end_entity_profile_name: name of the EJBCA entity profile, defaults to "Example EE"
-        subject_dn_template: template for the DN generation, defaults to "DC=cz,DC=example-ca,DC=warden,CN=%s"
-        username_suffix: suffix, which will be added to EJBCA entities, defaults to "@warden"
+    For OpenSSLRegistry or EJBCARegistry configuration please see
+    README.openssl or README.ejbca respectively.
 
 
 Command line
 ------------
 
-Whe run from the command line, RA allows for client and request management.
+When run from the command line, RA allows for client and request management.
 
 
     warden_ra.py [--help] [-c CONFIG] [-v]
@@ -226,7 +216,6 @@ Whe run from the command line, RA allows for client and request management.
 
     
 .. _Warden: https://warden.cesnet.cz/
-.. _EJBCA: https://www.ejbca.org/
 
 ------------------------------------------------------------------------------
 

warden_ra/README.ejbca

+EJBCA backend for Warden 3.# Registration Authority
+===================================================
+
+Introduction
+------------
+
+EJBCA_ is an open source CA management software. To use this backend
+with Warden RA, you need to have it already installed and running.
+Tested with EJBCA_ 3.9.
+
+.. _EJBCA: https://www.ejbca.org/
+
+
+Configuration
+-------------
+
+    Options for "Registry: EjbcaRegistry" section.
+
+    url: EJBCA API URL, for example "https://ejbca.example.org/ejbca/ejbcaws/ejbcaws?wsdl"
+    cert: certificate for authentication to EJBCA, defaults to "warden_ra.cert.pem"
+    key: key for authentication to EJBCA, defaults to "warden_ra.key.pem"
+    ca_name: name of the CA, dedicated for Warden, defaults to "Example CA"
+    certificate_profile_name: name of the EJBCA certificate profile, defaults to "Example"
+    end_entity_profile_name: name of the EJBCA entity profile, defaults to "Example EE"
+    subject_dn_template: template for the DN generation, defaults to "DC=cz,DC=example-ca,DC=warden,CN=%s"
+    username_suffix: suffix, which will be added to EJBCA entities, defaults to "@warden"
+
+
+------------------------------------------------------------------------------
+
+Copyright (C) 2017 Cesnet z.s.p.o

warden_ra/README.openssl

+OpenSSL local backed for Warden 3.# Registration Authority
+==========================================================
+
+Introduction
+------------
+
+This backend allows using basic `openssl ca`_ facility for certificate
+emission. Client information is kept as plain config files within "clients"
+subdirectory. Also, received CSRs and issued certificates are saved in "csr"
+and "newcerts" subdirectories, respectively. File "lock" is used to conduct
+concurrent access to running openssl binary.
+
+.. _openssl ca: https://www.openssl.org/docs/manmaster/man1/openssl-ca.html
+
+
+Installation
+------------
+
+Choose directory where OpenSSL CA structure will reside (for example
+"ca").
+
+    # mkdir ca
+    # cd ca/
+    /ca# mkdir certs crl newcerts private clients csr
+    /ca# chmod 700 private
+    /ca# touch index.txt
+    /ca# echo 1024 > serial
+
+Adjust permissions.
+
+   # s-bit, so newly created files receive permissions of parent
+   # directory, not of creator
+   ca# find . -type d | xargs chmod g+s
+   # owner - apache group (this is for Debian, adjust accordingly for
+   # different distribution)
+   ca# chgrp -R www-data .
+
+Generate CA root certificate.
+
+    ca# openssl genrsa -out private/ca.key.pem 4096
+    ca# openssl req -config openssl.cnf \
+                -key private/ca.key.pem \
+                -new -x509 -days 7300 -sha256 -extensions v3_ca \
+                -out certs/ca.cert.pem
+    ca# chmod 444 private/ca.key.pem certs/ca.cert.pem
+
+Create "openssl.cnf" in base directory. You can use "openssl.cnf.example" as
+a basis.
+
+
+Configuration
+-------------
+
+    Options for "Registry: OpenSSLRegistry" section.
+
+    base_dir: Base directory where OpenSSL CA environment is managed
+    subject_dn_template: Template for DN of issued certs, defaults to "DC=cz,DC=example-ca,DC=warden,CN=%s"
+    openssl_sign: OpenSSL command and arguments to run for signing, defaults to "openssl ca -config %(cnf)s -batch -extensions server_cert -days 375 -notext -md sha256 -in %(csr)s -subj '%(dn)s'"
+
+
+
+------------------------------------------------------------------------------
+
+Copyright (C) 2017 Cesnet z.s.p.o

warden_ra/openssl.cnf.example

+# OpenSSL root CA configuration file.
+# Copy to `/root/ca/openssl.cnf`.
+
+[ ca ]
+# `man ca`
+default_ca = CA_default
+
+[ CA_default ]
+# Directory and file locations.
+dir               = /var/spool/example-ca
+certs             = $dir/certs
+crl_dir           = $dir/crl
+new_certs_dir     = $dir/newcerts
+database          = $dir/index.txt
+serial            = $dir/serial
+RANDFILE          = $dir/private/.rand
+unique_subject    = no
+
+# The root key and root certificate.
+private_key       = $dir/private/ca.key.pem
+certificate       = $dir/certs/ca.cert.pem
+
+# For certificate revocation lists.
+crlnumber         = $dir/crlnumber
+crl               = $dir/crl/ca.crl.pem
+crl_extensions    = crl_ext
+default_crl_days  = 30
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md        = sha256
+
+name_opt          = ca_default
+cert_opt          = ca_default
+default_days      = 375
+preserve          = no
+policy            = policy_loose
+
+[ policy_loose ]
+# Allow the CA to sign a more diverse range of certificates.
+# See the POLICY FORMAT section of the `ca` man page.
+countryName             = optional
+stateOrProvinceName     = optional
+localityName            = optional
+organizationName        = optional
+organizationalUnitName  = optional
+commonName              = supplied
+emailAddress            = optional
+
+[ req ]
+# Options for the `req` tool (`man req`).
+default_bits        = 2048
+distinguished_name  = req_distinguished_name
+string_mask         = utf8only
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md          = sha256
+
+# Extension to add when the -x509 option is used.
+x509_extensions     = v3_ca
+
+[ req_distinguished_name ]
+# See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
+countryName                     = Country Name (2 letter code)
+stateOrProvinceName             = State or Province Name
+localityName                    = Locality Name
+0.organizationName              = Organization Name
+organizationalUnitName          = Organizational Unit Name
+commonName                      = Common Name
+emailAddress                    = Email Address
+
+# Optionally, specify some defaults.
+countryName_default             = CZ
+stateOrProvinceName_default     = Czech Republic
+localityName_default            =
+0.organizationName_default      = Example
+organizationalUnitName_default  =
+emailAddress_default            =
+
+[ v3_ca ]
+# Extensions for a typical CA (`man x509v3_config`).
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ server_cert ]
+# Extensions for server certificates (`man x509v3_config`).
+basicConstraints = CA:FALSE
+nsCertType = client
+nsComment = "OpenSSL Generate Client Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer:always
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = clientAuth
+

warden_ra/warden_ra.cfg.dist

@@ -4,14 +4,22 @@
         "level": "info"
     },
     "Registry": {
-        "type": "EjbcaRegistry",
-        "url": "https://ejbca.example.org/ejbca/ejbcaws/ejbcaws?wsdl",
-        "cert": "warden_ra.cert.pem",
-        "key": "warden_ra.key.pem",
-        "ca_name": "Example CA",
-        "certificate_profile_name": "Example",
-        "end_entity_profile_name": "Example EE",
-        "subject_dn_template": "DC=cz,DC=example-ca,DC=warden,CN=%s",
-        "username_suffix": "@warden"
+
+// Example configuration for OpenSSL CA backend
+//        "type": "OpenSSLRegistry",
+//        "base_dir": "/var/spool/example-ca",
+//        "subject_dn_template": "DC=cz,DC=example-ca,DC=warden,CN=%s"
+
+// Example configuration for EJBCA backend
+//        "type": "EjbcaRegistry",
+//        "url": "https://ejbca.example.org/ejbca/ejbcaws/ejbcaws?wsdl",
+//        "cert": "warden_ra.cert.pem",
+//        "key": "warden_ra.key.pem",
+//        "ca_name": "Example CA",
+//        "certificate_profile_name": "Example",
+//        "end_entity_profile_name": "Example EE",
+//        "subject_dn_template": "DC=cz,DC=example-ca,DC=warden,CN=%s",
+//        "username_suffix": "@warden"
+
     }
 }