Privilege Based Authorisation API Tutorial

This tutorial is based on the demonstration example. You have to download it and install all the relevant packages (see the list below) in order to be able to run it and to follow this example.
  The following packages must be installed in your system for the PERMIS classes to be operational. You do not need to download anything extra for the example application, because it contains all the necessary packages going with it.

Refer to the Java manual on details of the usual package installation procedure. Here is just a short guideline.

You can install the packages by either:

• move the .JAR file into the jre/lib/ext/ directory of your Java Runtime Environment installation directory
• update the CLASSPATH variable in your system to contain the directory with the .JAR file of the package
• update the manifest file of your own application package to have the Class-path set pointing to all the necessary .JAR files

Mandatory packages:

• JNDI (Sun; http://java.sun.com)
Note that this package is supplied with some versions of the JRE
• XALAN (Apache; http://xml.apache.org)
• PBA API (ISSRG; http://sec.cs.kent.ac.uk/permis/downloads/Level2/decisionEngine.shtml)
• The demonstration example can be found here
Note that it contains all the above packages licensed for educational and research use, and you do not need to install them for running the example.

1. Playing with It

The program will ask you to input your DN (it does not authenticate your identity in any way, it is just a demo with no authentication), and the target DN (target name you want to access) and the name of the action you want to perform. After you have input the names, it will tell you if the action is allowed or denied, or will report any errors it encounters.  Then it will repeat asking the user DN, target DN and the action name in loop remembering your last input (just press Enter to confirm the last value), until you input “.” as the user DN. In this way you can test various combinations of the users, targets they are trying to access and the actions they are attempting to perform. The policy for this test program is shown in the table below:
 
 

2. Changing the Rules

You can see that the OID of the policy is “1.2.826.0.1.3344810.6.0.0.3”. Don’t forget to change it when you decide to change the policy.

The Policy specifies one Subject domain with DN O=PERMIS,C=GB. It defines two roles of type permisRole, and which are not hierarchically connected: Role0 and Role1. It defines only one SOA: CN=SOA 1,O=PERMIS,C=GB. This is the only entity that is allowed to assign roles to users, and we see this statement in the Role Assignment Policy: the SOA can assign any role to any user from the specified domain.

The Policy also defines one Target domain with DN O=PERMIS,C=GB. There are three actions known: Action0, Action1 and Action3.

There are three target access statements that bind the permissions to the Roles.  Thus it is allowed for a holder of Role0 to perform Action0 on any target, a holder of Role1 is allowed to invoke Action1 on any target, and anyone is allowed to call Action3 on any target. Note that the last statement concerns only those users that match the previously defined Subject domain.

If you inspect the users’ ACs, you will notice CN=User0,O=PERMIS,C=GB has been allocated Role0 and CN=User1,O=PERMIS,C=GB has been allocated Role1. These allocations define their privileges at run time.

Now try creating new ACs with roles in them, edit existing ACs, etc. It does not matter what signature you put there, the sample code does not verify it. Note that the new version of our Default Signing Utility for the Privilege Allocator now lets you input the Issuer DN (previous versions would not let you do that, which meant that by default you could not create ACs that were understood by this sample code). Of course, if you have already got the signing utility, you can just sign the ACs (but remember to change the SOA name in the policy to your signing DN).
 

3. Connecting Your LDAP Directory

Example. Initialising Hashtables for multiple LDAP servers.

java.util.Hashtable [] ldaps = new java.util.Hashtable[howManyLDAPsYouHaveGot];

java.util.Hashtable env = new java.util.Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://146.87.80.18:389/");
      // put your own URL there
env.put("java.naming.ldap.version", "3");
      // change the version, if you are not running v3 LDAP server
env.put("java.naming.ldap.attributes.binary", ATTRIBUTE_CERTIFICATE_ATTRIBUTE_NAME);
     // otherwise it may sometimes retrieve it as a String

ldaps[0] = env;

env = new java.util.Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://146.87.80.18:17999/");
env.put(Context.SECURITY_PRINCIPAL, "cn=DSA Manager,c=GB");
env.put(Context.SECURITY_CREDENTIALS, "cutePassword");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put("java.naming.ldap.version", "3");
env.put("java.naming.ldap.attributes.binary", ATTRIBUTE_CERTIFICATE_ATTRIBUTE_NAME);

ldaps[1] = env;

...

PBAAPI pbaApi = new PermisRBAC(policyOID, soaDN, signatureVerifier, ldaps);

Now, before running your updated sample AEF, ensure the ACs are put in the proper entries of the LDAP directory (for example by using the Privilege Allocator). As soon as you place user certificates and the Policy AC in the directory, they will be picked up by the sample AEF.

Play with the program and see that it returns the same replies. The only difference you may notice is replies for users with non-existing entries. The sample AEF will say “cannot get credentials”, because it cannot handle LDAP errors yet.
 

4. Attaching Your PKI

The object should return true only if the signature has been verified fine and a trust relationship has been established between the root of trust of the PKI and the signer. In all other cases it may either return false or throw a PkiException, depending on the circumstances and the design of the SignatureVerifier implementation.

Example. Embedding a SignatureVerifier.

SignatureVerifier pki = new SignatureVerifierUsingMyPKI(...);

...

// configure your signature verifier here
...
PBAAPI pbaApi = new PermisRBAC(policyOID, soaDN, pki, ldaps);
 

A nonfatal internal JIT (3.10.107(x)) error 'Relocation error: NULL relocation t
arget' 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.cg
i