From bd24c739c4b02df686991c7d240b1cf042825d5a Mon Sep 17 00:00:00 2001 From: Nathaniel McCallum Date: Wed, 20 May 2015 00:47:22 -0400 Subject: [PATCH] Update documentation --- README.md | 103 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index c6c6e3e..b63f130 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Petera -##### Welcome to Petera! +#### Welcome to Petera! Petera is a system service and client for binding data to your local network. The concept of this application is simple, but let's look at an example. -###### Use Case: Network-bound Automatic Disk Decryption +##### Use Case: Network-bound Automatic Disk Decryption Suppose you have a disk with sensitive data. If it breaks, you can't just send it back for repair. This could expose the data. Nor can you just throw it away. @@ -23,17 +23,17 @@ the network. This is precisely what Petera does. Let's look at how it works. -###### Online Operation +##### Online Operation First, you encrypt some data to one or more particular servers. As mentioned in the example above, this data is usually a key to decrypt some secondary data. - $ petera anchor.pem encrypt one.me.com ... < key.txt > key.enc + $ petera encrypt -a anchor.pem one.me.com ... < key.txt > key.enc Second, this key can be decrypted so long as your have access to the server it was encrypted to. - $ petera anchor.pem decrypt one.me.com ... < key.enc > key.txt + $ petera decrypt < key.enc > key.txt That's it! @@ -47,41 +47,36 @@ If a payload is encrypted to multiple servers, only one of those servers is required to be online for decryption. This lets you have load balancing and redundancy for the decryption service. -###### Offline Operation +##### Offline Operation Petera encryption (but not, of course, decryption) can also be performed in offline mode. Start by downloading the encryption certificate chain: - $ petera anchor.pem fetch one.me.com > one.pem + $ petera query -a anchor.pem one.me.com > one.pem Now you can perform encryption offline: - $ petera anchor.pem encrypt one.pem < key.txt > key.enc + $ petera encrypt -a anchor.pem one.pem < key.txt > key.enc You can even mix online and offline mode: - $ petera anchor.pem encrypt one.pem two.me.com < key.txt > key.enc + $ petera encrypt -a anchor.pem one.pem two.me.com < key.txt > key.enc -###### Security Considerations +##### Security Considerations Petera tries very hard to always do the right thing. -In particular, you may notice that the petera client ALWAYS takes anchor.pem -as the first argument. This is because we always validate whatever -certificates we encounter. This includes pem files stored locally. We force -you to use this argument to think carefully about which certificates you trust. +In particular, you may notice that the petera client takes anchor.pem +as an option. This is because we always validate whatever certificates we +encounter. This includes pem files stored locally. We force you to use this +argument to think carefully about which certificates you trust. -###### Petera Server +##### Petera Server The Petera server is a simple systemd activated service. It listens on port 5700 by default. The most complex thing is getting the certificate setup -right. Here again, we test to make sure you don't expose sensitive certificates. - -The Petera daemon takes three parameters: - -1. A PEM file containing the TLS certificate chain and private key. -2. A PEM file containing the encryption certificate chain. -3. A directory of PEM files containing decryption certs/keys. +right. Here again, we test to make sure you don't expose sensitive +certificates. All communications are encrypted. Each Petera server offers only one certificate chain for encryption, but can decrypt using multiple certificates. @@ -91,26 +86,66 @@ decryption. The Petera server NEVER writes anything and is completely stateless. Feel free to run it in a container if you like. -###### Future Improvements +###### Configuration + +The Petera daemon requires only three configuration items: + +1. A PEM file containing the TLS certificate chain and private key. +2. A PEM file containing the encryption certificate chain. +3. A directory of PEM files containing decryption certs/keys. + +In the default install, these items are, respectively, located at: + +1. /etc/petera/decryptd.pem +2. /etc/petera/encrypt.pem +3. /etc/petera/decrypt.d + +###### Enablement + +To enable the server, just run the following as root: + + # systemctl enable petera-decryptd.socket + # systemctl start petera-decryptd.socket + +##### Using Petera with Disks +###### Prerequisites +First, you must have a Petera server running somewhere on your network. For +more information on this step, see the above section. + +Second, you must have a client with LUKS disk encryption already enabled. + +###### Setup +Both of the following commands are run as root. + +The first command we will run simply adds a new random key to the pre-existing +LUKS encrypted disk and then encrypts it using Petera in a known location: + + # petera cryptsetup -d /dev/ -a + +Next, we will configure the initramfs for networking. For more information, +please consult the dracut documentation. + +Finally, we need to rebuild the system's initramfs: + + # dracut -f + +That's it! Once you reboot, the disk should unlock automatically so long as +one of the specified encryption target servers is available. + +##### Future Improvements Here is a list of things we could improve: -1. MAC encrypted data. We don't protect against on-disk tampering / corruption. -2. Check certificate expiration. Does OpenSSL do this for us? -3. Support CRL/OCSP checking and maybe OCSP stapling. +1. Check certificate expiration. Does OpenSSL do this for us? +2. Support CRL/OCSP checking and maybe OCSP stapling. -###### Concluding Thoughts +##### Concluding Thoughts -Peter is still a new project and may have some rough edges. We'd +Petera is still a new project and may have some rough edges. We'd love to hear your feedback! -###### Installation +##### Installation ./configure make sudo make install - -###### Server Enablement - - sudo systemctl enable petera.socket - sudo systemctl start petera.socket