| author | Alberto Bertogli
<albertito@blitiri.com.ar> 2014-04-29 22:55:57 UTC |
| committer | Alberto Bertogli
<albertito@blitiri.com.ar> 2014-04-29 23:02:32 UTC |
| parent | e21f6396d3ab81b82f67c8d90cd5e1e3926d592f |
| README | +23 | -10 |
| doc/man/kxc-cryptsetup.rst | +7 | -0 |
| doc/man/kxc.rst | +7 | -0 |
| doc/man/kxd.rst | +7 | -0 |
| doc/quick_start.rst | +29 | -13 |
diff --git a/README b/README index 41cb678..fff2d53 100644 --- a/README +++ b/README @@ -23,15 +23,15 @@ The server configuration is stored in a root directory (/etc/kxd/data), and within there, with per-key directories (e.g. /etc/kxd/data/host1/key1), each containing the following files: - - key: Contains the key to give to the client. - - allowed_clients: Contains one or more PEM-encoded client certificates that - will be allowed to request the key. - If not present, then no clients will be allowed to access this key. - - allowed_hosts: Contains one or more host names (one per line). - If not present, then all hosts will be allowed to access that key (as long - as they are authorized with a valid client certificate). - - email_to: Contains one or more email destinations to notify (one per line). - If not present, then no notifications will be sent upon key accesses. + - key: Contains the key to give to the client. + - allowed_clients: Contains one or more PEM-encoded client certificates that + will be allowed to request the key. + If not present, then no clients will be allowed to access this key. + - allowed_hosts: Contains one or more host names (one per line). + If not present, then all hosts will be allowed to access that key (as long + as they are authorized with a valid client certificate). + - email_to: Contains one or more email destinations to notify (one per line). + If not present, then no notifications will be sent upon key accesses. Client configuration @@ -62,7 +62,7 @@ given on the command line, and will only accept keys from it. Note the server will return reasonably detailed information on errors, for example it will tell when a key is not found vs. when the client is not -allowed. While this leaks some information about existance of keys, it makes +allowed. While this leaks some information about existence of keys, it makes troubleshooting much easier. The server itself makes no effort to protect the data internally; for example, @@ -70,6 +70,19 @@ there is no on-disk encryption, and memory is not locked. We work under the assumption that the server's host is secure and trusted. +Dependencies +------------ + +There are no runtime dependencies for the kxd and kxc binaries. + +Building requires Go 1.2. + +The configuration helper scripts (create-kxd-config, kxc-add-key, etc.) +depend on: bash, openssl (the binary), and core utilities (mkdir, dd, etc.). + +Testing needs Python 2.7, and openssl (the binary). + + Bugs and contact ---------------- diff --git a/doc/man/kxc-cryptsetup.rst b/doc/man/kxc-cryptsetup.rst index 299e156..a6769b0 100644 --- a/doc/man/kxc-cryptsetup.rst +++ b/doc/man/kxc-cryptsetup.rst @@ -60,3 +60,10 @@ SEE ALSO ``kxc(1)``, ``kxd(1)``, ``crypttab(5)``, ``cryptsetup(8)``. + +BUGS +==== + +If you want to report bugs, or have any questions or comments, just let me +know. For more information, you can go to http://blitiri.com.ar/p/kxd. + diff --git a/doc/man/kxc.rst b/doc/man/kxc.rst index c6cd762..54b25f2 100644 --- a/doc/man/kxc.rst +++ b/doc/man/kxc.rst @@ -50,3 +50,10 @@ SEE ALSO ``kxc-cryptsetup(1)``, ``kxd(1)``. + +BUGS +==== + +If you want to report bugs, or have any questions or comments, just let me +know. For more information, you can go to http://blitiri.com.ar/p/kxd. + diff --git a/doc/man/kxd.rst b/doc/man/kxd.rst index 5383da0..9525b86 100644 --- a/doc/man/kxd.rst +++ b/doc/man/kxd.rst @@ -102,3 +102,10 @@ SEE ALSO ``kxc(1)``, ``kxc-cryptsetup(1)``. + +BUGS +==== + +If you want to report bugs, or have any questions or comments, just let me +know. For more information, you can go to http://blitiri.com.ar/p/kxd. + diff --git a/doc/quick_start.rst b/doc/quick_start.rst index 5a53a46..648e146 100644 --- a/doc/quick_start.rst +++ b/doc/quick_start.rst @@ -3,31 +3,35 @@ Key Exchange Daemon - Quick start =================================== -In this guide we show how to set up a key exchange daemon and client +In this guide we show how to set up a `key exchange daemon`_ and client on a typical scenario where the keys are used to open a device encrypted with -dm-crypt (the standard Linux disk encryption). +dm-crypt_ (the standard Linux disk encryption). -``server`` is the hostname of the server. -``client`` is the hostname of the client. -``sda2`` is the encrypted drive. +These steps have been checked on a Debian install, other distributions should +be similar but may differ on some of the details (specially on the +"`Configuring crypttab`_" section). + +- ``server`` is the hostname of the server. +- ``client`` is the hostname of the client. +- ``sda2`` is the encrypted drive. Initial server setup ==================== -First of all, install *kxd* on the server, usually via your distribution +First of all, install kxd_ on the server, usually via your distribution packages, or directly from source. Then, run ``create-kxd-config``, which will create the configuration -directories, and generate the server key/cert pair. Everything is in -``/etc/kxd/``. +directories, and generate a self-signed_ key/cert pair for the server. +Everything is in ``/etc/kxd/``. Initial client setup ==================== -Install *kxc* on the client machine, usually via your distribution packages, -or directly from source. +Install kxc_ on the client machine, usually via your distribution packages, or +directly from source. Then, run ``kxc-add-key server sda2``, which will create the configuration @@ -85,9 +89,10 @@ In order to get kxc to be run automatically to fetch the key, we need to edit sda2_crypt UUID=blah-blah-blah sda2 luks,keyscript=kxc-cryptsetup ^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^ -Note the "sda2" field corresponds to the name we've been passing around in -previous sections. The ``keyscript=kxc-cryptsetup`` is our way of telling the -cryptsetup infrastructure to use our script to fetch the key for this target. +Note the ``sda2`` field corresponds to the name we've been passing around in +previous sections. The ``keyscript=kxc-cryptsetup`` option is our way of +telling the cryptsetup infrastructure to use our script to fetch the key for +this target. You can test that this works by using:: @@ -96,3 +101,14 @@ You can test that this works by using:: cryptdisks_start sda2_crypt The second command should issue a request to your server to get the key. + +Consider running ``update-initramfs`` if your device is the root device, or it +is needed very early in the boot process. + + +.. _key exchange daemon: http://blitiri.com.ar/p/kxd +.. _kxd: http://blitiri.com.ar/p/kxd +.. _kxc: http://blitiri.com.ar/p/kxd +.. _dm-crypt: https://en.wikipedia.org/wiki/dm-crypt +.. _self-signed: https://en.wikipedia.org/wiki/Self-signed_certificate +