Skip to main content

Developing MEP Client Applications - Part 2

Posted by ryan_shoemaker on February 23, 2009 at 1:10 PM PST

Part 1 of this series focused on the core features of the MCBO API. In Part 2, we will see how to take advantage of many of the client security features provided in the API, using the MusicDB sample app as a framework for the discussion. I've stripped all of the UI related code from the sample fragments, but I did need to include some pseudo code in a few places to clearly illustrate some of the concepts.

Review of MCBO Security Features

The security features in SGMP v1.1 haven't changed much since MEP 1.0. The only new addition is an AES based security manager.

Here's a rundown of the security features we'll be exploring:

  • Authentication
  • Data Encryption
  • Transport Layer Security
  • Data Destruction
  • Lock Out
  • Data Fading
  • Extensible

Security Managers

The core class that provides all of the security features in the MCBO API is SecurityManager. This class is abstract so that application developers have the option to provide their own implementation. The MCBO API ships with two SecurityManager implementations: DefaultSecurityManager and AESSecurityManager. The DefaultSecurityManager class shipped as part of MEP 1.0 and provides Triple-DES encryption. The AESSecurityManager is a new addition to SGMP 1.1 and provides AES encryption.

To enable security in your MCBO client, you simply have to pass an instance of SecurityManager to the SyncManager constructor:

    private SyncManager syncMgr;
    private SecurityManager securityMgr;

    securityMgr = new DefaultSecurityManager("musicdb");
    syncMgr = new SyncManager(".alb", securityMgr);

In this sample, we are using a 3DES-based default security manager. The "musicdb" parameter passed to the constructor is a unique application specific context name that the MCBO library will use to store security related data in RMS on the device.


There are two layers of user authentication - one at the application layer (which is optional) and another at the synchronization layer (which is mandatory).

Application authentication provides a login mechanism that prevents unauthorized users from launching the application and gaining access to sensitive information. The SecurityManager is responsible for managing the information required to perform simple password based authentication. Here is some pseudo-code that illustrates the authentication process:

    String pin = UI.getPin();   // get the user's pin from the UI

    if(securityMgr.isPinSet()) {
        if(securityMgr.validatePin(pin)) {
            // valid pin, set the key and continue
        } else {
            // wrong pin, try again
    } else {
        // first login
        // set the key and store credentials based on user's secret
        String secret = UI.getSecret();  // get secret from UI
        // continue with app as usual

In this example, the "pin" is a plaintext alphanumeric string entered by the user on the UI. The isPinSet API determines if this is the first time the user is logging into the application. If so, then it is necessary to set the pin. Setting the pin requires the user to enter a "secret" which is also a plaintext alphanumeric string. Entering the secret is only done once and the user does not need to remember it - it should be a long random sequence of key presses on the device. The purpose of the secret is to calculate a derivative of the pin, so the pin isn't stored directly on the device. Once the pin and secret are entered a key is calculated (the MD5 hash of the pin) and the credential derivatives are stored in RMS via the storeCredentials API. If this isn't the first time the user is logging into the application, then the key is calculated from the pin and the security derivatives stored in RMS are retrieved and used to authenticate the pin with the validatePin API. In either case, once the user has successfully authenticated themselves, the MD5 hash of the pin becomes the key used for encrypting data at rest on the device by calling the setKey API.

Synchronization layer authentication is orthogonal to Application layer authentication and is not managed by SecurityManager. Every time the application performs a synchronization, the user's SGMP gateway credentials are sent to the gateway as part of the OMA DS protocol (syncml:auth-basic over http/s). This prevents unauthorized users from accessing or corrupting sensitive information in the back end systems. We are exploring the possibility of providing syncml:auth-md5 over http/s in a future version of SGMP. Synchronization layer credentials are managed by the SyncManager because they are not encrypted. To set them, you simply retrieve the values from the UI or from your own RMS record store and set them on your instance of SyncManager before initiating a sync session with the gateway:

    SyncType syncType = ...;

Data Encryption

Once you've enable client security (by passing an instance of SecurityManager into your SyncManager constructor), encryption of data at rest on the device happens automatically. The application developer doesn't need to write any special code to handle the encrypted data. The MCBO API will automatically decrypt/encrypt data when reading/writing business objects from/to the device filesystem. Furthermore, it will handle encryption/decryption of the records as they are received/sent to the gateway sync engine.

Transport Layer Security

TLS is provided by using HTTPS connections between the mobile device and the MEP gateway server. Because the synchronization layer credentials are visible on the wire and only minimally protected with MD5, https connections should be used to protect transmissions over the air. There are no specific APIs to enable the use of https - you simply configure your mobile device and gateway servers to use https and specify the sync url using https protocol.

Data Destruction

MCBO provides the ability for applications to perform complete data destruction under certain circumstances. The application developer may decide to wipe-out all data if the user fails a certain number of login attempts or after a certain amount of time has passed without a successful synchronization.

To initiate data destruction:


Since you can use the same security manager instance with multiple sync managers, you need to tell it which class of business objects to destroy.

Lock Out

Application developers can specify a maximum number of login attempts. If a user exceeds the threshold, then they are locked out of the application. For example:

    try {
        while(!securityMgr.validatePin(pin)) {
            // wrong pin - try again
    } catch(java.lang.SecurityException se) {

In this case, the user has 5 login attempts. On the 6th and subsequent failures, the call to validatePin will throw a SecurityException and all of the data on the device will be destroyed. The validatePin API keeps track of the number of validation attempts in RMS, so application lock-out will persist across restarts of the application or JVM.

SecurityManager also provides a couple of APIs that tell you the max and remaining validation attempts so you can generate nice warning messages on the UI. The default number of validation attempts is 10, but you can change that to any positive value or set it to 0 if you never want your application to lock-out.

Data Fading

A quiet period can be specified that allows the application to determine if a device is lost. After the quiet period expires, the application can take whatever protective measures it chooses (such as data destruction). For example, if you expect your mobile users to sync at least once a week, you could set a two-week quiet period after which an invalid pin entry would trigger data destruction:

    securityMgr.setMaxQuietPeriod(1000L * 60 * 60 * 24 * 14); // two-weeks
    String pin = UI.getPin();
    long remainingQuiet = securityMgr.getRemainingQuietTime();
    if(remainingQuiet == 0 && !securityMgr.isPinValid(pin)) {

Data fading is disabled by default. To enable it you specify a positive quiet period in ms and to disable it, you specify 0. The
clock is reset every time a successful sync occurs.


As I pointed out above, the MCBO SecurityManager is an abstract class so developers are free to supply their own implementations based on whatever cyrpto library they choose.


We've covered almost all of the security features offered in the MCBO API in Part 2 of this series. One of the things I hoped you would take away from this discussion is how flexible the security features are in the MCBO API. It doesn't dictate a security policy (in fact, you don't have to use security in your applications at all), but rather it provides a framework that allows you to fine-tune your own security policy by using the features you need and ignoring the rest.

Related Topics >>