aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2022-08-03 16:00:44 +0200
committerQuentin Dufour <quentin@deuxfleurs.fr>2022-08-03 16:00:44 +0200
commit0e45eb9a6953b02d422f9d2144c8229962ac0b40 (patch)
treed36ef9398c191ea1015c51622ad7a100be0dc734
parent5015b98db8bd231f2facc5692b881f78194af8e9 (diff)
downloadaerogramme-0e45eb9a6953b02d422f9d2144c8229962ac0b40.tar.gz
aerogramme-0e45eb9a6953b02d422f9d2144c8229962ac0b40.zip
Update documentation
-rw-r--r--doc/src/mutt_mail.pngbin0 -> 24325 bytes
-rw-r--r--doc/src/mutt_mb.pngbin0 -> 39035 bytes
-rw-r--r--doc/src/notes.md40
-rw-r--r--doc/src/setup.md24
-rw-r--r--doc/src/validate.md66
-rwxr-xr-xtests/inject_emails.sh9
6 files changed, 94 insertions, 45 deletions
diff --git a/doc/src/mutt_mail.png b/doc/src/mutt_mail.png
new file mode 100644
index 0000000..e8d04e4
--- /dev/null
+++ b/doc/src/mutt_mail.png
Binary files differ
diff --git a/doc/src/mutt_mb.png b/doc/src/mutt_mb.png
new file mode 100644
index 0000000..d1bafaf
--- /dev/null
+++ b/doc/src/mutt_mb.png
Binary files differ
diff --git a/doc/src/notes.md b/doc/src/notes.md
index 33c98a0..3a4c954 100644
--- a/doc/src/notes.md
+++ b/doc/src/notes.md
@@ -1,4 +1,42 @@
# Notes
+An IMAP trace extracted from Aerogramme:
-*No note currently*
+```
+S: * OK Hello
+C: A1 LOGIN alan p455w0rd
+S: A1 OK Completed
+C: A2 SELECT INBOX
+S: * 0 EXISTS
+S: * 0 RECENT
+S: * FLAGS (\Seen \Answered \Flagged \Deleted \Draft)
+S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft \*)] Flags permitted
+S: * OK [UIDVALIDITY 1] UIDs valid
+S: * OK [UIDNEXT 1] Predict next UID
+S: A2 OK [READ-WRITE] Select completed
+C: A3 NOOP
+S: A3 OK NOOP completed.
+ <---- e-mail arrives through LMTP server ---->
+C: A4 NOOP
+S: * 1 EXISTS
+S: A4 OK NOOP completed.
+C: A5 FETCH 1 FULL
+S: * 1 FETCH (UID 1 FLAGS () INTERNALDATE "06-Jul-2022 14:46:42 +0000"
+ RFC822.SIZE 117 ENVELOPE (NIL "test" (("Alan Smith" NIL "alan" "smith.me"))
+ NIL NIL (("Alan Smith" NIL "alan" "aerogramme.tld")) NIL NIL NIL NIL)
+ BODY ("TEXT" "test" NIL "test" "test" "test" 1 1))
+S: A5 OK FETCH completed
+C: A6 FETCH 1 (RFC822)
+S: * 1 FETCH (UID 1 RFC822 {117}
+S: Subject: test
+S: From: Alan Smith <alan@smith.me>
+S: To: Alan Smith <alan@aerogramme.tld>
+S:
+S: Hello, world!
+S: .
+S: )
+S: A6 OK FETCH completed
+C: A7 LOGOUT
+S: * BYE Logging out
+S: A7 OK Logout completed
+```
diff --git a/doc/src/setup.md b/doc/src/setup.md
index 66a1b7e..f954ae3 100644
--- a/doc/src/setup.md
+++ b/doc/src/setup.md
@@ -8,10 +8,14 @@ cargo run -- first-login \
--k2v-endpoint http://127.0.0.1:3904 \
--s3-endpoint http://127.0.0.1:3900 \
--aws-access-key-id GK... \
- --aws-secret-access-key c0ffee... --bucket mailrage-me \
+ --aws-secret-access-key c0ffee... \
+ --bucket mailrage-me \
--user-secret s3cr3t
```
+*Note: user-secret is not the user's password. It is an additional secret used when deriving user's secret key from their password. The idea is that, even if user leaks their password, their encrypted data remain safe as long as this additional secret does not leak. You can generate it with openssl for example: `openssl rand -base64 30`. Read [Cryptography & key management](./crypt-key.md) for more details.*
+
+
The program will interactively ask you some questions and finally generates for you a snippet of configuration:
```
@@ -39,12 +43,24 @@ s3_endpoint = "http://127.0.0.1:3900"
k2v_endpoint = "http://127.0.0.1:3904"
aws_region = "garage"
+[lmtp]
+bind_addr = "[::1]:12024"
+hostname = "aerogramme.tld"
+
+[imap]
+bind_addr = "[::1]:1993"
+
[login_static]
default_bucket = "mailrage"
+
[login_static.users.me]
bucket = "mailrage-me"
user_secret = "s3cr3t"
-alternate_user_secrets = []
+email_addresses = [
+ "me@aerogramme.tld"
+]
+
+# copy pasted values from first-login
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
aws_access_key_id = "GK..."
aws_secret_access_key = "c0ffee..."
@@ -58,8 +74,8 @@ cargo run -- show-keys \
--k2v-endpoint http://127.0.0.1:3904 \
--s3-endpoint http://127.0.0.1:3900 \
--aws-access-key-id GK... \
- --aws-secret-access-key c0ffee... \
- --bucket mailrage-me
+ --aws-secret-access-key c0ffee... \
+ --bucket mailrage-me \
--user-secret s3cr3t
```
diff --git a/doc/src/validate.md b/doc/src/validate.md
index 9f4f6ec..57903f6 100644
--- a/doc/src/validate.md
+++ b/doc/src/validate.md
@@ -6,43 +6,35 @@ Start a server as follow:
cargo run -- server
```
-Now you can use netcat to connect on the LMTP and IMAP endpoint to check that Aerogramme behaves as expected. As an example, here is an IMAP trace extracted from Aerogramme:
+Inject emails:
+```bash
+./test/inject_emails.sh '<me@aerogramme.tld>' dxflrs
```
-S: * OK Hello
-C: A1 LOGIN lx plop
-S: A1 OK Completed
-C: A2 SELECT INBOX
-S: * 0 EXISTS
-S: * 0 RECENT
-S: * FLAGS (\Seen \Answered \Flagged \Deleted \Draft)
-S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft \*)] Flags permitted
-S: * OK [UIDVALIDITY 1] UIDs valid
-S: * OK [UIDNEXT 1] Predict next UID
-S: A2 OK [READ-WRITE] Select completed
-C: A3 NOOP
-S: A3 OK NOOP completed.
- <---- e-mail arrives through LMTP server ---->
-C: A4 NOOP
-S: * 1 EXISTS
-S: A4 OK NOOP completed.
-C: A5 FETCH 1 FULL
-S: * 1 FETCH (UID 1 FLAGS () INTERNALDATE "06-Jul-2022 14:46:42 +0000"
- RFC822.SIZE 117 ENVELOPE (NIL "test" (("Alan Smith" NIL "alan" "smith.me"))
- NIL NIL (("Alan Smith" NIL "alan" "aerogramme.tld")) NIL NIL NIL NIL)
- BODY ("TEXT" "test" NIL "test" "test" "test" 1 1))
-S: A5 OK FETCH completed
-C: A6 FETCH 1 (RFC822)
-S: * 1 FETCH (UID 1 RFC822 {117}
-S: Subject: test
-S: From: Alan Smith <alan@smith.me>
-S: To: Alan Smith <alan@aerogramme.tld>
-S:
-S: Hello, world!
-S: .
-S: )
-S: A6 OK FETCH completed
-C: A7 LOGOUT
-S: * BYE Logging out
-S: A7 OK Logout completed
+
+Now you can connect your mailbox with `mutt`.
+Start by creating a config file, for example we used the following `~/.muttrc` file:
+
+```ini
+set imap_user = quentin
+set imap_pass = p455w0rd
+set folder = imap://localhost:1993
+set spoolfile = +INBOX
+set ssl_starttls = no
+set ssl_force_tls = no
+mailboxes = +INBOX
+bind index G imap-fetch-mail
```
+
+And then simply launch `mutt`.
+The first time nothing will happen as Aerogramme must
+process your incoming emails. Just ask `mutt` to refresh its
+view by pressing `G` (for *Get*).
+
+Now, you should see some emails:
+
+![Screenshot of mutt mailbox](./mutt_mb.png)
+
+And you can read them:
+
+![Screenshot of mutt mail view](./mutt_mail.png)
diff --git a/tests/inject_emails.sh b/tests/inject_emails.sh
index 1b1f5c7..a021170 100755
--- a/tests/inject_emails.sh
+++ b/tests/inject_emails.sh
@@ -1,12 +1,15 @@
#!/bin/sh
-cd $(dirname $0)
+SCRIPT=$0
+USER=$1
+SUBFOLDER=$2
+cd $(dirname $SCRIPT)
function mail_lmtp_session (
echo -e "LHLO localhost\r"
- for mail in $(find emails -name '*.eml'); do
+ for mail in $(find emails/$SUBFOLDER -name '*.eml' ); do
echo -e "MAIL FROM: <alex@adnab.me>\r"
- echo -e "RCPT TO: <lx@staging.deuxfleurs.org>\r"
+ echo -e "RCPT TO: $USER\r"
echo -e "DATA\r"
cat $mail
echo -e "\r"