File	Doc	Category	Size	Date	Package
SecurityHandler.java	API Doc	phoneME MR2 API (J2ME)	20962	Wed May 02 18:00:26 BST 2007	com.sun.midp.security

SecurityHandler

• java.lang.Object

Fields Summary
private static final byte	NOT_ASKED Session level interaction has not occured.
private static final byte	GRANTED User granted permission for this session.
private static final byte	DENIED User denied permission for this session.
private static SecurityToken	classSecurityToken The security token for this class.
public static final String	STD_EX_MSG The standard security exception message.
private byte[]	permissions Permission list.
private byte[]	sessionValues A flag for the session value of each permission.
private byte[]	maxPermissionLevels Maximum permission level list.
private boolean	trusted True, if trusted.

Constructors Summary
public SecurityHandler(byte[] apiPermissions, String domain) Creates a security domain with a list of permitted actions or no list to indicate all actions. The caller must be have permission for Permissions.MIDP or be the first caller of the method for this instance of the VM. param apiPermissions for the token param domain name of the security domain exception SecurityException if caller is not permitted to call this method MIDletStateHandler midletStateHandler = MIDletStateHandler.getMidletStateHandler(); MIDletSuite midletSuite = midletStateHandler.getMIDletSuite(); midletSuite.checkIfPermissionAllowed(Permissions.AMS); init(apiPermissions, domain);
public SecurityHandler(SecurityToken securityToken, byte[] apiPermissions, String domain) Creates a security domain with a list of permitted actions or no list to indicate all actions. The caller must be have permission for Permissions.MIDP or be the first caller of the method for this instance of the VM. param securityToken security token of the caller param apiPermissions for the token, can be null param domain name of the security domain exception SecurityException if caller is not permitted to call this method securityToken.checkIfPermissionAllowed(Permissions.AMS); init(apiPermissions, domain);

Methods Summary
public static boolean	askUserForPermission(SecurityToken token, boolean trusted, int title, int question, java.lang.String app, java.lang.String resource, java.lang.String extraValue) Ask the user yes/no permission question. param token security token with the permission to preempt the foreground display param trusted true to display the trusted icon, false to display the untrusted icon param title Resource constant for the title of the dialog param question Resource constant for the question to ask user param app name of the application to insert into a string can be null if no %1 a string param resource string to insert into a string, can be null if no %2 in a string param extraValue string to insert into a string, can be null if no %3 in a string return true if the user says yes else false exception InterruptedException if another thread interrupts the calling thread while this method is waiting to preempt the display. PermissionDialog dialog = new PermissionDialog(token, trusted, title, question, app, resource, extraValue); return dialog.waitForAnswer();
public boolean	checkForPermission(int permission, int title, int question, int oneshotQuestion, java.lang.String app, java.lang.String resource, java.lang.String extraValue) Check for permission and throw an exception if not allowed. May block to ask the user a question. The title, and question strings will be translated, if a string resource is available. Since the strings can have substitution token in them, if there is a "%" it must changed to "%%". If a string has a %1, the app parameter will be substituted for it. If a string has a "%2, the resource parameter will be substituted for it. If a string has a %3, the extraValue parameter will be substituted for it. param permission ID of the permission to check for, the ID must be from {@link com.sun.midp.security.Permissions} param title Resource constant for the title of the dialog param question Resource constant for the question to ask the user param oneshotQuestion Resource constant for the oneshot question to ask the user param app name of the application to insert into a string can be null if no %1 a string param resource string to insert into a string, can be null if no %2 in a string param extraValue string to insert into a string, can be null if no %3 in a string return true if the permission interaction has permanently changed and the new state should be saved, this will only happen if the permission granted exception SecurityException if the permission is not allowed by this token exception InterruptedException if another thread interrupts the calling thread while this method is waiting to preempt the display. return checkForPermission(permission, title, question, oneshotQuestion, app, resource, extraValue, STD_EX_MSG);
public boolean	checkForPermission(int permission, int title, int question, int oneShotQuestion, java.lang.String app, java.lang.String resource, java.lang.String extraValue, java.lang.String exceptionMsg) Check for permission and throw an exception if not allowed. May block to ask the user a question. The title, question, and answer strings will be translated, if a string resource is available. Since the strings can have substitution token in them, if there is a "%" it must changed to "%%". If a string has a %1, the app parameter will be substituted for it. If a string has a "%2, the resource parameter will be substituted for it. If a string has a %3, the extraValue parameter will be substituted for it. param permission ID of the permission to check for, the ID must be from {@link com.sun.midp.security.Permissions} param title Resource constant for the title of the dialog param question Resource constant for the question to ask user param oneShotQuestion Resource constant for the oneshot question to ask the user param app name of the application to insert into a string can be null if no %1 a string param resource string to insert into a string, can be null if no %2 in a string param extraValue string to insert into a string, can be null if no %3 in a string param exceptionMsg message if a security exception is thrown return true if the permission interaction has permanently changed and the new state should be saved, this will only happen if the permission granted exception SecurityException if the permission is not allowed by this token exception InterruptedException if another thread interrupts the calling thread while this method is waiting to preempt the display. if (permissions == null) { /* totally trusted, all permissions allowed */ return false; } synchronized (this) { if (permission >= 0 && permission < permissions.length) { switch (permissions[permission]) { case Permissions.ALLOW: case Permissions.BLANKET_GRANTED: return false; case Permissions.BLANKET: /* This level means the question has not been asked yet. */ if (askUserForPermission(classSecurityToken, trusted, title, question, app, resource, extraValue)) { Permissions.setPermissionGroup(permissions, permission, Permissions.BLANKET_GRANTED); return true; } Permissions.setPermissionGroup(permissions, permission, Permissions.BLANKET_DENIED); break; case Permissions.SESSION: if (sessionValues[permission] == GRANTED) { return false; } if (sessionValues[permission] == DENIED) { break; } if (askUserForPermission(classSecurityToken, trusted, title, question, app, resource, extraValue)) { /* * Save the fact that the question has already * been asked this session. */ Permissions.setPermissionGroup(sessionValues, permission, GRANTED); return false; } /* * Save the fact that the question has already * been asked this session. */ Permissions.setPermissionGroup(sessionValues, permission, DENIED); break; case Permissions.ONESHOT: if (askUserForPermission(classSecurityToken, trusted, title, oneShotQuestion, app, resource, extraValue)) { return false; } break; default: // Permissions.NEVER break; } // switch } // if throw new SecurityException(exceptionMsg); } // synchronized
public int	checkPermission(java.lang.String permission) Get the status of the specified permission. If no API on the device defines the specific permission requested then it must be reported as denied. If the status of the permission is not known because it might require a user interaction then it should be reported as unknown. param permission to check if denied, allowed, or unknown. return 0 if the permission is denied; 1 if the permission is allowed; -1 if the status is unknown boolean found = false; int i; synchronized (this) { for (i = 0; i < Permissions.NUMBER_OF_PERMISSIONS; i++) { if (Permissions.getName(i).equals(permission)) { found = true; break; } } if (!found) { // report denied return 0; } switch (permissions[i]) { case Permissions.ALLOW: case Permissions.BLANKET_GRANTED: // report allowed return 1; case Permissions.SESSION: if (sessionValues[i] == GRANTED) { // report allowed return 1; } if (sessionValues[i] == DENIED) { // report denied return 0; } // fall through case Permissions.BLANKET: case Permissions.ONESHOT: // report unknown return -1; default: // Permissions.NEVER break; } // report denied return 0; }
private void	init(byte[] apiPermissions, java.lang.String domain) Creates a security domain with a list of permitted actions or no list to indicate all actions. The caller must be have permission for Permissions.MIDP or be the first caller of the method for this instance of the VM. param apiPermissions for the token param domain name of the security domain exception SecurityException if caller is not permitted to call this method MIDletStateHandler midletStateHandler = MIDletStateHandler.getMidletStateHandler(); MIDletSuite midletSuite = midletStateHandler.getMIDletSuite(); maxPermissionLevels = (Permissions.forDomain(domain))[Permissions.MAX_LEVELS]; permissions = apiPermissions; sessionValues = new byte[permissions.length]; trusted = Permissions.isTrusted(domain);
static void	initSecurityToken(SecurityToken token) Initializes the security token for this class, so it can perform actions that a normal MIDlet Suite cannot. param token security token for this class. if (classSecurityToken != null) { return; } classSecurityToken = token;