================================================================================ Project name : MICROAGENT Author : Daniele Giannetti Version : 1.0 Date : 20/06/2010 ================================================================================ ------------------------------ BRIEF DESCRIPTION ------------------------------- The MICROAGENT software suite is a mobile application intended to locate stolen mobile devices supporting the JME CLDC configuration and the MIDP profile. The application is divided in 2 separate MIDlets to be used together on different devices. The first MIDlets runs hidden on the first phone, and may be activated remotely using the second MIDlet from a second phone. ---------------------------- APPLICATION STRUCTURE ----------------------------- The MICROAGENT mobile application is composed of 2 MIDlets. 1) MICROAGENT_SPY This MIDlet operates hidden on a target phone. When launched, it registers with the push registry listening for SMS messages on the 6060 SMS port coming from the second MIDlet in the software suite. The SPY MIDlet parses the message and extracts some information on the wanted activation behaviour. Note that a received message is accepted only if coming from one of the trusted MICROAGENT_CONTACTs, if the sender port is the correct MICROAGENT_CONTACT port and if its structure is correct. It then acts as follows: - Using the a location device which must be present on the phone, it tries to discover its current location. The coordinates are then sent back to the SMS sender if the location was successful. - If requested in the activation SMS message received, the MIDlet enters the annoying mode, in this case it will start playing sounds and will try to keep running even if terminated by registering for timed reactivation with the push registry. - If requested in the activation SMS message received, a message may be presented to the human user. This is intended to show the thief a message trying to convince her to get rid of the phone. If a message is sent with annoying mode requested, it will be stored in a record tore to be presented again in case of timed activation. Moreover, if the message is sent with annoying mode, the screen with the message will have no command to exit the screen (to terminate the MIDlet the user is forced to kill it using the AMS and by doing this timed reactivation is triggered). If annoying mode is not requested, the MIDlet will return to its previous sleeping state, registering with the push registry once again. This happens as soon as the user dismisses the message screen, meanwhile the MIDlet listens for activation messages ready to perform new locations. If annoying mode has been activated, the MIDlet keeps running while listening for activation messages. If destroyed while in this mode, the MIDlet registers with the push registry to self-reactivate in some time. We use the push registry for MIDlet activation when receiving an activation message, we may instead simply use a background MIDlet. The problem is that not every Java ME implementation supports this kind of behaviour, and often the user is asked to dismiss background running application explicitly by the AMS. The system may instead allow push-activated MIDlets. To work properly and be able to answer activation messages while working in background (not showing up to the user or thief) the SPY MIDlet must receive full privileges on every possible action regarding: - push registry - sms messaging - location services This is possible only if the MIDlet is signed by a fully trusted CA. In our case, the MIDlet is *not* signed (untrusted) to allow execution on every mobile device. 2) MICROAGENT_CONTACT This MIDlet is the one used to activate the SPY MIDlet on the remote phone. It provides a relatively rich user interface, allowing: - SPY database management A record store is used to store SPIES to be eventually located, the user may delete or add entries to the record store using a friendly GUI. - SPY location It is possible to locate a SPY registered in the record store. In that case, an activation message is sent to the desired SPY and a response is expected. If the response SMS is received and contains the desired coordinates, the Google Maps static API is used to fetch satellite pictures of the received location. The user may zoom in or out of those pictures in order to figure out the thief location. When a SPY location is requested, the user may choose to: - activate the annoying mode on the remote device - send a text message appended to the activation SMS to be presented on the remote device If a response message is received, it may not contain the desired coordinates because the remote location system was unable to obtain the coordinates, in such cases the CONTACT user is not able to discover the thief location (but at least an eventual text message sent with the activation request has been presented on the remote phone and the annoying mode has been activated if requested). The CONTACT MIDlet receives response messages on the 6061 SMS port. ----------------------------- SMS MESSAGES FORMAT ------------------------------ SPY ACTIVATION MESSAGE: The SMS message sent by the CONTACT MIDlet to activate a sleeping SPY MIDlet on a remote device is a pure text message with the following format: 1 1 80 max <- field size in characters +---------------+--------------+---------+ | annoying_flag | message_flag | message | <- message fields (left to right) +---------------+--------------+---------+ where: - annoying_flag = '0' if annoying mode must not be enabled, '1' if the CONTACT MIDlet requested annoying mode activation on the target SPY. - message_flag = '1' if a message is appended to the activation message (following this flag), '0' otherwise. - message (OPTIONAL) = message to be presented on the target phone. SPY RESPONSE MESSAGE: The SMS sent back by the SPY MIDlet to the CONTACT MIDlet is a pure text message as well, and the format is as follows: 15 max 1 15 max 1 11 max <- field size in characters +----------+-----+-----------+-----+----------+ | latitude | '|' | longitude | '|' | accuracy | <- message fields +----------+-----+-----------+-----+----------+ (left to right) Where: - latitude = mobile SPY device latitude (real decimal number), represented as a string. - longitude = mobile SPY device longitude (real decimal number), represented as a string. - accuracy = mobile SPY coordinates accuracy (usually intended as the standard deviation of the probability distribution) provided by the location system used. Expressed as a string representing an integer number of decimiters (0.1 meters). - '|' = separator. Sometimes it is possible to obtain the coordinates but the accuracy is unavailable depending on the location provider used. In such cases the response message will not contain the accuracy and the format is the following: 15 max 1 15 max <- field size in characters +----------+-----+-----------+ | latitude | '|' | longitude | <- message fields (left to right) +----------+-----+-----------+ Where the fields have the same meaning as in the standard response message. If it wasn't possible to obtain the coordinates on the remote device, then the response message will only contain the "null" string (4 characters): 4 <- field size in characters +--------+ | 'null' | <- message fields (left to right) +--------+ Where: - 'null' = "null" string. ----------------------------------- NOTES -------------------------------------- The two MIDlets have not been boundled in a single MIDlet suite because they may be installed together, but are not required to. Moreover, they have different requirements to run on mobile devices and even if a particular device is incompatible with a MIDlet of the MICROAGENT software suite, it may be compatible with the other one. --------------------------------------------------------------------------------