From 3d5f6aeec40ac1c719becdb031fe306f33bcfcc7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Pl=C3=B6tz?=
 <reneploetz@users.noreply.github.com>
Date: Tue, 29 Aug 2023 23:40:54 +0200
Subject: [PATCH] docs: Add documentation for iOS mail push support (#3513)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add documentation for iOS mail push support

---------

Signed-off-by: René Plötz <reneploetz@users.noreply.github.com>
---
 .../use-cases/ios-mail-push-support.md        | 232 ++++++++++++++++++
 docs/mkdocs.yml                               |   1 +
 2 files changed, 233 insertions(+)
 create mode 100644 docs/content/examples/use-cases/ios-mail-push-support.md

diff --git a/docs/content/examples/use-cases/ios-mail-push-support.md b/docs/content/examples/use-cases/ios-mail-push-support.md
new file mode 100644
index 00000000..d0eacd18
--- /dev/null
+++ b/docs/content/examples/use-cases/ios-mail-push-support.md
@@ -0,0 +1,232 @@
+---
+title: 'Advanced | iOS Mail Push Support'
+---
+
+## Introduction
+
+iOS Mail currently does not support the IMAP idle extension. Therefore users can only either check manually or configure intervals for fetching mails in their mail account preferences when using the default configuration.
+
+To support mail push Dovecot needs to advertise the `XAPPLEPUSHSERVICE` IMAP extension as well as sending the actual push notifications to the Apple Push Notification service (APNs) which will forward them to the device.
+
+This can be done with two components:
+
+- A Dovecot plugin (`dovecot-xaps-plugin`) which is triggered whenever a mail is created or moved from/to a mail folder.
+- A daemon service (`dovecot-xaps-daemon`) that manages both the device registrations as well as sending notifications to the APNs.
+
+## Prerequisites
+
+- An Apple developer account to create the required Apple Push Notification service certificate.
+- Knowledge creating Docker images, using the command-line, and creating shell scripts.
+
+## Limitations
+
+- You need to maintain a custom `docker-mailserver` image.
+- Push support is limited to the INBOX folder. Changes to other folders will not be pushed to the device regardless of the configuration settings.
+- You currently cannot use the same account UUID on multiple devices. This means that if you use the same backup on multiple devices (e.g. old phone / new phone) only one of them will get the notification. Use different backups or recreate the mail account.
+
+## Privacy concerns
+
+- The service does not send any part of the actual message to Apple.
+- The information sent contains the device UUID to notify and the (on-device) account UUID which was generated by the iOS mail application when creating the account.
+- Upon receiving the notification, the iOS mail application will connect to the IMAP server given by the provided account UUID and fetch the mail to notify the user.
+- Apple therefore does not know the mail address for which the mail was received, only that a specific account on a specific device should be notified that a new mail or that a mail was moved to the INBOX folder.
+
+## Installation
+
+Both components will be built using Docker and included into a custom `docker-mailserver` image. Afterwards the required configuration is added to `docker-data/dms/config`. The registration data is stored in `/var/mail-state/lib-xapsd`.
+
+1. Create a Dockerfile to build a `docker-mailserver` image that includes the [`dovecot-xaps-plugin`](https://github.com/freswa/dovecot-xaps-plugin) as well as the [`dovecot-xaps-daemon`](https://github.com/freswa/dovecot-xaps-daemon). This is required to ensure that the Dovecot plugin is built against the same Dovecot version. The `:edge` tag is used here, but you might want to use a released version instead.
+
+    ```dockerfile
+    FROM mailserver/docker-mailserver:edge AS dovecot-plugin-xaps
+    WORKDIR /tmp/dovecot-xaps-plugin
+    RUN <<EOF
+        apt-get update
+        apt-get -y --no-install-recommends install git cmake make build-essential dovecot-dev
+        git clone --single-branch --depth=1 https://github.com/freswa/dovecot-xaps-plugin.git .
+        mkdir build && cd build
+        cmake .. -DCMAKE_BUILD_TYPE=Release
+        make install
+    EOF
+
+    # Use an older Go version as Go >= 1.20 causes this issue: https://github.com/freswa/dovecot-xaps-daemon/issues/24#issuecomment-1483876081
+    # Note that the underlying issue are non-standard-compliant Apple http servers which might get fixed at some point
+    FROM golang:1.19-alpine AS dovecot-xaps-daemon
+    ENV GOPROXY=https://proxy.golang.org,direct
+    ENV CGO_ENABLED=0
+    WORKDIR /go/dovecot-xaps-daemon
+    RUN <<EOF
+        apk add --no-cache --virtual build-dependencies git
+        git clone --single-branch --depth=1 https://github.com/freswa/dovecot-xaps-daemon .
+        go build ./cmd/xapsd
+    EOF
+
+    FROM mailserver/docker-mailserver:edge
+    COPY --from=dovecot-plugin-xaps /usr/lib/dovecot/modules/*_xaps_* /usr/lib/dovecot/modules/
+    COPY --from=dovecot-xaps-daemon /go/dovecot-xaps-daemon/xapsd /usr/bin/xapsd
+
+    # create a non-root user for the daemon process as well as configuration and run state directories
+    RUN <<EOF
+        adduser --quiet --system --group --disabled-password --home /var/mail-state/lib-xapsd --no-create-home xapsd
+        mkdir -p /var/run/xapsd /etc/xapsd
+    EOF
+    ```
+
+2. Build the new image:
+    ```sh
+    docker build -t yourname/docker-mailserver .
+    ```
+
+3. Modify your `compose.yaml` to use the newly created image:
+    ```yaml
+        services:
+            mailserver:
+              image: yourname/docker-mailserver:latest
+    ```
+
+4. Recreate the container:
+    ```sh
+    docker compose down
+    docker compose up -d
+    ```
+
+5. Create a hash of your Apple developer account password using the provided `xapsd -pass` command:
+    ```sh
+    docker exec -it mailserver xapsd -pass
+    ```
+
+6. Add configuration for both components:
+    - Create a folder named `xaps` in `docker-data/dms/config`.
+
+    - Create a file named `xapsd.yaml` in `docker-data/dms/config/xaps`. 
+        - Replace `appleId` and `appleIdHashedPassword` with your actual credentials. For reference see also [here](https://github.com/freswa/dovecot-xaps-daemon/blob/master/configs/xapsd/xapsd.yaml).
+        - The service will use the provided username/hash combination to automatically request a new certificate from Apple as well as renewing an older certificate if needed.
+
+        ```yaml title="xapsd.yaml"
+
+        # set the loglevel to either
+        # trace, debug, error, fatal, info, panic or warn
+        # Default: info
+        loglevel: info
+
+        # xapsd creates a json file to store the registration persistent on disk.
+        # This sets the location of the file.
+        databaseFile: /var/mail-state/lib-xapsd/database.json
+
+        # xapsd listens on a socket for http/https requests from the dovecot plugin.
+        # This sets the address and port number of the listen socket.
+        listenAddr: '127.0.0.1'
+        port: 11619
+
+        # xapsd is able to listen on a HTTPS Socket to allow HTTP/2 to be used
+        # SSL is enabled implicitly when certfile and keyfile exist
+        # !!! only use HTTPS for connection pooling with a proxy e.g. nginx or HaProxy
+        # !!! direct usage with the plugin is discouraged and unsupported
+        tlsCertfile:
+        tlsKeyfile:
+        tlsListenAddr:
+        tlsPort: 11620
+
+        # Notifications that are not initiated by new messages are not sent immediately for two reasons:
+        # 1. When you move/copy/delete messages you most likely move/copy/delete more messages within a short period of time.
+        # 2. You don't need your mailboxes to synchronize immediately since they are automatically synchronized when opening
+        #    the app
+        # If a new message comes and the move/copy/delete notification is still on hold it will be sent with the notification
+        # for the new message.
+        # This sets the interval to check for delayed messages.
+        checkInterval: 20
+
+        # Set the time how long notifications for not-new messages should be delayed until they are sent.
+        # Whenever checkInterval runs, it checks if "delay" <= "waiting time" and sends the notification if the expression is
+        # true.
+        delay: 30
+
+        # To retrieve certificates from Apple, we need to login with a valid Apple ID
+        # The accounts email must be given in cleartext, but the password has to
+        # be hashed before sending it. To not leak working credentials on running servers,
+        # we do not accept the cleartext password here.
+        appleId: foo@example.com
+
+        # use `xaps -pass` to calculate the hash of the apple id password
+        appleIdHashedPassword: bar
+        ```
+
+    - Create a file named `95-xaps.conf` in `docker-data/dms/config/xaps`. For reference see also [here](https://github.com/freswa/dovecot-xaps-plugin/blob/master/xaps.conf).
+        ```txt title="95-xaps.conf"
+
+        protocol imap {
+          mail_plugins = $mail_plugins notify push_notification xaps_push_notification xaps_imap
+        }
+
+        protocol lda {
+          mail_plugins = $mail_plugins notify push_notification xaps_push_notification
+        }
+
+        protocol lmtp {
+          mail_plugins = $mail_plugins notify push_notification xaps_push_notification
+        }
+
+        plugin {
+            # xaps_config contains xaps specific configuration parameters
+            # url:              protocol, hostname and port under which xapsd listens
+            # user_lookup: Use if you want to determine the username used for PNs from environment variables provided by
+            #                   login mechanism. Value is variable name to look up.
+            # max_retries:      maximum num of retries the http client connects to the xaps daemon
+            # timeout_msecs     http timeout of the http connection
+            xaps_config = url=http://127.0.0.1:11619 user_lookup=theattribute max_retries=6 timeout_msecs=5000
+            push_notification_driver = xaps
+        }
+        ```
+
+    - Create a supervisord file named `xapsd.conf` in `docker-data/dms/config/xaps` with the following content:
+        ```txt title="xapsd.conf"
+
+        [program:xapsd]
+        startsecs=0
+        autostart=false
+        autorestart=true
+        stdout_logfile=/var/log/supervisor/%(program_name)s.log
+        stderr_logfile=/var/log/supervisor/%(program_name)s.log
+        user=xapsd
+        command=/usr/bin/xapsd
+        pidfile=/var/run/xapsd/xapsd.pid
+        ```
+
+    - Create or update your `user-patches.sh` in `docker-data/dms/config` to move the files to their final location as well as starting the daemon service:
+        ```sh title="user-patches.sh"
+        #!/bin/bash
+
+        # Copy the configs to internal locations:
+        cp /tmp/docker-mailserver/xaps/95-xaps.conf /etc/dovecot/conf.d/95-xaps.conf
+        cp /tmp/docker-mailserver/xaps/xapsd.yaml /etc/xapsd/xapsd.yaml
+        cp /tmp/docker-mailserver/xaps/xapsd.conf /etc/supervisor/conf.d/xapsd.conf
+
+        # Setup data persistence and ensure ownership is always for xapsd:
+        mkdir -p /var/mail-state/lib-xapsd
+        chown -R xapsd:xapsd /var/mail-state/lib-xapsd
+
+        # Start the xaps daemon:
+        supervisorctl update
+        supervisorctl start xapsd
+        ```
+
+7. Recreate the container again to apply the new configuration:
+    ```sh
+    docker compose down
+    docker compose up -d
+    ```
+
+8. Recreate your mail account on your iOS device and check the logs in `/var/log/supervisor/dovecot.log` and `/var/log/supervisor/xapsd.log` for any errors.
+
+
+## Other configuration options
+
+Both device registration and notifications send a username to the daemon to lookup the device. While the registration and other IMAP operations in Dovecot will send the Dovecot username, LMTP will send the provided authentication username.
+
+The format of that username is specified by the `auth_username_format` Dovecot setting. If you are not using mail addresses as Dovecot usernames - e.g. when using LDAP - you can either change the `auth_username_format` or add the mail address as property to the user account and use the lookup feature (see below).
+
+```sh title="user-patches.sh"
+sed -i -r "s|^#?(auth_username_format =).*|\1 %Ln|" /etc/dovecot/conf.d/10-auth.conf
+```
+
+You can also use notifications for Dovecot alias mailboxes. Depending on your server configuration, this might require to add the original Dovecot username as [Dovecot attribute](https://doc.dovecot.org/configuration_manual/authentication/user_database_extra_fields/) to the login user as well as changing the `user_lookup=theattribute` in `95-xaps.conf` to perform the lookup of that attribute.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index cef4a082..ba920774 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -162,6 +162,7 @@ nav:
     - 'Use Cases':
       - 'Forward-Only Mail-Server with LDAP': examples/use-cases/forward-only-mailserver-with-ldap-authentication.md
       - 'Customize IMAP Folders': examples/use-cases/imap-folders.md
+      - 'iOS Mail Push Support': examples/use-cases/ios-mail-push-support.md
   - 'FAQ' : faq.md
   - 'Contributing':
     - 'General Information': contributing/general.md