]> Beonex

ben.bucksch@beonex.com

art mailmaint config configuration autoconfig autodiscover mail email IMAP POP3 SMTP JMAP A protocol that allows email applications to set up mail accounts and related accounts with only the email address and password. It defines how service providers can publish the account configuration, so that email applications can automatically find a working configuration. It reduces setup friction for their users, and calls to the support for the service provider. Although the discovery process starts with an email address, the protocol is not limited setting up email accounts, but can also set up calendar, contact and file sync, video conference accounts and other accounts that are connected to the same user account. This protocol uses a well-known address and DNS lookups, based on the email address domain, to find the XML configuration file for the service provider. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the mailmaint Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Configuring email, calendar and contacts client applications for a given user account at a specific service provider is often a tedious, error-prone and unnerving process. Even technical users struggle to find the right combination of hostname, port number, security protocols, authentication methods and forms of username. Less technical users often abort entirely. This difficulty is one of the primary factors why many users use provider-specific applications which use proprietary internal protocols instead of generic provider-independent client applications that use open protocols specified by the IETF. This in turn leads to significantly less choice for end users in their everyday user experience for communication, already today. Long-term, this leads to an errosion of standards support and the ability for end users to use the software of their choice. This protocol allows users to set up their existing email account in a email client application, by entering only their name, email address, and password. The application, by means of the Autoconfig protocol 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. Calendar, contact and file sync, video conference accounts and other accounts that are connected to the same user account can be set up at the same time. The protocol works by first determining the domain from the email address, and then 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. While this Autoconfig protocol was originally conceived for configuring mail clients, it can also be used for accounts of other types, like contacts and calendar sync, chat, video conference, or online publishing. The primary concept and limitation here is that these accounts are hosted by the same provider as the email address. This protocol is in active production use since 15 years by major email clients, and the configuration database contains configurations for over 80% of all email accounts.

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 when, and only when, they appear in all capitals, as shown here.

Data format Whether the ISP or a common central database returns the configuration, the resulting document MUST have the following data format and qualities. The format is in . The MIME type is text/xml. The seconds below define the XML and its meaning. Most sections start with a concrete example of the elements that they define.

XML configuration file example The following example shows the syntax of the XML configuration file.

example.com example.net Google Workspace GMail imap.example.com 993 SSL password-cleartext %EMAILADDRESS% pop.example.com 995 SSL password-cleartext %EMAILADDRESS% smtp.googlemail.com 587 STARTTLS password-cleartext %EMAILADDRESS% https://jmap.example.com OAuth2 Basic %EMAILADDRESS% https://mail.example.com/EWS/Exchange.asmx %EMAILADDRESS% Basic https://mail.example.com/Microsoft-Server-ActiveSync %EMAILADDRESS% OAuth2 Configure mail app for IMAP Email mit IMAP konfigurieren https://contacts.example.com/remote.php/dav Basic %EMAILADDRESS% https://calendar.example.com/remote.php/dav Basic %EMAILADDRESS% https://share.example.com/remote.php/dav Basic %EMAILADDRESS% wss://example.com:5281/xmpp-websocket Basic %EMAILADDRESS% xmpp.example.com 5223 TLS password-cleartext %EMAILADDRESS% https://talk.example.com/login OAuth2 %EMAILADDRESS% https://login.example.com/auth https://login.example.com/token login.example.com IMAP POP3 SMTP CalDAV CardDAV WebDAV offline_access open give-me-your-password ]]>

The formal grammar is in appendix RELAX NG schema.

Global elements The file starts with an XML header, e.g. <?xml version="1.0"?>, and is encoded in UTF-8 without BOM.

clientConfig The root element of the XML file is <clientConfig version="1.2">. The version is 1.2 for the version defined in this specification. 1.1 is a compatible previous version of this protocol: . Higher versions are for future specifications. The client MUST NOT reject a configuration file solely based on the version number.

emailProvider Example:

]]>

RELAX NG:

Element <emailProvider> is within the root element. This element has no semantic purpose and exists for legacy reasons only, but its content is significant. The id is a unique string that typically matches the primary domain of the provider. The syntax of the ID is the same as for domain and hostname. Within <emailProvider> are <domain>, <displayName> and <displayShortName>, <documentation>, <incomingServer> and <outgoingServer>.

domain Example:

example.com example.net example-hosting.com ]]>

RELAX NG:

The content of the <domain> element defines which email addresses this config is valid for. For example, a configuration with <domain>example.com</domain> is valid for email address fred@example.com. Multiple <domain> elements may be included, which means that the configuration is valid for all of these domains. Their order has no meaning - they may be sorted by number of users, importance to the provider, or alphabethically. <domain purpose="mx"> specifies the domain name of the MX server of this provider. It is used during the configuration file lookup using MX server names, as specified in MX. If the email address that is to be configured has an MX server that is within the domain given by <domain purpose="mx">, then this configuration is applicable for that email address. Adding the purpose attribute is RECOMMENDED.

displayName and displayShortName Example:

Google Workspace GMail ]]>

RELAX NG:

The <displayName> element contains the name of the provider, e.g. as preferred by the marketing of the provider itself. It SHOULD be no longer than 30 characters, but MUST be no longer than 60 characters. The <displayShortName> element contains the name of the provider, as typically used by end users. It SHOULD be no longer than 12 characters, and it MUST NOT be longer than 20 characters. Both elements may used to display the provider or account name by the mail client UI, which has reasonable expectations on length and expressiveness. The <displayShortName> in particular may be used by the mail client together with the email address as partial base for the account name, and during everyday use of the app to represent the account, so it SHOULD be short, distinctive and represent the provider in the way end users refer and think of it.

documentation Example:

Configure mail app for IMAP Email mit IMAP konfigurieren ]]>

RELAX NG:

This is purely informational and not required for the automatic setup. This element contains the end-user help webpage at the provider that describes the mail server settings. The configuration may be based on that page, but does not necessarily have to match it, e.g. when a better configuration is available than the one described on the webpage. The url attribute contains the URL of the webpage. The <descr> content describes the content and purpose of the page and why it's referenced here. Multiple <descr> elements with different lang attributes are allowed, whereby the lang attribute contains the 2-letter ISO language code, like the HTML lang attribute.

Server sections <incomingServer type="jmap">, <calendar type="carddav"> etc. RELAX NG:

The type attribute specifies the wire protocol that this server uses. See type below. <incomingServer> specifies the server that the mail client retrieves email from and submits changes to. In many protocols, this server is also used for sending email. <outgoingServer> is used for sending, if <incomingServer> does not support that directly. This is currently used only for SMTP in combination with IMAP and POP3. <incomingServer> and <outgoingServer> are within element <emailProvider>, whereas <calendar>, <addressbook>, <fileShare>, <chatServer> and <videoConference> are within the root element <clientConfig>, i.e. one level higher. Other than that, they work the same. In some protocols, the <incomingServer> server additionally provides calendars, addressbooks, and other data. For such protocols, the same server is not repeated in other specific server sections like <calendar>. Calendar-only clients supporting such multi-purpose protocols MUST read the <incomingServer> (nonewithstanding that it's within legacy element <emailProvider>) and test and use the parts of the protocol needed for their functionality.

Multiple server sections Server sections of the same type (like <incomingServer> or <calendar>) may appear multiple times in the same configuration file. In this case, the one listed first is preferred by the configuration provider. Unless the client has specific other requirements, it SHOULD pick the first config. The client may deviate from this recommendation, because the client doesn't support a higher-priority protocol, e.g. a JMAP configuraion is listed first and is the most preferred, but the client does not support JMAP yet, or the client doesn't support a configuration setting, e.g. it doesn't support STARTTLS, or the configuration specifies only an OAuth2 authentication and the client either doesn't implement OAuth2, or there is a problem in the OAuth2 flow with this provider, or the client has a specific policy to prefer another configuration, e.g. a STARTTLS configuration is listed before a direct TLS config, and the client has a policy of preferring direct TLS, or likewise the client prefers IMAP over POP3. Server types, elements and protocols that the client does not support MUST be ignored and the client MUST continue to parse the other server sections, which may contain configs that the client understands and supports. The client ignores the file only if there is no supported and working configuration found.

type The type attribute on the server section element specifies the wire protocol that this server uses. Element Type Base Name Specification incomingServer jmap URL JMAP , , , et al incomingServer imap TCP IMAP or , et al incomingServer pop3 TCP POP3 , outgoingServer smtp TCP SMTP , calendar caldav URL CalDAV addressbook carddav URL CardDav fileShare webdav URL WebDAV chatServer xmpp URL XMPP , , chatServer xmpptcp TCP XMPP , chatServer matrix URL Matrix setupServer managesieve TCP ManageSieve , incomingServer ews URL Exchange Web Services   incomingServer activeSync URL ActiveSync   incomingServer graph URL Microsoft Graph   Other protocol names can be added using an IANA registry. See the corresponding section below.

URL-based protocols

https://jmap.example.com/session Basic %EMAILADDRESS% ]]>

For server sections with protocols that are based on HTTPS or other URLs, the following elements are supported:

url Example:

https://jmap.example.com/session ]]>

RELAX NG:

The content of the <url> element contains the where to contact the server. The URL scheme will normally be HTTPS and the URL starts with https:// (). Some protocols may use other schemes, e.g. WebSockets wss:// ().

authentication Examples:

OAuth2 Basic ]]>

RELAX NG:

The content of the <authentication> element defines which HTTP authentication method to use. The system="http" attribute signals that the value refers to a WWW-Authenticate mechanism. Basic: Authenticate to the HTTP server using WWW-Authenticate: Basic. See . Digest: Authenticate to the HTTP server using WWW-Authenticate: Digest. See OAuth2: Authenticate to the HTTP server using WWW-Authenticate: Bearer. See . The provider MUST adhere to the requirements defined in OAuth2 requirements. Note: The XML element for OAuth2 is <authentication>OAuth2</authentication> without system attribute. <authentication system="http">Bearer</authentication> is invalid. The rules as specified in Multiple authentication alternatives and Authentication verification and fallback apply here as well.

username Examples (alternatives):

%EMAILADDRESS% fred ]]>

RELAX NG:

The username to use for the authentication method. Placeholders MUST be replaced before using the actual value. See Placeholders.

TCP-based protocols For server sections with protocols that are based on TCP, the following elements are supported:

imap.example.com 993 SSL password-cleartext %EMAILADDRESS% ]]>

hostname Example:

imap.example.com ]]>

RELAX NG:

The content of the <hostname> element contains the fully qualified hostname of the server.

port Example:

993 ]]>

RELAX NG:

The content of the <port> element is an integer and contains the TCP port number at the hostname. The port is typically specific to the combination of the wire protocol and socketType.

socketType Example:

SSL ]]>

RELAX NG:

The content of the <socketType> element specifies whether to use direct TLS, STARTTLS, or none of these. SSL: Directly contact the TCP port using TLS. TLS version 1.2 or higher SHOULD be used. Higher versions may be required based on security situation, server support, and client policy decisions. STARTTLS: Contact the TCP port first using an unencrypted plain socket, then upgrade to TLS using the protocol-specific STARTTLS specification . With this configuration, STARTTLS MUST be used and TLS MUST be used after the STARTTLS upgrade. If the upgrade to TLS fails for whatever reason, the client MUST disconnect and MUST NOT try to authenticate. This prevents downgrade attacks that could otherwise steal passwords, user data, and impersonate users. plain: Unencrypted connection, with neither TLS nor STARTTLS. May be needed for local servers. Deprecated.

TLS validation In all cases where TLS is used, either directly or using STARTTLS, the client MUST validate the TLS certificate and ensure that the certificate is valid for the hostname given in this config. If not, or if the TLS certificate is otherwise invalid, the client MUST either disconnect or MAY warn the user of the dangers and ask for user confirmation. Such fallback with warning and confirmation is allowed only at original configuration and MUST NOT be allowed during normal everyday connection. If the server had a valid TLS certificate during original configuration and the TLS certificate is later invalid during normal connection, the client MUST disconnect. As an exception, if the problem is that the TLS certificate expired recently, the client MAY choose to not consider that a failure during normal connection and MAY use other recovery mechanisms.

authentication Example:

password-cleartext ]]>

RELAX NG:

The content of the <authentication> element defines which authentication method to use. This can be either an authentication defined by the wire protocol, or a SASL scheme, or a successor to SASL. password-cleartext: Send password in the clear. Uses either the native authentication method defined by the wire protocol (if that is based on plaintext passwords), or a SASL authentication scheme like SASL PLAIN or SASL LOGIN, or a successor. password-encrypted: An encrypted or hashed password mechanism. Includes SASL CRAM-MD5 , DIGEST-MD5 , SCRAM-SHA-256-PLUS , and successors. TLS by itself does not qualify as password-encrypted. NTLM: Legacy Windows login mechanisms NTLM or NTLMv2. GSSAPI: or , a single-signon mechanism based on TCP. TLS-client-cert: On the SSL/TLS layer, after server request, the client sends a TLS client certificate for the user, possibly after letting the user select confirm it. Uses SASL EXTERNAL scheme , Appendix A. OAuth: OAuth. SASL OAUTHBEARER (current) or XOAUTH2 (deprecated) or successors. The provider MUST adhere to the requirements defined in OAuth2 requirements. client-IP-address: Server can be used without any explicit authentication, and the client is admitted based on its IP address. This may be the case for some SMTP servers on local networks. Not supported on the Internet. Deprecated, because it breaks mobile devices.

Recommending specific SASL schemes Example:

SCRAM-SHA-256-PLUS ]]>

A specific SASL scheme MAY be specified using the specific SASL authentication scheme name, e.g. SCRAM-SHA-256-PLUS . To signal that, the <authentication> element SHOULD have the system attribute set to value sasl, i.e. <authentication system="sasl">. In such a case, the server configuration section SHOULD also specify a more generic authentication mechanism as a lower priority alternative. That would make clients use the specific authentication mechanism, if they support it, and other clients will use the more generic authentication mechanism.

Multiple authentication alternatives The <authentication> element may appear multiple times within a server section. In this case, they are ordered from the most to the least preferred method, based on the policy of the provider. If a client does not support a specific authentication scheme, or does not have the conditions to use it, e.g. the client does not have a Client ID for this OAuth2 server, then the client MUST skip this <authentication> element and use the next in the list instead. If none of the authentication methods are supported by the client, the client MUST ignore that server section and use the remaining server sections.

Authentication verification and fallback The client SHOULD test the configuration during setup, with an actual authentication attempt. If the authentication fails, the client decides based on the authentication error code how to proceed. For example, if the authentiocation method itself failed, or the error code indicates a systemic failure, the client SHOULD use a lower-priority authentication method from the list. If the authentication method is working, but the error code indicated that the username or password was wrong, then the client MAY ask the user to correct the password. For that reason, the server SHOULD be specific in the error codes and allow the client to distinguish between an unsupported or non-working authentication method or other systemic failures the client being rejected by the server the user being blocked from login the user authentication failing due to wrong password or username other reasons If the server were to return the same error code for all these cases, the client might tell the user that the password is wrong, and the user starts attempting other passwords, potentially revealing passwords to other higher-value assets, which is highly dangerous. If the authentification succeeded, the client SHOULD take note of the working configutation and use that for all subsequent connections, until an explicit reconfiguration occurs. During normal everyday operation, the client SHOULD NOT fallback nor attempt multiple different authentication methods.

username Examples (alternatives):

%EMAILADDRESS% fred ]]>

RELAX NG:

The username to use for the authentication method. Placeholders MUST be replaced before using the actual value. See next Placeholders.

Placeholders The <username> value may contain placeholders. The following special substrings in the value MUST be replaced by the client, before the value is actually used. Placeholder Replace with Example %EMAILADDRESS% E-Mail-Address of the user fred@example.com %EMAILLOCALPART% Part before @ in the E-Mail-Address fred %EMAILDOMAIN% Part after @ in the E-Mail-Address example.com Some clients MAY also support the same placeholders for the fields <hostname>, <url>, <authURL>, <tokenURL>, <issuer>, <displayName> and <displayShortName>.

XML validation The client SHOULD validate that the configuration file is valid XML, and if the XML syntax is invalid, the client SHOULD ignore the entire file. In contrast, if there are merely unknown elements or attributes, the client MUST NOT ignore the file. The client MUST disregard those elements, attributes and values that it does not support. The presence of unknown elements, attributes or values MUST NOT result in an error. Instead, they are simply ignored and treated as if they don't exist. Compare the rules for <authentication> elements in . If a server section then becomes invalid due to missing information, only that server section is ignored and the other server sections will still be processed. Only if no valid configuration is found in the document, the document as a whole is ignored, but other retrieval mechanisms might produce a different document with a valid configuration. This allows future extensions of the format without breaking existing clients. The RELAX NG schema in RELAX NG schema is written to follow these rules: it accepts unknown elements, attributes, attribute values and element values, so that a validator does not reject a document merely because it uses extensions not defined here.

Configuration retrieval by 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 SHOULD be preferred over a lower priority one, even if the lower priority one is available earlier. Exceptions apply when a higher priority result is either invalid or outdated, or the fetch method is less secure. 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, the implementor SHALL make explicit when advertizing or referring to Autoconfig that there is only partial support of this specification.

Mail provider The 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. emailaddress is Optional) 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: 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.

Customzing the configuration 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. For example, a global company might want to locate the mailbox geographically close to the user, in the same country or even in the same office building. 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 ). 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. Autoconfig servers that customize the returned configuration file to the email address should avoid that email addresses can be tested for validity by hostile parties like spammers or attackers. For that reason, Autoconfig servers SHOULD return a real configuration, even if the email address sent as URL parameter does not exist. If the query contains a non-existing email address, the server should not return an error nor a fake configuration, but rather a random real configuation, e.g. a random host out of the pool of real hosts. Supporting mail clients should test the login before completing setup, so spelling mistakes in the email address will be signaled to the user as login error in later stages of the setup process.

Central database The ISPDB is a central database that 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 that allows mail clients to support mail providers which do not host a configuration server described in the previous step. In practice, this step is required to find a working configuration for most email accounts, and increases the success rate by an order of magnitude. The mail client application may choose the mail configuration database provider. A public mail configuration 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

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 SHOULD perform a DNS MX lookup on the email domain, and retrieve the MX server (incoming SMTP server) for that domain. Only the highest priority MX hostname is considered. From that MX hostname, 2 values are extracted: 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 or a similarly suited method, to correctly handle domains like .co.uk and .com.au. Remove the first component from the MX hostname, i.e. everything up to and including the first ., and use that as value for %MXFULLDOMAIN%. Use it only if it is longer than %MXBASEDOMAIN%. For example: 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 configuration for these MX domains, using the previous methods: 3.1. https://autoconfig.%MXFULLDOMAIN%/mail/config-v1.1.xml?emailaddress=%EMAILADDRESS% (Required. emailaddress is Optional) 3.2. https://autoconfig.%MXBASEDOMAIN%/mail/config-v1.1.xml?emailaddress=%EMAILADDRESS% (Recommended. emailaddress is Optional) 3.3. %ISPDB%%MXFULLDOMAIN% (Recommended) 3.4. %ISPDB%%MXBASEDOMAIN% (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 3.3. https://v1.ispdb.net/premium.europe.example.com 3.4. https://v1.ispdb.net/example.com

Local disk For testing purposes, a mail client 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 the mail client 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/acmemailapp/isp/example.com.xml 4.2. /opt/acmemailapp/isp/example.com.xml

Other mechanisms A mail client may want to implement other mechanisms to find a configuration, for example Exchange AutoDiscover, DNS-SRV , or heuristic guessing. If the mail client implements 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 Security considerations.

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

Configuration validation

User approval Independent of the mechanisms used to find the configuration, before using that configuration, the mail client 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. To avoid spoofing, the client MUST NOT cut off parts of long second-level domains. At least 63 characters MUST be displayed. Care SHOULD be taken with international characters that look like ASCII characters, but have a different code.

Login test After the user confirmed the configuration, the mail client 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.

OAuth2 windows If the configuration contains OAuth2 authentication, or any other kind of authentication that uses a web browser with URL redirects, the mail client 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. The authentication start URL may be the email hoster, but it redirects to a corporate server for login, and then back to the hoster. This allows for setups where the hoster is not allowed to see the plaintext passwords. Showing the URL or hostname allows the end user to verify that he is logging in at the expected page, e.g. the login server of their company, instead of the email hoster's page. It is important that the user verifies that he enters the passwords on the right domain.

Configuration publishing by 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, MUST 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).

Configuration location for single domain The configuration file SHOULD be published at the URL for step 1.1., i.e. https://autoconfig.%EMAILDOMAIN%/mail/config-v1.1.xml e.g. for fred@example.com https://autoconfig.example.com/mail/config-v1.1.xml

Configuration 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 locations for step 3.1. and 3.2., i.e. https://autoconfig.%MXFULLDOMAIN%/mail/config-v1.1.xml https://autoconfig.%MXBASEDOMAIN%/mail/config-v1.1.xml For example, if the MX server for customer domain example.net is mx.premium.europe.example.com, then the configuration file should be at both https://autoconfig.premium.europe.example.com/mail/config-v1.1.xml https://autoconfig.example.com/mail/config-v1.1.xml

No authentication for config Any of the above URLs for retrieving the configuration file MUST NOT require authentication, but MUST be public. This is because the configuration information in the Autoconfig file includes the authentication method. Without the Autoconfig file, the client does not know which authentication method is required and which username form to use (e.g. username fred or fred@example.com or fred\EXAMPLE). Given that this information is required for authentication, the Autoconfig file itself cannot require authentication.

OAuth2 requirements If OAuth2 is used, the OAuth2 server MUST adhere to the specification, including all SHOULD requirements. Given that * authURL * tokenURL * client ID * scope are provided in the AutoConfig response, steps "Fetching the Authorization Server Metadata" and "Dynamic Client Registration" as well as scope names MAY be skipped in favor of the values in the Autoconfig response. The remaining guarantees in the specification that the OAuth2 server gives to the mail client stay in force, including refresh token validity times. The provider MUST allow any client application that acts on behalf of the end user who the mailbox is for. Failure to do so implies a cartell or monopolistic behavior to lock out competing email applications from fulfilling their purpose on behalf of end users, which may be contrary to laws in multiple countries. The OAuth2 server MUST accept the client ID that is given in the configuration file, or if that is not given, implement Dynamic Client Registration in the way as defined by and accept the resulting Client ID, without client secret. It MAY support multiple of those methods. The server MUST NOT employ any methods at any point to block or hinder clients applications that are acting on behalf of end users. The specifications above contain requirements for expiry times and the login page, which are needed for mail client applications to work, and MUST be followed. The OAuth2 scope MUST include all services defined in this configuration file, so that a single user login is sufficient for all services. The resulting refresh and access tokens MUST be valid for all services defined in the configuration file, including for all URL-based protocols like CalDAV and all TCP-based protocols like IMAP.

Security Considerations

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.

DNS Any protocol that relies on DNS without further validation, e.g. http, should be considered insecure. This also applies to the DNS MX lookup and the https calls that base on its results, as described in 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. If such configs are used, the end user MUST explicitly confirm the config, particularly the resulting second-level domains. See User approval.

HTTP HTTP requests may be intercepted, redirected, or altered at the network level. See Risk above. 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. For that reason, clients MUST prefer HTTPS over HTTP during configuration retrieval, within the same retrieval method. If such configs from HTTP are used, the end user MUST explicitly confirm the config, particularly the resulting second-level domains. See User approval.

Configuration 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 configuration 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.

Server security Given that mail clients will trust the configuration, the server delivering the configuration file needs to be secure. A static web server offers better security. The server software SHOULD be updated regularly and hosted on a dedicated secure server with all unnecessary services and server features turned off. For the ISPDB, 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. The risk is mitigated to some degree by User approval.

Alternatives considered

DNSSEC Due to their top-level domain, some domains do not have 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.

DNS SRV DNS SRV protocols are not used here, for 2 reasons: DNS SRV relies on insecure DNS and the configuration can therefore be trivially spoofed by an attacker. See also DNSSEC above. 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.

CAPABILITIES Deployments in the wild 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 / , 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.

Implementations

Clients Currently, this protocol or parts of it has been implemented by: Thunderbird Parula Evolution KMail Kontact K9 Mail and Thunderbird Mobile FairEmail NextCloud email Delta Chat and likely other mail clients.

Servers A large number of email domains already use AutoConfig to provide the configuration to mail clients and allow an automatic setup. Some mail servers automatically provide AutoConfig files that follow this specification, including Stalwart, Mailcow and many others.

IANA Considerations

Registration IANA will create the following registry in a new registry group called "Mail Autoconfig": Registry Name: "Autoconfig Protocol Type Names" Registration Procedure: Specification Required, per Designated Expert: The author of this document.

Contents Table, with fields Element (alphanumeric), Type (alphanumeric), Base (URL or TCP or URL/TCP), Name, Specification, and Additional Elements The registrations need to define: Element: The XML element wrapping the server section. Type: The type attribute value of the server section. Base: Whether the protocol is URL-based or TCP-based, Name: The commonly used name of the protocol Specification: Which RFCs or document specifies the protocol, and Additional Elements: (Optional) Protocol-specific XML elements and their meaning.

Initial registration Element Type Base Name Specification Additional Elements incomingServer jmap URL JMAP RFC 8620, RFC 8621, RFC 8887, RFC 9610 et al   incomingServer imap TCP IMAP RFC 9051 or RFC 3501, et al   incomingServer pop3 TCP POP3 RFC 1939, RFC 5034   outgoingServer smtp TCP SMTP RFC 5321, RFC 2822   calendar caldav URL CalDAV RFC 4791   addressbook carddav URL CardDav RFC 6352   fileShare webdav URL WebDAV RFC 4918   chatServer xmpp URL XMPP RFC 6120, RFC 6121, RFC 7395   chatServer xmpptcp TCP XMPP RFC 6120, RFC 6121   chatServer matrix URL Matrix https://spec.matrix.org   setupServer managesieve TCP ManageSieve RFC 5804, RFC 5228   incomingServer ews URL Exchange Web Services     incomingServer activeSync URL ActiveSync     incomingServer graph URL Microsoft Graph     The Additional Elements field is empty in all of the initial values.

Fastmail Beonex In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document specifies a protocol for clients to efficiently query, fetch, and modify JSON-based data objects, with support for push notification of changes and fast resynchronisation and for out-of- band binary data upload/download. This document specifies a data model for synchronising email data with a server using the JSON Meta Application Protocol (JMAP). Clients can use this to efficiently search, access, organise, and send messages, and to get push notifications for fast resynchronisation when new messages are delivered or a change is made in another client. This document defines a binding for the JSON Meta Application Protocol (JMAP) over a WebSocket transport layer. The WebSocket binding for JMAP provides higher performance than the current HTTP binding for JMAP. This document specifies a data model for synchronising contact data with a server using the JSON Meta Application Protocol (JMAP). The Internet Message Access Protocol Version 4rev2 (IMAP4rev2) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev2 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev2 also provides the capability for an offline client to resynchronize with the server. IMAP4rev2 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; removing messages permanently; setting and clearing flags; parsing per RFCs 5322, 2045, and 2231; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev2 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev2 does not specify a means of posting mail; this function is handled by a mail submission protocol such as the one specified in RFC 6409. The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev1 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev1 also provides the capability for an offline client to resynchronize with the server. IMAP4rev1 includes operations for creating, deleting, and renaming mailboxes, checking for new messages, permanently removing messages, setting and clearing flags, RFC 2822 and RFC 2045 parsing, searching, and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev1 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev1 supports a single server. A mechanism for accessing configuration information to support multiple IMAP4rev1 servers is discussed in RFC 2244. IMAP4rev1 does not specify a means of posting mail; this function is handled by a mail transfer protocol such as RFC 2821. [STANDARDS-TRACK] The Post Office Protocol - Version 3 (POP3) is intended to permit a workstation to dynamically access a maildrop on a server host in a useful fashion. [STANDARDS-TRACK] This document defines a profile of the Simple Authentication and Security Layer (SASL) for the Post Office Protocol (POP3). This extension allows a POP3 client to indicate an authentication mechanism to the server, perform an authentication protocol exchange, and optionally negotiate a security layer for subsequent protocol interactions during this session. This document seeks to consolidate the information related to POP3 AUTH into a single document. To this end, this document obsoletes and replaces RFC 1734, and updates the information contained in Section 6.3 of RFC 2449. [STANDARDS-TRACK] This document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK] This document specifies a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. [STANDARDS-TRACK] This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing calendaring and scheduling information based on the iCalendar format. This document defines the "calendar-access" feature of CalDAV. [STANDARDS-TRACK] This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing contact information based on the vCard format. [STANDARDS-TRACK] Web Distributed Authoring and Versioning (WebDAV) consists of a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, URL namespace manipulation, and resource locking (collision avoidance). RFC 2518 was published in February 1999, and this specification obsoletes RFC 2518 with minor revisions mostly due to interoperability experience. [STANDARDS-TRACK] The Extensible Messaging and Presence Protocol (XMPP) is an application profile of the Extensible Markup Language (XML) that enables the near-real-time exchange of structured yet extensible data between any two or more network entities. This document defines XMPP's core protocol methods: setup and teardown of XML streams, channel encryption, authentication, error handling, and communication primitives for messaging, network availability ("presence"), and request-response interactions. This document obsoletes RFC 3920. [STANDARDS-TRACK] This document defines extensions to core features of the Extensible Messaging and Presence Protocol (XMPP) that provide basic instant messaging (IM) and presence functionality in conformance with the requirements in RFC 2779. This document obsoletes RFC 3921. [STANDARDS-TRACK] This document defines a binding for the Extensible Messaging and Presence Protocol (XMPP) over a WebSocket transport layer. A WebSocket binding for XMPP provides higher performance than the current HTTP binding for XMPP. Sieve scripts allow users to filter incoming email. Message stores are commonly sealed servers so users cannot log into them, yet users must be able to update their scripts on them. This document describes a protocol "ManageSieve" for securely managing Sieve scripts on a remote server. This protocol allows a user to have multiple scripts, and also alerts a user to syntactically flawed scripts. [STANDARDS TRACK] This document describes a language for filtering email messages at time of final delivery. It is designed to be implementable on either a mail client or mail server. It is meant to be extensible, simple, and independent of access protocol, mail architecture, and operating system. It is suitable for running on a mail server where users may not be allowed to execute arbitrary programs, such as on black box Internet Message Access Protocol (IMAP) servers, as the base language has no variables, loops, or ability to shell out to external programs. [STANDARDS-TRACK] A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The WebSocket Protocol enables two-way communication between a client running untrusted code in a controlled environment to a remote host that has opted-in to communications from that code. The security model used for this is the origin-based security model commonly used by web browsers. The protocol consists of an opening handshake followed by basic message framing, layered over TCP. The goal of this technology is to provide a mechanism for browser-based applications that need two-way communication with servers that does not rely on opening multiple HTTP connections (e.g., using XMLHttpRequest or s and long polling). [STANDARDS-TRACK] This document defines the "Basic" Hypertext Transfer Protocol (HTTP) authentication scheme, which transmits credentials as user-id/ password pairs, encoded using Base64. The Hypertext Transfer Protocol (HTTP) provides a simple challenge- response authentication mechanism that may be used by a server to challenge a client request and by a client to provide authentication information. This document defines the HTTP Digest Authentication scheme that can be used with the HTTP authentication mechanism. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK] Recognizing that such sites will desire simple password authentication in combination with TLS encryption, this specification defines the PLAIN SASL mechanism for use with protocols which lack a simple password authentication command such as ACAP and SMTP. [STANDARDS-TRACK] This specification provides a simple challenge-response authentication protocol that is suitable for use with IMAP4. [STANDARDS-TRACK] This specification defines how HTTP Digest Authentication can be used as a SASL mechanism for any protocol that has a SASL (Simple Authentication and Security Layer) profile. [STANDARDS-TRACK] This document registers the Simple Authentication and Security Layer (SASL) mechanisms SCRAM-SHA-256 and SCRAM-SHA-256-PLUS, provides guidance for secure implementation of the original SCRAM-SHA-1-PLUS mechanism, and updates the SCRAM registration procedures of RFC 5802. The Simple Authentication and Security Layer (SASL) is a framework for providing authentication and data security services in connection-oriented protocols via replaceable mechanisms. It provides a structured interface between protocols and mechanisms. The resulting framework allows new protocols to reuse existing mechanisms and allows old protocols to make use of new mechanisms. The framework also provides a protocol for securing subsequent protocol exchanges within a data security layer. This document describes how a SASL mechanism is structured, describes how protocols include support for SASL, and defines the protocol for carrying a data security layer over a connection. In addition, this document defines one SASL mechanism, the EXTERNAL mechanism. This document obsoletes RFC 2222. [STANDARDS-TRACK] OAuth enables a third-party application to obtain limited access to a protected resource, either on behalf of a resource owner by orchestrating an approval interaction or by allowing the third-party application to obtain access on its own behalf. This document defines how an application client uses credentials obtained via OAuth over the Simple Authentication and Security Layer (SASL) to access a protected resource at a resource server. Thereby, it enables schemes defined within the OAuth framework for non-HTTP-based application protocols. Clients typically store the user's long-term credential. This does, however, lead to significant security vulnerabilities, for example, when such a credential leaks. A significant benefit of OAuth for usage in those clients is that the password is replaced by a shared secret with higher entropy, i.e., the token. Tokens typically provide limited access rights and can be managed and revoked separately from the user's long-term password. This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. Beonex The Extensible Markup Language (XML) is a framework for structuring data. While it evolved from Standard Generalized Markup Language (SGML) -- a markup language primarily focused on structuring documents -- XML has evolved to be a widely-used mechanism for representing structured data. There are a wide variety of Internet protocols being developed; many have need for a representation for structured data relevant to their application. There has been much interest in the use of XML as a representation method. This document describes basic XML concepts, analyzes various alternatives in the use of XML, and provides guidelines for the use of XML within IETF standards-track protocols. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document provides an overview and specification of Version 5 of the Kerberos protocol, and it obsoletes RFC 1510 to clarify aspects of the protocol and its intended use that require more detailed or clearer explanation than was provided in RFC 1510. This document is intended to provide a detailed description of the protocol, suitable for implementation, together with descriptions of the appropriate use of protocol messages and fields within those messages. [STANDARDS-TRACK] This memo obsoletes [STANDARDS-TRACK] This specification describes how SRV records can be used to locate email services. [STANDARDS-TRACK] This document describes the DNS Security Extensions (commonly called "DNSSEC") that are specified in RFCs 4033, 4034, and 4035, as well as a handful of others. One purpose is to introduce all of the RFCs in one place so that the reader can understand the many aspects of DNSSEC. This document does not update any of those RFCs. A second purpose is to state that using DNSSEC for origin authentication of DNS data is the best current practice. A third purpose is to provide a single reference for other documents that want to refer to DNSSEC. This document describes a DNS RR which specifies the location of the server(s) for a specific protocol and domain. [STANDARDS-TRACK] Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226.

RELAX NG schema This appendix specifies the RELAX NG compact syntax for the configuration file format defined in this document. It is provided for the convenience of implementers and not normative. Where the schema and the body of this document disagree, the body of this document is normative. The schema deliberately implements the must-ignore rule of : it accepts unknown attributes, unknown child elements, and unknown attribute and element values, instead of rejecting them. This is achieved by: using text for the content of every value-bearing element, so that values that are not defined here still validate, for example a future socketType or authentication method. The values defined by this document are listed in comments next to the corresponding patterns allowing any attribute whose name is not defined for a given element, using the attribute * - (...) and attribute * { text } patterns allowing any element whose name is not defined by this schema, at every extension point, using the extensionElement pattern. Known elements are still validated against their own definitions. A malformed known element (for example, a <port> whose content is not an integer) makes that element invalid, and therefore its enclosing server section is invalid as well. The remaining server sections and the rest of the document are still processed. A document is rejected as a whole only when it is not well-formed XML. The fragments shown in the body of this document are excerpts of the grammar below. The grammar below additionally carries the wildcards that implement the must-ignore rule.