Class glguerin.authkit.Authorization

All Packages  This Package  Class Hierarchy  Class Search  Index

Class glguerin.authkit.Authorization

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

Summary

public abstract class  Authorization
     extends java.lang.Object
{
          // Fields 13
     public static final int HAS_PROCESS_COUPLED_STREAMS;
     public static final int HAS_PROCESS_DESTROY;
     public static final int HAS_PROCESS_ELEVATED;
     public static final int HAS_PROCESS_ERRORSTREAM;
     public static final int HAS_PROCESS_EXITVALUE;
     public static final int HAS_PROCESS_INPUTSTREAM;
     public static final int HAS_PROCESS_OUTPUTSTREAM;
     public static final int HAS_PROCESS_WAITFOR;
     public static final int HAS_SESSION_MULTIPROCESS;
     public static final int HAS_SYNTHETIC_PREAUTH;
     public static final int WHEN_EARLIEST;
     public static final int WHEN_LATEST;
     protected Hashtable pastGranted;

          // Constructors 1
     protected Authorization();

          // Methods 23
     protected void addGranted(Privilege);
     public abstract void attach(byte[]);
     public abstract void attachPrivileged();
     public abstract void authorize(Privilege, boolean);
     protected void clearGranted();
     public abstract void detach(boolean);
     public abstract Process execPrivileged(String[]);
     protected void finalize() throws Throwable;
     protected String formFingerprint(String, byte[]);
     public abstract int getCapabilities();
     public abstract Date getPastGrantedDate(Privilege, int);
     public abstract Enumeration getPastGrantedPrivileges();
     public String getPublicIdentifier();
     public abstract byte[] getSecretIdentifier();
     public abstract int getSecretLength();
     public abstract boolean isAvailable(Privilege);
     public boolean isCapable(int);
     protected Enumeration keysGranted();
     public abstract Privilege makeExecPrivilege(String);
     public byte[] makeFingerprint(String);
     public abstract void preauthorize(Privilege);
     public void release();
     protected Date whenGranted(Privilege, int);
}

An Authorization is a high-level way to manage access to restricted parts of a Java program, or to privileged functionality provided by the system, such as executing another program with elevated privileges (i.e. with and effective user-ID of root). Instances of the Privilege class represent named individual privileges or groups of privileges. Access to restricted services is granted or denied with one principal method: authorize(). Privileged execution of other programs is controlled by one method: execPrivileged(). Other methods supplement these core facilities. An Authorization is essentially a simple facade placed over any kind of implementation one cares to use or provide.

The Authorization class is abstract, so a concrete implementation is always needed. Different concrete implementations can perform authentication and authorization in different ways, using different mechanisms or credentials. A concrete implementation may be platform-neutral or platform-specific. It can be based on any underlying technology desired. For example, it's possible to implement Authorization using smart-cards, USB biometric devices, JAAS, Kerberos, or almost any other authentication and authorization technology.

An Authorization isn't really like any of the existing Java classes or frameworks that provide access controls, because it takes a very high-level view and hides all the details within its implementation. All the details of principals, subjects, identities, roles, credentials, policies, authenticators, pre-conditions, expiries, etc. are hidden in the specific implementation. That implementation may be entirely self-enforced (say, by java.security classes), or it may be entirely system-enforced (say, by Mac OS X's Auth Services or by Kerberos), or it may be some balance between self-enforced and system-enforced facilities.

A concrete Authorization is provided for Mac OS X, based on the Authorization Services API. As a result, it can execute other programs, including Java programs, with an effective user-ID of root. This execution is controlled through a system-enforced authentication dialog, under system-provided and system-restricted authorization policies. That is, the transition to an effective user-ID of root is entirely system-controlled.

Any Java program executing a process with elevated privileges must be entirely trustworthy itself, and it must remain trustworthy. If the Java program or any of its components can be altered by an unprivileged agent, then the program can be "turned to the Dark Side" for possible malicious ends. This is always true for any program using any kind of Authorization -- if you can't trust it's entire chain of provenance, you shouldn't trust that it will act properly with elevated privileges.

In any Authorization implementation, some Privileges may only be effectively exercised by executing another program (process). The threshold at which this becomes necessary is implementation-dependent. On typical Unix-like systems, a process is the smallest entity that can have distinct enforceable privileges, rather than a thread, a class, or an object. Mac OS X works this way, so if special system-enforced privileges are needed, it may require a separate process to do it. That's why execPrivileged() exists.

The threshold of when to execute another process may be affected by the use of setuid and setgid processes, or by the manipulation of effective uid and gid within a single process. Nothing in standard Java knows anything about setuid or setgid processes. Neither does any implementation of Authorization. You may be able to use my Easy Posix Toolkit for Java to manage a process's real and effective uid/gid's.

SESSIONS

Each Authorization is attached to a single underlying authorization and authentication session. That session manages all the credentials and authorizations, and performs authentication as neeeded, using whatever means are defined in the security policies and rules. The precise nature or mechanisms of the session, its authorization policies, etc. are not defined by the Authorization class. Instead, an Authorization is an opaque facade over whatever means or mechanisms an implementation wishes to encapsulate.

A newly instantiated Authorization is not attached to any session. A session may be explicitly attached with either of two methods, or implicitly by calling certain Authorization methods. Once attached to a session, an Authorization remains attached to the same session until explicitly detached, or until the current process terminates. Process termination is equivalent to release() or detach(false).

One way to attach an Authorization to an existing session is possible if you know the session's secret identifier. You can also attach to an existing session if you have privileged access, but only when the current process is a child by execPrivileged().

If no session is attached, the following Authorization methods will implicitly create and attach a new session:

authorize()
execPrivileged()
isAvailable()
preauthorize()

In addition to creating and attaching a new session as needed, each of the above methods will then use that session to perform its particular action. In all methods but isAvailable(), failing to authorize or authenticate throws an UnauthorizedException, which is a subclass of SecurityException.

To ensure that a session is attached, the simplest approach is to call isAvailable() with a dummy Privilege, such as Privilege.EMPTY. Since isAvailable() will create a session as needed, yet won't throw an UnauthorizedException, you can call it for the side-effect of creating a session as needed. Just ignore whether the dummy Privilege is available or not.

The following methods never cause automatic session creation:

attach()
attachPrivileged()
detach()
release()
getPublicIdentifier()
makeFingerprint()
getSecretIdentifier()
getSecretLength()
getPastGrantedPrivileges()
getPastGrantedDate()
makeExecPrivilege()
getCapabilities()
isCapable()

The attaching methods need an unattached Authorization in order to succeed. The detaching methods will behave properly whether a session is attached or not. The identifier-returning methods do not create a session, by definition. The remaining methods don't need a session attached in order to return a result.

ENFORCEMENT

An underlying grant of privilege may be enforced by the system (system-enforced), or it may be enforced only by your own code (self-enforced). There is no way to distinguish which privileges are system-enforced and which are self-enforced except by authorizing or using them. Or by reading the documentation. Or by examining the system's policy rules.

"Self-enforced" or "self-restricted" means that either your own code or some code in the Java environment enforces access controls. For example, Java's extensive security infrastructure is entirely self-enforced, largely by classes written by Sun or other security-library providers. Those classes call SecurityManager or AccessController methods at appropriate points in their execution, so that desired security policies are enforced in the intended way. If calls weren't done at the proper points, then the policies would not be enforced.

"System-enforced" or "self-restricted" means that the OS itself, or at least some entity outside the Java environment, enforces access controls. An example of a system-enforced privilege might be access to a file owned by some other user-account. Even if Java's security policies (or JAAS's policies) state that your program has full access to the file-system, you still can't access files or directories that the system forbids you from accessing. For example, many system files and directories are not public-writable on Mac OS X. If your Java app tries to write them, the attempt fails, even when there is no stated Java security policy preventing it. It fails because the system is enforcing a policy, not because Java is enforcing one. As another example, must user-accounts on Mac OS X do not have public-read permission on most of the home-directory's contents. If you aren't logged in as that user, you can't read their files or see into their directories, even if you have unrestricted Java privileges.

A system-enforced privilege must use system-provided access mechanisms in order to succeed. Such mechanisms may be system-dependent or unsupported in plain Java. Some mechanisms are supported in plain Java, such as a few in java.io.File. Many more mechanisms are not supported or even known in plain Java.

The whole purpose of the Authorization class is to give Java access to a system-provided mechanism, when it exists. Since this is a fairly simple class, it provides some hope of being ported to other systems, or of being adapted to other mechanisms.

The amount and kind of system-enforcement depends on the system. Different OSes enforce different rules under different circumstances, and different user-IDs have different privileges on a given OS (e.g. root vs. admin user vs. ordinary user on Mac OS X). Also, different things may be restricted by different mechanisms. For example, some things are restricted by user-ID, while others are restricted by group-ID. Or a given platform may have Access-Control Lists (ACL's), or there may be other mechanisms used (smart-cards, dongles, biometrics, whatever).

The Authorization class does not require any particular access-control policy or mechanism. Nor does it require any particular division of self-enforced vs. system-enforced privilege. You could create an implementation using AWT or Swing Dialogs, if you wanted. If the goal was to truly grant root-user privileges, though, you'd still have to figure out some way of doing that securely for your target platform.

See Also: Privilege

Cross Reference

Extended By:: MacOSXAuthorization, DenyAllAuthorization, GrantAllAuthorization
Returned By:: Envoy.buildAuth(), Envoy.getAuthorization(), Envoy.newAuth(), Tool.newAuth(), AuthTest.makeAuth()

Fields