WIP README: Narrative documentation

README.rst

@@ -117,6 +117,112 @@ caucase, the CRL is re-generated whenever it is requested and:
 - previous CRL expired
 - any revocation happened since previous CRL was created
 
+Narrative introduction
+======================
+
+caucase is tool which simplifies SSL key & certificate management.
+But as SSL is based on cryptography, and cryptography is hard topic, even
+with caucase is quite hard to start. There are a lot of options, use cases
+and usage scenarios.
+
+First take a look at `caucase website <https://caucase.nexedi.com/>`_ and
+study a bit the graph.
+
+Now let's start with simple scenario, which will involve using caucase. We
+are going to cover `caucase`_ and `caucased`_ commands.
+
+
+Create virtualenv ``caucase`` and there install the tool::
+
+  mkdir caucase
+  virtualenv caucase
+  cd caucase
+  bin/pip install caucase
+
+You'll see a bit of ``caucase*`` binaries in ``bin`` directory. That's good.
+
+Create there caucased, user and service directories::
+
+  mkdir caucased user service
+
+Before we begin, lets create two environment variables, which will ease the understanding of which side is used::
+
+  CAU=bin/caucase --ca-url http://127.0.10.1:8890 --ca-crt user/ca-crt.pem --user-ca-crt user/user-ca-crt.pem --crl user/crl --user-crl user/user-crl
+  CAS=
+
+
+``CAU`` is going to be used to execute Certificate Authority for Users, and ``CAS`` for Certificate Authority for SErvices. As server is going to be just running, there is no need for special environment variable.
+
+Let's start a server in separate terminal, which will approve automatically one user certificate -- if you're lucky, it will be yours::
+
+  bin/caucased --db caucased/caucase.sqlite --server-key caucased/server.key.pem --netloc 127.0.10.1:8890
+
+You'll need key for yourself so lets create it::
+
+  openssl req -out user/client.csr.pem -new -newkey rsa:2048 -nodes -keyout user/client.key.pem -subj /CN=user
+
+And now sign it::
+
+  $CAU --mode user --send-csr user/client.csr
+
+It will return its id and path, so fetch it with the id::
+
+  $CAU --mode user --send-csr user/client.csr.pem --get-crt <user-cert-id> user/client.key.pem
+
+Voila, you have your key signed by caucase you started, and you became user of this caucase, so you now have the power to decide which service certificate requests will be granted and which will be rejected.
+
+Let's create key for the service::
+
+  openssl req -out service/csr.pem -new -newkey rsa:2048 -nodes -keyout service/crt.pem -subj /CN=service
+
+And now as a service, let's ask caucase for signing::
+
+  $CAS --send-csr service/csr.pem
+
+Again remember the id. Let's ask for the certificate immediately::
+
+  $CAS --get-crt <service-cert-id> service/crt.pem
+
+The reply is::
+
+  <service_id> CSR still pending
+
+You might end up in situation with bad network, so there is nothing wrong with asking the server again to sign the certificate, it will return the same id::
+
+  $CAS --send-csr service/csr.pem
+
+Now using user certificate, but in ``--mode service``, which is default, let's see what is to sign::
+
+  $CAU --user-key user/client.key.pem --list-csr
+
+You'll see::
+
+  -- pending service CSRs --
+      csr_id | subject preview (fetch csr and check full content !)
+      <service_id> | <Name([<NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'service')>])>
+  -- end of pending service CSRs --
+
+As they say, you shall fetch the CSR and check the full content::
+
+  $CAU --user-key user/client.key.pem --get-csr <service_id> <service_id>.csr
+
+**Exercise**: Use ``openssl`` to inspect downloaded CSR, you can start with `openssl req -text -noout <service_id>.csr`.
+
+Now you can sign the CSR::
+
+  $CAU --user-key user/client.key.pem --sign-csr <service_id>
+
+Now do the service part -- fetch the certificate::
+
+  $CAS --get-crt <service-cert-id> service/crt.pem
+
+It will download it to ``service/crt.pem`` and inform about the process::
+
+  <service_id> was (originally) manually approved
+
+Take some time and inspect ``caucased``, ``client`` and ``user`` directories.
+This is good place to start playing with below commands.
+
 Commands
 ========