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

SecurityToken

public final class SecurityToken extends Object
Contains methods to get various security state information of the currently running MIDlet suite.

Fields Summary
private static final String
BLANKET_ANSWER
The default blanket level answer.
private static final String
SESSION_ANSWER
The default session level answer.
private static final String
CANCEL_ANSWER
The default cancel cancel answer.
private static final String
DENY_ANSWER
The default deny level answer.
public static final String
STD_EX_MSG
The standard security exception message.
private static boolean
firstCaller
Enables the first domain be constructed without a domain.
private byte[]
permissions
Permission list.
private boolean[]
permissionAsked
A flag for each permission, True if permission has been asked this session.
private byte[]
maxPermissionLevels
Maximum permission level list.
Constructors Summary
public SecurityToken(SecurityToken securityToken, byte[] ApiPermissions)
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, can be null for the first caller
param
ApiPermissions for the token, can be null
exception
SecurityException if caller is not permitted to call this method


                                                                                                                  
      
              
        // assume the JAM is the first caller
        if (firstCaller) {
            firstCaller = false;
        } else {
            securityToken.checkIfPermissionAllowed(Permissions.MIDP);
        }

        maxPermissionLevels = ApiPermissions[Permissions.MAX_LEVELS];

        permissions = ApiPermissions[Permissions.CUR_LEVELS];

        permissionAsked = new boolean[permissions.length];
private SecurityToken()
Creates a security domain for preempting, all permitted actions.

Methods Summary
public static intaskUserForPermission(com.sun.midp.security.SecurityToken token, java.lang.String title, java.lang.String question, java.lang.String app, java.lang.String resource, java.lang.String extraValue, int maximumLevel, int defaultLevel)
Ask the user permission, selecting the max level, default level.
param
token security token with the permission to peempt the
foreground display
param
title title of the dialog
param
question 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
param
maximumLevel maximum permission level to display
param
defaultLevel default permission level, DENY_SESSION,
or CANCELLED for "Not Now". If the level is greater than the
maximum level, maximum level will be used.
return
new permission level or -1 if user cancelled
exception
InterruptedException if another thread interrupts the
calling thread while this method is waiting to preempt the
display.

        PermissionDialog dialog =
            new PermissionDialog(token, title, question, app, resource,
                extraValue, maximumLevel, defaultLevel, 0, BLANKET_ANSWER,
                SESSION_ANSWER, CANCEL_ANSWER, DENY_ANSWER);
        
        return dialog.waitForAnswer();
    
public static intaskUserForPermission(com.sun.midp.security.SecurityToken token, java.lang.String title, java.lang.String question, java.lang.String app, java.lang.String resource, java.lang.String extraValue, int maximumLevel, int defaultLevel, int skip, java.lang.String blanketAnswer, java.lang.String sessionAnswer, java.lang.String cancelAnswer, java.lang.String denyAnswer)
Ask the user permission and wait for the answer.



The title, question, and answer strings will be translated,
if a string resource is available.
Since the strings can have sustitution 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
token security token with the permission to peempt the
foreground display
param
title title of the dialog
param
question 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
param
maximumLevel maximum permission level to display
param
defaultLevel default permission level, DENY_SESSION,
or CANCELLED for "Not Now". If the level is greater than the
maximum level, maximum level will be used.
param
skip permission to skip, SESSION, DENY,
or any other for skip none, multiple permissions can be added
together
param
blanketAnswer text for the blanket answer
param
sessionAnswer text for the session answer or one shot if
the maximum permission level is one shot
param
cancelAnswer text for the cancel answer
param
denyAnswer text for the deny answer
return
new permission level or -1 if user cancelled
exception
InterruptedException if another thread interrupts the
calling thread while this method is waiting to preempt the
display.

        PermissionDialog dialog =
            new PermissionDialog(token, title, question, app, resource,
                extraValue, maximumLevel, defaultLevel, skip, blanketAnswer,
                sessionAnswer, cancelAnswer, denyAnswer);
        
        return dialog.waitForAnswer();
    
public voidcheckForPermission(int permission, java.lang.String title, java.lang.String question, 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 sustitution 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 title of the dialog
param
question 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
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.

        checkForPermission(permission, title, question, app, resource, 
             extraValue, 0, SESSION_ANSWER, CANCEL_ANSWER, STD_EX_MSG);
    
public voidcheckForPermission(int permission, java.lang.String title, java.lang.String question, java.lang.String app, java.lang.String resource, java.lang.String extraValue, int skip, java.lang.String sessionAnswer, java.lang.String cancelAnswer, 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 sustitution 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 title of the dialog
param
question 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
param
skip permission to skip, SESSION, DENY,
or any other for skip none, multiple permissions can be added
together
param
sessionAnswer text for the session answer or one shot if
the maximum permission level is one shot
param
cancelAnswer text for the cancel answer
param
exceptionMsg message if a security exception is thrown
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;
        }

        synchronized (this) {
            if (permission >= 0 && permission < permissions.length) {
                switch (permissions[permission]) {
                case Permissions.SESSION:
                case Permissions.DENY_SESSION:
                    if (permissionAsked[permission]) {
                        break;
                    }

                    // fall through
                case Permissions.ONE_SHOT:
                case Permissions.BLANKET:
                case Permissions.DENY:
                    permissions[permission] =
                        (byte)askUserForPermission(new SecurityToken(), title,
                        question, app, resource, extraValue,
                        maxPermissionLevels[permission],
                        permissions[permission], skip, BLANKET_ANSWER,
                        sessionAnswer, cancelAnswer, DENY_ANSWER);
                    
                    permissionAsked[permission] = true;
                }

                switch (permissions[permission]) {
                case Permissions.BLANKET:
                    // do not ask again
                    permissions[permission] = Permissions.BLANKET_GRANTED;

                    // fall through
                case Permissions.ALLOW:
                case Permissions.BLANKET_GRANTED:
                case Permissions.SESSION:
                case Permissions.ONE_SHOT:
                    return;

                case Permissions.DENY:
                    // do not ask again
                    permissions[permission] = Permissions.USER_DENIED;

                case Permissions.NEVER:
                    // fail do not ask again
                    break;

                default:
                    // fail but ask again, so switch back to DENY session
                    permissions[permission] = (byte)Permissions.DENY_SESSION;
                }
            }

            throw new SecurityException(exceptionMsg);
        }
    
public voidcheckIfPermissionAllowed(int permission)
Check to see the suite has the ALLOW level for specific permission.
This is used for by internal APIs that only provide access to
trusted system applications.
param
permission permission ID from com.sun.midp.security.Permissions
exception
SecurityException if the permission is not
allowed by this token
        checkIfPermissionAllowed(permission, STD_EX_MSG);
    
public voidcheckIfPermissionAllowed(int permission, java.lang.String exceptionMsg)
Check to see the suite has the ALLOW level for specific permission.
This is used for by internal APIs that only provide access to
trusted system applications.
param
permission permission ID from com.sun.midp.security.Permissions
param
exceptionMsg message if a security exception is thrown
exception
SecurityException if the permission is not
allowed by this token
        if (permissions == null) {
            /* totally trusted, all permission allowed */
            return;
        }

        if (permission >= 0 && permission < permissions.length &&
            (permissions[permission] == Permissions.ALLOW)) {
            return;
        }

        // this method do not ask the user
        throw new SecurityException(exceptionMsg);
    
public intcheckPermission(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 (permissionAsked[i]) {
                    return 1;
                }

                // fall through
            case Permissions.BLANKET:
            case Permissions.ONE_SHOT:
            case Permissions.DENY:
                // report unknown
                return -1;

            case Permissions.DENY_SESSION:
                if (!permissionAsked[i]) {
                    return -1;
                }
            }

            // report denied
            return 0;
        }