Network Working Group B. Bucksch
Internet-Draft Beonex
Intended status: Informational 6 November 2023
Expires: 9 May 2024
Mail Autoconfig
draft-bucksch-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-bucksch-autoconfig/.
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 9 May 2024.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Bucksch Expires 9 May 2024 [Page 1]
Internet-Draft autoconfig November 2023
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 . . . . . . . . . . . . . . . . . . . . 8
4. Config retrieval . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Mail provider . . . . . . . . . . . . . . . . . . . . . . 9
4.2. Central database . . . . . . . . . . . . . . . . . . . . 10
4.3. MX . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4. Local disk . . . . . . . . . . . . . . . . . . . . . . . 12
4.5. Other mechanisms . . . . . . . . . . . . . . . . . . . . 12
4.6. Manual configuration . . . . . . . . . . . . . . . . . . 12
5. Config validation . . . . . . . . . . . . . . . . . . . . . . 12
5.1. User approval . . . . . . . . . . . . . . . . . . . . . . 12
5.2. Login testing . . . . . . . . . . . . . . . . . . . . . . 13
6. OAuth2 windows . . . . . . . . . . . . . . . . . . . . . . . 13
7. Conventions and Definitions . . . . . . . . . . . . . . . . . 13
8. Alternatives considered . . . . . . . . . . . . . . . . . . . 13
8.1. DNSSEC . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.2. DNS SRV . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.3. CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . 14
9. Security Considerations . . . . . . . . . . . . . . . . . . . 15
9.1. Risk . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.2. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.3. Config updates . . . . . . . . . . . . . . . . . . . . . 16
9.4. Server security . . . . . . . . . . . . . . . . . . . . . 16
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
11. Normative References . . . . . . . . . . . . . . . . . . . . 17
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 17
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17
Bucksch Expires 9 May 2024 [Page 2]
Internet-Draft autoconfig November 2023
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)
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.
Bucksch Expires 9 May 2024 [Page 3]
Internet-Draft autoconfig November 2023
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
example.com
example.net
Google Mail
GMail
pop.example.com
995
SSL
%EMAILLOCALPART%
password-cleartext
true
true
14
optional: the user's password
smtp.googlemail.com
587
STARTTLS
%EMAILLOCALPART%
password-cleartext
client-IP-address
true
true
optional: the user's password
Configure Thunderbird 2.0 for IMAP
Thunderbird 2.0 mit IMAP konfigurieren
%EMAILADDRESS%
http-basic
https://contacts.example.com/remote.php/dav
Bucksch Expires 9 May 2024 [Page 6]
Internet-Draft autoconfig November 2023
%EMAILADDRESS%
http-basic
https://calendar.example.com/remote.php/dav
%EMAILADDRESS%
http-basic
https://share.example.com/remote.php/dav
%EMAILADDRESS%
Bucksch Expires 9 May 2024 [Page 7]
Internet-Draft autoconfig November 2023
Elise Bauer
Check 'Enable IMAP and POP' in Google settings page
Schalten Sie 'IMAP und POP aktivieren' auf der Google Einstellungs-Seite an
3.2. Formal definition
TODO Schema for XML
4. Config retrieval
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.
Bucksch Expires 9 May 2024 [Page 8]
Internet-Draft autoconfig November 2023
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.
Mail providers MUST return a working configuration, with state-of-
the-art security. Configuration fields MUST NOT contain invalid or
non-working configuration data.
To allow the mail provider to return a configuration adjusted for
that mailbox, the client sends the email address as query parameter.
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.
* 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 (Recommended)
* 1.3. http://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml
(Optional)
For example:
Bucksch Expires 9 May 2024 [Page 9]
Internet-Draft autoconfig November 2023
* 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
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.
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://autoconfig.thunderbird.net/v1.1/. (TODO change ISPDB URL)
%ISPDB% below is the base URL of that database.
* 2.1. %ISPDB%%EMAILDOMAIN% (Recommended)
For example:
* 2.1. https://autoconfig.thunderbird.net/v1.1/geologist.com
(https://autoconfig.thunderbird.net/v1.1/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.
Bucksch Expires 9 May 2024 [Page 10]
Internet-Draft autoconfig November 2023
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 %MXMAINDOMAIN%. 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:
* For "mx.example.com", the MXFULLDOMAIN and MXMAINDOMAIN are both
"example.com".
* For "mx.example.co.uk", the MXFULLDOMAIN and MXMAINDOMAIN are both
"example.co.uk".
* For "mx.premium.europe.example.com", the MXFULLDOMAIN is
"premium.europe.example.com" and the MXMAINDOMAIN is
"example.com".
Then, attempt to retrieve the config for these MX domains, using the
previous methods:
* 3.1. https://autoconfig.%MXFULLDOMAIN%/mail/config-
v1.1.xml?emailaddress=%EMAILADDRESS% (Recommended)
* 3.2. https://autoconfig.%MXMAINDOMAIN%/mail/config-
v1.1.xml?emailaddress=%EMAILADDRESS% (Recommended)
* 3.3. %ISPDB%%MXFULLDOMAIN% (Recommended)
* 3.4. %ISPDB%%MXMAINDOMAIN% (Recommended)
For example:
* 3.1. https://autoconfig.premium.europe.example.com/mail/config-
v1.1.xml?emailaddress=fred@example.com
* 3.2. https://autoconfig.example.com/mail/config-
v1.1.xml?emailaddress=fred@example.com
Bucksch Expires 9 May 2024 [Page 11]
Internet-Draft autoconfig November 2023
* 3.3. https://autoconfig.thunderbird.net/v1.1/
premium.europe.example.com
* 3.4. https://autoconfig.thunderbird.net/v1.1/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:
* 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:
Bucksch Expires 9 May 2024 [Page 12]
Internet-Draft autoconfig November 2023
* 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.
6. 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.)
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.
Bucksch Expires 9 May 2024 [Page 13]
Internet-Draft autoconfig November 2023
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:
* 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
Bucksch Expires 9 May 2024 [Page 14]
Internet-Draft autoconfig November 2023
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.
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.
Bucksch Expires 9 May 2024 [Page 15]
Internet-Draft autoconfig November 2023
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".
Such insecure configs may only be used, if the end user confirms the
config, particularly the resulting second-level domains. See section
"User approval".
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.
Bucksch Expires 9 May 2024 [Page 16]
Internet-Draft autoconfig November 2023
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".
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,
.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
Acknowledgments
TODO acknowledge.
Author's Address
Ben Bucksch
Beonex
Email: ben.bucksch@beonex.com
Bucksch Expires 9 May 2024 [Page 17]