= ABAC access control for Fedd =

The [http://www.isso.sparta.com/research_projects/security_infrastructure/abac_overview.html ABAC] access control system, developed at Stanford and realized by a group in Trusted Information Systems that later moved to SPARTA, is a formal, flexible, scalable access control system based on formal derivation of user attributes, attested by other trusted users.  We have been [http://groups.geni.net/geni/wiki/TIEDABACModel planning] to integrate it into fedd for some time.  We have recently implemented ABAC in a [http://abac.deterlab.net portable library] and this implementation has been integrated into fedd.  Under our associated TIED project, we have completed a similar [http://groups.geni.net/geni/attachment/wiki/TIED/ABAC_GENIAPIv1.2.pdf integration] with GENI's [http://trac.gpolab.bbn.com/gcf reference aggregate manager], part of their developing [http://groups.geni.net/geni/wiki/GeniApi GENI API].

This page describes the use of ABAC with fedd, concentrating on using the transition tools to create initial ABAC credential stores from which to run fedd.  In order to get the most from this page, you should be familiar with

 * [FeddAbout#GlobalIdentifiers:Three-levelNames three-names] and [FeddAbout#GlobalIdentifiers:Fedids fedids]
 * [http://groups.geni.net/geni/wiki/TIEDABACModel The ABAC model] as it is used by DETER.
  * There is a [http://groups.geni.net/geni/wiki/TIEDABACDemo worked example] that can be helpful here
 * The existing [FeddDatabases fedd access databases]
 * [wiki:FeddABAC#UserCredentials User credentials]

This page discusses how and where credentials are stored, details of the experiment controller operation relevant to ABAC operation, how three-name authorization is mapped into ABAC, and the specific tools used to make that conversion.

'''Fedd users will need to run a command to [wiki:FeddABAC#UserCredentials convert their default credentials].'''

== Storing Credentials ==

Users and servers (fedd instances) now both have credential stores to maintain.  When using ABAC credentials to enforce the same kinds of access control as [FeddAbout#GlobalIdentifiers:Three-levelNames three-names] neither users nor servers will see much change.  Credentials will be managed transparently.

By default a user will maintain a credential store in a directory named {{{.abac}}}. Any credentials in the users abac directory will be passed as parameters when requests are made to fedd.  The user can limit the credentials passed by specifying a directory with only a subset of the credentials.

Similarly, a running fedd instantiation will be configured to use a specific abac directory in which its credentials are kept.  As the instance learns more credentials they are aslo stored in this directory.

Unlike a user, the fedd directory contains metadata beyond the credential lists.  This directory is populated using the {{{access_to_abac.py}}} command for access controllers and the {{{fedd_to_abac.py}}} command for experiment controllers.

== Operation of Experiment Controller ==

The experiment controller can operate in two modes, as an experiment controller dedicated to use by a single user, or as a service on behalf of multiple users.  In the first case the controller acts as the same principal as the user commands.  Essentially the experiment controller is a command run by the single user.  In the second case a common piece of infrastructure acts as an experiment controller for many users.  Because this fedd acts as a distinct principal, some additional delegation is required to make the access control reasonable.

When the experiment controller is run as a service, it acts as a separate principal for the purposes of experiment creation, and the user and the controller negotiate what principal the controller will act as when making resource allocations from access controllers.  This allows a user to delegate a subset of attributes to the experiment principal and then allow the experiment controller to act as that principal.  (The experiment principal may have attributes delegated by multiple principals, if needed).  This extra principal is required to prevent the experiment controller from combining rights from multiple principals that did not intend it.  The figure below shows this:

[[Image(complex.png)]]

When a user is running an experiment controller on their own behalf, like a utility program, the situation is much simpler.  Both experiment controller operations and experiment allocations are simply carried out as the user.  The user's fedid is specified for both the experiment controller's ID and the experiment ID, leading to the simpler situation below:

[[Image(simple.png)]]


== Expressing Three-names as ABAC credentials ==

[FeddAbout#GlobalIdentifiers:Three-levelNames Three-names] are really an encoding of a fairly small attribute space used by access controllers to control which fedids can perform operations and how to map authorized fedids into the local identifier space.  Experiment controllers assert the attributes.

The attributes an experiment controller asserts are given in its [FeddDatabases#ExperimentControlComponentAccessDB access database] in lines of the form:

{{{
fedid:xxx -> (proj1, user1)
}}}

That line asserts that this controller will assert that a user with fedid of xxx is in project {{{proj1}}} and is user {{{user1}}}.  This encodes in ABAC (using the RT0 syntax supported by [http://abac.deterlab.net libabac] as:

{{{
ec_fedid.user_user1 <- fedid:xxx
ec_fedid.project_proj1 <- fedid:xxx
}}}

{{{ec_fedid}}} is the fedid of the experiment controller.  The {{{fedd_to_abac.py}}} script converts an experiment controller's access DB to an ABAC credential store with those credentials, encoded as X.509 attribute certificates.

The access controller uses three-names to both make the access control decision (does a requester have the right to make this call) and a mapping of the fedid into the user access space.  For example a line like:

{{{
(ec_fedid, proj1, user1) -> create, (DETER, faber, faber)
}}}

says that a user with a project of {{{proj1}}} and a user of {{{user1}}} attested by the controller with fedid {{{ec_fedid}}} can create experiments as local user {{{faber}}} on the local {{{DETER}}} project.  The ABAC credentials for the access control decision look like:

{{{
ac_fedid.project_proj1_user_user1 <- ec_fedid.project_proj1 & ec_fedid.user_user1
ac_fedid.create <- ac_fedid.project_proj1_user_user1
}}}

The first rule names the conjunction of two experiment controller attributes and the second line maps that to a local create attribute.  The first attibute is used to map to local credentials.

The mapping to local credentials is accomplished by a map file that maps an ABAC credential to a local data tuple.  The encoding above would be:

{{{
ac_fedid.project_proj1_user_user1 -> (DETER, faber, faber)
}}}

The tuple has the same format as the non-ABAC [FeddDatabases#AccessComponentAccessDB access control database] for that kind of controller.

== ABAC Logic: RT0 vs. RT1 ==

ABAC can support several underlying logics.  The current logic, RT0, implemented by [http://abac.deterlab.net libabac] represents attributes as simple strings.  This is why encoding a project takes the form {{{project_}}}''name''.

RT1 allows for parameterized attributes, that is an attribute is a string and 0 or more typed parameters.  Those attributes would take the form of {{{project(}}}''name''{{{)}}}, and would allow some more sophisticated deduction rules.  While the RT0 vs. RT1 distinction is only a convenience for the encoding of three-names, we intend to pursue implementing the more powerful logic.

== Conversion Utilities ==

This section describes the utilities for converting existing [FeddAbout#GlobalIdentifiers:Three-levelNames three-name-based]configurations into ABAC.  Users do not need to do anything, but there is a utility for converting experiment controllers and access controllers.

In addition to running the utilties, add set '''auth_type''' to '''abac''' and '''auth_dir''' to the ABAC directory created by the utilities below. For access controllers, the '''accessdb''' variable should point to the generated map file.

=== fedd_to_abac.py ===

{{{fedd_to_abac.py}}} converts an existing fedd experiment controller configuration into an ABAC configuration.  A certificate and key are required as well as an output directory for the ABAC authorizer (target of the '''auth_dir''' parameter in the configuration file.

It takes the following arguments:
  {{{--cert=}}}''file''::
    A file containing an X.509 certificate in pem format.  This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity.  It may be a combination certificate and key file.
  {{{--key=}}}''file''::
    The key for signing attributes.  It should be a pem file with an RSA key in it.  This can be omitted if {{{--cert}}} specifies a combination file.
  {{{--dir=}}}''dir''::
    The output directory for the authorizer.
  {{{--make_dir}}}::
    If given, make the output directory.
  {{{--debug}}}::
    Just output the creddy commands that would be issued to create the certificates.
  {{{--policy_only}}}::
    Only output the ABAC certificates, not the full ABAC authorizer.  This is primarily for debugging.
  {{{--update}}}::
    Update the output directory rather than creating it.  This allows the authorizer to remember credentials it has learned or issued while updating the policy.

After the named arguments are given, the [FeddDatabases#ExperimentControlComponentAccessDB aceess DB file] is a required argument.

=== access_to_abac.py ===

{{{access_to_abac.py}}} converts access controller policies into ABAC and generates a DB for mapping the derived attributes into an appropriate credential mapping database, the target of the '''accessdb''' configuration directive.  Keys and certificates are required parameters as well as a directory for the ABAC authorizer and a file for the access DB.

It takes the following arguments:

  {{{--cert=}}}''file''::
    A file containing an X.509 certificate in pem format.  This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity.  It may be a combination certificate and key file.
  {{{--key=}}}''file''::
    The key for signing attributes.  It should be a pem file with an RSA key in it.  This can be omitted if {{{--cert}}} specifies a combination file.
  {{{--dir=}}}''dir''::
    The output directory for the authorizer.
  {{{--type=}}}''type''::
    The type of access controller used by the [FeddConfig#AccessOptions access_type] configuration directive.  Used to parse the various formats of the old accessDB.
  {{{--quiet}}}::
    Do not produce extra output
  {{{--no_create_creds}}}::
    Do not create the authorizer (debugging only)
  {{{--file=}}}''old_accessdb''::
    The accessDB to convert.  May also be specified as a bare parameter after the named parameters have been given.
  {{{--mapfile=}}}''new_accessdb''::
    The new accessDB to create.  It must be a different file name than the file being converted.
  {{{--no_delegate}}}::
    By default the ABAC created attributes include a layer of delegation for a standalone fedd running with a different principal.  Specifying this parameter eliminates a layer of delegation.  Even for single-user experiment controllers, this option is rarely necessary.
  {{{--no_auth}}}::
    Do not create an authorizer.  For debugging only.
  {{{--debug}}}::
    Just produce debugging output.

If {{{--file}}} is not given, the [FeddDatabases#AccessComponentAccessDB accessDB] to convert must follow.

== User Credentials ==

The fedd tools expect the identity of the user to be a self-signed certificate.  This is accomplished using the command:

{{{
$ cert_to_fedid.py --cn $USER --out $HOME/.ssl/fedid.pem $HOME/.ssl/emulab.pem
}}}

The '''cert_to_fedid.py''' utility will list other parameters, but most are not needed for users.  The fedid_tools search for {{{.ssl/fedid.pem}}} as a default identity, so putting the output there will make things simple.