All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----glguerin.authkit.Privilege

Summary

public final class  Privilege
     extends java.lang.Object
{
          // Fields 1
     public static final Privilege EMPTY;

          // Constructors 2
     public Privilege(String);
     public Privilege(String, Object, int);

          // Methods 6
     public boolean equals(Object);
     public int getFlags();
     public String getName();
     public byte[] getValue();
     public int hashCode();
     public String toString();
}

A Privilege encapsulates a privilege-name with an optional value-Object and flags. It represents a privilege to be authorized or otherwise used by an Authorization.

The meaning (semantics or utility) of a Privilege's name, value, and flags are always platform-dependent and implementation-dependent. There may also be application-specific names, values, and flags. A Privilege name, in particular, usually represents the name of a privilege or set of privileges defined or described in some security-policy database. The form, location, and access mechanisms of that database are irrelevant to the public API of the Privilege or Authorization classes.

Whether a Privilege needs a value-Object or not depends on the privilege being requested. It also depends on the Authorization imp, since different imps may do things differently.

Regardless of the concrete Authorization imp, a Privilege is immutable once created, for the obvious security reasons. To maintain this premise, a byte[] value-Object is copied and kept, rather than keeping the original byte[]. Other types of value-Object have their toString() representation transformed into a byte[], which is then kept.

A Privilege's value, if any, is always ultimately represented as a byte[]. All types passed to the constructor, other than byte[], are first represented as a String by calling the toString() method, then that String is represented as a byte[] by encoding to UTF-8. Object types that do not return meaningful results from toString() cannot be used directly as value-Objects. All instances of String simply return themselves from toString(), so Strings are directly usable as value-Objects.

At this time, few privileges need a value-Object at all. The main exception to this (at least on Mac OS X) is the privilege to run a program as root using Authorization.execPrivileged(). To create such a Privilege, you should always use Authorization.makeExecPrivilege(), rather than assembling one yourself. The makeExecPrivilege() method will always create a Privilege with the appropriate name and value for the implementation.

Currently, a Privilege's flags are not used by any Authorization implementation. You should not use them for your own purposes, either. Doing so could conflict with any future use by a concrete Authorization imp.

This class is final for security reasons. Changing this may have security consequences.

See Also: Authorization

Cross Reference

Returned By:

Authorization.makeExecPrivilege(), MacOSXAuthorization.makeExecPrivilege(), DenyAllAuthorization.makeExecPrivilege(), GrantAllAuthorization.makeExecPrivilege()

   public static final Privilege EMPTY

Public constant Privilege, usable as a dummy or placeholder. Its name is the empty String "", and its value is an empty byte[].

Constructors

· Privilege

Summary  |  Top

   public Privilege(String name) 

Construct with given name, a null value, and zero flags.

   public Privilege(String name, 
                    Object value, 
                    int flags) 

Construct with given name, value, and flags. The name must not be null. The flags should normally be zero, since they are all reserved for future use. The value may be null, a byte[], or an instance of some other type. Every type other than byte[] must implement a meaningful toString() method, which will eventually be turned into a byte[].

If the given value is null, an empty byte[] is assigned to the 'value' instance variable. If the given value is a byte[], a replica of it is assigned to the 'value' instance variable. If the given value is any other type, its toString() method is called, that String is encoded as UTF8 bytes, and that byte[] is assigned to the 'value' instance variable. Therefore, any non-null non-byte[] value-Object must return something sensible from its toString() method.

Whatever is assigned to the internal instance variable, a replica of it will be returned by getValue().

The flags are not currently used by any Authorization implementation, and are available for future expansion. Since all flags are reserved for future use, you should normally pass 0 as the flags value.

   public String getName() 

Return the non-null name.

   public byte[] getValue() 

Return a non-null replica of the value byte[].

   public int getFlags() 

Return the flags.

   public String toString() 

Return a String holding the name, a value-descriptive String, and flags, separated by :'s.

Overrides:

toString in class Object

   public int hashCode() 

Return an int that depends on name, value, and flags.

Overrides:

hashCode in class Object

   public boolean equals(Object other) 

Return a boolean that depends on the match of name, value, and flags. This imp returns true only if other is a Privilege with the same name via String.equals(), the same flags via 'int' comparison, and the same byte-for-byte value via byte[] element comparison. The internal 'asStr' String IS NOT directly involved in the overall test.

Since byte-by-byte comparison is used, two byte-arrays that have the same length and contents are considered equal. This is necessary since the Privilege constructors make copies of any byte[] arg supplied. Thus, using byte[].equals(), which tests reference comparison, would not work.

Overrides:

equals in class Object

All Packages  This Package  Class Hierarchy  Class Search  Index