FileDocCategorySizeDatePackage
Permissions.javaAPI DocJ2ME MIDP 2.021189Thu Nov 07 12:02:24 GMT 2002com.sun.midp.security

Permissions

public final class Permissions extends Object
This class is a standard list of permissions that a suite can do and is used by all internal security features. This class also builds a list of permission for each security domain. This only class that would need to be updated in order to add a new security domain.

Fields Summary
public static final String
POLICY_FILENAME
Name of the security policy file.
public static final String
INTERNAL_DOMAIN_NAME
Name of the internal domain. (all actions allowed)
public static final String
UNTRUSTED_DOMAIN_NAME
Name of the untrusted domain.
private static String[]
names
Names to compare to JAD and policy file entries.
static final String
CLIENT_DIALOG_TITLE
Common permission dialog title for client protocols.
static final String
CLIENT_PERMISSION_QUESTION
Common permission question for client protocols.
static final String
SERVER_DIALOG_TITLE
Common permission dialog title for server protocols.
static final String
SERVER_PERMISSION_QUESTION
Common permission question for server protocols.
private static String[]
questions
Questions to use for the user permission form. Any %1 in the question will be replaced with the suite name and any %2 will be replaced with the resource name.
private static String[]
titles
Titles use for the user permission form.
public static final int
MAX_LEVELS
The maximum levels are held in the first element of the permissions array.
public static final int
CUR_LEVELS
The current levels are held in the first element of the permissions array.
public static final int
MIDP
com.sun.midp permission ID.
public static final int
AMS
com.sun.midp.midletsuite.ams permission ID.
public static final int
HTTP
javax.microedition.io.Connector.http permission ID.
public static final int
TCP
javax.microedition.io.Connector.socket permission ID.
public static final int
HTTPS
javax.microedition.io.Connector.https permission ID.
public static final int
SSL
javax.microedition.io.Connector.ssl permission ID.
public static final int
TCP_SERVER
javax.microedition.io.Connector.serversocket permission ID.
public static final int
UDP
javax.microedition.io.Connector.datagram permission ID.
public static final int
UDP_SERVER
javax.microedition.io.Connector.datagramreceiver permission ID.
public static final int
COMM
javax.microedition.io.Connector.comm permission ID.
public static final int
PUSH
javax.microedition.io.PushRegistry permission ID.
public static final int
NUMBER_OF_PERMISSIONS
Number of permissions.
public static final byte
NEVER
Never allowed an permission.
public static final byte
ALLOW
Allow an permission with out asking the user.
public static final byte
BLANKET_GRANTED
Allow permission until the the user changes it in the settings form.
public static final byte
BLANKET
Allow a permission after asking the user once.
public static final byte
SESSION
Allow an permission after asking the user once a session.
public static final byte
ONE_SHOT
Allow an permission after asking the user every use.
public static final byte
DENY_SESSION
Denied by the user, until next session.
public static final byte
DENY
Ask the user to Deny by default.
public static final byte
USER_DENIED
Deny by the user, until the user changes it in the settings form.
private static Hashtable
permissionsTable
Table to save all permissions; keyed by the domain
Constructors Summary
Methods Summary
private static voidclearPerms(byte[] perms)
Clear the permissions list by setting all permissions to Permissions.DENY.

param
perms a permission array to clear.

        // Assume perms array is non-null
        for (int i = 0; i < perms.length; i++) {
            perms[i] = Permissions.NEVER;          // This is default perm
        }
private static java.util.VectorexpandAlias(java.util.Vector apiList, java.util.Hashtable aliasTable)
Expand all alias names in the given API list to their constituent APIs.

param
apiList a list of APIs that may or may not contain alias names.
param
aliasTable a table that contains all known aliases.
return
Vector a list of APIs with all aliases fully expanded.

        boolean aliasMatch = false;
        Vector  returnList;
        int     aliasIdx;
        int     apiIdx;

        /* Exit if there are no APIs or aliases defined */
        if ((aliasTable == null) || (apiList == null)) {
            return apiList;
        }

        /* We will have at leave apiList.size() elements in the return list */
        returnList = new Vector(apiList.size());

        /* Check every API entry to see if it's an alias */
        for (apiIdx = 0; apiIdx < apiList.size(); apiIdx++) {
            String apiName   = (String)apiList.elementAt(apiIdx);

            /* If the API name contains a period, it cannot be an alias */
            if (apiName.indexOf('.") == -1) {
                Enumeration e  = aliasTable.keys();

                while (e.hasMoreElements()) {
                    String aliasName = (String)e.nextElement();

                    if (apiName.equals(aliasName)) {
                        Vector aliasVector =
                            (Vector)aliasTable.get(aliasName);
                        
                        // Add all API names contained in the alias
                        for (int i = 0; i < aliasVector.size(); i++) {
                            returnList.addElement(aliasVector.elementAt(i));
                        }

                        aliasMatch = true;
                        
                        break; // Can only match one alias name per apiName
                    }
                }
            }

            if (aliasMatch) {
                aliasMatch = false;
                continue;           // Do not add apiName if it is an alias
            }

            /* Did not match an alias name; this must be a real API name */
            returnList.addElement(apiName);
        }

        return returnList;
public static byte[][]forDomain(SecurityToken token, java.lang.String name)
Create a list of permission groups a domain is permitted to perform.

param
token security token of the calling class, can be null for built-in classes.
param
name name of domain
return
2 arrays, the first containing the maxium level for each permission, the second containing the default or starting level for each permission supported

        byte [] maximums = new byte[NUMBER_OF_PERMISSIONS];
        byte [] defaults = new byte[NUMBER_OF_PERMISSIONS];
        byte[][] permissions = {maximums, defaults};

        if (INTERNAL_DOMAIN_NAME.equals(name)) {
            for (int i = 0; i < maximums.length; i++) {
                maximums[i] = ALLOW;
                defaults[i] = ALLOW;
            }

            return permissions;
        }

        /*
         * Get permissions from the permissions file
         */
        if (getPermissions(token, name, maximums, defaults)) {
            return permissions;
        }            

        // unknown is the same as untrusted
        if (getPermissions(token, "untrusted", maximums, defaults)) {
            return permissions;
        }

        throw new SecurityException("untrusted domain is not configured");
public static byte[]getEmptySet()
Create an empty list of permission groups.

return
array containing the empty permission groups

        byte[] permissions = new byte[NUMBER_OF_PERMISSIONS];

        clearPerms(permissions);  // Set permissions to default values
        return permissions;
public static java.lang.StringgetName(int permission)
Get the name of a permission.

param
permission permission number
return
permission name
exception
SecurityException if the permission is invalid


                             
         
        if (permission < 0 || permission >= names.length) {
            throw new SecurityException(SecurityToken.STD_EX_MSG);
        }

        return names[permission];
private static bytegetPermFromString(java.lang.String permString)
Convert the string permission name to the byte constant value.

param
permString the permission string to convert
return
byte the permission constant value
exception
IllegalArgumentException if permString is not one of pre-defined permission values

        /* Do not check for 'null'; we should throw an NPE */
        if ("allow".equals(permString)) {
            return Permissions.ALLOW;
        } else if ("blanket".equals(permString)) {
            return Permissions.BLANKET;
        } else if ("session".equals(permString)) {
            return Permissions.SESSION;
        } else if ("oneshot".equals(permString)) {
            return Permissions.ONE_SHOT;
        } else {
            // Abort processing
            throw new IllegalArgumentException("bad perm level: " +
                                               permString);
        }
private static intgetPermIndex(java.lang.String apiName)
Find the given permission name in the global names list.

param
apiName the name of the API to find.
return
int the index into global names list.
exception
IllegalArgumentException if apiName is not found in the global names list

        int nameIdx;

        for (nameIdx = 0; nameIdx < names.length; nameIdx++) {
            if (names[nameIdx].equals(apiName)) {
                return nameIdx;
            }
        }

        // Abort processing
        throw new IllegalArgumentException("bad API name: " + apiName);
private static booleangetPermissions(SecurityToken token, java.lang.String domain, byte[] permissions, byte[] defaults)
Get the list of permissions and defaults for a domain.

param
token security token of the calling class
param
domain name of domain
param
permissions array to hold the permissions
param
defaults array to hold the defaults for the user query
return
true if the domain was found, otherwise false


        if (permissionsTable == null) {
            // We have not read the policy file yet..
            try {
                readPermissionsTable(token);
            } catch (InvalidJadException ije) {
                return false;
            }
        }

        byte[] permList = (byte[])permissionsTable.get(domain);

        if (permList != null) {
            // Copy permissions from permission table
            for (int idx = 0; idx < NUMBER_OF_PERMISSIONS; idx++) {
                int permIdx = idx * 2;
                
                permissions[idx] = permList[permIdx];
                defaults[idx]    = permList[permIdx+1];
            }
            
            return true;
        }

        return false;
public static java.lang.StringgetQuestion(int permission)
Get the question for a permission.

param
permission permission number
return
permission question
exception
SecurityException if the permission is invalid

        if (permission < 0 || permission >= questions.length) {
            throw new SecurityException(SecurityToken.STD_EX_MSG);
        }

        return questions[permission];
public static java.lang.StringgetTitle(int permission)
Get the dialog title for a permission.

param
permission permission number
return
permission dialog title
exception
SecurityException if the permission is invalid

        if (permission < 0 || permission >= titles.length) {
            throw new SecurityException(SecurityToken.STD_EX_MSG);
        }

        return titles[permission];
private static voidreadPermissionsTable(SecurityToken token)
Read the permissions file into the global permissions table.

param
token security token of the calling class
exception
InvalidJadException if there was any trouble reading or parsing the permissions file.

        RandomAccessStream storage;
        InputStream permIS;
        
        try {
            storage = new RandomAccessStream(token);
            storage.connect(File.getStorageRoot() + POLICY_FILENAME,
                            Connector.READ);
            permIS = storage.openInputStream();
        } catch (Exception e) {
            throw new InvalidJadException(InvalidJadException.JAD_NOT_FOUND);
        }
        
        try {
            PermissionProperties pp = new PermissionProperties();
            byte[]    newPerms      = new byte[NUMBER_OF_PERMISSIONS*2];
            String    currentDomain = null;
            Hashtable aliasTable    = null;
            String    propertyValue;
            String    propertyKey;
            
            pp.load(permIS);
            clearPerms(newPerms);
            
            for (int i = 0; i < pp.size(); i++) {
                propertyKey   = pp.getKeyAt(i);
                propertyValue = pp.getValueAt(i);
                
                if ("alias".equals(propertyKey)) {
                    String aliasName;
                    String aliasValue;
                    int    nameIdx;
                    
                    nameIdx    = propertyValue.indexOf(' ");
                    aliasName  = propertyValue.substring(0, nameIdx);
                    aliasValue = propertyValue.substring(nameIdx + 1, 
                                     propertyValue.length());
                    if (aliasTable == null) {
                        aliasTable = new Hashtable();
                    }
                    aliasTable.put(aliasName, 
                                   Util.getCommaSeparatedValues(aliasValue));
                } else if ("domain".equals(propertyKey)) {
                    if (permissionsTable == null) {
                        permissionsTable = new Hashtable();
                    }

                    if (currentDomain != null) {
                        permissionsTable.put(currentDomain, newPerms);

                        // hash tables do not copy values
                        newPerms = new byte[NUMBER_OF_PERMISSIONS*2];
                        clearPerms(newPerms);
                    }

                    currentDomain = propertyValue;
                } else if ("allow".equals(propertyKey)) {
                    Vector apiNames;
                    
                    apiNames = Util.getCommaSeparatedValues(propertyValue);
                    apiNames = expandAlias(apiNames, aliasTable);

                    setPerms(newPerms, apiNames, 
                             Permissions.ALLOW, Permissions.ALLOW);
                } else {
                    /* 
                     * Must be a user permission level. If it is some
                     * other string, getPermFromString() will throw
                     * an IllegalArgumentException and abort processing
                     * of the policy file
                     */
                    byte perm;
                    byte defaultPerm;
                    int  defaultPermIdx;
                    if ((defaultPermIdx = propertyKey.indexOf('(")) != -1) {
                        String permString = 
                            propertyKey.substring(0, defaultPermIdx);
                        String defaultPermString = 
                            propertyKey.substring(defaultPermIdx + 1, 
                                                  propertyKey.indexOf(')"));
                        
                        perm = getPermFromString(permString);
                        defaultPerm = getPermFromString(defaultPermString);
                    } else {
                        perm = getPermFromString(propertyKey);
                        defaultPerm = Permissions.DENY;
                    }
                    
                    Vector apiNames;
                    
                    apiNames = Util.getCommaSeparatedValues(propertyValue);
                    apiNames = expandAlias(apiNames, aliasTable);

                    setPerms(newPerms, apiNames, perm, defaultPerm);
                }
            }
            if (permissionsTable == null) {
                permissionsTable = new Hashtable();
            }
            if (currentDomain != null) {
                permissionsTable.put(currentDomain, newPerms);
            }
        } catch (Exception e) {
            System.out.println("Corrupt policy file");
            e.printStackTrace();
            permissionsTable = null; // Do not save half-processed permissions
            throw new InvalidJadException(InvalidJadException.INVALID_KEY);
        } finally {
            try {
                storage.disconnect();
            } catch (Exception e) {
                // nothing we can do.
            }
        }
private static voidsetPerms(byte[] perms, java.util.Vector apiList, byte highestLevel, byte defaultLevel)
Set the default and highest permission level for the given API(s). The API list must only include real API names and not alias names.

param
perms the permission array to set
param
apiList a list of APIs to set
param
highestLevel the highest permission level for every API in apiList
param
defaultLevel the default permission level for every API in apiList

        int apiIdx;

        for (apiIdx = 0; apiIdx < apiList.size(); apiIdx++) {
            int permIdx;

            permIdx = getPermIndex((String)apiList.elementAt(apiIdx)) * 2;
            perms[permIdx]   = highestLevel;
            perms[permIdx+1] = defaultLevel;
        }