Update documentation

This commit is contained in:
Quentin 2022-08-03 16:00:44 +02:00
parent 5015b98db8
commit 0e45eb9a69
Signed by: quentin
GPG key ID: E9602264D639FF68
6 changed files with 94 additions and 45 deletions

BIN
doc/src/mutt_mail.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

BIN
doc/src/mutt_mb.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

View file

@ -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
```

View file

@ -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
```

View file

@ -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)

View file

@ -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"