Stakeholder's Guide to Akenti
Mary Thompson and Srilekha Mudumbai
/home/g1/proj//Akenti/docs/admin/stakeholder.html
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.
Table of Contents
- 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.