Stakeholder's Guide to Akenti

Mary Thompson and Srilekha Mudumbai
/home/g1/proj//Akenti/docs/admin/stakeholder.html

Security Hompage Akenti Homepage Documentation Manuals Stakeholder Guide

Introduction

Akenti access control is implemented by as set of policy certificates and distributed use-condition and attribute certificates. These certificates express the conditions that the various stakeholders wish to impose on access to their resources. Stakeholders are identified by entries in the resource's policy certificate (.htauthority). CA information, Attribute, values, attribute issuers, and actions are defined in the resource attribute file (.resattributes). The three certficate types can be created and signed by either of two methods.

Create a correct XML definition of the certificate, have the pem encoded private key of the certificate issuer and use CertGen to generate and sign the certificate.
Use the GUI generator programs: Attribute.sh, UseCondition.sh, and Policy.sh which will interact with the resource definition server and the resattributes file and step you through acceptable options for the certificate.

Exporting your User Identity for use in signing
Command line generation of certificates
Generating a Use Condition Certificate
Generating an Attribute Certificate

1. Export your Identity Certificate

If you are a resource stakeholder and wish to sign Akenti certificates you must have your private key and identity saved in a PKCS12 format file, where the generator programs can use it for signing. If you are using Netscape to handle your identity certificates, you can export any of your certificates as a PKCS12 file by going to the security menu->certificates->Yours, select the identity you want to use, and click export which will create a PKCS12 format file with the extension .p12.The identity you choose, must be listed as a stakeholder in the Authorization file for the resouce that you want to control.

2.Command line generation of certificates

This approach is mainly useful for small test setups where there are not too many certificates to be generated. It has the advantage of not requiring a Resource Definition server to be running or the need for a resattributes file. The disadvantage is any contextual mistakes in the XML description of the certificate will not be caught until you attempt to use the certificate in an authorization. The method is to create an XML description of the certificate following the Akenti Certificate XML DTD . Examples of XML certificates can be found in policy certificate, attribute certificate and use-condition certificate. Then call the CertGen.java program withthe XML file, a PKCS12 file containing the signers private key and the passphrase for the key file. CertGen will create a new unique id, update the notBefore time to the current time, and write a certificate that contains the new XML and a signed base64 encoded version of it. CertGen verifies the XML syntax, but has no way of checking if the content of the certificate is reasonable. After generating a certificate with CertGen it should be verified with verifyAkentiCert. This will check that the certificate is in fact signed by the principal specified in the issurer field, and that the syntax of the Distinguished names is corret and a few other things.

3. Generate and sign a use-condition certificate

Use-condition certificates are signed documents that grant use rights for a named resource. They can be stored anywhere that is accessible by a URL. If you are named as a UseCondGroup Principal for a resource you can create a use-condition by following the steps outlined below. Each window of the generators contain a brief explanation of what it is doing. More details are available by clicking on the "help" buttons on each window. The "back" button on each window will let you go back to review your progress so far or to correct mistakes.

Run the script UseCondition.sh It will present a set of windows to step you through the process of building a use-condition Certificate.
The first window will ask for the name of the resource for which you are creating this use-condition and the location of the Policy Definition server for the resource tree. The resource name is specified as the resource tree name and a name relative to that base. The Policy Defintion server host and port and the resource root name will default to the values in AkentiGen.conf. Normally each Policy Definition server will only support one resource tree and the correct default will be displayed. But if you are unsure, you can use the browse button next to the Base Resource field to show all the roots. If you are unsure of the exact resource name, the browse button next to the relative resource field will cause the generator to go off to the Policy Definition server and get a list of all the resources on that server.
Clicking on "next" will bring up a window that asks for the use-condition issuer and its CA. These names are taken from the policy certificate for the resource. If your name does not appear in the list, you are not authorized to create use-conditions for this resource. In this case you should contact the Akenti resource administrator. At the end of the use-condition creation process, you will be asked for the file that contains the private key for the identity that you chose and the passphrase that was used to encrypt that file. You must select an name from the list, even if there is only one item, and click next.
You are now presented with a series of Expression Builder windows which step you though the creation of a boolean expression of attributes and values that a user must satisfy to use the resource.
The list of attributes is taken from the resource definition file. Select an attribute and click on "next element". If you have selected an attribute that appears in the X.509 identity certificate: cn (common name), ou (organizational unit), or o (organization), the next window will contain a list of acceptable Certificate Authorities (CA's) to verify that attribute. You must select one and then go to next element.
Having selected a CA, the generator will present you will a list of all the values for the atttribute that you have selected that are supported by that CA. You should select one value and click the "add" button.
If you had selected an non-identity attribute, the next window would have given you all the possible values for that attribute, and the final window would have given you a list of allowed attribute issuers and CA's for that attribute. All these values are found in the resource definition file associated with the resource.
Once you have added one term to your boolean expression you can use the AND or OR buttons to repeat the process to add more terms or can go on to the next window by clicking "next".
From the next window you choose the scope and actions of this use-condition. Local means it just applies to the named resource. Sub-tree means it applies to any resources that are hierarchically below this one as well.
The list of possible actions are taken from the resource definition file. If you select the "enable access" button, any user who attempts to access this resource must satisfy this use-condition. If you leave it unselected it grants the selected actions to anyone who satisfies this use-condition, but does not prevent those users who fail this use-condition, but meet other ones from accessing the resource.
You now get to chose the CA(s) that you will trust to verify the User Identity of some one trying to access this resource. Again you are given a list of acceptable CAs.You may choose more than one.
Finally you are give a window that displays what you have done and gives you a change to go back and make changes.
click "next" and you are presented with a window to select the keyfile where your private key is stored, the passphrase with which it is encrypted and where you want to store the signed certificate. You need to store this certificate someplace where it can be accessed via a URL.
After filling in all the fields click "sign and save".
Once the certificate has been signed and saved, the generator will go back to the first window to allow you to generate another certificate. If you are done, click "exit".

Generate and sign an Attribute Certificate

If you have included any attributes in your use-conditions that can are not included in Identity Certificates (ones other than "o","ou" and "cn"), you will need to issue attribute certificates for each person who you want to have that attribute. For example, if you chose group/my_friends, you need to issue an Attribute Certificate for each person you want to be in the group my_friends.

run the script Attribute.sh
The first screen is the same as for the use-condition generator. It needs to know the resource for which this attribute certificate will apply in order to find the valid list of attributes and CAs for the resource.
On the next screen, the left window lists all the attributes currently known to the resource server. Selecting a value here will bring up a list of known values in the right text window.
After you have selected an attribute and value and clicked on "next" you are asked to identify yourself as one of the allowed attribute issuers. As before, if your name does not appear in this list, you will be unable to issue a valid certificate and should contact the resource administator and ask to be added to the policy definition file for the resource.
The next screen lets you choose the user for whom the attribute is being issued.First select the Certificate Authority who will validate the user. This selection will fill in the Country and Organization fields and give a pull-down menu of all the organizational units for which this CA issues certificates. You can then either type in the individual's complete common name or search for the name. The search is case-insensitive and * is the wild-card character.
A window will appear with all the names that matched your search. You should select the one you want and close that window. The selected name will appear in the previous window.
You next select the lifetime of the certificate. There is a pulldown menu to chose a time.
You then see a preview of the certificate that you are generating. At this point you can use the back button to go back and correct any errors. When you go to next, you will see the same sign and save dialog as described above.

Page last modified: Tuesday, 18-Sep-2001 23:30:36 PDT 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