PERMIS Java API Cookbook

 Authors: Sassa Otenko, David Chadwick, Edward Thornton

Contents

 

Tables and Figures

Release Number

Date

Comments

1.0

23 December 2002

Initial public release

1.01

21 August 2003

Minor editorial corrections

1.02

20 February 2004

Minor editorial corrections

1.1

11 August 2008

Using the o=PERMISv5,c=gb entry in the Kent LDAP

Introduction

This cookbook provides a step-by-step example for using the PERMIS Java API authorisation infrastructure.  On completion of this tutorial, you will be able to:

  • Install/setup all necessary components for using the PERMIS API.
  • Run example code of the PERMIS API on a pre-configured LDAP directory server based at Salford University.
  • Configure an LDAP directory server of your own to run the PERMIS API examples.
  • Understand how to use the PERMIS API for authorisation in applications of your own.

Downloads/Packages

Mandatory

To run the example PERMIS gatekeeper application it is only necessary to download the Cookbook example:

  • Cookbook Example – the example software used in this cookbook. http://sec.cs.kent.ac.uk/permis/private/pba_sample.zip
  • Java Runtime Environment (JRE) – needed to run the PERMIS software.  Please note, if you wish to modify the software, you will need the Java SDK.

http://java.sun.com

To develop your own application using the PERMIS API it is necessary to download and install the following packages:

  • Java SDK – needed to run and modify the software.  Note that Java SDK also includes JRE.

http://java.sun.com

  • Java Naming and Directory Interface (JNDI) API – used to connect to LDAP directories.  This may not be necessary depending on which version of the JRE you are using, as JNDI is included in newer versions of the JRE.  http://java.sun.com/jndi
  • XALAN Java 2 – used for the XML policies in the PERMIS API.  http://xml.apache.org/
  • IAIK JCE – used for parsing Attribute Certificates and as a cryptography provider – you do not need this installation, if you have installed Privilege Allocator and made the IAIK JCE, contained in it, available on the CLASSPATH (or in the <java home>/jre/lib/ext directory).

http://www.iaik.at/

  • PBA API – the PERMIS software.  http://sec.cs.kent.ac.uk/permis/private/pba/pba1_2.jar  (check for the latest version available! See http://sec.isi.salford.ac.uk/permis/private/wip.html)
  • PERMIS LDIF file – LDAP Data Interchange Formatted file, containing entries for loading into your LDAP server.

http://sec.cs.kent.ac.uk/permis/private/ldif.zip

You will also require your own LDAP Directory Server in order to perform later parts of this cookbook that involve using an LDAP Directory Server.

Optional

·        WinZip – if using Microsoft Windows you may need to download WinZip to extract the files.  Evaluation version available from: http://www.winzip.com

·        Entrust Signature Verifier – used to verify digital signatures on BER encoded Attribute Certificates – only if you are going to use Entrust PKI in the future

http://sec.cs.kent.ac.uk/permis/private/entrust.zip

Installation

1.      Run the Java installation program.

2.      If a separate download for JNDI was necessary, move the .jar file to <Java installation directory>/jre/lib/ext/

3.      Extract files from Xalan download to <Java installation directory>/jre/lib/ext/

4.      Extract files from Cookbook download to <Java installation directory>/jre/lib/ext/

5.      Extract files Entrust download to a temporary folder on your computer.  Then open this folder and move all files into <Java installation directory>/jre/lib/ext/sampleaef/include/.

 

After performing installation steps 1-5, your ext directory should look as below:

 screen shot 1

Screenshot 1 – Extracted Files Following Installation

 

Step 1 – Running The Example Program

You should now be ready to run the example program.  The example program should be run from the following directory in the command prompt:

 

<Java installation directory>/jre/lib/ext/sampleaef/

 

Once in this directory, execute sample1.bat.  This will invoke the JRE to run the program.  You are now ready to begin using the policy for the test program, detailed in table 1 below:

 

Table 1 – Policy For Test Program

User DN

Target DN

Action name
(case sensitive)

Result

cn=user0,o=permis,c=gb

Any DN from the o=PERMIS,c=GB domain

Action0

0: action succeeded

cn=user0,o=permis,c=gb

Any DN from the o=PERMIS,c=GB domain

Action1

1: the action is not allowed

cn=user1,o=permis,c=gb

Any DN from the o=PERMIS,c=GB domain

Action0

1: the action is not allowed 

cn=user1,o=permis,c=gb

Any DN from the o=PERMIS,c=GB domain

Action1

0: action succeeded

Any other DN from the o=PERMIS,c=GB domain (none of the above)

Any DN from the o=PERMIS,c=GB domain

Action0 or Action1

1: the action is not allowed

Any DN from the o=PERMIS,c=GB domain

Any DN from the o=PERMIS,c=GB domain

Action2

2: invalid input: Unacceptable Action for this Policy: Action2

Any DN from the o=PERMIS,c=GB domain

Any DN from the o=PERMIS,c=GB domain

Action3

0: action succeeded

Any DN from the o=PERMIS,c=GB domain

Any DN out of the o=PERMIS,c=GB domain

Any action

2: invalid input: Target is out of target domain

Any DN out of the o=PERMIS,c=GB domain

Any DN

Any action

2: invalid input: Failed to get credentials

 
The program first asks if you want to use an LDAP repository – ignore this for now and simply press return.  The program then requests whether you wish to use Entrust signature verification – again, ignore this for now and press return.  The program will ask you to input your DN, and the target DN (target name you want to access) and the name of the action you want to perform. After you have input appropriate names from Table 1 above, PERMIS will tell you if the action is allowed or denied, or will report any errors encountered.  The program will repeat this process, until “. is input as the user DN.  Using the entries in Table 1 (above), you can test different combinations of users, targets they are trying to access and the actions they are attempting to perform.

 

For example, if you input the first entry from the policy (in table 1):

User DN: cn=User0,o=permis,c=gb

Target DN: o=permis,c=gb

Action : Action0

 

You should see the result ‘0: Action succeeded, as shown in the screenshot below.  However if you input the second entry from the policy (in table 1) - the same as before, but this time with ‘Action: Action1, you should now see the result ‘1: the action is not allowed.

screen shot 2

Screenshot 2 – Testing A Policy In The Example Program

 

NOTE:  Sometimes the Apache XML parser outputs a non-fatal error (see sample message), but this is debugging information for the Apache developers. The mentioned error does not affect the security of the decision-making, and the error is shown in Appendix A.

 

You have now validated that the PERMIS API runs on your computer.

 

Step 2 – Using The Kent LDAP Directory

Now we will run the program again, this time use the example LDAP directory running at the University of Salford.  If you open ‘sample1.cfg’ located in <Java installation directory>/jre/lib/ext/sampleaef/ you will see the third line contains:

 

LDAP=ldap://sec.cs.kent.ac.uk/

 

This is the URL of the example directory we will be using.  Run ‘Sample1.bat’ again, and this time, when asked if you want to use this LDAP repository, type ‘l and press return.  Again, ignore signature verification for now, and press return.  Using the entries of the policy in Table 1, you can test the program again, this time running against the directory at the University of Kent.  An example of this can be seen in the screenshot below:

screen shot 3

Screenshot 3 – Testing A Policy Using The Kent LDAP Directory

 

You have now validated that the PERMIS API can talk to LDAP servers on the Internet.

 

 

Step 3 - Setting Up Your Own LDAP Directory

Modifying The Directory Schema

Now you must modify the schema of your LDAP directory.  This example assumes you already have a standard LDAP directory installed and configured, and we provide screenshot examples from iPlanet/SunONE Directory Server 5.1.  Please note that other LDAP server(s) could have been used, for example OpenLDAP, and the screenshots are purely for illustration.

 

We will first add the attribute ‘attributeCertificateAttribute, which will be added to the pmiUser objectClass that we will define after.  This attribute needs the following:

·        Name: attributeCertificateAttribute

·        OID (object identifier): 2.5.4.58

·        Syntax: Binary

screen shot 4

Screenshot 4 – Adding ‘attributeCertificateAttribute attribute to the schema

 

The X.509 standard defines 'attributeCertificateAttribute as shown below:

 

attributetype (2.5.4.58 NAME 'attributeCertificateAttribute'
DESC 'A binary attribute certificate'
EQUALITY octetStringMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.8
)

 

After creating the attribute ‘attributeCertificateAttribute we are now ready to create the objectClass pmiUser.  The pmiUser objectClass needs the following:

·        Name: pmiUser

·        OID (object identifier): 2.5.6.24

·        Parent: top

·        Required Attributes: - (NONE)

·        Optional Attributes: attributeCertificateAttribute

 

 screen shot 5

Screenshot 5 – Adding ‘pmiUser objectClass to the schema 

The X.509 standard defines 'pmiUser' as shown below:



objectclass (2.5.6.24 NAME 'pmiUser'
SUP top
DESC 'a pmi entity that can contain X509 ACs'
MAY (attributeCertificateAttribute)
)

 

Importing Entries Into Your Directory From LDIF

You now need to import the entries from the PERMIS LDIF file (http://sec.cs.kent.ac.uk/permis/private/ldif.zip).  This will insert all of the entries you need to run the program, each containing one or more of it’s own attributeCertificateAttribute(s).

 

Modifying The Sample Program For Your Directory

Now you should open ‘sample1.cfg’ again (located in <Java installation directory>/jre/lib/ext/sampleaef/) and this time, you should change the details of the LDAP server to fit your own.  Replace the following line:

 

LDAP=ldap://sec.cs.kent.ac.uk/

 

With the details of your own LDAP server, for example:

 

LDAP=ldap://146.87.01.01/

 

NOTE: The schema of the OpenLDAP directory server running at Salford University is slightly different from the schema you will set up for your own LDAP server.  The X.509 standard describes the object with and OID of 2.5.4.58 as attributeCertificateAttribute, however the Entrust i500 Server schema had a different name for the same OID – AttributeCertificate.  To be conformant with Entrust i500 Server, the schema of the OpenLDAP server here at Salford University has been updated to reflect this.  The difference is you should set 2.5.4.58 to attributeCertificateAttribute, but the test server has 2.5.4.58 set to attributeCertificate.  For this reason, you will also need to change the line:

 

LDAP_AC_attribute=attributeCertificate;binary

 

To:

 

LDAP_AC_attribute=attributeCertificateAttribute;binary

 

Now save the changes in the file, close it and run ‘sample1.bat’ once again.  Now you will be able to see the sample program using Attribute Certificates from your own LDAP server.

 

You have now validated that your local LDAP server is capable of storing PMI attributes and object classes.

size=2 width="100%" align=center>

 

Step 4 – Attaching Your PKI

We will now use Entrust Signature Verification to verify the signatures of the attribute certificates.  Please note that as well as using the Entrust classes, you also have the option to add your own signatureVerifier classes to PERMIS.  To implement this please refer to http://sec.cs.kent.ac.uk/download/doc.zip for the Java docs (online version available at http://sec.cs.kent.ac.uk/permis/doc/).

 

For now, we will use Entrust Signature Verifier.  Run ‘sample1.bat’ again, and this time when prompted, type ‘e to use Entrust Signature Verification.  Now each time the program acquires Attribute Certificates (from whatever source) the signature will be verified.  To see the effect of signature verification now you can try to perform Action0 by User0.  This will fail because ‘sample1.cfg’ contains a reference to an unsigned attribute certificate:

 

AC=1\user0_unsigned.ace

 

Due to this, the certificate is discarded and the user is denied access.  To allow access for User0, replace the above line with:

 

AC=1\user0.ace

 

Which refers to the same attribute certificate, but signed by the correct attribute authority.  The Salford LDAP directory contains the signed Attribute Certificate.

 

You have now validated that your signatureVerifier object is capable of validating digitally signed attribute certificates.

size=2 width="100%" align=center>

Step 5 – Replace The Test Program With Your Own Application

You should now be ready to begin using the PERMIS authorisation engine within programs of your own.  To do this, you might find ‘SampleAEF1.java’ (located in ‘<Java installation directory>/lib/ext/sampleaef/src/issrg/aef/SampleAEF.java) helpful.  If you have any further queries regarding PERMIS, please contact either:

 

Prof. David Chadwick @ d.w.Chadwick@kent.ac.uk

or

Alexander Otenko @ o.otenko@kent.ac.uk

 

You are now well on the way to having a policy based authorisation system for your application using the PERMIS API.

size=2 width="100%" align=center>

 

 

Appendix A – Apache XML parser non-fatal error

A non-fatal error may occur in the Apache XML parser when loading the PERMIS RBAC policy.   The error is displayed below:

 

A nonfatal internal JIT (3.10.107(x)) error 'Relocation error: NULL relocation target' has occurred in :

  'org/apache/crimson/parser/Parser2.maybeComment (Z)Z': Interpreting method.

  Please report this error in detail to http://java.sun.com/cgi-bin/bugreport.cgi