Autoconfiguration

Because configuring an e-mail account for normal users is still nontrivial process I decided that something has to be done to make this as easy as possible. si.Mail supports basic auto-configuration from the beginning , I’m just taking this to the next level. With this proposal si.Mail can be configured by entering 2-3 required fields when using basic auto-configuration (His e-mail address, his password, and sometimes user name). Using full advanced auto-configuration all he needs to enter is his e-mail address.

How it works? si.Mail extracts domain part of e-mail address and fetches TXT records from name server for that domain. If it founds correct TXT record it downloads the file and auto configures everything that’s needed to send and receive e-mail messages.

As of January 2009 this is the specification for e-mail auto-configuration.

There are two types of auto-configuration, basic and advanced. The only difference between them is that for advanced one you’ll need a PHP, Perl, Python,… script to build the auto-configuration file.

Add new TXT record to the domain DNS. TXT record format is: mailAC=http[s]://path_to_AC_file. And reload zone file.

Basic Auto config Example: TXT     “mailAC=http://www.example.com/autoconfiguration.xml”
Advanced Auto config Example: TXT     “mailAC=http://www.example.com/autoconfiguration.php?email={email}”

{email} – is replaced with the e-mail address we are searching auto-configuration for.

Even though the advanced version is supposed to be pretty safe, it is recommended, if most client configurations is done inside a company, to add this TXT record only to the internal DNS.

This is the XML draft specification si.Mail currently supports. Please note, that you MUST define XML namespaces  as they are show in examples. (In the root node and without changing namespace names.)

XML definition

<root version="1" xmlns="http://www.simail.si/autoconfiguration" xmlns:ext="http://www.simail.si/autoconfiguration-extensions">
  <domain value="domain part of e-mail address | *" serial=" record version in following format (same as serial in DNS) YYYYMMDDxx"> <!-- multiple instances -->
    <ext:organization>When auto-configuration is used inside organization you can fill in this field. When you provide general e-mail service please leave this one blank or just skip it.</ext:organization>
    <protocols>
      <protocol type="pop3|smtp|imap" preferred="secure|normal"> <!-- multiple instances -->
        <normal>
          <server>Field is parsed. Variables: {domain}</server>
          <port></port>
          <username>none - no authentication required
            email - use whole e-mail
            local_part - use local part of e-mail
            required - user name is not part of e-mail and can't be auto-configured
            use_incoming - use same authentication as for incoming mail - valid only when protocol type is smtp
          </username>
          <ext:username>account user name</ext:username>
          <ext:password>encrypted account password</ext:password>
        </normal>
        <secure>
          <server>Field is parsed. Variables: {domain}</server>
          <port></port>
          <type>none|tsl|ssl</type>
          <username>none|email|local_part|required|use_incoming</username>
          <ext:username>account user name</ext:username>
          <ext:password>encrypted account password</ext:password>
        </secure>
      </protocol>
    </protocols>
  </domain>
</root>

Simple ISP example:

<root version="1" xmlns="http://www.simail.si/autoconfiguration" xmlns:ext="http://www.simail.si/autoconfiguration-extensions">
  <domain value="siol.net" serial="2009011801">
    <protocols>
      <protocol type="pop3" preferred="normal">
        <normal>
          <server>pop.{domain}</server>
          <port>110</port>
          <username>required</username>
        </normal>
      </protocol>
      <protocol type="smtp" preferred="normal">
        <normal>
          <server>mail.{domain}</server>
          <port>25</port>
          <username>none</username>
        </normal>
      </protocol>
    </protocols>
  </domain>
</root>

Example for multiple same domains. e.g Plesk shared hosting:

<root version="1" xmlns="http://www.simail.si/autoconfiguration" xmlns:ext="http://www.simail.si/autoconfiguration-extensions">
  <domain value="*" serial="2008122701">
    <protocols>
      <protocol type="pop3" preferred="normal">
        <normal>
          <server>mail.{domain}</server>
          <port>110</port>
          <username>email</username>
        </normal>
        <secure>
          <server>mail.{domain}</server>
          <port>995</port>
          <type>ssl</type>
          <username>email</username>
        </secure>
      </protocol>
      <protocol type="smtp" preferred="normal">
        <normal>
          <server>mail.{domain}</server>
          <port>25</port>
          <username>email</username>
        </normal>
        <secure>
          <server>mail.{domain}</server>
          <port>995</port>
          <type>ssl</type>
          <username>email</username>
        </secure>
      </protocol>
    </protocols>
  </domain>
</root>

Inside a company simple example:

<root version="1" xmlns="http://www.simail.si/autoconfiguration" xmlns:ext="http://www.simail.si/autoconfiguration-extensions">
  <domain value="*" serial="2008122701">
    <ext:organization>My company Inc.</ext:organization>
    <protocols>
      <protocol type="pop3" preferred="normal">
        <normal>
          <server>mail.{domain}</server>
          <port>110</port>
          <username>email</username>
        </normal>
      </protocol>
      <protocol type="smtp" preferred="normal">
        <normal>
          <server>mail.{domain}</server>
          <port>25</port>
          <username>none</username>
        </normal>
      </protocol>
    </protocols>
  </domain>
</root>

Additional information for advanced auto-configuration is needed on how passwords are protected. By default

<ext:password></ext:password>

field contains AES encrypted user password which is base64 encoded so it can safely be embedded into XML. You MUST ship decryption key as part of si.Mail installation in file named autoconfiguration.key. This file contains single line with key in hexadecimal form.
I’m also thinking about adding ability to implement your own encryption scheme, but API for that hasn’t been finalized.

No comments.

Leave a Reply

You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>