Merge branch '7-write-documentation-on-some-security-aspects' into 'master'

First sketch of security considerations

Closes #7

See merge request open/cryptops!2

README.md

-# Usage
+CryptOps implements full disk encryption for virtual private servers.
 
-```sh
-cryptops-api --root-device=DEV --crypt-name=LABEL [--notify-command=COMMAND]
-```
+All documentation can be found on
+[the website](https://cryptops.com).
 
-*   The `--root-device=DEV` option is mandatory. `DEV` should be the root device
-    of the machine, like `/dev/sda` or `/dev/xvda`.
-    
-    When the root device is still unencrypted (for example when starting
-    cryptops-api for the first time), this should be an unpartitioned device,
-    with the file system spanning the whole device.
-    
-    As part of the encryption process, this device will be partitioned and the
-    encrypted contents will be stored on the second partition, but DEV should
-    still point to the whole device, as before.
-
-*   The `--crypt-name=LABEL` option is mandatory. `LABEL` will be used by
-    cryptsetup to name the encrypted volume. This will be visible to the operating
-    system, as the decrypted root disk is available at `/dev/mapper/LABEL`.
-
-*   The `--notify-command=COMMAND` option is optional. The given `COMMAND` will be
-    run whenever cryptops-api detects that the root device needs the user to enter
-    their password to continue the booting process. You can use this to notify the
-    user of this situation.
+In particular, please read the
+[security considerations](https://cryptops.com/considerations.html).

docs/considerations.rst

+Considerations
+==============
+
+CryptOps is a tool that can be used to raise the level of security in some
+particular aspects. It does not provide all-round security of your VPS.
+
+CryptOps can be used as a part of an overall security strategy and should never
+be used as definitive security solution.
+
+Possible reasons to use CryptOps
+--------------------------------
+
+* You want to make it harder for the hoster's employees to casually view your
+  data on disk.
+* You trust your hoster now, but you want to have an easy way to cut off their
+  access to your data – maybe when they change owners, or when you anticipate
+  that they are forced by some authority to grant access to your data.
+* You want your data to be safe in case the hosters disks get confiscated,
+  stolen, or discarded without shredding.
+* You want your data to be encrypted at rest.
+
+Invalid reasons to use CryptOps
+-------------------------------
+
+* You don't trust your hoster, or you fear that they may be forced to grant
+  access to your data without a timely warning. If your hoster or a powerful
+  third party really wants to view your data, they could
+
+    * install a modified version of CryptOps that doesn't really encrypt;
+    * man-in-the-middle your first ssh connection to the server running in the
+      initrd, capturing your encryption password when you first enter it;
+    * access your decrypted data in memory while your vps is active;
+    * various other methods.
+
+It is very hard to prevent someone who has access (physical or via network) to
+the host running your vps from reading your data, and CryptOps does not pretend
+to do so.
+
+Possible reasons to not use CryptOps
+------------------------------------
+
+* It increases the chance of data loss: if you forget or lose your encryption
+  password, a single reboot of your vps (for whatever reason) renders your data
+  irrecoverably lost.
+* It can increase downtime of your vps: whenever your vps reboots, you need to
+  become aware of this (though we have a customisable hook to notify you of this
+  situation), connect to the vps, and enter your encryption password; only then
+  can the boot process of the vps continue. All this time the service provided
+  by your vps is not running.
+* You may not need full disk encryption of your vps: depending on the software
+  running on your vps, it could be easier to encrypt only some data directories.
+  On the other hand, it is easy to overlook some sensitive data stored in
+  configuration, cache files, temporary files, etc.
+

docs/index.rst

-.. Cryptops documentation master file, created by
+.. CryptOps documentation master file, created by
    sphinx-quickstart on Tue Oct 17 10:00:20 2017.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -24,7 +24,7 @@ provider? Existing solutions often rely on encryption keys being managed by the
 service providers themselves or the data being encrypted at the application
 level.
 
-CryptOps is a new, provider agnostic approach which makes full-disk encryption
+CryptOps is a new, provider agnostic approach which makes full disk encryption
 at the Virtual Machine layer more accessible and secure for the average user.
 Users can encrypt their VPSs by logging into a `Dropbear SSH`_ shell
 that runs in the initrd. In this environment, the user is allowed to type
@@ -35,8 +35,11 @@ to manage their SSH and LUKS encryption keys. The CryptOps framework has been
 designed to be open & extensible, allowing it to support external client
 applications in the future.
 
-Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example initrd at
-`<https://code.greenhost.net/open/cryptops-initrd>`_
+Please read the :doc:`security considerations <considerations>` to learn
+exactly what CryptOps does and doesn't protect against.
+
+Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example
+initrd at `<https://code.greenhost.net/open/cryptops-initrd>`_
 
 .. _`Dropbear SSH`: https://matt.ucc.asn.au/dropbear/dropbear.html
 .. _Greenhost: https://greenhost.net
@@ -45,8 +48,9 @@ Find the code at `<https://code.greenhost.net/open/cryptops>`_ and an example in
    :maxdepth: 2
    :caption: Contents:
 
-   readme.md
-   api_documentation.rst
+   considerations
+   usage
+   api_documentation
 
 
 

docs/readme.md

-../README.md
\ No newline at end of file

docs/usage.rst

+Usage
+=====
+
+::
+
+  cryptops-api --root-device=DEV --crypt-name=LABEL [--notify-command=COMMAND]
+
+*   The ``--root-device=DEV`` option is mandatory. ``DEV`` should be the root device
+    of the machine, like ``/dev/sda`` or ``/dev/xvda``.
+    
+    When the root device is still unencrypted (for example when starting
+    cryptops-api for the first time), this should be an unpartitioned device,
+    with the file system spanning the whole device.
+    
+    As part of the encryption process, this device will be partitioned and the
+    encrypted contents will be stored on the second partition, but DEV should
+    still point to the whole device, as before.
+
+*   The ``--crypt-name=LABEL`` option is mandatory. ``LABEL`` will be used by
+    cryptsetup to name the encrypted volume. This will be visible to the operating
+    system, as the decrypted root disk is available at ``/dev/mapper/LABEL``.
+
+*   The ``--notify-command=COMMAND`` option is optional. The given ``COMMAND`` will be
+    run whenever cryptops-api detects that the root device needs the user to enter
+    their password to continue the booting process. You can use this to notify the
+    user of this situation.