From 0be4cdca4b1283234b355e7b85b955216a1dfae0 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Mon, 22 Jan 2024 12:03:09 +0100 Subject: [PATCH] Rework skeleton --- content/documentation/cookbook/_index.md | 3 +- content/documentation/cookbook/config.md | 35 ++++++++++++++++++ .../cookbook/static-user-management.md | 5 +-- content/documentation/design/_index.md | 8 +++- .../design/per-user-encryption.md | 31 ++++++++++++++++ .../design/unbreakable-mailboxes.md | 6 +++ .../{design => internals}/aero-compo.png | Bin .../{design => internals}/aero-paranoid.png | Bin .../{design => internals}/aero-schema.png | Bin .../{design => internals}/aero-states.png | Bin .../{design => internals}/aero-states2.png | Bin .../{design => internals}/imap_uid.md | 0 .../{design => internals}/log.md | 0 .../{design => internals}/mailbox.md | 0 .../{design => internals}/mailbox.png | Bin .../{design => internals}/overview.md | 2 +- .../{design => internals}/related-work.md | 0 content/documentation/quick-start/_index.md | 27 +------------- 18 files changed, 85 insertions(+), 32 deletions(-) create mode 100644 content/documentation/cookbook/config.md create mode 100644 content/documentation/design/per-user-encryption.md create mode 100644 content/documentation/design/unbreakable-mailboxes.md rename content/documentation/{design => internals}/aero-compo.png (100%) rename content/documentation/{design => internals}/aero-paranoid.png (100%) rename content/documentation/{design => internals}/aero-schema.png (100%) rename content/documentation/{design => internals}/aero-states.png (100%) rename content/documentation/{design => internals}/aero-states2.png (100%) rename content/documentation/{design => internals}/imap_uid.md (100%) rename content/documentation/{design => internals}/log.md (100%) rename content/documentation/{design => internals}/mailbox.md (100%) rename content/documentation/{design => internals}/mailbox.png (100%) rename content/documentation/{design => internals}/overview.md (99%) rename content/documentation/{design => internals}/related-work.md (100%) diff --git a/content/documentation/cookbook/_index.md b/content/documentation/cookbook/_index.md index f210986..2645e84 100644 --- a/content/documentation/cookbook/_index.md +++ b/content/documentation/cookbook/_index.md @@ -16,7 +16,8 @@ However, as Aerogramme is a distributed-first server, you will not benefit from all of its nice properties, and many manual work will be required. - - [Static user management](@/documentation/cookbook/static-user-management.md) + - [Configuration file](@/documentation/cookbook/config.md) + - [User management](@/documentation/cookbook/static-user-management.md) - [Local storage](@/documentation/cookbook/single-node-garage-storage.md) - [TLS encryption](@/documentation/cookbook/tls-encryption.md) - [Integration with a service manager](@/documentation/cookbook/service-manager.md) (systemd or docker) diff --git a/content/documentation/cookbook/config.md b/content/documentation/cookbook/config.md new file mode 100644 index 0000000..f2c85ed --- /dev/null +++ b/content/documentation/cookbook/config.md @@ -0,0 +1,35 @@ ++++ +title = "Configuration file" +weight = 5 ++++ + +In the [quickstart](@/documentation/quick-start/_index.md), you launched Aerogramme in "development mode", that do not require a configuration file. But for a real-world usage, you will need to specificy many things: how your users are managed, which port to use, how and where data is stored, etc. + +## A first configuration file + +Let's start with the following configuration file: + +```toml +role = "Provider" +pid = "aerogramme.pid" + +[imap] +bind_addr = "[::]:1143" + +[lmtp] +bind_addr = "[::1]:1025" +hostname = "example.tld" + +[users] +user_driver = "Static" +user_list = "users.toml" +``` + +Copy this content in a file named `aerogramme.toml`. +Also create an empty file named `users.toml` (Aerogramme does not know how to create it automatically yet). + +And then you can start Aerogramme with the following configuration file: + +```bash +aerogramme -c aerogramme.toml provider daemon +``` diff --git a/content/documentation/cookbook/static-user-management.md b/content/documentation/cookbook/static-user-management.md index c78bd0f..cc7357b 100644 --- a/content/documentation/cookbook/static-user-management.md +++ b/content/documentation/cookbook/static-user-management.md @@ -1,7 +1,6 @@ +++ -title = "Static User Management" +title = "User Management" weight = 10 +++ -Todo - +Aerogramme can externalize its user management through [LDAP](@/documentation/cookbook/ldap.md), but if you target a simple deployment, it has also an internal user management system that will be covered here. diff --git a/content/documentation/design/_index.md b/content/documentation/design/_index.md index 39b0336..9ab8e56 100644 --- a/content/documentation/design/_index.md +++ b/content/documentation/design/_index.md @@ -1,8 +1,12 @@ +++ -title = "Design" +title = "Concepts" weight = 40 sort_by = "weight" template = "documentation.html" +++ -Test +[Per-user encryption](@/documentation/design/per-user-encryption.md) - TODO + +[Unbreakable mailboxes](@/documentation/design/unbreakable-mailboxes.md) - TODO + +**Stateless** - 12 factor app. diff --git a/content/documentation/design/per-user-encryption.md b/content/documentation/design/per-user-encryption.md new file mode 100644 index 0000000..c7a9fea --- /dev/null +++ b/content/documentation/design/per-user-encryption.md @@ -0,0 +1,31 @@ ++++ +title = "Per-user encryption" +weight = 10 ++++ + + +Aerogramme can't store plaintext data, instead all users data must be encrypted with a per-user key on the storage target. +Of course, cryptography is always a tradeoff with other properties (usability, compatibility, features, etc.), +so the way the key is derived and where the encryption/decryption can take place can be configured. + +## Security flavors + +These different configurations are identified as flavors: + +**Transparent Flavor** - Users' data are decrypted in the server's RAM. The key is derived from the user's password upon IMAP login. +It's completely transparent to end users. While an attacker having full access to the server can still compromise users' data, it reduces the attack surface. +In term of security, it's similar to [TREES](https://0xacab.org/liberate/trees) (from [RiseUp](https://riseup.net)) or [scrambler](https://github.com/posteo/scrambler-plugin) (from [Posteo](https://posteo.de/)). + + +**Hardened Flavor** - Users' data are decrypted on the user's device. The private key is only stored on the user's device. +The server knows only users' public keys. When an email is received by the server, it is directly encrypted and stored by the server. +The user must run Aerogramme locally as a proxy that will manipulate the encrypted blobs stored in the server +and decrypt them locally, exposing an IMAP proxy interface. An attacker having full access to the server at a point in time +will not be able to compromise your already received data (but can intercept new emails). It's similar to [Proton Mail Bridge](https://proton.me/fr/mail/bridge), +but keep in mind that Aerogramme does not support (yet) end-to-end email encryption like Proton Mail or Tutanota, *so Aerogramme is less secure*. + +When run on server (both for the transparent and hardened flavor), Aerogramme must be started in the "provider mode", as in "email service provider". +When run on the end-user device (only the hardened flavor require that), Aerogramme must be started in the "companion mode", as in "a companion process of your email client". +These 2 words are materialized as 2 subcommands on the Aerogramme binary: `aerogramme provider` and `aerogramme companion`. + +## Aerogramme "role" diff --git a/content/documentation/design/unbreakable-mailboxes.md b/content/documentation/design/unbreakable-mailboxes.md new file mode 100644 index 0000000..26cd757 --- /dev/null +++ b/content/documentation/design/unbreakable-mailboxes.md @@ -0,0 +1,6 @@ ++++ +title = "Unbreakable mailboxes" +weight = 20 ++++ + +Test diff --git a/content/documentation/design/aero-compo.png b/content/documentation/internals/aero-compo.png similarity index 100% rename from content/documentation/design/aero-compo.png rename to content/documentation/internals/aero-compo.png diff --git a/content/documentation/design/aero-paranoid.png b/content/documentation/internals/aero-paranoid.png similarity index 100% rename from content/documentation/design/aero-paranoid.png rename to content/documentation/internals/aero-paranoid.png diff --git a/content/documentation/design/aero-schema.png b/content/documentation/internals/aero-schema.png similarity index 100% rename from content/documentation/design/aero-schema.png rename to content/documentation/internals/aero-schema.png diff --git a/content/documentation/design/aero-states.png b/content/documentation/internals/aero-states.png similarity index 100% rename from content/documentation/design/aero-states.png rename to content/documentation/internals/aero-states.png diff --git a/content/documentation/design/aero-states2.png b/content/documentation/internals/aero-states2.png similarity index 100% rename from content/documentation/design/aero-states2.png rename to content/documentation/internals/aero-states2.png diff --git a/content/documentation/design/imap_uid.md b/content/documentation/internals/imap_uid.md similarity index 100% rename from content/documentation/design/imap_uid.md rename to content/documentation/internals/imap_uid.md diff --git a/content/documentation/design/log.md b/content/documentation/internals/log.md similarity index 100% rename from content/documentation/design/log.md rename to content/documentation/internals/log.md diff --git a/content/documentation/design/mailbox.md b/content/documentation/internals/mailbox.md similarity index 100% rename from content/documentation/design/mailbox.md rename to content/documentation/internals/mailbox.md diff --git a/content/documentation/design/mailbox.png b/content/documentation/internals/mailbox.png similarity index 100% rename from content/documentation/design/mailbox.png rename to content/documentation/internals/mailbox.png diff --git a/content/documentation/design/overview.md b/content/documentation/internals/overview.md similarity index 99% rename from content/documentation/design/overview.md rename to content/documentation/internals/overview.md index 31afdbd..cef045a 100644 --- a/content/documentation/design/overview.md +++ b/content/documentation/internals/overview.md @@ -1,5 +1,5 @@ +++ -title = "Overview" +title = "Architecture" weight = 10 +++ diff --git a/content/documentation/design/related-work.md b/content/documentation/internals/related-work.md similarity index 100% rename from content/documentation/design/related-work.md rename to content/documentation/internals/related-work.md diff --git a/content/documentation/quick-start/_index.md b/content/documentation/quick-start/_index.md index 1783d3a..7d3b6c0 100644 --- a/content/documentation/quick-start/_index.md +++ b/content/documentation/quick-start/_index.md @@ -8,7 +8,7 @@ template = "documentation.html" This quickstart guide will teach you how to run an in-memory instance of Aerogramme, because it is easier to run than a distributed real-world deployment. The goal here is that you get familiar with the software, you understand what it does and what it does not, -so you can evaluate it. Once ready for a real deployment, you will find all the information you need in the cookbook. +so you can evaluate it. Once ready for a real deployment, you will find all the information you need in the [cookbook](@/documentation/cookbook/_index.md). *Enjoy your reading!* @@ -120,7 +120,7 @@ Remember, Aerogramme is about managing your mailbox, not managing mail transfer. As this is an Aerogramme specific, the goal here is not to deploy Postfix, opensmtpd or any other MTA software. Instead we will emulate their action: forwarding the messages they received to Aerogramme through the LMTP protocol. -Python natively supports the LMTP protocol, the following command this capability to deliver a fake email: +Python natively supports the LMTP protocol: the following command uses Python to deliver a fake email: ```bash @@ -158,29 +158,6 @@ user management, auto-discovery, persistent storage, high-availability design, o All these points will be covered in the [Cookbook](@/documentation/cookbook/_index.md), it should be your next stop!