Email configuration via SMS

Posted by Julien Buratto 1 year 41 weeks ago

Many of you will have experienced how a call to a network operator has resulted in an SMS containing configuration settings being sent to your phone. In this article we will look at how to configure a mobile phone's email account settings via SMS. Many phones support POP3 and IMAP accounts; in this example we are going to configure a simple POP3 account.

To check emails, an access point (APN) is also needed, so we will also configure an internet connection.

Caveats

Not all phones that support POP3 email also support SMS configuration and not all phones have email support.

Also, some phones don't support over the air (OTA) configuration, and some phones still don't support OMA specifications. Many phones will not accept OTA configuration if a "USER PIN" isn't requested. This situation will not be covered in this article.

Requirements

In order to correctly configure your phone, you will need:

• A POP3 email account
  Your email account details, including:
  • A profile name
  • POP3 address
  • SMTP address
  • Username
  • Password
• An internet provider for your phone (typically a GPRS access point)
• An SMS gateway which allows the sending of binary SMS (for example over http)

So, to be clear, we will OTA configure a simple email account with SMTP authenticated mail server. Let's imagine that my email address is "julien.buratto@example.com" and that my password is "dev.mobi".

The POP3 server (to check emails) could be "pop.example.com" and the SMTP server (to send emails) could be "smtp.example.com" and let's assume that SMTP and POP user/passwords are the same.

The profile will be called "MyEmail".

For the APN

In order to configure an internet connection (for example via GPRS), we will use the minimum details, that is the Access Point Name, for example "web.gprsprovider.com".

Configurations

A few words about configurations

In general we can say that the container for email configuration is the same for configuring a normal internet connection on a mobile device. Or better, a general settings SMS for email must also contain the connection details in order to work correctly.

All configurations are normally sent to port 49999 (hex C34F). If you don't know what a port is and how to use it, check the mobiForge article "Binary SMS: sending rich content to devices using SMS".

The port 49999 is also known as "WAP OTA configuration".

Configuration characteristics

What we are going to do is to write an XML file which describes what we want configure.

The most important configuration is, in general, the APN configuration which allows to prepare the connection to a specific resource. For example, in order to access to the mailbox julien.buratto@example.com, we will use the "web.gprsprovider.com" internet connection.

An APN is also called NAP (Network Access Point) and it's definition is a NAPDEF.

A configuration is defined to be a "characteristic", so the goal will be to create an "apn" characteristic (NAPDEF), and a some characteristics to read (POP3) and to send (SMTP) emails.

A quick note on POP3 and SMTP: IANA standard ports for POP3 is 110, while for SMTP is 25.

More characteristics can be combined into one single XML file, and each characteristic will have some parameters.

So, to resume, we will define:

• One characteristic for an APN
• One characteristic to read emails (on port 110)
• One characteristic to send emails (on port 25)

• Logially link them togheter in the same configuration XML file
• Convert the generic XML file into a WBXML file
  (just to bring back some knowledge from the previous article, WBXML is a binary version of a textual XML file used over WAP).
• We will then send this file to the SMS gateway, which will send the SMS to the phone, and the phone will use the SMS to configure the settings

The basic XML file

The code

Below we have included a basic XML file. While it doesn't make for the most riveting reading, it is worth studying since it gives a very clear understanding of what is going on. Eachnode will be explained step by step.

<?xml version="1.0"?>
<!DOCTYPE wap-provisioningdoc PUBLIC "-//WAPFORUM//DTD PROV 1.0//EN" "http://www.wapforum.org/DTD/prov.dtd">
<!-- So, let's start the configuration using OMA CP 1.1 specifications -->
<wap-provisioningdoc version="1.1">
	<!-- Here we start the Access Point Name Definition -->
	<characteristic type="NAPDEF">
		<!-- Let's give an ID to identify this APN valid into this XML file -->
		<parm name="NAPID" value="dev.mobi"/>
		<!-- Connection type is over GPRS -->
		<parm name="BEARER" value="GSM-GPRS"/>
		<!-- The Connection name -->
		<parm name="NAME" value="Operator GPRS"/>
		<!-- The APN value -->
		<parm name="NAP-ADDRESS" value="mailweb.operator.com"/>
		<!-- The type of access point -->
		<parm name="NAP-ADDRTYPE" value="APN"/>
		<!-- Here are general credentials to access the APN  -->
		<characteristic type="NAPAUTHINFO">
			<parm name="AUTHTYPE" value="PAP"/>
			<parm name="AUTHNAME" value="user"/>
			<parm name="AUTHSECRET" value="passwd"/>
		</characteristic>
	</characteristic>
	<!-- Here is the POP3 configuraton -->	
	<characteristic type="APPLICATION">
		<!-- The APPID rappresents a unique identifier to POP3 -->
		<parm name="APPID" value="110" />
		<!-- This is an internal ID to internal reference -->
		<parm name="PROVIDER-ID" value="MyPOPMail" />
		<!-- This tells the device that the mail should be read using the previous configured APN -->
		<parm name="TO-NAPID" value="dev.mobi" />
		<!-- Here is the POP3 server details -->
		<characteristic type="APPADDR">
			<parm name="ADDR" value="pop.example.com" />
			<!-- Port number for POP3 is normally 110 -->
			<characteristic type="PORT">
				<parm name="PORTNBR" value="110" />
			</characteristic>
		</characteristic>
		<!-- Here are the username/password of your POP3 server -->
		<characteristic type="APPAUTH">
			<!-- Julien.buratto is my email's username to access via POP3 -->
			<parm name="AAUTHNAME" value="julien.buratto" />
			<parm name="AAUTHSECRET" value="Password" />
		</characteristic>
	</characteristic>
	<!-- Now let's configure the SMTP to send emails -->
	<characteristic type="APPLICATION">
		<!-- Same as per any "application" you want to configure, the unique ID for smtp is 25 -->
		<parm name="APPID" value="25" />
		<!-- Same provider ID as per POP3 so both POP3 and SMTP will be bound together -->
		<parm name="PROVIDER-ID" value="MyPOPMail" />
		<!-- To send emails, also use the previous APN configured at the beginning -->
		<parm name="TO-NAPID" value="dev.mobi" />
		<!-- Emails will be sent as  -->
		<parm name="FROM" value="someone@example.com" />
		<!-- Here is the SMTP server address -->
		<characteristic type="APPADDR">
			<parm name="ADDR" value="smtp.example.com" />
			<!-- Here is the SMTP port -->
			<characteristic type="PORT">
				<parm name="PORTNBR" value="25" />
			</characteristic>
		</characteristic>
		<!-- Here are the username/password to access the SMTP server if authenticated -->
		<characteristic type="APPAUTH">
			<parm name="AAUTHNAME" value="OutgoingName" />
			<parm name="AAUTHSECRET" value="Password" />
		</characteristic>
	</characteristic>
<!-- That's all folks, no more things to configure -->
</wap-provisioningdoc>

Explaining the code

Now let's go into the code. If you read the XML text, you will notice a lot more than you might have expected, so here is something of an explanation:

• We define an access point (APN) with a NAPDEF (just mix up the letters "APN DEFinition" to get NAPDEF) and we give it an ID called "MyApnID".
• We define an "application" for the port 110 and we link it to the previously created APN using the parameter TO-NAPID.
• We define another "application" for the port 25 and we link it too to the same APN using the same parameter TO-NAPID.
• We link the 110 application (POP3) with the 25 application (SMTP) in a single "application provider" putting the same PROVIDER-ID called "OurEmailConfiguration" in both applications.

You have also noticed that each application can have sub-characteristics. These characteristics describe ADDRESSes, PORTs and AUTHentications for each service. That is the POP3 server address and port, the SMTP server address and port and for each one the username/password for it.

XML to WBXML

In the first article about binary SMS, we converted the XML file into WBXML by hand, checking the documentation and converting each single element and character into its binary representation. This time, as the configuration is pretty long and could lead to confusion, we will introduce the use of a LGPL library written in C which can be used to convert XML into WBXML. I'm talking about http://libwbxml.aymerick.com/ which is under LGPL library.

Using the libwbxml library

The library is pretty easy to install; under linux you just download the library, untar the file and run "make all" (please read INSTALL file if you encounter problems while compiling). Once that you have finished compiling, you will have a pretty "xml2wbxml" and "wbxml2xml" files in the tools directory.

So, just copy the XML into a text file called "gota_config.xml" and then use the xml2wbxml command to create your binary file.
./xml2wbxml -o ota_config.wbxml ota_config.xml

The compiled WBXML file

Once that you receive a "xml2wbxml succeded" message from the previous command, you will have a binary file called ota_config.wbxml, please compare the orginal file to the compiled on.

-rw-r--r-- 1 root root 459 2 dic 10:38 ota_config.wbxml

-rw-r--r-- 1 root root 3404 2 dic 10:38 ota_config.xml

You can now understand why wbxml is so nice: the file has been converted into another file which is 7 times smaller.

How many SMS ?

As we will need to send UTF-8 chars, each SMS will allow 140 chars.
459 / 140 = 3.27 which make 4 SMS.

Prepare for the SMS gateway

This time we will use the open source SMS gateway, Kannel, to send out the SMS, and not the J2ME application as we did in the previous article, so we will need to:

• Setup Kannel

• Send the XML file to Kannel

Why Kannel?

Kannel has some very interesting advantages with resepect to OTA configurations. Many devices attempt to protect users from suspicious remote configurations by refusing to accept OTA configurations if not "pin" protected. Kannel can internally add the "pin" feature to our OTA SMSs and also prevent us to do the boring WBXML conversion and the UDH writing.

Using Kannel - the open source gateway

Kannel is an open source project which aims to provide a WAP gateway for free. Kannel can also be used to send SMS messages with its "SMS box". Explaining how to install and run Kannel is out of the scope of this article, but let's consider the simple "real life example" where you already have a Kannel installation working.

In order to send a binary SMS via Kannel, you will need to submit an HTTP request to Kannel with the following parameters:

• username and password for the Kannel service
• sender and destination phone numbers
• text (the binary sms)
• udh (the user data header)

Using "OMA Settings" Kannel feature

Kannel also provide a special feature which can be triggered via HTTP in order to send OTA messages, compliant to OMA CP 1.1 specifications directly without having the hassle of WBXML and UDH handling.

In order to trigger this feature, you will need to call the Kannel URL:

http://localhost:13013/cgi-bin/ota

The parameters you need to issue are:

• from: the sender phone number of the SMS (let's assume is "003933512345698")
• to: the device phone number that you want to configure (let's assume is "00393351234567")
• text: the XML file we have previously created (this must be "url encoded" before sending)
• username: to access the Kannel server (let's assume is "myName")
• password: to access the Kannel server (let's assume is "foobar")
• type: the type of OTA we want to send (we will be using "oma-settings")
• sec: the security feature to protect the OTA setting (we will use "userpin")
• pin: the pin number that the user will need to enter on the device when the OTA gets opened in the phone (let's assume is "1234")

The best way to do all this, is to create a simple HTML form with all the variables and submit it (illustrated below). The file is attached to this article and can be downloaded below.

References

1. OMA Client Provisioning V.1.1 - "Provisioning Content"
http://www.openmobilealliance.org/release_program/cp_v1_1.htm

2. Kannel: Open Source WAP and SMS gateway
http://www.kannel.org

4. Nokia S60 Platform: OMA Client Provisioning
http://www.forum.nokia.com/info/sw.nokia.com/id/d5013d63-fb88-4f58-8de9-e29cedfd5a1f/S60_Platform_OMA_Client_Provisioning.html