Commit 5e1949b4 by Łukasz Nowak

WIP README: Narrative documentation

1 parent 05e261bb
Showing 1 changed file with 100 additions and 0 deletions
......@@ -114,6 +114,106 @@ 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 powerful 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::
cd caucase
bin/pip install caucase
You'll see a bit of ``caucase*`` binaries in ``bin`` directory. That's good.
Create there server, user and service directories::
mkdir server 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
CASE=
``CAU`` is going to be used to execute Certificate Authority for Users, and ``CASE`` 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, which will approve automatically one user certificate -- if you're lucky, it will be yours::
bin/caucased --db server/caucase.sqlite --server-key server/server.key.pem --netloc 127.0.10.1:8890 --lock-auto-approve-count
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 master of the caucase.
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::
$CASE --send-csr service/csr.pem
Again store the id. Let's ask for the certificate immediately::
$CASE --get-crt <service-cert-id> service/crt.pem
The reply is::
<service_id> CSR still pending
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.
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::
$CASE --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 ``server``, ``client`` and ``user`` directories.
This is good place to start playing with below commands.
Commands
========
......
Styling with Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!