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:

Mandatory packages:

The PERMIS classes should work under all versions of Java2. It has been tested under JDK1.2.2 and JDK1.3. Note however, that the Entrust code cannot operate under JRE1.4 properly, so if you are a user of the Entrust PKI you should install a run-time environment of versions lower than 1.4.

1. Playing with It

Now you can run this example and see the simplest possible user interface to an authorisation gateway. Sometimes the Apache XML parser outputs a non-fatal error (see sample message here), but this is a debugging information for the Apache developers. The mentioned error does not affect security of decision-making.

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:

User DN
Target DN
Action name
(case sensitive)
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

2. Changing the Rules

The demo picks up the Policy and the users’ ACs as specified in the configuration file, which you can observe in the directory where you have installed the demo: sample1.cfg. You can notice that the configuration file specifies the DN of the SOA, the OID of the policy and a set of ACs that are located in 1/ subdirectory.  If you go to that directory, you will see several Attribute Certificate files (.ace) and an XML file. The XML is the policy in force, but it is purely illustrative here, since the actual policy is taken from the Policy AC (policy1.ace). This XML is just for you to study the policy and update it when you decide to change the Policy AC.

You can see that the OID of the policy is “1.2.826.0.1.3344810.”. 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

Now you will have to update the code of the sample AEF to let it access your LDAP Directory. The example below shows an approximate code for configuring access to a multiple-root LDAP repository.

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://");
      // 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://");
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);

The last line of the example initialises the authorisation object in the same way, as it does in the sample code, only that instead of the VirtualRepository object filled in with ACs read in from files, it uses an LDAP repository (an array of parameters for them).

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

In terms of current PBA API design, you need to provide a working SignatureVerifier (Entrust users will be provided with our EntrustSignatureVerifier - download the necesary Entrust classes, licensed for educational and research use). The purpose of the object is to verify the signature on an arbitrary byte array. Our authorisation object will pass a BER encoded Attribute Certificate (the part that is signed), the byte array of the signature, the Algorithm Identifier as a string, and the identity of the signer. The SignatureVerifier implementation will have to retrieve PKCs relevant to trust establishment, verify their revocation status, if supported, and do all cryptographic operations needed to verify the signature.

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);

You can see now that it is pretty easy to enable PermisRBAC to use any PKI you have available.

The sample non-fatal error Apache XML parser displays when loading the PERMIS RBAC policy.
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

Created on 14 May 2002 by Alexander Otenko.
ISSRG, University of Salford