This document presents an overview of the Akenti policy language in order to provide guidance to a stakeholder in designing the Policy and Use Condition Certificates for a resource or set of resources. Details on the exact format of the certificates are available from http://www-itg.lbl.gov/Akenti/docs/AkentiCertificates1.1.html, but should not be needed by stakeholder, since the actual certificates should be written by one of the certificate generator programs that are part of the Akenti distribution. Details on how to use these certificate generator programs to create a certificate is available in http://www-itg.lbl.gov/Akenti/docs/stakeholder.html.
The Akenti Authorization system expresses authorization policy in a collection of digitally signed certificates. This implementation was motivated by the emergence of distributed computing environments such as collaboratories or grids, where the resources, user and stakeholders may be distributed across geographically and administratively diverse domains. We wanted the people, i.e. users and stakeholders, to have domain neutral identities and we wanted to facilitate non-centralized control of the authorization policies. Since the policy depends on signed certificates, it must not only express allowed access to resources, but must also make explicit the trust relationships of who may sign, and therefore define, the policy.
Three types of certificates are used to express policy: Policy certificates, Use Condition certificates and Attribute certificates. The Policy certificates may be hierarchical, if the resources are hierarchical, e.g a set of directories and files, or a set of web documents. However, each level of a hierarchy has only one Policy certificate and the certificate at the root of the hierarchy, called the Root Policy certificate has some unique entries. The certificates may be located on machines other than the machine that controls access to the resources and may be signed by a variety stakeholders.
a server that mediates requests for access to resources. Normally it runs on the machine on which the resources reside (e.g. files, or compute cycles). But it may have unrestricted access to a machine that controls the resource (e.g, the router for controlling premium bandwidth or a dedicated PC for instrument control)
The Root Policy certificate is the starting point for determining the authorization policy for a resource tree. It defines which CA's are trusted to sign identity certificates used by this resource tree. For each trusted CA the Root Policy contains the Distinguished Name (DN), the X.509 certificate which includes its public key and pointers to where the CA puts its Certificate Revocation Lists (CRL). These certificates are fetched over a secure channel from a trusted location by the administrator of the resource tree and put in the Root Policy certificate by one of the stakeholders. Each Policy certificate also includes a list of the directories in which to look for identity certificates, attribute certificates and a list of all the stakeholders and where they store Use Condition certificates. This certificate is signed by one of the stakeholders mentioned in it and is stored in a location which is defined in the Akenti configuration file. Policy certificates are effectively self-signed certificates, as the certificate itself says who is allowed to sign it. Thus they must either be stored on the resource gateway machine or a trusted machine to which the resource gateway has a secure connection. The main advantage of signing Policy certificates is that they can be updated remotely by an already established stakeholder. It is also a bit harder for someone with access to the machine on which they are stored to make unauthorized modifications to them. For a set resources that all have the same authorization policy, this is the only Policy certificate that is required.
For a hierarchical set of resources with different policies, the stakeholder would create directories below the one in which the Root Policy certificate is stored and place Policy certificates in each one for which there is a distinct policy. These resources would inherit the trusted CA's from the Root Policy, but would have their own stakeholders and search locations.
Use Condition certificates express what actions are allowed to what users for a resource. Akenti must be able to find a least one Use Condition certificate signed by each member of a stakeholder group, or it will assume that a critical network connection is broken and deny all access to the resource. The Use Condition contains a boolean expression that specifies what attributes a user must have to get a certain set of rights. It can also include run-time or resource dependent constraints of these actions. (Run-time constraints are not implemented yet, but will be soon.) The names of the attributes, values and actions comprise a policy vocabulary for a resource. This vocabulary is defined in a Resource Attributes file associated with a resource domain or subdomain. Some user attributes derive from the Distinguished Name components in X.509 certificates such as O, OU or CN. Other attributes such as group or role, are simply defined by the stakeholders to serve as a conditions for granting access and merely need to be consistent between the Use Condition certificates and the Attribute certificates. Runtime attribute names and values may also need to be understood by the resource gateway or whatever authority is called on to verify them. Use Condition certificates also specify the stakeholders who are trusted to issue Attribute certificates to satisfy the Use Condition, and what CAs are trusted to issue X.509 certificates for users. The CA's in the Use Condition certificate must be a subset of the CA's in the Root Policy certificate.
Attribute certificates attest to the fact that a certain user has a given attribute. They are issued by Attribute Authorities who are authorized by the stakeholder in the Use Condition certificate to be trusted to issue such certificates. In turn the Attribute Authorities must have X.509 id certificates that chain back to one of the globally trusted CA's. An Attribute certificate may optionally contain runtime or resource specific constraints that can limit the use of the attribute. Note: the constraints have not yet been implemented.
Assume that you either have a resource gateway process that has linked with the Akenti authorization library or a process that is calling an Akenti server to make the authorization decisions. In either case the Akenti code is running on a machine which must have an Akenti configuration file and secure access to one or more resource directories containing Policy certificates for the resources. The Akenti configuration file defines the base name of the resource as seen by the users, gives the pathname to the base directory that contains the Policy certificates, defines the file name of the Policy certificates and the file name of the Resource Attributes files.
It also defines parameters defining various supporting servers. See http://www-itg.lbl.gov/Akenti/docs/AK1.1-akentiConf.html for complete details.
All Akenti Certificates have the following fields:
Certificate format version (currently V1)
Certificate issuer (DN, and DN of CA)
time that certificate is not valid before
time that certificate is not valid after
A certificate is stored in several formats in a single file. First there is an XML version for readability. Second there is a canonical ASCII string that represents what is going to be signed which is mostly for debugging and will eventually be removed, and finally there is a base 64-encoded version of the signed string and the signature, surrounded by PEM style tags. The Akenti Policy engine only uses the signed encoded version. The certificate generators use the XML part. One way to create a new certificate is to take an existing one, edit the XML and then hand it and the private key of the issuer to the CertGen program, which will parse the XML for correctness, create a new unique certificate id, update the time not valid before to the current time, create the canonical format, sign it and write it to new Certificate file.
The other way to create certificates, is to use one of the three GUI generator programs which step a user through a certificate creation process relying on a Resource Definition server to suggest acceptable values for the various fields.
In this example the file /home/akenti/testResourceTree/LBL/.htauthority contains the Root Policy Certificate.
The Root Policy certificate contains:
Resource Name (in this example LBL)
Maximum time in seconds to cache any certificates relevant to this resource
Vector of directories in which to search for Attribute certificates (specified by URLs).
Vector of directories in which to search for Identify certificates (specified by URLs).
Vector of Akenti Principal names
CA for Issuer's identity certificate
Vector of locations in which Use Condition certificates are stored (specified by URLs).
Vector of Certificate Authority Info
Base 64-encoded DER coded x.509 certificate
Vector of Certificate Revocation List locations (specified by URLs).
Members of the same stakeholder group share responsibility for issuing Use Condition certificates that represent their interests. Thus if the Akenti policy engine finds a least one Use Condition certificate issued by any member of the group, it assumes that interest is represented. The multiple locations in which to store the Use Conditions are only there for redundancy in case one of the locations is unreachable. All the Use Condition certifications issued by any member of the group must be stored in all of the locations. Different stakeholder groups are assumed to represent different interests. If the Akenti policy engine cannot find at least one verifiable certificate from each group, access will be denied on the basis that some stakeholder's interests are not represented, possibly because of a network partition or an attack on that stakeholder's certificate repository.
If there are additional resources with different policies they can be represented by Unix-style hierarchical file names, e.g., LBL/test1, LBL/test2. If there is no Policy certificate in the directory /home/akenti/testResourceTree/LBL/test1, the resource will inherit the same policy as LBL. If the policy it to be different, then the new parameters can be defined in /home/akenti/testResourceTree/LBL/test1/.htauthority and only the trusted CAs will be inherited from the Root Policy certificate.
Use Condition certificates contain the gist of the authorization policy. All the rights granted to a user from all the relevant Use Condition certificates are combined to determine his access. The heart of the Use Condition is a boolean expression that lists the constraints that a user must satisfy. The expression consists of a per-resource-tree vocabulary of attributes, values and actions, combined with the usual relational and logical operators. It also contains a list of the principals who are trusted to issue Attribute certificates for each attribute used by the expression.
The complete contents of a Use Condition certificate are:
Resource Name to which this Use Condition certificate applies
Scope - does it just apply to this resource or to all resources below it
Enable - must every user satisfy this certificate to get any access
Vector of Attribute Authorities
Attr type - x509, cert-based, runtime
Vector of Defining Authorities -
for cert-based attribute is an Attribute Authority which is an Akenti Principal
for runtime is other (e.g, time-server, system-clock, file-system, resource gateway)
Actions - a list of actions that are granted
Vector of CA's that are acceptable as issuers of user's id certificates.
The abbreviated grammar for the constraint expression is:
constraint_expr ::= and_expr { `||' and_expr }*
and_expr ::= prim_expr { `&&' prim_expr }*
prim_expr ::= av_expr | ( constraint_expr )
rel_op ::= `=' | ` !=' | `< ` | `<=' |' >' | `>='
char ::= digit | letter | _ | # | . | , | / | : | ;
White space is generally ignored except in the case of value where multiple white space between words is compressed to one space. digits are 0-9, letters are a-z,A-Z. Attr are not case-sensitive, but values are.
Attributes come in several flavors. X509 attributes are components of X.509 Distinguished Names such as C, O, OU, CN. A user's value for such an attribute is the value (or values) for that component of his Distinguished Name. Cert-based attributes are arbitrarily named attributes and value sets that the stakeholders for a resource have defined. A user has such an attribute, if the Akenti policy engine is able to find an Attribute Certificate granting the user such a value. Cert-based attributes are always used in an additive manner in order to avoid granting a user more access when an Attribute Certificate can not be found due to a network partition. Thus an expression of the form "group != DSD" is not allowed, since there is no way to be sure that a user is not a member of the group. On the other hand, "C != France" is acceptable, since the user must present a single valid X509 certificate to identify himself. He will pass the constraint either if there is no C component in his Distinguished Name or if it something other than "France". There are also runtime attributes whose current values are determined by conditions at the time the resource is accessed. Examples of these attributes are time-of-day, current disk quota and IP address access is coming from. The value of some of these attribute-value expressions can be determined by the Akenti Policy engine, for example "time-of-day > 5PM", but some must be passed to the resource gateway to evaluate, e.g. load on machine and disk quota used. (Currently runtime constraints are not implemented.)
Associated with the constraint expression is a list of trusted authorities for each attribute/value pair. In the case of x509 attributes one or more CAs are listed. For cert-based attributes, a list of issuers and CAs for each attribute/value pair is given. In the case of runtime constraints a server or arbitrary id is used. The Akenti policy evaluator will evaluate the runtime constraints that it recognizes. Otherwise the constraint will be returned to the resource gateway for evaluation.
There are two more items in a Use Condition certificate. One is the enable bit If this bit is set on for a Use Condition, then every user seeking access to the resources to which this Use Condition applies must satisfy the condition. Normally satisfying a Use Condition just grants the user the rights that the Use Condition controls. Since there can be many Use Conditions for a single resource, it may not be necessary to satisfy more than one of them to get access to the resource. The enable bit is to allow a stakeholder veto power over all the other certificates, by forcing all users to satisfy this Use Condition as well as any others.
The scope setting, is only applicable to hierarchical sets of resources, and specifies whether this Use Condition applies only to resources at its level in the hierarchy or to any resources in the tree below it as well.
Attribute certificates specify a single attribute-value pair for a single user. They are valid for a resource if they are issued by one of the principals listed in the Use Condition certificate that they are being used to satisfy. An Attribute certificate may optionally contain one or more constraints on when the Attribute is valid. Note: onstraints have not been implemented yet. This is similar to the constraint expression in a Use Condition, but in this case specifying an x509 attribute doesn't make sense, since the Attribute certificate already fully specifies the user's DN. Cert-based constraints could be used to make membership in one group contingent on membership in another, or one role depend on having another one. The runtime constraints make the most sense here, where one might want to restrict a role to a certain time of day, or to allow a privileged group membership only if the user is connecting from a recognized IP domain.
The contents of an Attribute certificate are:
Akenti Principal to whom this attribute applies
Vector of Attribute Authorities
Attr type - cert-based, runtime
Attr Value - one predefined value is "ANY"
Vector of Defining Authorities -
for cert-based attribute - Attribute Authority which is an Akenti Principal
for runtime - other (e.g, time-server, system-clock, file-system, resource gateway)
Appendix A - Certificate examples
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE AkentiCertificate SYSTEM "/home/g1/proj/akenti/release/common/AkentiCertificate.dtd">
<Header Type="RootPolicy" SignatureDigestAlg="RSA-MD5" CannonAlg="AkentiV1">
<ID id="rocky.lbl.gov#104b8965#Fri May 18 18:53:02 PDT 2001"/>
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing</UserDN>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<ValidityPeriod start="010519015301Z" end="020504001529Z"/>
<ResourceName>LBL</ResourceName>
<URL>ldap://idcg-ds.lbl.gov</URL>
<URL>file:/home/g1/proj/akenti/release/common/testResourceTree/idCerts</URL>
<URL>http://www-itg.lbl.gov/~mrt/NewCertificates/</URL>
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Mary R. Thompson
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing</UserDN>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<URL>http://www-itg.lbl.gov/~mrt/NewCertificates</URL>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<X509Certificate>-----BEGIN CERTIFICATE-----
MIICvzCCAiigAwIBAgIBETANBgkqhkiG9w0BAQUFADBbMRkwFwYDVQQKExBET0Ug
U2NpZW5jZSBHcmlkMSAwHgYDVQQLExdDZXJ0aWZpY2F0ZSBBdXRob3JpdGllczEc
MBoGA1UEAxMTQ2VydGlmaWNhdGUgTWFuYWdlcjAeFw0wMTAxMzAwMDM0MzlaFw0w
NjAxMjkwMDM0MzlaMHgxDTALBgNVBAoTBEdyaWQxLjAsBgNVBAoTJUxhd3JlbmNl
IEJlcmtlbGV5IE5hdGlvbmFsIExhYm9yYXRvcnkxIDAeBgNVBAsTF0NlcnRpZmlj
YXRlIEF1dGhvcml0aWVzMRUwEwYDVQQDEwxMQk5MLUdyaWQtQ0EwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAL2t4aX933WXYlofuY+L+16Tdl/KxpAammyfcW8u
kHHT6RYDjaQdfV1FpNEqfSrRjKNwGGGkrG4XHZWiUO0Di0AlBN04lsRY6jB68l6B
5byujfZv+8EeCI2c1ObBLYZYi4lToJf0sm0Hpn3GD7PZBv6BVHLOuwEFDl9z9Dnc
DFDdAgMBAAGjdjB0MBEGCWCGSAGG+EIBAQQEAwIAhzAOBgNVHQ8BAf8EBAMCAcYw
HQYDVR0OBBYEFIn+csPVyp+iprpYUIu1SziMQiDxMA8GA1UdEwEB/wQFMAMBAf8w
HwYDVR0jBBgwFoAUm85P8ry9WHAx1fIyDn6eveJRFOcwDQYJKoZIhvcNAQEFBQAD
gYEAehijYRFhkM1odxkZ0xUsoI1PjrPCHDRy54sp4oWHl53r5CJdYR+5b33ZDw32
RKBH9XAp8WJV5zppLtf9T9BAKddfCnmcREvaCOoFjBTWgEPVyVz64ax4TvaPXqRK
XtPCTyJt4zDYX68qlqmt3VLDnBSIGydTDFZ+QSwd0Tc02R8=
-----END CERTIFICATE-----</X509Certificate>
<URL>ldap://idcg-ds.lbl.gov</URL>
<CADN>/C=US/OU=LBL/CN=TEST CA I</CADN>
<X509Certificate>-----BEGIN CERTIFICATE-----
MIIBSjCB9aADAgEAAgEBMA0GCSqGSIb3DQEBBQUAMC8xCzAJBgNVBAYTAlVTMQww
CgYDVQQLEwNMQkwxEjAQBgNVBAMTCVRFU1QgQ0EgSTAeFw0wMTA1MDYwMTAyNTVa
Fw0wMjA1MDYwMTAyNTVaMC8xCzAJBgNVBAYTAlVTMQwwCgYDVQQLEwNMQkwxEjAQ
BgNVBAMTCVRFU1QgQ0EgSTBaMA0GCSqGSIb3DQEBAQUAA0kAMEYCQQDDcic5+wMp
L6z+qkOTUUhmVgqUchN4kKWBLPKWxqOjln0HRMLIddNDp2dzK/h452ultIo3E5TJ
kCsH9knwfCbDAgEDMA0GCSqGSIb3DQEBBQUAA0EAGrnEUiCzdp4rUJzMonTD6srN
VS8/I8IYPB8TK6Puz+81lJb0r97SbifSj24fbM0MyMqqw9mZ/PBfZ8S8dOyilA==
-----END CERTIFICATE-----</X509Certificate>
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE AkentiCertificate SYSTEM "/home/g1/proj/akenti/release/common/AkentiCertificate.dtd">
<Header Type="Policy" SignatureDigestAlg="RSA-MD5" CannonAlg="AkentiV1">
<ID id="rocky.lbl.gov#add30f6c#Fri May 18 17:50:14 PDT 2001"/>
<UserDN>/C=US/OU=LBL/CN=Stake Holder I</UserDN>
<CADN>/C=US/OU=LBL/CN=TEST CA I</CADN>
<ValidityPeriod start="010519005013Z" end="020504001529Z"/>
<ResourceName>LBL/test1</ResourceName>
<URL>ldap://idcg-ds.lbl.gov</URL>
<URL>file:/home/g1/proj/akenti/release/common/testResourceTree/idCerts</URL>
<URL>http://www-itg.lbl.gov/~mrt/NewCertificates/</URL>
<UserDN>/C=US/OU=LBL/CN=Stake Holder I</UserDN>
<CADN>/C=US/OU=LBL/CN=TEST CA I</CADN>
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing</UserDN>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL
<URL>file:/home/g1/proj/akenti/release/common/testResourceTree/certs</URL>
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE AkentiCertificate SYSTEM "/home/g1/proj/akenti/release/common/AkentiCertificate.dtd">
<Header Type="useCondCertificate" SignatureDigestAlg="RSA-MD5" CannonAlg="AkentiV1">
<ID id="rocky.lbl.gov#104b8965#Mon May 07 17:04:23 PDT 2001"/>
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Mary R. Thompson
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<ValidityPeriod start="010508000421Z" end="020506080443Z"/>
<UseConditionCert scope="sub-tree" enable="false">
<ResourceName>LBL</ResourceName>
<Constraint>( O : Lawrence Berkeley National Laboratory )</Constraint>
<AttrValue>Lawrence Berkeley National Laboratory</AttrValue>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<SubjectCA>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-Grid-CA</SubjectCA>
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE AkentiCertificate SYSTEM "/home/g1/proj/akenti/release/common/AkentiCertificate.dtd">
<Header Type="attributeCertificate" SignatureDigestAlg="RSA-MD5" CannonAlg="AkentiV1">
<ID id="rocky.lbl.gov#9ba89106#Wed Jun 10 14:00:13 PDT 1998"></ID>
<UserDN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing</UserDN>
<CADN>/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-
<ValidityPeriod start="981224003646Z" end="020506080443Z"/>
<UserDN>/C=US/OU=LBL/CN=Stake Holder I</UserDN>
<CADN>/C=US/OU=LBL/CN=TEST CA I</CADN>
Appendix B - Resource Attributes Definition File
Based on sample .resattributes file (resattributes_sample in docs
You must quote any items that have spaces in them, as shown below.
Otherwise, the parser will strip out the spaces and concatenate the
<AKENTI_ATTRSPEC VERSION="1.0"/>
<ca name="/C=US/OU=LBL/CN=TEST CA I">
<ds type="file" searchbase="/home/g1/proj/akenti/release/common/testResourceTree/idCerts">imglib.lbl.gov</ds>
<ca name="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=CertificateAuthorities/CN=LBNL-Grid-CA">
<ds type="ldap" searchbase="O=Lawrence Berkeley National Laboratory,O=Grid">idcg-ds.lbl.gov</ds>
<attr name="group" value="IDCG">
name="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Mary R. Thompson"
ca="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=CertificateAuthorities/CN=LBNL-Grid-CA"
name="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing"
ca="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-Grid-CA"
<attr name="role" value="Tester">
name="/C=US/O=Lawrence Berkeley National Laboratory/OU=ICSD/CN=Srilekha Mudumbai Issuer"
ca="/C=US/O=Lawrence Berkeley National Laboratory/OU=ICSD/CN=IDCG-CA"
name="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=ICSD/CN=Mary R. Thompson"
ca="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=CertificateAuthorities/CN=LBNL-Grid-CA"
name="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=DSD/CN=Akenti Testing"
ca="/O=Grid/O=Lawrence Berkeley National Laboratory/OU=Certificate Authorities/CN=LBNL-Grid-CA"