Legion 1.2
System Administrator Manual

6.0 Using security features

Here is brief overview of how to use security in the current system:

If you want secure file objects, go to the source directory Legion/src/UserObjects/Security and execute "make secure" before bringing up the system.

If you are running a multi-architecture system, you will need to register other implementations for the AuthenticationObject (an implementation for your current architecture is automatically created when the system is first initialized). Use the following command on each different architecture:

$ legion_create_implementation \ 
 $LEGION/bin/$LEGION_ARCH/AuthenticationObject \
 $LEGION_ARCH -c /class/AuthenticationObjectClass

You can now create users. A user name is simply an entry in context space for an AuthenticationObject. You can create users with the legion_create_user command. To create a user "bob" in the current context, enter:

$ legion_create_user bob

To create the bob entry elsewhere, enter:

$ legion_create_user /my/path/bob

The command will prompt for a password for the new user. Note that the context where the user name is placed has nothing to do with whether that user can access anything in that context space.

The legion_create_user command is actually a simple wrapper around legion_create_user_object. The full command can give more control to the creation of AuthenticationObjects; execute it without arguments for a summary of its options.

Once a user is created, log in is achieved by giving the context path of the user object and a password to legion_login.

$ legion_login bob
Password:xxxx
$

On a successful log in, a new shell is created. Log out is achieved by exiting the shell.

Like Unix rsh, legion_login can also execute a specific command rather than create a new interactive shell. For example, to use legion_login to execute legion_ping on object bob, enter:

$ legion_login bob -e legion_ping -c bob
Password:
Pinging:  1.01.69000000.01000000.000001fc0bbd003e30xxx
Returned: 1.01.69000000.01000000.000001fc0bbd003e30xxx
$

With the default security policies, nobody else can ping bob except bob himself. If you try to ping bob while not logged in, you'll get something like this:

$ legion_ping -c bob
Pinging:  1.01.69000000.01000000.000001fc0bbd003e30xxx
LegionException (2:1)
LEGION_EXCEPTION_TYPE_SECURITY, LEGION_EXCEPTION_SECURITY_MAYI
Security fault, MayI failed
$

Once logged in, the user's password can be changed by calling legion_passwd. Note that the name or LOID of the user must be supplied as an argument to legion_passwd (this will likely change in the future):

$ legion_passwd bob
New Legion password: yyyy
Retype new password: yyyy
Password changed.
$

Running while logged in has a benefit even if you do not plan to use security features. Normally every command-line tool needs to create a public key pair for its self-generated LOID before it can do its work. When logged in, the tool gets the LOID from the legion_login process instead, which maintains several pre-generated LOIDs. On slow machines the time to generate a fresh LOID can be quite noticeable, and using legion_login can eliminate some of the delay.

There is a suite of four commands for manipulating implicit parameters and access control information. Running legion_set_acl with no arguments will provide a summary of all of them, or you can see the Reference Manual.

To set the implicit parameters of a user while logged into that user, run legion_set_implicit_params and specify the user and the file containing the parameters (see the command summary for the full options). Here is an example implicit parameters file that sets message security and an access control policy.

 
## Set up message level protection. Legal values are 
## "Protected", "Private", and "Off".

String MessageSecurity = "Protected"

## Set up an access control set and store it in the 
## specified implicit parameter.

Notes:

AccessControlSet {
   instanceOf /class/BasicFileClass {

      Method "read()" {
         allow bob fred
         ## Only bob and fred can call this method 
         ## (the class and instance can call it and 
         ## grant certificates for it, too, of 
         ## course--see note above).
      }

      Method "        LegionLOID ping();" {
         allow group
         deny fred
      }

      Default {
         allow bob unknown
         ## All other methods are covered by this 
         ## case. Suppose that bob is the one setting 
         ## up this file. He probably wants to put 
         ## himself in the allow list for every method 
         ## he lists, as well as for the default. 
         ## Of course, if he doesn't want access of 
         ## a particular type (e.g., write access), he 
         ## can leave himself off. For any method 
         ## where he grants access to unknown, he 
         ## doesn't have to list himself. However, it 
         ## doesn't hurt.
      }
   }

   Default {

      Method "        LegionLOID ping();" {
         allow bob

         ## Nobody can ping objects except bob
      }

      Default {
         allow unknown
      }
   }
}

Once the implicit parameters for a user have been set, you must log out and log in again for them to take affect. Alternatively, legion_set_implicit_params can be used to change the implicit parameters of the current session. If you do this, make sure that the implicit parameters contains a certificate definition for your AuthenticationObject, or you will have to you log out and log in again in order to execute any further commands as an authenticated user. This documentation does not yet include an example of defining a certificate.

To show the current implicit parameters or the parameters for a particular user, use legion_get_implicit_params. You may use legion_ set_acl (and the corresponding legion_get_acl) to change the access policy of an existing object. This differs from changing the implicit parameters, which (in the case of access control) will only affect the creation of new objects. The legion_set_acl tool uses the same input file as legion_set_implicit_params, but it only uses the access control information.

If you have created a system with secure files, try creating a file as a logged-in user (the executable "testBasicFiles" will create a sample one for you). You can experiment with permissions and access control. To get the names of the methods available on an object, run legion_get_interface. The method names follow the output line titled "Object Interface." Some of the methods are Legion object-mandatory functions, while others (usually listed at the end) are particular to objects of that class. You can cut and paste lines from the output into an implicit parameters file: Put the names in double quotes in the "Method" definitions. Be sure to make your cut be from the real start and end of the line output by legion_get_interface; some method names have leading or trailing tabs and spaces. Directing the output of legion_get_interface into a file and editing that may be helpful.

If a user's AuthenticationObject is deleted from the system, there is no way to regenerate an equivalent AuthenticationObject; the user must be re-created from scratch. The reason is that the private key of the original AuthenticationObject cannot be recovered, so the same LOID cannot be used for the object.

When shutting down a Legion system, the shutdown procedure will be unable to delete objects that it does not have permission for. If you have only created one user, run shutdown while logged in. Otherwise you will need to clean up after the system by hand.


Back to Legion Security sectional index

Back to System Administrator Manual Table of Contents