Description of Resattributes File

Purpose and contents of the .resattributes file

The .resattributes file provides hints (pretty strong ones) to the use-condition and attribute certificate generators as to attribute names, and associated values, recognized by a particular resource. The generators, in turn, use those names and values to generate valid certificates.

This file also lists the CAs trusted to issue attribute certificates attesting to a given attribute-name/attribute-value/distinguished-name triple. Each CA is associated with a directory server (usually an LDAP server) where it publishes the certificates that it issues.

Finally, the file also includes the actions allowed on a possible resource. The actions should be defined as low in in the policy hierarchy (i.e., as close to the resource) as possible, since the policy engine and cert generators will use the first actions found in a search up from the bottom of the resource's directory.

Format of the .resattributes file

The .resattributes file is an XML document. All information is encoded either as an attribute of an XML element, or is sandwiched between an element's opening and closing tags. As in HTML, <!-- opens a comment and --> closes it.

Here is a sample .resattributes file.

The "formal" XML DTD can be found here.

Note that "attribute" means something different in the context of the .resattributes file versus XML. In the following discussion, we've tried to use the term "resource attribute" whenever we mean the Akenti definition and "XML attribute" whenever we mean the XML definition.

There are four top-level elements in the .resattributes file: AKENTI_ATTRSPEC, CA, ATTR, and ACTIONS. Broadly speaking, here are their purposes:

The top-level elements and their subelements, if any, are described in greater detail below.
<AKENTI_ATTRSPEC>

To allow compatibility between different versions of this spec, we require a version ID of some kind, denoted by the AKENTI_ATTRSPEC element.

The ID itself is just a string specified as part of the VERSION XML attribute. The string should be of the form <version_number>.<revision_number>, e.g., "1.0". The current AKENTI_ATTRSPEC version number is 1.0.

There are no subelements defined for AKENTI_ATTRSPEC.

There should be only one AKENTI_ATTRSPEC element defined in the .resattributes file.

Example:

    <AKENTI_ATTRSPEC VERSION="1.0" />

<CA>

This describes a certificate authority (CA), which is where the certificate generators will look for identity-based resource attributes.

A CA element has one XML attribute, NAME, which is the CA's DN.

CA elements contain two types of subelements, CAATTR and DS:

<CAATTR>

Each CA has a set of X.509-based fields it recognizes. These should each be encoded in a CAATTR element.

There should be at least one CAATTR element defined for each CA element.

There are no XML attributes or subelements defined for CAATTR.

Example:

	<CAATTR>o</CAATTR>
    

<DS>

A CA has at least one associated "directory service," usually an LDAP server but possibly something else, e.g., a flat file or an SQL database. Each directory service must be described in the DS element.

The DS element has two XML attributes, its TYPE and a SEARCHBASE. At present, two TYPEs are recognized ("ldap" and "file"). The SEARCHBASE for an ldap server, is the location in the tree to start searching. For a file system, it is absolute pathname of the directory in which the certificates are stored. The DS element's contents should be the service's identifier: for an LDAP server, this would be its fully-qualified hostname or IP address with an optional port if the default port of 389 is not used. For a file system it can just be the hostname..

There are no subelements defined for DS.

There should be at least one DS element defined for each CA element.

Example:

	<DS TYPE="ldap" SEARCHBASE="O=LBNL,C=US">ldap.domain.TLD</DS>
	<DS TYPE="file" SEARCHBASE="/usr/CA/certs">fs.domain.TLD</ds>
    

There should be at least one CA element in the .resattributes file.

<CA> example:

    <CA NAME=ca.domain.TLD>
	<CAATTR>o</CAATTR>
	<CAATTR>ou</CAATTR>
	[etc. if necessary]
	<DS TYPE="ldap" SEARCHBASE="O=LBNL,C=US">ldap.domain.TLD</ds>
	[etc. if necessary]
    </CA>

<ATTR>

This describes an AKENTI resource attribute.

An ATTR element has two XML attributes, NAME and VALUE. These are, respectively, the resource attribute's name, e.g., "group," and the value of that resource attribute, e.g., "my_group." The current assumption is that a resource attribute must always have a name and value.

It might be nice to eliminate the requirement that a resource attribute have a value. For example, for a resource attribute like "x-ray trained," merely holding a certificate for this resource attribute is sufficient to indicate that you satisfy the use-condition; you don't need to have a "value" that says, "Yes," or "Yes, holder is x-ray trained." Because of this possibility, VALUE is not currently required under the syntax shown below, but it is accepted if present.

Both NAME and VALUE are declared as character data rather than as enumerations because resource managers have to be able to declare their own resource attribute names and values as needed.

There are two subelements, SIGNER and DS defined for ATTR.

<SIGNER>

The SIGNER element identifies who is authorized to issue an attribute certificate for the ATTR NAME/VALUE association.

There must be at least one SIGNER for each ATTR.

The SIGNER element has two XML attributes, NAME and CA. NAME is the DN of someone authorized to issue a certificate for this attribute. CA is the DN of the certificate authority that identifies the issuer.

Example:

	<SIGNER 
	    NAME="/C=MyCountry/O=MyOrg/OU=MyOrgUnit/CN=MyOrgUnit'sSigner"
	    CA="/C=MyCountry/O=MyOrg/OU=MyOrgUnit/CN=MyOrgUnit'sCA"
	/>
    
<DS>

DS is an optional list of directory services e.g. URLs, that may hold the attribute certificates that this signer issues. See the example above.

We wish to allow users to define their own XML attributes and their own subelements (in addition to SIGNER). This may require that the users modify the policy engine, e.g., if the new element requires the policy engine to do something besides matching strings, like getting the time of day or some other currently unsupported behavior.

<ATTR> example:

    <ATTR NAME="group" VALUE="myGroup">
	<SIGNER 
	    NAME="/C=MyCountry/O=MyOrg/OU=MyOrgUnit/CN=MyOrgUnit'sSigner"
	    CA="/C=MyCountry/O=MyOrg/OU=MyOrgUnit/CN=MyOrgUnit'sCA"
	/>
	<DS TYPE="ldap">ldap.domain.TLD</DS>
	[etc. if necessary]
    </ATTR>

<ACTION>

This describes all the operations the resource supports.

There are no XML attributes, but there is one subelement, ACT, defined for ACTION.

<ACT>

This describes one operation the resource supports. The description should be a string recognized by the application that will interpret Akenti's decision. Neither Akenti nor the certificate generators will attempt to assign any meaning to the contents of ACT elements.

There are no XML attributes or subelements defined for ACT.

There must be at least one ACT element defined for the ACTIONS element.

Example:

	<ACT>read</ACT>
	<ACT>write</ACT>
	[etc. if necessary]
    

There should be only one ACTIONS element defined in the .resattributes file.

ACTIONS example:

    <ACTIONS>
	<ACT>read</ACT>
	<ACT>write</ACT>
    </ACTIONS>

Implementation notes