Commit fc4b250a by Łukasz Nowak

WIP README: Narrative documentation

1 parent dfbb2e0f
Showing 1 changed file with 106 additions and 0 deletions
......@@ -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
========
......
Styling with Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!