Akenti Certificate Specification

Security Hompage ->Akenti Homepage ->Documentation ->Details ->Akenti Certificates

This document describes both the internal certificate classes that are used by the Akenti policy engine, and the Akenti native or canonical string formats of the certificates. The classes are defined in the source directory akentiServer/certs. There are a number of elements which are used in constructing the AkentiCertificates. The Akenti elements are defined in the source directory akentiServer/certs/elements The base elements are defined in the source directory akentiServer/shared/net and akentiServer/shared/security.

The external string formats are generated by the writeObject methods for each class. They basically consist of ordered ASCII values for each component separated by a single space character. If values include significant spaces they are escaped by \'s. A \ is escaped as \\. Where there can be 0 or more than 1 values, the values are preceeded by an integer count. In the Format definition, components which can have 0 or more values will be followed by *, components which can have 1 or more values will be followed by +.

Akenti certificates are generally stored in files as an XML version of the certificate for readability, followed by the ASCII canonical form (for debugging), followed by signed version of the certifcate. The signed certificate is surround by PEM tags:
-----BEGIN AKENTI <TYPE> CERTIFICATE-----
base64 encoding of the canonicalform with the signature appended
-----END AKENTI <TYPE> CERTIFICATE-----
The Akenti policy engine only uses the signed certificate. The Certificate Generators use the XML part. The certificate XML is defined in Akenti Certificate Schema.

Thus programs that parse such files, need to search for the begin tag and ignore any other contents of the file.

Format <multi-line-text>\n
-----BEGIN AKENTI <TYPE> CERTIFICATE-----\n
<akenti canonical cert>\n
-----END AKENTI <TYPE> CERTIFICATE-----

Base Elements

URL

Class to hold a uniform resource locator. Akenti currently handles 3 protocols: http, ldap, and file. Items enclosed in [] are optional. The basic class is defined in shared/net/URL.hpp and implemented by three handler classes that are defined in the following files: shared/net/FileURLHandlerImpl.hpp, shared/net/HttpURLHandlerImpl.hpp and sharedLdapURLHandlerImpl.hpp. 
URL {
  string     protocol    // connection protocol: one of http, ldap, file
  string     host        // host to which to connect
  int        port        // port to which to connect
  string     file        // file location on target machine
  URLHandler handler     // pointer to implementation for the specific protocol
}
The external representation of a URL is simply a string as defined in the
Akenti class Directory.
Examples

<URL>http://itg.www.lbl.gov/Akenti</URL>
<URL>http://itg.www.lbl.gov:8080/Projects/Akenti</URL>
<URL>file:/usr/local/mrt/Certificates</URL>

Canonical Format protocol:[//host[:port]]/file
Example1 http://itg.www.lbl.gov/Akenti
Example2 http://itg.www.lbl.gov:8080/Projects/Akenti
Example3 file:/usr/local/mrt/Certificates

Distinguished Name (DN)

This is the Distinguished Name that is defined in X.509 identity certificates. It consists of variable number of components where each component consists of a identifier and a value. The common identifiers we use are C for country, O for organization, OU for Organizational Unit and CN for common name. This type is defined in the file shared/security/DistinguishedName.hpp. 

typedef pair<string, string> Pair;
DistinguishedName {
  vector<Pair> components
}
Example

<UserDN>/C=US/O=LBNL/OU=DSD/CN=Abdelilah Essiari</UserDN>

Canonical Format /<id>=<value>
Example /C=US/O=LBNL/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA

PublicKey

This is an Akenti class to wrap an openSSL key and to provide methods that are applicable to only the public part of the key. This type is defined in shared/security/PublicKey.hpp, shared/security/PublicKeyImpl.hpp, shared/openssl/OpenSSLPublicKeyImpl.hpp.

Example

<PublicKey> DER representation of public key</PublicKey>

Canonical Format <length of DER encoding><space><DER encoding>

Akenti Elements

AkentiPrincipal

An AkentiPrincipal consists of the DN of a person or other entity and the DN of the Certificate Authority (CA) that issued the certificate linking this DN to a public/private key pair. This type is defined in the file certs/elements/AkentiPrincipal.hpp. 
AkentiPrincipal { 
  DistinguishedName name          // DN of the principal
  DistinguishedName guarantor     // DN of the CA that issued a Identity 
}
Example
<Principal>
   <UserDN> /C=US/O=LBNL/CN=Abdelilah Essiari</UserDN>  
   <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
</Principal>

Canonical Format name<space>guarantor
Example /C=US/O=LBNL/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA

AkentiIssuer

An AkentiIssuer consists of the DN of a person or other entity and the DN of the Certificate Authority (CA) that issued the certificate linking this DN to a public/private key pair. It may also contain an optional list of directories in which the X509 certificate for this issuer may be found. This type is defined in the file certs/elements/AkentiIssuer.hpp. 
AkentiIssuer { 
  AkentiPrincipal   issuerAndCA   // DN of the principal and its CA
  vector<Directory> idDirs        // optional list of directories in which
                                  //    the issuer's X509 cert may be found
}
Example
<Issuer>
   <UserDN> /C=US/O=LBNL/CN=Abdelilah Essiari</UserDN>  
   <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
</Issuer>

<Issuer>
   <UserDN> /C=US/O=LBNL/CN=Abdelilah Essiari</UserDN>  
   <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   <URL>ldap://idcg-ca.lbl.gov</URL>
</Issuer>

Canonical Format name<space>guarantor
Example1 /C=US/O=LBNL/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 0
Example2 /C=US/O=LBNL/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 1 ldap://idcg-ca.lbl.gov

Directory

This element contains a string represention of a directory URL. This type is defined in certs/elements/Directory.hpp. The XML tag for this type is the same as for the URL type. 
Directory {
  string url             // string representation of a URL
}

Examples
<URL>http://itg.www.lbl.gov/Akenti</URL>
<URL>ldap:/idcg-ca.lbl.gov</URL>
<URL>file:/user/local/mrt/Certificated</URL>

Format rep
Example1 http://itg.www.lbl.gov/Akenti
Example2 ldap:/idcg-ca.lbl.gov
Example3 file:/usr/local/mrt/Certificates

AttributeInfo

An attribute is a characteristic of a person or other named entity. An attribute usually fulfills a condition in Akenti. The AttributeInfo class consists of an attribute type; the name and value of the attribute; and the principals that are authorized to attest to this attribute; an optional list of URLs in which Attribute Certificates or external authorities can be found and an optional list of parameters that can be passed to the external authority who evaluates this attribute. An atribute type can be one of: SYSTEM, X509, AKENTI or EXT_AUTH. An X509 attribute is one that is defined in a X.509 identity certificate such as O,OU or CN. AKENTI attributes are ones for which an Attribute Certificate can be found. Examples of AKENTI attributes are "group", "role", "citizenship", or "training level completed". An EXT_AUTH attribute is one where some authority or mechanism outside of Akenti will determine its validity, such a time of day from a time server. SYSTEM attributes are ones that are determined by some function of the resource gateway system such as time determined by a system clock call, or disk usage as returned by a filesystem call. This class is used as a component in the Condition element found in UseCondition and Attribute certificates. The AttributeInfo type is defined in the file certs/elements/AttributeInfo.hpp. 
AttributeInfo { 
  Type                type   // SYSTEM(0), X509(1), AKENTI(2), or EXT_AUTH(3)
  string              name   // name of attribute                     
  string              value  // value of attribute
  vector<DistinguishedName>  CAs    // issuers for X509 attributes
  vector<AkentiPrincipal>    auths  // Attrribute Cert issuers for AKENTI attrs
                                    //  OR external authorities for EXT_AUTH attrs
  vector<URL>         attrDirs      // optional list of places to search for 
                                    //   attribute certs, or to contact 
                                    //   external authorities
  vector<string>      ext_auth_args // optional arguments to an external authority
}
Examples:
<AttributeInfo type="X509">
  <AttrName>CN</AttrName>
  <AttrValue>Mary R. Thompson </AttrValue> 
  <CADN> /O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA </CADN>
</AttributeInfo>

<AttributeInfo type="AKENTI">
  <AttrName>group</AttrName>
  <AttrValue>dc-lbnl</AttrValue>  
   <Principal> 
      <UserDN>/C=US/O=LBNL/OU=DSD/CN=Abdelilah Essiari</UserDN>
      <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   </Principal> 
   <Principal>
      <UserDN>/C=US/O=LBNL/OU=DSD/CN=Mary R. Thompson</UserDN> 
      <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   </Principal>
   <AttrDirs>
       <URL>http:/itg-www.lbl.gov/~mrt/Certificates</URL>
    </AttrDirs>
</AttributeInfo>

Canonical Format type<space>name<space>value<space>[[caSize<space>cas+]|[<space>issuersSize <space>issuers+ ]] [ <space>attrDirSize<space>attrDirs*] [ <space>argSize<space>ext_auth_args* ]
Example1 1 CN Mary\ R.\ Thompson 1 /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA
Example2 2 group dc-lbnl 2 /C=US/O=LBNL/OU=DSD/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA /C=US/O=LBNL/OU=DSD/CN=Mary\Thompson /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 1 http:/itg-www.lbl.gov/~mrt/Certificates

Condition

A Condition element holds a boolean expression and a vector of AttributeInfo objects that describe the attribute/value pairs used by the expression. It is defined in the file certs/elements/Condition.hpp 
 Condition {
     string constraint; 
     vector<AttributeInfo> attributeInfos;
  }
The constraint is expressed in a relational language whose grammar is as follows:

constraint_expr ::= and_expr { `||' and_expr }*
and_expr ::= prim_expr { `&&' prim_expr }*
prim_expr ::= av_expr | ( constraint_expr )

av_expr ::= attr rel_op value
rel_op ::= `=' | ` !=' | `< ` | `<=' |' >' | `>='
attr ::= word
value ::= word {word}*
word ::= {char}+
char ::= digit | letter | _ | # | . | , | / | : | ;
White space is generally ignored except within a value element 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.

Note that the characters '&', '<' and '>' are special characters in xml. So if you are manually writing an xml version of an Akenti certificate they must either be written as &amp;, &lt; and &gt; or the entire constraint can be enclosed in a <![CDATA[ ...]]> clause. If you are using our GUI certificate generators, they will do this for you.

Examples: 

<Condition>
   <Constraint>group=teamA</Constraint>
   <AttributeInfo type="AKENTI">
      <AttrName>group</AttrName>
      <AttrValue>teamA</AttrValue>
      <Principal>
         <UserDN>/C=US/O=LBNL/OU=DSD/CN=Abdelilah Essiari</UserDN>
         <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
      </Principal>
      <AttrDirs>  
        <URL>http://www-itg.lbl.gov/~aes/Certificates</URL>
     </AttrDirs>
   </AttributeInfo>
</Condition>


<Condition>
   <Constraint>(ou=NERSC)&amp;&amp;(cn=Mary R. Thompson)</Constraint>
   <AttributeInfo type="X509">
       <AttrName>ou</AttrName>
       <AttrValue>NERSC</AttrValue>
       <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   </AttributeInfo>
   <AttributeInfo type="X509">
        <AttrName>cn</AttrName>
        <AttrValue>Mary R. Thompson</AttrValue>
        <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   </AttributeInfo>
</Condition>


<Condition>
  <Constraint><![CDATA[(group=researchers || (time > 6pm && time
                 < 8am)) && (O=LBNL))]]> </Constraint>
  <AttributeInfo type="AKENTI" >
      <AttrName>group</AttrName>
      <AttrValue>researchers</AttrValue>
      <Principal>
         <UserDN>/C=US/O=LBNL/OU=DSD/CN=Abdelilah Essiari</UserDN>
         <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
      </IdDirs>ldap://idcg-ca.lbl.gov </IdDirs>
      </Principal>
   </AttributeInfo>
   <AttributeInfo type="SYSTEM">
       <AttrName>time</AttrName>
       <AttrValue>6pm</AttrValue>
   </AttributeInfo>
   <AttributeInfo type="SYSTEM">
       <AttrName>time</AttrName>
       <AttrValue>8am</AttrValue>
   </AttributeInfo>
   <AttributeInfo type="X509">
       <AttrName>O</AttrName>
       <AttrValue>LBNL</AttrValue>
       <CADN>/O=LBNL/OU=Certificate Authorities/CN=LBNL-Grid-CA</CADN>
   </AttributeInfo>
</Condition>

Format constraint<space>attrInfoSize<space>attrInfo+
Example1 group=teamA 1 2 group teamA 1 /C=US/O=LBNL/OU=DSD/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 0 1 http://www-itg.lbl.gov/~aes/Certificates
Example2 (ou=NERSC) || (cn=Mary R. Thompson) 2 1 ou NERSC /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 1 cn Mary R. Thompson /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 0
Example3 (group=researchers || (time > 6pm && time < 8am)) && (O=LBNL) 4 2 group researchers 1 /C=US/O=LBNL/OU=DSD/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 1 ldap://idcg-ca.lbl.gov 0 0 time 6pm 0 time 8am 1 O LBNL /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 0

UseCondition

A UseCondition element is used in the UseCondition certificate to contain the condition that must be met by a user accessing the resource and two flags controlling its use. One flag specifies whether the Condition applies to resource and its subtree or to the resource only, and one flag that allows an owner to refuse access if this Condition is not met. This type is defined in file certs/elements/UseCondition.hpp 
UseCondition {
  Condition condition      // boolean constraint and corresponding attributeInfos

  bool      isScopeLocal   // if true UC applies only tothe local resource
                           //    if false UC applies to the whole subtree
  bool      critical       // if true, this UseCondition MUST be satisified
}

Examples
There is no coresponding XML element. It is part of the UseConditionCert element.

Format isScopeLocal<space>critical<space>Condition
Example 1 1 (role=tester)&(o=LBNL) 2 2 role tester 2 /C=US/O=LBNL/OU=DSD/CN=Abdelilah\ Essiari /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA /C=US/O=LBNL/OU=DSD/CN=Mary\Thompson /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 1 o LBNL 1 /O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA

CertificateAuthorityInfo

This element is part of a Policy Certificate and defines the CA's that are trusted. A complete list of all the trusted CA's must appear in the Policy Certificate for the resource root.If a listed CA has signed for subordinate CAs, these subordinates are implicitly trusted. If CertificateAuthorityInfo elements occur in subtree Policy Certificate, they must be a subset of those that are in the Policy Certificate for the root and are used to limit the trusted CA's for the subtree. A subset of CA's is defined as some subset of those explicitly listed in the root, or it may include CA's that are subordinate to (and thus implicitly trusted) those listed in the root.

Note that the certificate includes the public key of the CA, which Akenti uses to get a trusted copy of a self-signed CA public key. The idDirs are where Akenti will search for X.509 certificates for principals that have signed UseCondition or Attribute certificates. Currently the CRLdirs are optional since not all CAs implement such a mechanism. But if this field is omitted, Akenti has no way to check if an X509 certificate has been revoked. This type is defined in the file certs/elements/CertificateAuthorityInfo.hpp. 

CertificateAuthorityInfo { 
  DistinguishedName   ca          // Certificate Authority to be trusted
  vector<Certificate> certificate // CA's x.509 identity cert or chain
                                  //    of certs including public key
  vector<Directory>   idDirs      // Dirs where the CA stores the certificates 
                                  //     that it issues
  vector<Directory>   crlDirs     // Pointer to some type of mechanism to 
                                  //    handle certificate revocation
}

Examples

<CAInfo>
   <CADN>/O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA</CADN>
   <X509Certificate>-----BEGIN CERTIFICATE-----
MIICvzCCAiigAwIBAgIBDzANBgkqhkiG9w0BAQUFADBbMRkwFwYDVQQKExBET0Ug
U2NpZW5jZSBHcmlkMSAwHgYDVQQLExdDZXJ0aWZpY2F0ZSBBdXRob3JpdGllczEc
MBoGA1UEAxMTQ2VydGlmaWNhdGUgTWFuYWdlcjAeFw0wMDA4MjkyMjI4MDJaFw0w
MTA4MjkyMjI4MDJaMHgxDTALBgNVBAoTBEdyaWQxLjAsBgNVBAoTJUxhd3JlbmNl
IEJlcmtlbGV5IE5hdGlvbmFsIExhYm9yYXRvcnkxIDAeBgNVBAsTF0NlcnRpZmlj
YXRlIEF1dGhvcml0aWVzMRUwEwYDVQQDEwxMQk5MLUdyaWQtQ0EwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAL2t4aX933WXYlofuY+L+16Tdl/KxpAammyfcW8u
kHHT6RYDjaQdfV1FpNEqfSrRjKNwGGGkrG4XHZWiUO0Di0AlBN04lsRY6jB68l6B
5byujfZv+8EeCI2c1ObBLYZYi4lToJf0sm0Hpn3GD7PZBv6BVHLOuwEFDl9z9Dnc
DFDdAgMBAAGjdjB0MBEGCWCGSAGG+EIBAQQEAwIAhzAOBgNVHQ8BAf8EBAMCAcYw
HQYDVR0OBBYEFIn+csPVyp+iprpYUIu1SziMQiDxMA8GA1UdEwEB/wQFMAMBAf8w
HwYDVR0jBBgwFoAUm85P8ry9WHAx1fIyDn6eveJRFOcwDQYJKoZIhvcNAQEFBQAD
gYEAHindWQ4P4VUmJVt5sUGA05hSAZriDJDDnkvkm/9AR7xgGxtsy21QruhUVe2E
eVFBws85zbwRqMpfUQyE/xHhUcka2GQTaKlBlcEjZTMnsh27Si2PMYU/UPr/PIpq
kBkoxVV1bMWRK57mG2tzzTy9j0wkct4G5IjEsrYNDzW6U3E=
-----END CERTIFICATE-----
   </X509Certificate>
   <IdDirs>
     <URL>ldap:/idcg-ca.lbl.gov</URL>
   </IdDirs>
</CAInfo>
Format ca<space>certificate<space>idDirSize<space>idDir*<space>crlDirSize<space>crlDir*
Example 
/O=LBNL/OU=Certificate\ Authorities/CN=LBNL-Grid-CA 
-----BEGIN CERTIFICATE-----
MIICvzCCAiigAwIBAgIBDzANBgkqhkiG9w0BAQUFADBbMRkwFwYDVQQKExBET0Ug
U2NpZW5jZSBHcmlkMSAwHgYDVQQLExdDZXJ0aWZpY2F0ZSBBdXRob3JpdGllczEc
MBoGA1UEAxMTQ2VydGlmaWNhdGUgTWFuYWdlcjAeFw0wMDA4MjkyMjI4MDJaFw0w
MTA4MjkyMjI4MDJaMHgxDTALBgNVBAoTBEdyaWQxLjAsBgNVBAoTJUxhd3JlbmNl
IEJlcmtlbGV5IE5hdGlvbmFsIExhYm9yYXRvcnkxIDAeBgNVBAsTF0NlcnRpZmlj
YXRlIEF1dGhvcml0aWVzMRUwEwYDVQQDEwxMQk5MLUdyaWQtQ0EwgZ8wDQYJKoZI
hvcNAQEBBQADgY0AMIGJAoGBAL2t4aX933WXYlofuY+L+16Tdl/KxpAammyfcW8u
kHHT6RYDjaQdfV1FpNEqfSrRjKNwGGGkrG4XHZWiUO0Di0AlBN04lsRY6jB68l6B
5byujfZv+8EeCI2c1ObBLYZYi4lToJf0sm0Hpn3GD7PZBv6BVHLOuwEFDl9z9Dnc
DFDdAgMBAAGjdjB0MBEGCWCGSAGG+EIBAQQEAwIAhzAOBgNVHQ8BAf8EBAMCAcYw
HQYDVR0OBBYEFIn+csPVyp+iprpYUIu1SziMQiDxMA8GA1UdEwEB/wQFMAMBAf8w
HwYDVR0jBBgwFoAUm85P8ry9WHAx1fIyDn6eveJRFOcwDQYJKoZIhvcNAQEFBQAD
gYEAHindWQ4P4VUmJVt5sUGA05hSAZriDJDDnkvkm/9AR7xgGxtsy21QruhUVe2E
eVFBws85zbwRqMpfUQyE/xHhUcka2GQTaKlBlcEjZTMnsh27Si2PMYU/UPr/PIpq
kBkoxVV1bMWRK57mG2tzzTy9j0wkct4G5IjEsrYNDzW6U3E=
-----END CERTIFICATE-----
1 ldap:/idcg-ca.lbl.gov 0

UseCondIssuerGroup

This element is part of a Policy Certificate and specifies a stakeholder or group of stakeholders that may issue Use Condition certificates for this resource and where to look for these certificates. The multiple directories are only for redundancy and each one must contain all of the stakeholder-group's Use Condition certificates. As soon as one or more certificates are found in one of the directories, no further directories will be searched. If no certificates are found for this group of stakeholders, access to the resource will be denied. The UseCondIssuerGroup is defined in the file certs/elements/UseCondIssuerGroup.hpp. 
UseCondIssuerGroup { 
  vector<AkentiPrincipal>  issuers  // stakeholders who may issue UseCond certs
  vector<URL>              locators // URLs to search for UseCondition certs
}
Examples 
<UseCondIssuerGroup>
<Principal>
   <UserDN>/C=US/O=LBNL/OU=DSD/CN=Mary R. Thompson</UserDN>
   <CADN>/C=US/O=LBNL/OU=Certificate Authorities/CN=IDCG-CA</CADN>
</Principal>
<URL> http://www-itg.lbl.gov/~mrt/Certificates/</URL>
</UseCondIssuerGroupl>
Format issuerSize<space>issuer+<space>locatorSize<space>locator+
Example 1 /C=US/O=LBNL/OU=DSD/CN=Mary\ R.\ Thompson /C=US/O=LBNL/OU=Certificate\ Authorities/CN=IDCG-CA 1 http://www-itg.lbl.gov/~mrt/Certificates/

ConditionalActions

ConditionalActions are returned by the access checking interface when actions have attributes associated with them that cannot be evaluated by the Akenti policy engine. Examples of such attributes are: the remaining disk quota of a user or some measure of the current resource use. In these cases the actions that depend on the unevaluated attributes are combined with the required attribute and value. This element constains a boolean condition, a list of actions that will be granted if the condition evaluates to true and a flag marking the condition as critical or not. Critical expresions must evaluate to to true otherwise access must be denied even if ohter unconditionalActions exist. Such conditions come from UseConditions that have the enable flag set and must be satisified. 
   ConditionalActions {
      Condition condition;
      vector<string> actions;
      bool critical;                 
   }
Example
<ConditionalActions  critical="true">
  <Condition>
     <Constraint>AvailDisk>2Gig </Constraint>
     <AttributeInfo type="SYSTEM">
        <AttrName>AvailDisk</AttrName>
        <AttrValue>2Gig</AttrValue>
     </AttributeInfo>
  </Condition>
</ConditionalActions>
Format condition<space>actionsSize<space>actions+<space>critical
Example AvailDisk>2Gig 1 0 AvailDisk 2Gig 2 read write 1

Akenti Certificates

Akenti uses the term Certificate to refer to a digitally signed document that contains some information that is part of the Use Policy for a resource. In addition to the X.509 Identity certificates that we use to identitfy principals, we define the following types of certificates: Certificates are referenced externally by a ref_ptr which contains a reference to a concrete certificate implementation. The internal structure of each certificate type is defined in a file named <certname>CertificateImpl.hpp in the directory certs. There is a base class AkentiCertificateImpl defined in the file certs/AkentiCertificateImpl.hpp that is inherited by all the specific certficate implementation classes.

AkentiCertificate

This is the base class for all the other certificates, thus it is automatically included as part of all the specific certificate classes. It's external represention which will be refered as CertificateHead appears at the beginning of every certificate's external format. It is defined in the file certs/AkentiCertificateImpl.hpp. 
AkentiCertificate {
  string           type         // certificate type
  int              version      // certificate format version
  string           id           // certificate's unique ID
  AkentiIssuer     guarantor    // principal that issued and signed the certificate     
  UtcTime          notBefore    // Certificate not valid before this date   
  UtcTime          notAfter     // Certificate not valid after this date   
  string           signatureAlg // name of hashMac and encryption algorithm 
                                //  used to sign this certifacate
  // information specific to the type of certificate 
  string           signature    // signature of the actual certificate
}
Certificate type is one of: UseCondition, Attribute, Policy, Capability, Cache.
SignatureAlg is a combinatation of hash MAC name and encryption algorithm. Akenti passes it as an opaque string to openssl. Thus any of the values supported by openssl may be used. We recommend either "RSA-MD5", "DSA-SHA1" ...

Examples 

<AkentiCertificate>
  <SignablePart>
     <Header type="Attribute" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
       <Version ver="V2"></Version>
       <ID id="mrtnote.lbl.gov#78a152ca#SunNov1417:11:57PST1999"></ID>
       <Issuer>
        <UserDN>/C=US/O=Lawrence Berkeley National Laboratory/OU=ICSD/
               CN=Mary R. Thompson </UserDN>
        <CADN>/C=US/O=Lawrence Berkeley National Laboratory/OU=ICSD/
               CN=IDCG-CA</CADN>
       </Issuer>
       <ValidityPeriod start="000111224101Z" end="010110224101Z"/>
     </Header>
    (...)
  </SignablePart>
</AkentiCertificate>
Format type<space>version<space>ID<space>issuer<space>notBefore<space>notAfter <space>;signatureAlg<space><type specific cert info><space>signature
Example Attribute V2 mrtnote.lbl.gov#78a152ca#SunNov1417:11:57PST1999 /C=US/O=LBNL/OU=DSD/CN=Mary\ R.\ Thompson /C=US/O=LBNL/OU=Certificate\Authorities/CN=IDCG-CA 0 000111224101Z 010110224101Z 3600 RSA-MD5

Note that the signature is written at the end of the certificate not after the CertificateHead and is the signature of the entire certificate.

Use Condition Certificate

The UseCondition certificate expresses a stakeholder's restrictions on how a resource may be used. A UseCondition certificate applies to a single resource or subtree of resources (if the resources are hierarchical) that is named in the certificate. There may be many Use Condition certificates applying to a single resource which Akenti needs to evaluate simultaneously when evaluating a user's access to a resource. The constraint is a boolean expression stating attributes and values that the user must possess in order to satisfy it. A list of which principals are trusted to grant these attribute/value pairs is included in the attributes vector. The allowed actions are represented by an vector of strings consisting of a list of rights. The rights are uninterpreted by Akenti, which returns them to the caller who must understand what actions the rights grant. The enable boolean is used to specify that this Use Condition Certificate MUST be satisfied if the user it to gain any access to the resource. This allows a stakeholder to veto a user's access regardless of what the other Use Condition certificates for the resource may grant. If enable is true, it may make sense to allow no rights, if the stakeholder just wants to be sure that every user satisifies the constraint. If this is the case, then there must be additional rights granting UseConditions. If the enable boolean is not set, this certificate will be used to grant rights to any user who satisifies it but will not affect those users who do not satisfy it. This type is defined in the file certs/UseCondCertificateImpl.hpp. When the certificates are stored as files they are named by a hash encoding of the resource name plus a numeric suffix. The suffix starts at 0 and increments by one until a name that is unique to the local directory is found. 
UseCondCertificate {
  string        resource      // name of resource  or resource subtree
  UseCondition  useCondition  // boolean expression that user must satisfy  
                              //    plus the issuers and CAs for each attribute 
                              //    used by the constraint           
  vector<string> actions      // defined by stakeholder, 
                              //   interpreted by resource gateway

}
Example 
<AkentiCertificate>
  <SignablePart>
    <Header type="UseCondition" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
        (...)
   </Header>
   < UseConditionCert scope="sub-tree" critical="false"> 
     <ResourceName>DieselCollab/PREServer/chad </ResourceName>
     <Condition> 
       <Constraint>(( cn = Diane Gomes ) || ( cn = Mary R. Thompson ))</Constraint>
       <AttributeInfo type="X509">
          <AttrName>cn</AttrName>
          <AttrValue>Diane Gomes</AttrValue>
          <CADN>/C=US/O=Diesel Combustion Collaboratory/OU=SNL/
               CN=DieselCert.ca.sandia.gov </CADN>
       </AttributeInfo>
       <AttributeInfo type="X509">
          <AttrName>cn</AttrName>
          <AttrValue>Mary R. Thompson</AttrValue>
          <CADN>/C=US/O=LBNL/OU=ICSD/CN=IDCG-CA</CADN>
       </AttributeInfo>
    </Condition>
    <Rights>read,execute </Rights>
  </UseConditionCert>
  </SignablePart>
</AkentiCertificate>
   



Format
CertificateHead<space>resource<space>scope<space>enable<space>useCondition<space>
actionsSize<space>actions*<space>subjectCAsSize<space>subjectCAs+ 

Example
<CertificateHead> DieselCollab/PREServer/chad 1 0 (\ (\ cn\ =\ Diane\ Gomes\ )\ ||\ (\ cn\ =\ Mary\ R.\ Thompson\ )\ ) 2 1 cn Diane\ Gomes 1 /C=US/O=Diesel\ Combustion\ Collaboratory/OU=SNL/CN=DieselCert.ca.sandia.gov 1 cn Mary\ R.\ Thompson 1 /C=US/O=LBNL/OU=ICSD/CN=IDCG-CA 2 read execute

AttributeCertificate

An Attribute Certificate grants a single attribute to a single principal. There may be some constraints applied to this attribute which are listed in as a vector of akentiExtensions. Note that attribute certificates only exist for non-X509 attributes. The X509 attributes are defined in the X509 identity certificates. The AttributeCertificate is defined in the file certs/AttributeCertificateImpl.hpp. 
AttributeCertificate { 
  AkentiPrincipal     principal  // to whom this attribute applies
  string              attribute  // attribute name            
  string              value      // attribute value                
  Condition           condition  // Optional constraint on this attribute
}
An optional condition may be applied to the attribute. It is expressed in the same fomat as is used in the UseCondition certificate. However, the X509 attibute type does not make sense here since the user's DN is already completely defined by the principal field. The other attribute types can be used to limit the validity of this attribute to a specific time of day, or make it contingent on the user holding another attribute.

When attribute certificates are stored in files they are named by a hash encoding of the subject Name and CA of the principal, the name and value of the attribute plus a numeric suffix.The suffix starts at 0 and increments by one until a name that is unique to the local directory is found.

Examples 

<AkentiCertificate>
  <SignablePart>
     <Header type="Attribute" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
     (...)
     </Header>
    <AttributeCert>
      <SubjectAndCA>
         <UserDN>/C=US/O=LBNL/OU=ICSD/CN=Mary R. Thompson</UserDN>
         <CADN>/C=US/O=LBNL/OU=Certificate Authorities/CN=IDCG-CA</CADN>
      </SubjectAndCA>
      <AttrName>group</AttrName>
      <AttrValue>staff</AttrValue>
    </AttributeCert>
  </SignablePart>
</AkentiCertificate>

<AkentiCertificate>
  <SignablePart>
     <Header type="Attribute" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
     (...)
     </Header>
    <AttributeCert>
      <SubjectAndCA>
         <UserDN>/C=US/O=LBNL/OU=ICSD/CN=Mary R. Thompson</UserDN>
         <CADN>/C=US/O=LBNL/OU=Certificate Authorities/CN=IDCG-CA</CADN>
      </SubjectAndCA>
      <AttrName>group</AttrName>
      <AttrValue>sysadmin</AttrValue>
      <Condition>
         <Constraint>(IP=131.243.2.11)</Constraint>
         <AttributeInfo type="SYSTEM">
           <AttrName>IP</AttrName>
           <AttrValue>131.243.2.11</AttrValue>
        </AttributeInfo>
      </Condition> 
    </AttributeCert>
  </SignablePart>
</AkentiCertificate>
Format certificateHead<space>principal<space>attribute<space>value<space>condition
Example1
no condition 		<CertificateHead>/C=US/O=LBNL/OU=ICSD/CN=Mary\ R.\ Thompson /C=US/O=LBNL /OU=Certificate\ Authorities/CN=IDCG-CA group staff
Example2
with condition 		<CertificateHead>/C=US/O=LBNL/OU=ICSD/CN=Mary\ R.\ Thompson /C=US/O=LBNL /OU=Certificate\ Authorities/CN=IDCG-CA group sysadmin IP=131.243.2.11 0 IP 131.243.2.11

PolicyCertificate

A Policy certificate defines the trusted authorities for a resource or a resource subtree. This certificate is stored on the resource gateway or the Akenti server machine and is signed by a stakeholder for the resource. It contains the name of the resource to which it applies; may optionally contain a limiting list of trusted CA's; a list of zero or more directories in which to search for attribute certificates; a cache life-time that specifies the maximum time in seconds that certificates that are used in satisifying conditions for this resource may be cached. If a list of CA's is included, then only those CA's are trusted. If there is no CA list, then all the CA's listed in the Policy Certificate for the resource root are trusted. The Policy certificate at the resource root must have a list of trusted CA's. It also contains one or more groups of stakeholders and their directories. At least one Use Condition certificate must be found for each group of stakeholders. The PolicyCertificate is defined in the file certs/PolicyCertificateImpl.hpp. When PolicyCertificates are stored in directories they are named by a hash encoding of the resource name and a numerical suffix. The suffix starts at 0 and increments by one until a name that is unique to the local directory is found. 


PolicyCertificate {  
  string               resourceName  // resource to which this policy applies
  vector<CertificateAuthorityInfo> CAInfo // Certificates for CA's that 
                                     // are trusted to sign X509 certs.
  vector<UseCondIssuerGroup> useCondIssuerGroup // stakeholders and directories in 
                                     //   which they publish their UseCondtions
  vector<URL>          attrDirs      // directories in which to search for 
                                     //   attribute certificates
  long                 cacheTime     // maximum cache time in seconds
}

Example 

<AkentiCertificate>
  <SignablePart>
     <Header type="Policy" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
     (...)
     </Header>
  <PolicyCert>
    <ResourceName>DCC Servers</ResourceName>
    <CAInfo>
        <CADN>/c=US/O=LBNL/OU==ICSD/CN=IDCG-CA</CADN>
        <X509Certificate>
"-----BEGIN CERTIFICATE-----
\MIIC1jCCAj+gAwIBAgIBbzANBgkqhkiG9w0BA
QQFADBeMQswCQYDVQQGEwJVUzEuMCwGA1UEChMlTGF3cmVuY2UgQmVya2VsZXkgTm
F0aW9uYWwgTGFib3JhdG9yeTENMAsGA1UECxMESUNTRDEQMA4GA1UEAxMHSURDRy1
DQTAeFw05OTA3MjgxODAyMjNaFw0wMTA3MjcxODAyMjNaMF4xCzAJBgNVBAYTAlVT
MS4wLAYDVQQKEyVMYXdyZW5jZSBCZXJrZWxleSBOYXRpb25hbCBMYWJvcmF0b3J5M
Q0wCwYDVQQLEwRJQ1NEMRAwDgYDVQQDEwdJRENHLUNBMIGfMA0GCSqGSIb3DQEBAQ
UAA4GNADCBiQKBgQDArly+tnX5eW7v4KT5CVf/IwR8rDkqniDUq34x/wqrKbM0AY+
SV2hEHz+MCDgSlmPOXfwEplXW5IYYXqJ3+dK06et7mUodOhAB+0b6a8dVwul1+gRw
Ei80vft4+WvDUUHMZQiq3UqFTsPN+09sW+2paqXNQZvBq2r+6/ovM4OqVwIDAQABo
4GjMIGgMBEGCWCGSAGG+EIBAQQEAwIABzBLBglghkgBhvhCAQMEPhY8aHR0cHM6Ly
9pZGNnLWNhLmxibC5nb3YvY21zP29wPWNoZWNrUmV2b2NhdGlvbiZzZXJpYWxOdW1
iZXI9MB8GA1UdIwQYMBaAFAkHHatS78FaazO5C5Ty5e35luD7MB0GA1UdDgQWBBQJ
Bx2rUu/BWmszuQuU8uXt+Zbg+zANBgkqhkiG9w0BAQQFAAOBgQBDM7EfXJcsN4kqP
9nURhduCf4vuQ62QA+HsP06SkopofXdNrKnlN/hVb85C66jcvUKQhbuNlX+2M0HgP
uBVr7NbplVUeNeMmRFlA/RCeNtdqlO/MxMXpJYQb2ci39Crabt5gBWEk+0RRc/nHx
Fco+e8GiZ5S9kZ52J6frmhfYnCcA==
\-----END CERTIFICATE-----"
       </X509Certificate>
      <IdDirs>
       <URL> ldap://idcg-ca.lbl.gov/</URL>
      </IdDirs>
    </CAInfo>
    <UseCondIssuerGroup>
       <Principal>
          <UserDN>/C=US/O=LBNL/OU=ICSD/CN=Mary R. Thompson</UserDN>
          <CADN> /C=US/O=LBNL/OU=ICSD/CN=IDCG-CA</CADN>
       </Principal>
       <URL> http://www-itg.lbl.gov/~mrt/Certificates/</URL>
    <UseCondIssuerGroup>
    <AttrDirs>
        <URL>file:/usr/mrt/Attributes</URL>
        <URL> http://idcg-ds.lbl.gov/~kjackson/Certificates/</URL>
    </AttrDirs>
    <CacheTime>1800</CacheTime>
    </PolicyCert>
  </SignablePart>
</AkentiCertificate>
Format CertificateHead<space>ResourceName<space>certificateAuthorityInfosSize<space> certificateAuthorityInfos* <space>useCondIssuerGroupSize<space>useCondIssuerGroup+ <space>attrDirsSize<space>attrDirectories*<space>cacheTime
Example 
<CertificateHead>DCC/servers 1  
/C=US/O=Lawrence\ Berkeley\ National\ Laboratory/OU=ICSD/CN=IDCG-CA" 
"-----BEGIN CERTIFICATE-----
\MIIC1jCCAj+gAwIBAgIBbzANBgkqhkiG9w0BA
QQFADBeMQswCQYDVQQGEwJVUzEuMCwGA1UEChMlTGF3cmVuY2UgQmVya2VsZXkgTm
F0aW9uYWwgTGFib3JhdG9yeTENMAsGA1UECxMESUNTRDEQMA4GA1UEAxMHSURDRy1
DQTAeFw05OTA3MjgxODAyMjNaFw0wMTA3MjcxODAyMjNaMF4xCzAJBgNVBAYTAlVT
MS4wLAYDVQQKEyVMYXdyZW5jZSBCZXJrZWxleSBOYXRpb25hbCBMYWJvcmF0b3J5M
Q0wCwYDVQQLEwRJQ1NEMRAwDgYDVQQDEwdJRENHLUNBMIGfMA0GCSqGSIb3DQEBAQ
UAA4GNADCBiQKBgQDArly+tnX5eW7v4KT5CVf/IwR8rDkqniDUq34x/wqrKbM0AY+
SV2hEHz+MCDgSlmPOXfwEplXW5IYYXqJ3+dK06et7mUodOhAB+0b6a8dVwul1+gRw
Ei80vft4+WvDUUHMZQiq3UqFTsPN+09sW+2paqXNQZvBq2r+6/ovM4OqVwIDAQABo
4GjMIGgMBEGCWCGSAGG+EIBAQQEAwIABzBLBglghkgBhvhCAQMEPhY8aHR0cHM6Ly
9pZGNnLWNhLmxibC5nb3YvY21zP29wPWNoZWNrUmV2b2NhdGlvbiZzZXJpYWxOdW1
iZXI9MB8GA1UdIwQYMBaAFAkHHatS78FaazO5C5Ty5e35luD7MB0GA1UdDgQWBBQJ
Bx2rUu/BWmszuQuU8uXt+Zbg+zANBgkqhkiG9w0BAQQFAAOBgQBDM7EfXJcsN4kqP
9nURhduCf4vuQ62QA+HsP06SkopofXdNrKnlN/hVb85C66jcvUKQhbuNlX+2M0HgP
uBVr7NbplVUeNeMmRFlA/RCeNtdqlO/MxMXpJYQb2ci39Crabt5gBWEk+0RRc/nHx
Fco+e8GiZ5S9kZ52J6frmhfYnCcA==
-----END CERTIFICATE-----"
1 ldap://idcg-ca.lbl.gov 0
1 1 /C=US/O=LBNL/OU=DSD/CN=Mary\ R.\ Thompson
/C=US/O=LBNL/OU=Certificate\Authorities/CN=IDCG-CA 
1 http://www-itg.lbl.gov/~mrt/Certificates/
2 file:/usr/mrt/Attributes http://idcg-ds.lbl.gov/~krj/Certificates/ 
1800

CapabilityCertificate

A capability certificate contains the rights that a user has with respect to a resource. The Akenti server creates such a certificate the first time it is asked to authorize a user for a resource. It then caches these certificates (along with the certifcates which were used to authorize the rights) so that if is asked to authorize the same user again within a short time, it can do so very quickly. Applications such as Web servers and CORBA applications frequently reference many related resources in the course of one interaction with a user. This capability caching makes it possible for these applications to use Akenti authorization which is otherwise too heavy-weight for frequent authorization requests .The validity period is the minimum of the cache time specified in any of the certifcates that were used to generate it and any cacheTime that was set in the Policy file.

The Capability Certificate is returned by the Akenti policy engine. When it is returned from an Akenti server it may be signed, depending on the settings in the configuration file. This type is defined in the file certs/CapabilityCertificateImpl.hpp . 

CapabilityCertificate {
  string             resource     // resource to which this capability applies
  AkentiPrincipal    principal    // user to whom this capability applies
  PublicKey          publicKey    // publicKey of user to whom the 
                                  //   capability applies
  vector<string>     Actions      // actions that are allowed
  vector<ConditionalActions>  ConditionalActions  
                                  //actions with additional constraints
}
Format CertificateHead<space>resource<space>principal<space>publicKey<space> actionsSize<space>UncondActions*<space> UncondActionsSize<space>CondActions*

CacheCertificate

Cache certificates are only used internally to the Akenti policy engine. Cache certificates hold one X509, UseCondition or Attribute certificate or may hold a capability certificate and all the certificates from which it was derived. These certificates are used only by the Akenti server and its cache manager. Each contained cache certificate has a validity flag that indicates if that certifcate was validiated or not and a latest time for which it is valid. They are created and signed by the Akenti server. This type is defined in the files certs/CacheCertificateImpl.hpp and certs/CertificateHolder.hpp. 
CacheCertificate {
  vector<AKCertHolder> holders;
}
Format CertificateHead<space>CertHolder.size<space>CertHolder+

AkentiX509Certificate

AkentiX509Certificates are only used internally by the Akenti policy engine. This is an AkentiCertificateImpl class containing the SSL X.509 certificate structure. It serves the purpose of presenting a uniform interface for access to X509 identity certificates. It is created by parsing the X509 certficate and saving the most frequently used members into members of the AkentiCertificate. It also saves the entire X509 certficate as a Certificate. This type is defined in the file AkentiX509CertificateImpl.hpp. The Certificate type is defined in shared/security/CertificateImpl.hpp. The following AkentiCertificate members contain information taken from the X509 certificate: The AkentiX509Certificate has the following additional members that are also filled in from the contents of the X509 certificate: 
AkentiX509Certificate{ 
  string           signable      // opaque string containing the base64 encoded
                                 //   DER encoded identity certificate 
 
  AkentiPrincipal  principal     // subject of the Certificate and the issuer(CA)
  int              SerialNumber  // extracted from X.509
  URL              revocationURL // URL to where the CA keeps its revocation list
                                 //   extracted from X.509
  PublicKey        subjectPublicKey;  //    extracted from X.509

  Certificate      cert;         // DER encoded  ASN1 X.509 certiticate

}

This certificate is not written out in this form. The writeObject method writes out the contained X.509 cert.

AKCertHolder

CertificateHolders are held within CacheCertificates and provide the extra information that is needed when deciding whether to use a cached certificate. This element is defined in certs/AKCertHolder.hpp. It is only used internally. 
AKCertHolder{
  AkentiCertificate cert;    // cached certificate 

  int level-verified;        // level at which the cert has been verified
                             //     -1 = did not verify, 0 = not yet
  
  UtcTime notBefore;         // cached cert cannot be used before this time
  UtcTime notAfter;          // cached cert cannot be used after this time
}

Page last modified: Wednesday, 09-Mar-2005 16:52:24 PST Contact: MRThompson@lbl.gov <Akenti development group> Credits:Distributed Security research and development is funded by the U.S. Dept. of Energy, Office of Science, Office of Advanced Scientific Computing Research, Mathematical, Information, and Computational Sciences Division. Privacy and site security notice to Users
Akenti Homepage
DSD Homepage
LBNL Homepage