From 8415efa7bb54d702cf3f63fac6daae8cd78d42c5 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Sat, 19 Apr 2014 16:32:17 -0400
Subject: [PATCH] break out page on security

---
 doc/index.mdwn    |  1 +
 doc/security.mdwn | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 doc/security.mdwn

diff --git a/doc/index.mdwn b/doc/index.mdwn
index 5f2abd3..8ab9a2b 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 0000000..5576bf0
--- /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.