From 8415efa7bb54d702cf3f63fac6daae8cd78d42c5 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sat, 19 Apr 2014 16:32:17 -0400 Subject: break out page on security --- doc/index.mdwn | 1 + doc/security.mdwn | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 doc/security.mdwn (limited to 'doc') diff --git a/doc/index.mdwn b/doc/index.mdwn index 5f2abd35..8ab9a2b3 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -4,6 +4,7 @@ [[Install]] [API documentation](http://hackage.haskell.org/package/propellor) [Sample config file](http://git.joeyh.name/?p=propellor.git;a=blob;f=config-joey.hs) +[[Security]] [[Todo]] [[Forum]] """]] diff --git a/doc/security.mdwn b/doc/security.mdwn new file mode 100644 index 00000000..5576bf06 --- /dev/null +++ b/doc/security.mdwn @@ -0,0 +1,36 @@ +Propellor's security model is that the hosts it's used to deploy are +untrusted, and that the central git repository server is untrusted too. + +The only trusted machine is the laptop where you run `propellor --spin` +to connect to a remote host. And that one only because you have a ssh key +or login password to the host. + +Since the hosts propellor deploys are not trusted by the central git +repository, they have to use git:// or http:// to pull from the central +git repository, rather than ssh://. + +So, to avoid a MITM attack, propellor checks that any commit it fetches +from origin is gpg signed by a trusted gpg key, and refuses to deploy it +otherwise. + +That is only done when privdata/keyring.gpg exists. To set it up: + + gpg --gen-key # only if you don't already have a gpg key + propellor --add-key $MYKEYID + +In order to be secure from the beginning, when `propellor --spin` is used +to bootstrap propellor on a new host, it transfers the local git repositry +to the remote host over ssh. After that, the remote host knows the +gpg key, and will use it to verify git fetches. + +Since the propoellor git repository is public, you can't store +in cleartext private data such as passwords, ssh private keys, etc. + +Instead, `propellor --spin $host` looks for a +`~/.propellor/privdata/$host.gpg` file and if found decrypts it and sends +it to the remote host using ssh. This lets a remote host know its own +private data, without seeing all the rest. + +To securely store private data, use: `propellor --set $host $field` +The field name will be something like 'Password "root"'; see PrivData.hs +for available fields. -- cgit v1.2.3