test

Sun GlassFish Mobility Platform 1.1 Developer's Guide for Client Applications

The SecurityManager Class

Table 4–6 lists the constructors and methods belonging to the SecurityManager class. This class manages all of the client-side security features. A default implementation is provided (DefaultSecurityManager), but you are free to supply your own implementation.

Security features include the following:

Authentication

A simple form of pin-based authentication is provided. The isPinSet() method determines if the user of the application has set a pin yet. If not, you will need to prompt the user to enter a “secret”, which is just a long random alphanumeric string, and a pin, which is also an alphanumeric string. You must compute a security key from the pin using computeKey(String) and then set the key on the SecurityManager with setKey(byte[]). You then persist the user credentials using the storeCredentials(String) method. This method computes a hash of the unencrypted secret and stores this value along with the secret encrypted with the key into the device's RMS record store.

If the user has already set their pin, use the validatePin(String) method to determine if the pin is valid. This method computes an encryption key from the supplied pin and reverses the encryption and hash calculation on the encrypted secret stored in RMS. If the hash calculations match, the pin is valid.

The SecurityManager also keeps track of pin validation attempts (that is, how many times the MIDlet calls validatePin(String)). If the MIDlet exceeds the maximum number of attempts (getMaxValidationAttempts()), a SecurityException is thrown. The number of pin validation attempts is stored in RMS so they can be tracked across restarts of the MIDlet.

Encryption

The encrypt(byte[]) and decrypt(byte[]) methods are callbacks used by the MEP synchronization library to perform encryption and decryption of the business objects as they are read from and written to the device file system. If security is enabled, the data is never written to the device in clear text.

Data Fading

You can specify a maximum “quiet period” between successful synchronizations by using setMaxQuietPeriod(long). Using the getRemainingQuietTime(SyncManager) method, you can determine how much time is left before the quiet period expires. Based on this information, you could choose to destroy all of the business objects on the device.

Data Destruction

In certain circumstances, you may choose to destroy all of the business objects stored on the device(for example, if the MIDlet has failed pin validation too many times, or if the quiet period has expired since the last sync). To destroy the data, call the destroyBusinessObjects(SyncManager) method for each type of business object you wish to destroy.

Table 4–6 Class com.sun.mep.client.api.SecurityManager

Method 

Description 

public SecurityManager()

No-argument constructor. 

public abstract byte[] computeKey(java.lang.String pin)

Computes an encryption key from the pin. There are no restrictions on the length of the pin or the key. It is up to the implementing class to produce the appropriate length key for the encryption algorithm being used. Calling this method will also set the key value so it can be retrieved using getKey().

public abstract byte[] decrypt(byte[] cipherText)

Callback handler to perform decryption of data on device. The MEP runtime will invoke this method whenever it is necessary to decrypt data. 

public final boolean destroyBusinessObjects(SyncManager mgr)

Activates data destruction on business objects managed by the specified SyncManager. All business objects managed by the specified SyncManager will be deleted from the device.

public abstract byte[] encrypt(byte[] plainText)

Callback handler to perform encryption of data on device. The MEP runtime will invoke this method whenever it is necessary to encrypt data.  

public abstract byte[] getKey()

Returns the value of the key computed by computeKey(String).

public final long getMaxQuietPeriod()

Returns the maximum allowable quiet time. 

public final int getMaxValidationAttempts()

Returns the maximum allowable validation attempts. 

public final long getRemainingQuietTime(SyncManager mgr)

Returns the time remaining (in milliseconds) before the quiet period expires. If there is no specified quiet period (that is, if the value returned by getMaxQuietPeriod() is less than zero), this method returns a negative value. Otherwise, it returns the time remaining in milliseconds, or zero if the quiet period has been exceeded. If a sync has not been attempted yet, it returns getMaxQuietPeriod().

public abstract int getValidationAttempts()

Returns the number of validation attempts. 

public abstract boolean isPinSet()

Returns true if the user has never logged into the application. Use this method to determine when the credentials need to be stored on the device. 

public abstract void setKey(byte[] key)

Sets the key on the SecurityManager so it can be used during callbacks to encrypt or decrypt data on the device.

public final void setMaxQuietPeriod(long period)

Sets the maximum allowable quiet time (in milliseconds) between sync requests. If the device has been quiet for too long, the application will be prevented from performing the sync. Additionally, the application can decide to perform data destruction by calling destroyBusinessObjects(SyncManager). Passing a negative value indicates that there should be no timeout.

public final void setMaxValidationAttempts(int attempts)

Sets the maximum allowable validation attempts. When the number of pin validation attempts exceeds this value, the application can decide to lock out the user and perform data destruction by calling destroyBusinessObjects(SyncManager). The default value is 10 validation attempts. An argument of 0 (zero) indicates that there is no maximum number of validation attempts.

public abstract void storeCredentials(java.lang.String secret)

Persists derivatives of the pin/key and the supplied secret on the device. These derivatives are used upon subsequent logins to validate the pin. 

The secret can be any non-null, non-zero length alphanumeric string. Typically, the application developer would prompt the user to enter a random sequence of key presses on the device and pass that value into this method. This is a single-use value, so the user does not need to remember it. 

This method should only be called once, when the user needs to set their pin number (if isFirstLogin() returns true).

public abstract boolean validatePin(java.lang.String pin)

Determines if the pin is able to recompute the derivatives stored on the device in storeCredentials(byte[], String). If so, it returns true; otherwise, it returns false.

This method also keeps track of how many times it has been invoked. If it exceeds the maximum number of allowed attempts (getMaxValidationAttempts()), then a SecurityException is thrown, unless getMaxValidationAttempts() returns 0.