Commit 890ca070 authored by Maarten de Waard's avatar Maarten de Waard 🤘🏻
Browse files

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

First sketch of security considerations

Closes #7

See merge request !2
parents 55bbba4f 86b24957
# 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).
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.
.. 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
......
../README.md
\ No newline at end of file
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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment