PACC - Automatic configuration for mail servers, calendar and contacts sync

2.1. JSON config file

The following example shows the syntax of the JSON config file.¶

{
  servers: {
    jmap: {
      url: "https://jmap.example.net/session",
      authentication: [
        "OAuth2",
        "http-basic",
      ]
    },
    imap: {
      url: "imaps://imap.example.net",
      authentication: [
        "OAuth2",
        "sasl-plain",
      ]
    },
    pop3: {
      url: "imaps://pop3.example.net",
      authentication: [
        "OAuth2",
        "sasl-SCRAM-SHA-256-PLUS",
        "sasl-plain",
        "native"
      ]
    },
    smtp: {
      url: "imaps://pop3.example.net",
      authentication: [
        "OAuth2",
        "sasl-SCRAM-SHA-256-PLUS",
        "sasl-plain"
      ]
    },
    caldav: {
      url: "https://sync.example.net/calendar/",
      authentication: [
        "OAuth2",
        "http-basic",
      ]
    },
    carddav: {
      url: "https://sync.example.net/contacts/",
      authentication: [
        "OAuth2",
        "http-basic",
      ]
    }
  },
  oAuth2: {
    issuer: "auth.example.net"
  },
  provider: {
    name: "ACME BestService WorkPlaceMail",
    shortName: "ACME",
    logo: [
      {
        url: "https://www.example.net/logo.svg",
        mimetype: "image/svg"
      },
      {
        url: "https://www.example.net/logo.png",
        mimetype: "image/png",
        width: "128",
        height: "128",
      },
      {
        url: "https://www.example.net/logo-512.png",
        mimetype: "image/png",
        width: "512",
        height: "512",
      }
    ]
  },
  help: {
    documentation: "https://help.example.net/howto/set-up-your-mail-app.html",
    developer: "https://developer.example.net/client-apps/",
    contact: "mailto:it@team.example.net"
  },
  version: "1.0"
}

2.2. servers

E.g.¶

servers: {
  jmap: {
    url: "https://jmap.example.net/session",
    authentication: [ ... ]
  },
  imap: { ... }
}

servers is a top-level property containing an object map. The key is a protocol name, defined in section "Protocol". The value is an object which describes the server and is defined in this section.¶

    url: "https://jmap.example.net/session"
    url: "imaps://imap.example.net:1993"

authentication: [ "http-basic" ]
authentication: [ "sasl-SCRAM-SHA-256-1" ]

2.3. provider

provider property is a top-level property and contains name, shortName, and logo.¶

name: "ACME BestService WorkPlaceMail"
shortName: "ACME"

2.4. help

This is purely informational and not required for the automatic setup. All of the information is optional. A contact SHOULD be included.¶

2.5. version

version property is a top-level property.¶

The version is 1.0 for the version defined in this specification. Higher versions are for future specifications. The client MUST NOT reject a config file solely based on the version number.¶

2.6. JSON validation

The client SHOULD validate that the config file is valid JSON as per RFC 8259, and if the JSON syntax is invalid, the client SHOULD ignore the entire file. In contrast, if there are merely unknown JSON properties, the client MUST NOT ignore the file.¶

The client SHOULD read only the properties that are supported by the client, and MUST ignore the others that are unknown to the client.¶

The client may optionally want to validate the XML before parsing it. This is not required. If the client choses to validate, the validation MUST ignore unknown properties and MUST NOT drop or ignore a configuration that contains unknown properties. This is required to allow future extensions of the format without breaking existing clients.¶

3.1. Email address domain

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.¶

DNS SRV _pacc._https.%EMAILDOMAIN%.

DNS SRV _pacc._https.example.com.

_pacc._https.%EMAILDOMAIN%.   SRV   0 0 443 %HOSTNAME%.

_pacc._https.example.com.   SRV   0 0 443 pacc.example.com.

https://%HOSTNAME%/.well-known/pacc.json

https://pacc.example.com/.well-known/pacc.json

3.2. MX domain

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 with valid TLS certificate for each of their customers, and to convince their customers to modify their root DNS specifically for PACC. To handle such domains, the protocol first needs to find the domain of the party hosting the email.¶

If the query on the email domain as described above yields no result, the client SHOULD perform a DNS MX lookup on the email domain, and retrieve the MX server hostname for that domain and look for a PACC file for the MX hostname, using the following mechanism.¶

DNS MX %EMAILDOMAIN%.

DNS MX example.com.

example.com   MX   %PRIORITY% %MXSERVER1%.

example.com   MX   10 beetruche1.mx.example.net.
example.com   MX   10 beetruche2.mx.example.net.
example.com   MX   30 beetruche3.mx.example.net.

DNS SRV _paccmx._https.%EMAILDOMAIN%.

DNS SRV _paccmx._https.beetruche1.mx.example.net.

_paccmx._https.%MXSERVER%.   SRV   0 0 443 %HOSTNAME%.

_paccmx._https.beetruche1.mx.example.net.   SRV   0 0 443 pacc.example.net.

3.3. Example DNS SRV records for an email domain

In this example, example.com hosts its email and PACC config file itself:¶

$ORIGIN example.com.
_pacc._https   SRV   0 0 443 pacc.example.com.
pacc           A     192.0.2.9

3.4. Example DNS SRV records for an email hoster

In this example, example.com hosts its email with hoster example.net:¶

$ORIGIN example.com.
@             MX    10 beettruce1.mx.example.net

$ORIGIN example.net.
_paccmx._https.beettruce1.mx   SRV   0 0 443 pacc.example.net.
pacc                           A     192.0.1.9

3.5. 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 to use. Given that the config is required for authentication, the config itself cannot require authentication.¶

4.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.¶

4.2. Login test

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.¶

4.3. OAuth2 windows

If the configuration contains OAuth2 authentication, or any other kind of 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. The authentication start URL may be the email hoster, but it may redirect 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.¶

4.4. OAuth2 requirements

If OAuth2 is used, the OAuth2 server MUST adhere to the OAuth Profile for Open Public Clients.¶

Particularly, the Dynamic Client Registration MUST be implemented and give a working Client ID in response HTTP calls defined by the specification. Alternatively, the Client ID open MUST be accepted without client secret. 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 specifications also contain requirements for expiry times and the login page, which are needed for mail client applications to work.¶

The OAuth2 scopes defined in the specification MUST be included and MUST give access to the servers published in PACC.¶

A single token MUST work for all servers returned in PACC, so that a single user login is sufficient for all services. For that purpose, the client will include all relevant scopes in the authentication requests.¶

5.1. 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 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.¶

6.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.¶

6.2. DNS

This protocol relies on DNS SRV and DNS MX lookups to find the PACC file. DNS requests are not signed and can therefore be intercepted, spoofed and manipulated. This would allow the attacker to change the PACC file URL and return email and authentication servers under the attacker's control, stealing passwords.¶

One possible mitigation is to check whether the domain of the PACC file URL matches the user's email address domain. However, that will not be the case for the majority of domains, which are served by email hosters.¶

Another 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 section "User approval".¶

6.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.¶

6.4. Server security

Given that mail clients will trust the configuration, the server delivering the PACC 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.¶

7.1. Registration

IANA will create the following registry in a new registry group called "PACC":¶

Registry Name: "PACC Protocol Type Names"¶

Registration Procedure: Specification Required, per RFC 8126, Section 4¶

Designated Expert: Ben Bucksch, author of this document.¶

7.2. Contents

Table, with fields Protocol (alphanumeric), URL scheme, Port (default port number, if not specified in the URL), Name, Specification, and Additional Properties¶

The registrations need to define * Protocol: The protocol name, as appearing in the JSON * URL scheme: Which URL scheme or schemes are to used in the URL * Port: The default port number, if none is given in the URL * Name: The commonly used name of the protocol * Specification: Which RFCs or document specifies the protocol, and * Additional Properties: (Optional) Protocol-specific JSON properties and their meaning.¶

7.3. Initial registration

The Additional Properties field is empty in all of the initial values.¶

7.4. Addition of DNS SRV Service Names pacc and pacc_mx