8.0 Using security features

You are not required to use any of Legion's security options. We realize that not all systems will benefit from our security and Legion can run with or without security. However, you must decide whether or not to enable Legion security before you use your new system: the command-line tool that starts the security mode (legion_init_security) will not run correctly if you have started to work in your system (i.e., if you have created new objects, changed context space, run classes, etc.).

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

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

If you choose to enable the security features (see Set security) you must run legion_init_security immediately after you have started a new system and you must log in as admin. If you do not enable security, Legion will run normally but none of your processes will be protected.

8.1 Authentication objects

When you create a user account in a running Legion net, Legion creates an AuthenticationObject, which holds the user's credentials and represents an individual user id in Legion. AuthenticationObjects are displayed in context space as /users/<user id>.

As of version 1.8, AuthenticationObjects also hold the user's home context (/home/<user id>) in the "home_dir" attribute.¹ They are also allowed to have any number of attributes with the name "legionrc_file." These attributes are assumed to point to LegionRC files in context space. LegionRC files are scripts that contain instructions for when the user logs in. The files are downloaded and executed on your local machine.

A default LegionRC file is created when you create a new user (page 37). Its context path is /home/<user id>/.legionrc and its contents are:

$ legion_cat /home/<user id>/.legionrc
legion_cd ${home_dir}
$

This means that when the user logs in, she will automatically be moved to her home context. Users can edit their own AuthenticationObject and LegionRC files at any time, however, so they can easily remove or change this behavior.²

A LegionRC file MUST use the following syntax:

• Anything following a # on a line is a comment
• Any value included in $() is assumed to be a local environment variable. For example, $(LEGION) refers to $LEGION in the current shell.
• Any value included in ${} is assumed to be a remote environment variable. For example, ${home_dir} refers to the "home-dir" attribute in the user's AuthenticationObject.
• All remote variables come from your Authentication object's attributes
• All variables are replaced with their values BEFORE the script is run

Aside from the semantic elements described, the file MUST contain nothing else except programs to execute on the command line, one per line in the script.

8.2 Security and context space

While all users can "read" (i.e., look at and move to) all of the new context space, non-admin users can "write" (i.e., create new context objects) only in the /home, /etc, /tmp, /mpi, and /pvm contexts. Only admin can "write" in the all parts of context space (Figure 6). Log out is achieved by exiting the shell.

Figure 6: Context space access in a secure Legion system

The legion_change_permissions command can be used to alter "read," "write," and "execute" object permissions so that other users can use those objects (see page 11 in the Basic User Manual).

8.3 Creating new users

You add users to your system by creating new user ids. A user id is an entry in context space that represents an AuthenticationObject (see section 8.1). The user id signifies ownership of all objects that a logged in user creates.

If you have enabled security you must be logged in as admin in order to create new users.

The legion_create_user command creates new user ids. This command is actually a simple wrapper around the legion_create_user_object command (see page 66 in the Reference Manual). The latter command gives more control in creating AuthenticationObjects, so that you can choose a particular host or vault, or (if you have another class that can create AuthenticationObjects) specify the new object's class. We strongly suggest that you put all new users in the /users context.

You will be asked to assign a password. The user can change it later on with the legion_passwd command (page 38).

New users are assigned a "home" context in /home/<user id>. They are also given a LegionRC file (page 35).

$ legion_create_user /users/jill
New Legion password: xxxxx
Retype password: xxxxx
1.3a8ba36a.6b000000.02000000.0000...
Creating a Home context:  /home/jill
Changing ACLs on /home/jill
Setting up initial LegionRC file
legion_update_attributes: Added 1 attributes(s) to object
legion_update_attributes: Added 1 attributes(s) to object
$

8.4 Logging in users

Please allow about five minutes for a new user id to propagate in your system after creating it. If a new user tries to log in too early, he or she will get security errors when trying to create objects.

The new user can then log in with legion_login, using the new user id's context path (note that you need to include /users):

$ legion_login /users/jill
Password:xxxxx
$

On a successful login, a credentials file (a user read-only file) is created in the local /tmp directory (see page 68 in the Reference manual). The user will automatically be moved to his or her home context (unless the default LegionRC file has been edited).

8.5 Changing user passwords

Use legion_passwd to change passwords. You must be logged in as either admin or the user to change a user password. Note that you need to use /users/<user id> as the argument.

$ legion_passwd /users/jill
New Legion password: xxxx
Retype new password: xxxx
Password changed.
$

If you are logged in as admin you can change all passwords. Otherwise, you can only change your own password.

8.6 Changing implicit parameters and ACL information

There is a suite of four commands for manipulating implicit parameters and access control information:

legion_set_implicit_params
legion_get_implicit_params
legion_set_acl
legion_get_acl

To set the implicit parameters for a user id, run legion_set_implicit_params and specify the user and the file containing the parameters.

$ legion_set_implicit_params /home/<user_name> <file_name>

Below 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:

• An object instance gets both the access control lists for its specific class and the default lists (if defined). The specific class lists override the default ones on a per-method basis. For example, if the method read() is in each, only the access control information in the specific class definition for read() will be kept and used.
• Every object instance and its class are automatically allowed to call all of the object's methods and to grant certificates for them. That is not affected by the access control set in the implicit parameters. These permissions can be modified by using the explicit SetACL method for the object.
• On log in, an authentication object returns the implicit parameters. It adds on to the access control set in those parameters the following right: for all methods in all classes, the authentication object is a valid granter of certificates. Subsequent objects are created with this right, so a user holding a certificate from the authentication object (after legion_login) can manipulate all objects that he creates.
• The access control for the default method is only applied if there is no control information for the specific method being called.
• Access is denied by default. So deny unknown (though valid) is unnecessary. The main purpose of deny is to deny access to specific individuals or subgroups who would otherwise have access because of their membership in a larger group.
• Names that only include letters and digits, plus underscore, dot, slash, and comma, do not need to be in quotes. Others must be in quotation marks. The reserved name unknown can be made unreserved by surrounding it in double quotation marks.
• The default cases can be in any order with the others. Anything between braces can be empty.

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
		}
		## The function identifier for this method 
		## includes the spaces within the quotation marks

		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 not specify a file name the command sets the implicit parameters of the current environment). If you do this, make sure that the implicit parameters contains a certificate definition for your AuthenticationObject, or you will have to 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. Use legion_set_acl to change the access policy of an existing object: this is not the same as changing implicit parameters, which (in the case of access control) will only affect the creation of new objects. The legion_set_acl tool can have the same input file as legion_set_implicit_params but it only uses the access control information.

The legion_change_permissions command manipulates an object's ACL so that other users can call methods on that object.

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.

Run legion_get_interface to get the names of methods available on an object. 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 quotation marks 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, since some method names have leading or trailing tabs and spaces. Directing the output of legion_get_interface into a file then editing the file may be helpful.

If a user's AuthenticationObject is deleted 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.

1. Use legion_list_attributes to view an object's attributes and legion_update_attributes to change them (see pages 10 and 12 in the Reference Manual).

2. In this case, she could use legion_update_attributes to change /users/jill's "home_dir" attribute to a different context path. For example:

$ legion_update_attributes -c /users/jill -r "home_dir('/home/spw4s')" \
   "home_dir('/home')"
legion_update_attributes: Replaced 1 attributes(s) in object
$ 

The next time Jill logs in, she will automatically be moved to the /home context. She can edit her /home/jill/.legionrc file to remove to legion_cd command altogether, if she prefers, in which case she will start at /.

Table of Contents 1.0 Introduction    1.1 About this manual    1.2 Style conventions    1.3 About Legion 2.0 Installing and running Legion    2.1 Legion structure    2.2 Space requirements    2.3 Software requirements    2.4 RSA and OpenSSL    2.5 Downloading binary files 3.0 Starting a new system    3.1 Before you start    3.2 Set up the environment    3.3 Starting a single host system       3.3.1 Choose a bootstrap host       3.3.2 Set up and configure the system       3.3.3 Start up       3.3.4 Initialize       3.3.5 Set security       3.3.6 Starting up other packages    3.4 Starting a multihost system       3.4.1 Set up       3.4.2 Create a new vault       3.4.3 Create a new host       3.4.4 Adding new users to a secure net       3.4.5 Working in the new net    3.5 Making a set-up script for users 4.0 System shutdown    4.1 Shutting down an insecure system    4.2 Shutting down a secure system 5.0 System restart 6.0 Summary of commands    6.1 Starting a new system    6.2 Start working in a running system    6.3 Shutdown    6.4 Restart 7.0 About Legion security    7.1 Message layer    7.2 MayI layer    7.3 Special implications of security    7.4 Legion and Kerberos    7.5 Session file 8.0 Using security features    8.1 Authentication objects    8.2 Security and context space    8.3 Creating new users    8.4 Logging in users    8.5 Changing user passwords    8.6 Changing implicit parameters and ACL information 9.0 Legion core objects    9.1 Core class objects 10.0 Implementation model    10.1 Implementation caches    10.2 Implementation tools 11.0 Host and vault objects    11.1 About host-vault pairs    11.2 Manipulating host-vault pairing    11.3 Adding a new host       11.3.1 legion_starthost flags       11.3.2 The host object's log    11.4 Adding a new vault       11.4.1 legion_startvault flags    11.5 Backup vaults 12.0 Process control daemon host objects    12.1 Adding a PCD host object       12.1.1 Configure the daemon       12.1.2 Start the daemon and the host object    12.2 PCD host commands       12.2.1 Adding a new account       12.2.2 Removing an account       12.2.3 Viewing available accounts    12.3 How the PCD host object works    12.4 Using a PCD host as your bootstrap host 13.0 Batch queue host objects    13.1 Starting a batch queue host object    13.2 Setting the local queue    13.3 Before running objects on the new host    13.4 Troubleshooting 14.0 Virtual hosts

15.0 Setting up a native MPI host

16.0 Legion domains    16.1 Naming Legion domains    16.2 Domains and binding services    16.3 Joining domains    16.4 Related commands       16.4.1 Listing currently connected domains       16.4.2 Generating cookies       16.4.3 Displaying cookies       16.4.4 Connecting domains 17.0 Resource management    17.1 Scheduling-related commands       17.1.1 Configuring the scheduler       17.1.2 Setting a class's default scheduler       17.1.3 Setting scheduler policy       17.1.4 Adding resources to a collection       17.1.5 Subcollections Getting help Index

Directory of Legion 1.8 Manuals [Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search] Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/