All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----app.authkit.test.AuthTest
           |
           +----app.authkit.test.TestAuth

Summary

public class  TestAuth
     extends app.authkit.test.AuthTest
{
          // Constructors 1
     public TestAuth();

          // Methods 2
     public static void main(String[]);

     public void testAuth(Authorization, String, String[]);
}

TestAuth is the Swiss Army Knife test for Authorization methods. It can call every method of Authorization in one way or another. It does this by acting as a simple command interpreter over its command-line args. Some of its commands are "builtins" that call the Authorization methods. Everything else is an external command, which is run with elevated privileges using the execPrivileged() method.

The command-line args form an interpretable sequence of strings consisting of:

1. builtin commands, with args
2. external commands, with args
3. separators between groupings of command+args

The command parser is very simple, and works with the individual Strings of the String[] received by main(). Those Strings are not subdivided or otherwise parsed or manipulated. The interpreter simply breaks the sequence into groups, examines the first String of the group, and acts accordingly. For example, the grouping separator is ":", but it's only recognized in isolation. The interpreter will not recognize embedded :'s, nor will it subdivide commands or args at :'s.

A command grouping is separated from a subsequent grouping by a single isolated ":". Within a grouping, the first String is the command, and all other Strings are args for that command. A grouping may be empty, which is quietly ignored.

Builtins were named to minimize collisions with external commands on Mac OS X. The builtin commands and their args are:

see [privilege-name ...]

Display the current availability of each privilege-name, by calling isAvailable(). If no privilege-names are given, then list identity, latest date granted, and current availability of the getPastGrantedPrivileges() enumeration.

pre privilege-name [...]

Call preauthorize() for the named privilege(s). Interaction is always allowed. To preauthorize the root-execution privilege, use a name of "system.privilege.admin" on Mac OS X.

au+ privilege-name [...]

Call authorize() for the named privilege(s), with interaction allowed.

au- privilege-name [...]

Call authorize() for the named privilege(s), with interaction disallowed.

put [pathname ...]

Write the secret identifier in binary to each given pathname, overwriting any file of that name. If no pathnames are given, the secret identifier is dumped to stdout in hex.
THIS APPROACH IS INSECURE, AND IS ONLY SUITABLE FOR TESTING.

get [pathname]

If pathname is ".", call attachPrivileged() on a new Authorization, using it if successful. If pathname is anything other than ".", read the secret identifier from the file, call attach() on a new Authorization, and use it if successful. The secret identifier in a file must refer to a still-active session, or it will fail. The "." notation will only work if TestAuth is running in a JVM that was executed as a child of execPrivileged(). Also see the TestAttach class.

#

Call release() on the current Authorization.

##

Call detach( true ) on the current Authorization.

ver

Print the values of the "java.version" and "java.home" system properties, as a diagnostic aid.. This calls no Authorization method.

zzz [seconds]

Sleep for the given integer number of seconds, or for 3 secs if no value given. This calls no Authorization method. It only uses Java code, and does not execute an external command.

Any command not recognized as a builtin is interpreted as an external command, and will be executed using execPrivileged(). Some pre-processing may occur first:

JAVA ...

The all-upper-case "JAVA" command is a quasi-builtin, a little like a shell command-alias. It eventually executes an external command, but some substitution happens first. It takes the "java.home" property, appends "/bin/java" to it, and then executes that as an external command using execPrivileged().

The reason for doing this is that "java.home" will reflect the JVM currently running, which may be 1.3.1 or 1.4.1 on Mac OS X, and execute that same JVM in another process. If you just entered the command "/usr/bin/java", it won't necessarily be the current JVM.

You can customize which command in "java.home" is executed by defining it as a relative pathname in the "auth.bin.java" property. Be sure to use a file-separator appropriate to your platform. The value should always be a partial pathname relative to the location given by "java.home".

@ command [...]

When "@" appears as a separated token before an external command, then that command will have the secret identifier piped to it on its stdin stream. The "@" must be separated from the following command by white-space. Any external command can be run, including the JAVA quasi-builtin. Only commands that read their standard input will be useful. For example, the 'echo' command will be useless at reading the secret.

All external commands are executed using execPrivileged(), so they all run with elevated privileges. This is unwise as a general approach, but is acceptable for a test.

If authorization is needed before running an external command, it is obtained interactively if necessary. Failure to authorize or authenticate will fail to run the external command.

On Mac OS X, all commands executed by execPrivileged() must be absolute pathnames. If you don't know the absolute pathname of a command, use the 'which' command in your shell to tell you the pathname of a particular command. For example, 'which java' or 'which id'.

The external command's stdout is piped to the System.out stream, and the bytes are counted and CRC'ed for comparison purposes. On Mac OS X, the stderr is simply shared with the privileged process.

If the Authorization's privileged Process implements waitFor(), the external command is waited for. Otherwise a 3-second delay occurs, then the interpreter resumes parsing and executing commands. Since MacOSXAuthorization's privileged Process doesn't provide waitFor(), long-running external commands may need a subsequent 'zzz' builtin command.

Before each command is executed, whether builtin or external, the Authorization's current public identifier is displayed on stdout. This is done to help track when sessions are created, attached, and detached. It's also useful to compare to public identifiers displayed by other processes that attach to the same session. The identifiers should be identical, even though from different processes.

Several system properties affect the TestAuth command interpreter:

"authkit.imp"

This property's value is the fully qualified class name of an Authorization to instantiate and use. See method main().

"between"

This optional property defines an override for the ":" string separating command groupings. The main use for this property is so you can execute a privileged version of this class in another process, and change the separator. If you couldn't change the separator, you couldn't distinguish its commands from those of its parent. That's because the TestAuth interpreter doesn't do escaping. Usually, you don't have to set "between" or change it in any way.

"auth.bin.java"

This optional property defines an override for the "bin/java" command assembled by the quasi-builtin JAVA command. The main use for this property is when the external command isn't "bin/java", such as on Windows. Usually, you don't have to set "auth.bin.java" or change it in any way. See method doExec().

Constructors

· TestAuth

Summary  |  Top

   public TestAuth() 

Create with default separator defined by "between" property, or ":".

   public static void main(String[] args) 

Static entry point, when used as an application.

   public void testAuth(Authorization auth, 
                        String dontCare, 
                        String[] args) 

Do the test over all the args. In this test, the args represent a series of command+parameters groupings. As a result, we DO NOT want to iterate using AuthTest.testAuth(), hence this override.

The groupings contain both external commands, which must have absolute pathnames, and builtin commands, which are performed by methods of this class. All external commands are executed using Authorization.execPrivileged().

Overrides:

testAuth in class AuthTest

All Packages  This Package  Class Hierarchy  Class Search  Index