mailmaint                                                     B. Bucksch
Internet-Draft                                                    Beonex
Intended status: Informational                         20 September 2024
Expires: 24 March 2025


                            Mail Autoconfig
                   draft-ietf-mailmaint-autoconfig-00

Abstract

   Set up a mail account with only email address and password.

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://benbucksch.github.io/autoconfig-spec/draft-autoconfig-1.html.
   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-ietf-mailmaint-autoconfig/.

   Discussion of this document takes place on the mailmaint Working
   Group mailing list (mailto:mailmaint@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/mailmaint/.  Subscribe at
   https://www.ietf.org/mailman/listinfo/mailmaint/.

   Source for this draft and an issue tracker can be found at
   https://github.com/benbucksch/autoconfig-spec.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 24 March 2025.





Bucksch                   Expires 24 March 2025                 [Page 1]

Internet-Draft                 autoconfig                 September 2024


Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Implementations . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Data format . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Sample config file  . . . . . . . . . . . . . . . . . . .   4
     3.2.  Formal definition . . . . . . . . . . . . . . . . . . . .   9
     3.3.  Placeholders  . . . . . . . . . . . . . . . . . . . . . .   9
   4.  Config retrieval for mail clients . . . . . . . . . . . . . .  10
     4.1.  Mail provider . . . . . . . . . . . . . . . . . . . . . .  10
       4.1.1.  Customzing the config for a specific user . . . . . .  11
     4.2.  Central database  . . . . . . . . . . . . . . . . . . . .  11
     4.3.  MX  . . . . . . . . . . . . . . . . . . . . . . . . . . .  12
     4.4.  Local disk  . . . . . . . . . . . . . . . . . . . . . . .  13
     4.5.  Other mechanisms  . . . . . . . . . . . . . . . . . . . .  14
     4.6.  Manual configuration  . . . . . . . . . . . . . . . . . .  14
   5.  Config validation . . . . . . . . . . . . . . . . . . . . . .  14
     5.1.  User approval . . . . . . . . . . . . . . . . . . . . . .  14
     5.2.  Login testing . . . . . . . . . . . . . . . . . . . . . .  14
     5.3.  OAuth2 windows  . . . . . . . . . . . . . . . . . . . . .  15
   6.  Config publishing for mail providers  . . . . . . . . . . . .  15
     6.1.  Config location for single domain . . . . . . . . . . . .  15
     6.2.  Config location for domain hosters  . . . . . . . . . . .  16
     6.3.  No authentication for config  . . . . . . . . . . . . . .  16
     6.4.  Return config for non-existing email addresses  . . . . .  16
     6.5.  OAuth2 requirements . . . . . . . . . . . . . . . . . . .  17
   7.  Conventions and Definitions . . . . . . . . . . . . . . . . .  17
   8.  Alternatives considered . . . . . . . . . . . . . . . . . . .  17
     8.1.  DNSSEC  . . . . . . . . . . . . . . . . . . . . . . . . .  17
     8.2.  DNS SRV . . . . . . . . . . . . . . . . . . . . . . . . .  17
     8.3.  CAPABILITIES  . . . . . . . . . . . . . . . . . . . . . .  18
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  19
     9.1.  Risk  . . . . . . . . . . . . . . . . . . . . . . . . . .  19
     9.2.  DNS . . . . . . . . . . . . . . . . . . . . . . . . . . .  19



Bucksch                   Expires 24 March 2025                 [Page 2]

Internet-Draft                 autoconfig                 September 2024


     9.3.  Config updates  . . . . . . . . . . . . . . . . . . . . .  20
     9.4.  Server security . . . . . . . . . . . . . . . . . . . . .  20
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  21
   11. Normative References  . . . . . . . . . . . . . . . . . . . .  21
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  21
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  21

1.  Introduction

   This protocol allows users to set up their existing email account in
   a new mail client application, by entering only their name, email
   address, and password.  The mail application, by means of mail
   autoconfig specified here, will determine all the other parameters
   that are required, including IMAP or POP3 hostname, TLS
   configuration, form of username, authentication method, and other
   settings, and likewise for SMTP.  Contact sync and calendar, file
   sharing and other services can also be set up automatically.

   The protocol works by first determining the domain from the email
   address, and the querying well-known URLs at the email provider,
   which return the configuration parameters in computer-readable form.
   Failing that, various fallback sources can be applied, like a common
   database of configurations for large email providers who do not
   directly support this protocol, or other mechanisms to determine the
   configuration.

2.  Implementations

   This protocol is in production use since 15 years by major email
   clients, and the config database (used as fallback) contains
   configurations for over 50% of all email accounts.

   Currently, this protocol or parts of it has been implemented by:

   *  Thunderbird (https://thunderbird.net)

   *  Evolution (https://projects.gnome.org/evolution/)

   *  KMail (https://userbase.kde.org/KMail)

   *  Kontact (https://www.kontact.org)

   *  K9 Mail (https://k9mail.app)

   *  FairEmail (https://email.faircode.eu)

   *  NextCloud email (https://apps.nextcloud.com/apps/mail)




Bucksch                   Expires 24 March 2025                 [Page 3]

Internet-Draft                 autoconfig                 September 2024


   *  Delta Chat (https://delta.chat/)

   and likely other mail clients.

   The purpose of this paper is to document and specify what is deployed
   in the wild.  A later version 2 of the protocol might be based on
   JSON.

   Additionally, there are known problems with OAuth2 in combination
   with mail clients, which would need to be solved by another
   specification.

3.  Data format

   Whether the ISP or a common central database returns the
   configuration, the resulting document has the following data format.

   The MIME type is text/xml or text/xml+autoconfig.

3.1.  Sample config file

<?xml version="1.0"?>
<clientConfig version="1.2">
    <emailProvider id="example.com">
      <domain>example.com</domain>
      <domain>example.net</domain>

      <displayName>Google Mail</displayName>
      <displayShortName>GMail</displayShortName>

      <!-- type=
          "imap": IMAP
          "pop3": POP3
          "jmap": JMAP
          "ews": Microsoft Exchange Web Services
          "activesync": Microsoft ActiveSync
          -->
      <incomingServer type="imap">
        <hostname>imap.example.com</hostname>
        <port>993</port>
          <!-- "plain": no encryption
                "SSL": SSL 3 or TLS 1 on SSL-specific port
                "STARTTLS": on normal plain port and mandatory upgrade to TLS via STARTTLS
                -->
        <socketType>SSL</socketType>
        <username>%EMAILADDRESS%</username>
            <!-- Authentication methods:
                "password-cleartext",



Bucksch                   Expires 24 March 2025                 [Page 4]

Internet-Draft                 autoconfig                 September 2024


                          Send password in the clear
                          (dangerous, if SSL isn't used either).
                          AUTH PLAIN, LOGIN or protocol-native login.
                "password-encrypted",
                          A secure encrypted password mechanism.
                          Can be CRAM-MD5 or DIGEST-MD5. Not NTLM.
                "NTLM":
                          Use NTLM (or NTLMv2 or successors),
                          the Windows login mechanism.
                "GSSAPI":
                          Use Kerberos / GSSAPI,
                          a single-signon mechanism used for big sites.
                "TLS-client-cert":
                          On the SSL/TLS layer, the server requests a client certificate and the client sends one (possibly after letting the user select/confirm one), if available.
                "OAuth2":
                          mAuth. Should be added only as second alternative.
                "none":
                          No authentication
                -->
        <authentication>password-cleartext</authentication>
        <password>optional: the user's password</password>
      </incomingServer>

      <!-- You can have multiple incoming servers,
        and even multiple IMAP server configs.
        The first config is the preferred one, but the user or
        or client can choose the alternative configs. -->
      <incomingServer type="pop3">
        <hostname>pop.example.com</hostname>
        <port>995</port>
        <socketType>SSL</socketType>
        <username>%EMAILADDRESS%</username>
        <authentication>password-cleartext</authentication>
        <pop3>
            <!-- optional -->
            <leaveMessagesOnServer>true</leaveMessagesOnServer>
            <daysToLeaveMessagesOnServer>14</daysToLeaveMessagesOnServer>
        </pop3>
      </incomingServer>

      <!-- Needed only for IMAP or POP3 -->
      <outgoingServer type="smtp">
        <hostname>smtp.googlemail.com</hostname>
        <port>587</port>
        <socketType>STARTTLS</socketType>
        <username>%EMAILADDRESS%</username> <!-- if smtp-auth -->
            <!-- smtp-auth (RFC 2554, 4954) or other auth mechanism.
                For values, see incoming.



Bucksch                   Expires 24 March 2025                 [Page 5]

Internet-Draft                 autoconfig                 September 2024


                Additional options here:
                "client-IP-address":
                          The server recognizes this user based on the IP address.
                          No authentication needed, the server will require no username nor password.
            -->
        <authentication>password-cleartext</authentication>
        <password>optional: the user's password</password>
      </outgoingServer>

      <incomingServer type="jmap">
        <url>https://jmap.example.com</url>
        <username>%EMAILADDRESS%</username>
        <authentication>http-basic</authentication>
      </incomingServer>

      <incomingServer type="ews">
        <url>https://mail.example.com/EWS/Exchange.asmx</url>
        <username>%EMAILADDRESS%</username>
        <authentication>http-basic</authentication>
      </incomingServer>

      <incomingServer type="activesync">
        <url>https://mail.example.com/Microsoft-Server-ActiveSync</url>
        <username>%EMAILADDRESS%</username>
        <authentication>OAuth2</authentication>
      </incomingServer>

      <!-- A page where the ISP describes the configuration.
          This is purely informational and currently mainly for
          maintenance of the files and not used by the client at all.
          Note that we do not necessarily use exactly the config suggested
          by the ISP, e.g. when they don't recommend SSL, but it's available,
          we will configure SSL.
          The text content should contains a description in the native
          language of the ISP (customers), and a short English description,
          mostly for us.
      -->
      <documentation url="http://www.example.com/help/mail/">
        <descr lang="en">Configure mail app for IMAP</descr>
        <descr lang="de">Email mit IMAP konfigurieren</descr>
      </documentation>

    </emailProvider>

    <!-- Syncronize the user's address book / contacts. -->
    <addressBook type="carddav">
      <username>%EMAILADDRESS%</username>
        <!-- Authentication methods. See also <incomingServer>.



Bucksch                   Expires 24 March 2025                 [Page 6]

Internet-Draft                 autoconfig                 September 2024


              "http-basic":
                        Authenticate to the HTTP server using
                        WWW-Authenticate: Basic
              "http-digest":
                        Authenticate to the HTTP server using
                        WWW-Authenticate: Digest
              "OAuth2":
                        mAuth. Uses the same token as for email. <scope> needs to include
                         addressbook/calendar.
              -->
      <authentication>http-basic</authentication>
      <url>https://jmap.example.com/remote.php/dav</url>
    </addressBook>

    <!-- Syncronize the user's calendar. -->
    <calendar type="caldav">
      <username>%EMAILADDRESS%</username>
      <authentication>http-basic</authentication> <!-- see <addressBook> -->
      <url>https://calendar.example.com/remote.php/dav</url>
    </calendar>

    <!-- Upload files, allowing the user to share them.
        This can be used for Thunderbird's FileLink feature,
        or to set up a file sync folder on the user's desktop. -->
    <fileShare type="webdav">
      <username>%EMAILADDRESS%</username>
      <authentication>http-basic</authentication> <!-- see <addressBook> -->
      <url>https://share.example.com/remote.php/dav</url>
    </fileShare>

    <!-- This allows to login in to the webmail service of the provider.
        The URLs are loaded into a standard webbrowser for the user.
        This is optional. -->
    <webMail>
      <!-- Webpage where the user has to log in manually by entering username
          and password himself.
          HTTPS required. -->
      <loginPage url="https://mail.example.com/login/" />

      <!-- Same as loginAutomaticDOM, but the website makes checks that
          the user comes from the login page. So, open the login page
          in the browser, get the page's DOM, fill out name and password
          fields for the user, and trigger the login button.
          The login button might not be an HTML button, just a div, so
          to trigger it, send a click event to it.
          HTTPS is required for the URL. -->
      <loginPageInfo url="https://mail.example.com/login/">
        <!-- What to fill into the usernameField.



Bucksch                   Expires 24 March 2025                 [Page 7]

Internet-Draft                 autoconfig                 September 2024


            Format is the same as for <username> within <incomingServer>,
            including placeholders. See below for valid placeholders. -->
        <username>%EMAILADDRESS%</username>
        <!-- Allows to find the textfield on the page, to fill it out.
            The id attribute give the DOM ID,
            The name attribute give the DOM name attribute.
            One or both of id and name attributes must exist.
            Try the ID first (e.g. using getElementById()), if existing.
            Otherwise, try finding the element by name.
            Don't treat the IDs given in this XML file as trusted,
            but before using them, verify the format
            (e.g. only characters and digits for IDs).
            If you use powerful functions like jQuery, and the XML returns
            you code in the username ID, and you feed it unchecked to jQuery,
            it may be executed. -->
        <usernameField id="email_field" name="email" />
        <passwordField name="password" />
        <!-- The submit button to trigger the server submit
            after filling in the fields.
            id and name attributes: See <usernameField> -->
        <loginButton id="submit_button" name="login"/>
      </loginPageInfo>
    </webMail>

    <!-- Ask user for custom input,
       and use them as placeholders in the values.
       Optional. -->
    <inputField key="USERNAME" label="Screen name"></inputField>
    <inputField key="GRANDMA" label="Grandma">Elise Bauer</inputField>

    <!-- oAuth2 specced for mail apps,
        e.g. clientID, expiry, and login page
        MUST adhere to mAuth <https://benbucksch.github.io/mauth-spec/draft-mauth.html>
        -->
    <mAuth>
      <authURL>https://login.example.com/common/oauth2/v2.0/authorize</authURL>
      <tokenURL>https://login.example.com/common/oauth2/v2.0/token</tokenURL>
      <issuer>login.example.com</issuer>
      <scope>IMAP POP3 SMTP CalDAV CardDAV WebDAV offline_access</scope>
      <clientID>open</clientID>
      <!-- optional -->
      <clientSecret>give-me-your-pass-word</clientSecret>
    </mAuth>

    <!-- Add this only when users (who already have an account) have to
        do something manually before the account can work with IMAP/POP or SSL.
        Mandatory only if the ISP requires such settings
        before the configs above work.



Bucksch                   Expires 24 March 2025                 [Page 8]

Internet-Draft                 autoconfig                 September 2024


        Note: Per XML, & (ampersand) needs to be escaped to
        & a m p ; (without spaces). -->
    <enable
      visiturl="https://mail.google.com/mail/?ui=2&amp;shva=1#settings/fwdandpop">
      <instruction>Check 'Enable IMAP and POP' in Google settings page</instruction>
      <instruction lang="de">Schalten Sie 'IMAP und POP aktivieren' auf der Google Einstellungs-Seite an</instruction>
    </enable>

    <clientConfigUpdate url="https://www.example.com/config/mail.xml" />

</clientConfig>

3.2.  Formal definition

   TODO Schema for XML

3.3.  Placeholders

   The fields for <username>, <hostname>, <serverURL>, <displayName>,
   <displayShortName> (*1) support placeholders.  The config returned by
   the autoconfig server may contain these placeholders, which are to be
   replaced by the client.  The following special strings (or
   substrings/parts) of the value should be replaced by the client,
   after the config was retrieved and before its values are actually
   used.

   +==================+============================+==================+
   | Placeholder      | Replace with               | Example          |
   +==================+============================+==================+
   | %EMAILADDRESS%   | E-Mail-Address of the user | fred@example.com |
   +------------------+----------------------------+------------------+
   | %EMAILLOCALPART% | Part before @ in the E-    | fred             |
   |                  | Mail-Address               |                  |
   +------------------+----------------------------+------------------+
   | %EMAILDOMAIN%    | Part after @ in the E-     | example.com      |
   |                  | Mail-Address               |                  |
   +------------------+----------------------------+------------------+
   | %REALNAME%       | Real-world name of the     | Fred Flintstone  |
   |                  | user                       |                  |
   +------------------+----------------------------+------------------+

                                 Table 1

   *1 and possibly <inputField> value, <authURL>, <tokenURL>, <issuer>







Bucksch                   Expires 24 March 2025                 [Page 9]

Internet-Draft                 autoconfig                 September 2024


4.  Config retrieval for mail clients

   The mail client application, when it needs the configuration for a
   given email address, will perform several steps to retrieve the
   configuration from various sources.

   The steps are ordered by priority.  They may all be requested at the
   same time, but a higher priorty result that is available MUST be
   preferred over a lower priority one, even if the lower priority one
   is available earlier.  Lower priority requests MAY be cancelled, if a
   valid higher priority result has been successfully received.  The
   priority is expressed below with the number before the URL or
   location, with lower numbers meaning higher priority, e.g. 1.2 has
   higher priority than 4.1.

   In the URLs below,%EMAILADDRESS% shall be replaced with the email
   address that the user entered and wishes to use, and %EMAILDOMAIN%
   shall be replaced with the email domain extracted from the email
   address.  For example, for "fred@example.com", the email domain is
   "example.com", and for "fred@test.cs.example.net", the email domain
   is "test.cs.example.net".

   For full support of this specification, all "Required" and
   "Recommended" mechanisms MUST be implemented and working.  For
   partial support of this specification, all "Required" mechanisms MUST
   be implemented and working, and in this case, you shall make explicit
   when advertizing or referring to auto config that there is only
   partial support of this specification.

4.1.  Mail provider

   First step is to directly ask the mail provider and allow it to
   return the configuration.  This step ensures that the protocol is
   decentralized and the mail provider is in control of the
   configuration issued to mail clients.

   *  1.1. https://autoconfig.%EMAILDOMAIN%/mail/config-
      v1.1.xml?emailaddress=%EMAILADDRESS% (Required)

   *  1.2. https://%EMAILDOMAIN%/.well-known/autoconfig/mail/config-
      v1.1.xml (Optional)

   *  1.3. http://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml
      (Optional)

   For example:





Bucksch                   Expires 24 March 2025                [Page 10]

Internet-Draft                 autoconfig                 September 2024


   *  1.1. https://autoconfig.example.com/mail/config-
      v1.1.xml?emailaddress=fred@example.com

   *  1.2. https://example.com/.well-known/autoconfig/mail/config-
      v1.1.xml

   *  1.3. http://autoconfig.example.com/mail/config-v1.1.xml

   Step 1.3. is mainly for legacy servers.  Many current deployments use
   this HTTP URL.

4.1.1.  Customzing the config for a specific user

   To allow the mail provider to return a configuration adjusted for
   that mailbox, the client sends the email address as query parameter
   in URL 1.1.  This allows the mail provider to e.g. separate mailboxes
   on geographically local mail servers, e.g. a mail server located in
   the same office building where an employee works.

   However, while the protocol allows for such heterogenous
   configurations, mail providers are discouraged from doing so, and are
   instead encouraged to provide one single configuration for all their
   users.  For example, DNS resolution based on location, mail proxy
   servers, or other techniques as necessary, can be used to route the
   traffic and host the mail efficiently.

   This mechanism also allows the autoconfig server to map the email
   address to a username that cannot be expressed using the Placeholders
   (see section).  However, this method is discouraged.  Instead, the
   email server login should accept email addresses as username, and
   doing the mapping to internal usernames at login time, which avoids
   the need for the client to know a different username.

   To avoid that email addresses can be tested for validity, whenever
   customized configs are returned, the autoconfig server should respond
   to non-existing email addresses with a configuation that appears to
   be real and is similar in structure to real configurations, e.g. a
   random host out of the pool of actual hosts.

4.2.  Central database

   The ISPDB contains the configurations for most mail providers with a
   market share larger than 0.1%, and contains configurations for half
   of the email accounts in the world.







Bucksch                   Expires 24 March 2025                [Page 11]

Internet-Draft                 autoconfig                 September 2024


   This is a useful fallback for mail providers which do not host a
   config server described in the previous step.  Using a central
   database (ISPDB) of mail configurations for the large mail providers
   will increase the success rate of finding a valid configuration
   drastically, up to 10-fold.

   The mail client application may choose the mail config database
   provider.  A public mail config database is available at base URL
   https://v1.ispdb.net/.

   %ISPDB% below is the base URL of that database.

   *  2.1. %ISPDB%%EMAILDOMAIN% (Recommended)

   For example:

   *  2.1. https://v1.ispdb.net/geologist.com (https://v1.ispdb.net/
      geologist.com)

4.3.  MX

   Many companies do not maintain their own mail server, but let their
   email be hosted by a hosting company, which is then responsible for
   the email of dozens or thousands of domains.  For these hosters, it
   may be difficult to set up the configuration server (step 1.1.) with
   valid TLS certificate for each of their customers, and to convince
   their customers to modify their root DNS specifically for autoconfig.
   On the other side, the ISPDB can only contain the hosting company and
   cannot know all their customers.  To handle such domains, the
   protocol first needs to find the server hosting the email.

   If the previous mechanisms yield no result, the client may perform a
   DNS MX lookup on the email domain, and retrieve the MX server
   (incoming email server) for that domain.  Only the highest priority
   MX hostname is considered.  From that MX hostname, 2 values are
   extracted:

   *  Remove the first component from the MX hostname, i.e. everything
      up to and including the first ., and use that as value for
      %MXFULLDOMAIN%.

   *  Extract only the second-level domain from the MX hostname, and use
      that as value for %MXBASEDOMAIN%. To determine the second-level
      domain, use the Public Suffic List (https://publicsuffix.org) or a
      similarly suited method, to correctly handle domains like ".co.uk"
      and ".com.au".

   For example:



Bucksch                   Expires 24 March 2025                [Page 12]

Internet-Draft                 autoconfig                 September 2024


   *  For "mx.example.com", the MXFULLDOMAIN and MXBASEDOMAIN are both
      "example.com".

   *  For "mx.example.co.uk", the MXFULLDOMAIN and MXBASEDOMAIN are both
      "example.co.uk".

   *  For "mx.premium.europe.example.com", the MXFULLDOMAIN is
      "premium.europe.example.com" and the MXBASEDOMAIN is
      "example.com".

   Then, attempt to retrieve the config for these MX domains, using the
   previous methods:

   *  3.1. https://autoconfig.%MXFULLDOMAIN%/.well-known/mail-
      v1.xml?emailaddress=%EMAILADDRESS% (Required)

   *  3.2. https://autoconfig.%MXBASEDOMAIN%/.well-known/mail-
      v1.xml?emailaddress=%EMAILADDRESS% (Recommended)

   *  3.3. %ISPDB%%MXFULLDOMAIN% (Recommended)

   *  3.4. %ISPDB%%MXBASEDOMAIN% (Recommended)

   For example:

   *  3.1. https://autoconfig.premium.europe.example.com/.well-known/
      mail-v1.xml?emailaddress=fred@example.com

   *  3.2. https://autoconfig.example.com/.well-known/mail-
      v1.xml?emailaddress=fred@example.com

   *  3.3. https://v1.ispdb.net/premium.europe.example.com

   *  3.4. https://v1.ispdb.net/example.com

4.4.  Local disk

   For testing purposes, you may want to define a location on the disk,
   relative to the application installation directory, or relative to
   the user configuration directory, which may contain a configuration
   file for a specific domain, and which your application will use, if
   the above methods fail.

   *  4.1. %USER_CONFIGURATION_DIR%/isp/%EMAILDOMAIN%.xml (Optional)

   *  4.2. %APP_INSTALL_DIR%/isp/%EMAILDOMAIN%.xml (Optional)

   For example:



Bucksch                   Expires 24 March 2025                [Page 13]

Internet-Draft                 autoconfig                 September 2024


   *  4.1. /home/fred/.config/yourapp/isp/example.com.xml

   *  4.2. /opt/yourapp/isp/example.com.xml

4.5.  Other mechanisms

   You may want to implement other mechanisms to find a configuration,
   for example Exchange AutoDiscover, DNS SRV, or heuristic guessing.
   If you implement such alternative methods, and if they are less
   secure than some of the mechanisms provided here, the alternative
   methods SHOULD be considered only with lower priority (as defined
   above) than the more secure mechanisms defined here.  For evaluating
   other mechanisms, use similar criteria as outlined in section
   "Security considerations".

4.6.  Manual configuration

   If the above mechanisms fail to provide a working configuration, or
   if the user explicitly chooses so, you SHOULD give the end user the
   ability to manually enter a configuration, and use that configuration
   to configure the account.

5.  Config validation

5.1.  User approval

   Independent of the mechanisms used to find the configuration, before
   using that configuration, you SHOULD display that configuration to
   the end user and let him confirm it.  While doing so:

   *  At least the second-level domain name(s) of the hostnames involved
      MUST be shown clearly and with high prominence.

   *  The client MUST NOT cut off parts of long second-level domains, to
      avoid spoofing.  At least 63 characters MUST be displayed.

   *  Care SHOULD be taken with international characters that look like
      ASCII characters, but have a different code.

5.2.  Login testing

   After the user confirmed the configuration, you SHOULD test the
   configuration, by attempting a login to each server configured.  Only
   if the login succeeded, and the server is working, should the
   configuration be saved and retrieving and sending mail be started.






Bucksch                   Expires 24 March 2025                [Page 14]

Internet-Draft                 autoconfig                 September 2024


5.3.  OAuth2 windows

   If the configuration contains OAuth2 authentication, or any other
   authentication that uses a web browser with URL redirects, you MUST
   show the full URL or the second-level domain of the current page to
   the end user, at all times, including after page changes, URL changes
   or redirects.  This allows the end user to verify that he is logging
   in at the expected page, e.g. the login server of their company.

   (Editor's note: Not really part of autoconfig, but autoconfig can
   enable OAuth2, and it's important that this is implemented correctly
   by mail applications.)

6.  Config publishing for mail providers

   Mail service providers who want to support this specification and
   publish the mail configuration for their own mail service, so that
   mail client apps can be automatically configured, SHOULD follow this
   section as guideline and MUST respect the definitions in this
   specification.

   *  Configuration fields MUST NOT contain invalid or non-working
      configuration data.

   *  The provided configuration MUST be working, and SHOULD use state-
      of-the-art security.

   *  Configurations MUST be public and MUST NOT require authentication
      (see below).

6.1.  Config location for single domain

   The configuration file SHOULD be published at the URL for step 1.1.,
   i.e.

   *  https://autoconfig.%EMAILDOMAIN%/.well-known/mail-
      v1.xml?emailaddress=%EMAILADDRESS%

   e.g. for fred@example.com

   *  https://autoconfig.example.com/.well-known/mail-
      v1.xml?emailaddress=fred@example.com

   For backwards compatibility with older mail clients, step 1.2. should
   also be implemented.






Bucksch                   Expires 24 March 2025                [Page 15]

Internet-Draft                 autoconfig                 September 2024


6.2.  Config location for domain hosters

   For mail providers which host entire domains for their business
   customers, the same URL as listed in the previous section is
   preferred.

   Alternatively, the configuration file SHOULD be published at the
   location for step 3.1., i.e.

   *  https://autoconfig.%MXFULLDOMAIN%/.well-known/mail-
      v1.xml?emailaddress=%EMAILADDRESS%

   E.g. if the MX server for customer domain example.net is
   "mx.premium.europe.example.com", then the config file should be at

   *  https://autoconfig.premium.europe.example.com/.well-known/mail-
      v1.xml?emailaddress=fred@example.net

   For backwards compatibility with older mail clients, step 3.2. should
   also be implemented.

6.3.  No authentication for config

   Any of the above URLs for retrieving the config file MUST NOT require
   authentication, but MUST be public.

   This is because the config contains the authentication method.
   Without knowing the config, the client does not know which
   authentication method is required and which username form (e.g.
   username "fred" or "fred@example.com" or "fred\EXAMPLE") to use.
   Given that the config is required for authentication, the config
   itself cannot require authentication.

6.4.  Return config for non-existing email addresses

   Servers SHOULD return a valid config, even if the email address sent
   as URL parameter does not exist.  Otherwise, spammers or attackers
   would be able to test the validity of email addresses.  This is true
   even if the config server needs the email address to determine which
   of multiple configurations is correct.  In such a configuration, if
   the client sends a non-existing email address, the config server
   SHOULD return one of the valid configuations, so that valid and
   invalid email addresses are indistiguishable.








Bucksch                   Expires 24 March 2025                [Page 16]

Internet-Draft                 autoconfig                 September 2024


6.5.  OAuth2 requirements

   If OAuth2 is used, the OAuth2 server MUST adhere to the mAuth
   (https://benbucksch.github.io/mauth-spec/draft-mauth.html)
   specification.

   The OAuth2 server MUST either accept the public client ID as given in
   the config file, without secret, or MUST allow the string open as
   client ID, or both.

   There are also specific requirements for expiry times and the login
   page, which are needed for mail client applications to work.

7.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

8.  Alternatives considered

8.1.  DNSSEC

   Due to their top-level domain, some domains do not have DNSSEC
   available to them, even if they would like to deploy it.

   Even where the top-level domain supports it, DNSSEC is currently
   deployed in only 1% of domains, with adoption rates falling instead
   of rising, due to the difficulties of administrating it correctly.

   Therefore, DNSSEC cannot be relied on in this specification, and DNS
   must be considered insecure for the purposes of this specification.

8.2.  DNS SRV

   DNS SRV protocols (RFC 2782, RFC 6186) are not used here, for 2
   reasons:

   1.  DNS SRV relies on insecure DNS and the config can therefore be
       trivially spoofed by an attacker.  See also DNSSEC above.

   2.  DNS SRV does not provide all the necessary configuration
       parameters.  For example, we need all of:






Bucksch                   Expires 24 March 2025                [Page 17]

Internet-Draft                 autoconfig                 September 2024


   *  the username form ("fred@example.com", or "fred", or
      "fred\EXAMPLE", or even a username with no relation to the email
      address)

   *  authentication method (password, CRAM-MD5, OAuth2, SSL client
      certificate)

   *  authentication method parameters (e.g.  OAuth parameters)

   and other parameters.  If any of these parameters are not configured
   right, the configuration won't work.  While these parameters could
   theoretically be added to DNS SRV, that would mean a new
   specification and render the idea void that this is a protocol that
   already exists, is standardized and deployed.  It is unlikely that
   all DNS SRV records would be updated with the new values.  Therefore,
   it does not solve the problem.

   This specification was created as an answer to these deficiencies and
   provides an alternative to DNS SRV.

8.3.  CAPABILITIES

   In the wild deployments from actual ISPs show that protocol-specific
   commands to find available authentication methods, e.g.  IMAP
   CAPABILITIES or POP3 CAPA, are not reliable.  Many email servers
   advertize authentication methods that do not work.

   Some IMAP servers are default configured to list all SASL
   authentication methods that have corresponding libraries installed on
   the system, independent on whether they are actually configured to
   work.  The client receives a long list of authentication methods, and
   many of them do not work.  Additionally, the server response may be
   only "authentication failed" and may not indicate whether the method
   failed due to lack of configuration, or because the password was
   wrong.  Because some authentication servers lock the account after 3
   failed login attempts, and it may also fail due to unrelated reasons
   (e.g. username form, wrong password, etc.), the client cannot blindly
   issue countless login attempts.  Locking the account must be avoided.
   So, simply attempting all methods and seeing which one works is not
   an option for the email client.

   Additionally, some email servers advertize Kerberos / GSSAPI, but
   when trying to use it, the method fails, and also runs into a long 2
   minute timeout in some cases.  End users consider that to be a broken
   app.

   Additionally, such commands are protocol specific and have to be
   implemented in multiple different ways.



Bucksch                   Expires 24 March 2025                [Page 18]

Internet-Draft                 autoconfig                 September 2024


   Finally, some non-mail protocols may not support capabilties commands
   that include authentication methods.

9.  Security Considerations

9.1.  Risk

   If an attacker can provide a forged configuration, the provided mail
   hostname and authentication server can be controlled by the attacker,
   and the attacker can get access to the plain text password of the
   user.  The attack can be implemented as man-in-the-middle, so the end
   user might receive mail as expected and never notice the attack.

   An attacker gaining the plain text password of a real user is a very
   significant threat for the organization, not only because mail itself
   can contain sensitive information and can be used to issue orders
   within the organization that have wide-ranging impact, but given
   single-sign-on solutions, the same username and password may give
   access to other resources at the organization, including other
   computers or, in the case of admin users, even adminstrative access
   to the core of the entire organization.

   Multi-factor authentication might not defend against such attacks,
   because the user may believe to be logging into his email and
   therefore comply with any multi-factor authentication steps required.

9.2.  DNS

   Any protocol that relies on DNS without further validation, e.g.
   http, should be considered insecure.  Even if an http URL redirects
   to a https URL, and the domain of the https URL cannot be validated
   against the email domain, that is still insecure.  This also applies
   to the DNS MX lookup and the https calls that base on its results, as
   described in section "MX".

   One possible mitigation is to use multiple different DNS servers and
   verify that the results match, e.g. to use the native DNS resolver of
   the operating system, and additionally also query a hardcoded DoH
   (DNS over HTTPS) server.  Nonetheless, the result should be used with
   care.

   Such insecure configs may only be used, if the end user confirms the
   config, particularly the resulting second-level domains.  See section
   "User approval".







Bucksch                   Expires 24 March 2025                [Page 19]

Internet-Draft                 autoconfig                 September 2024


9.3.  Config updates

   Part of the security properties of this protocol assume that the
   timeframe of possible attack is limited to the moment when the user
   manually sets up a new mail client.  This moment is triggered by the
   end user, and a rare action - e.g. maybe once per year or even less,
   for typical setups -, so an attacker has limited chances to run an
   attack.  While not a complete protection on its own, this reduces the
   risk significantly.

   However, if the mail client does regular configuration updates using
   this protocol, this security property is no longer given.  For
   regular configuration updates, the mail client MUST use only
   mechanisms that are secure and cannot be tampered with by an active
   attacker.  Furthermore, the user SHOULD still approve config changes.

   But even with all these protections implemented, the mail client
   vendor should make a security assessment for the risks of making such
   regular updates.  The mail client vendor should consider that servers
   can be hacked, and most users simply approve changes proposed by the
   app, so these give only a limited protection.

9.4.  Server security

   Given that mail clients will trust the configuration, the server
   delivering it needs to be secure.  Even though we call it "database",
   static configuration files that are generated before deployment in
   combination with a static web server offer better security and
   significantly better performance than dynamic queries from a database
   and responses generated on-the-fly on request.  If a custom server is
   used, it SHOULD be updated regularly and hosted on a dedicated secure
   server with all unnecessary services and server features turned off.

   Additions and modifications to the configurations are applicable to
   all respective users and must be made with care.  The authenticity of
   the configuration MUST be verified from authorative sources.  Server
   hostnames MUST be compared with the email domain names they are
   serving, and if they differ, the ownership of the server hostnames
   MUST be validated.

   For these reasons, mail clients may use the public mail config
   database mentioned above.

   The risk is mitigated to some degree by section "User approval".







Bucksch                   Expires 24 March 2025                [Page 20]

Internet-Draft                 autoconfig                 September 2024


10.  IANA Considerations

   This document has no IANA actions.

11.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

Acknowledgments

   TODO acknowledge.

Author's Address

   Ben Bucksch
   Beonex
   Email: ben.bucksch@beonex.com



























Bucksch                   Expires 24 March 2025                [Page 21]