Generic AAA Toolkits (GAAA-TK) Pluggable library ------------------------------------------------------------------ Version 0.1, 8 May 2008 1. GAAA-TK general structure Described in details in a separate document. Major functional package is GAAAPI (Generic AAA programming interface) that accepts calls for service request evaluation against AuthZ policy. 2. Major GAAAPI Components Described in details in a separate document. - PEP (POlicy Enforcement Point) - PDP (POlicy Decision Point) - TVS (Token Validation Service) 2.1. GAAAPI PEP Interfaces PEP-GAAAPI interface provides a few commands/methods to request policy based AuthZ decision depending on the set of provided information: a) Method #1 should either return a logical value "True" or "False", or throw the appropriate exception Boolean authorizeAction (String resourceId, String actions, HashMap subjmap) throws java.lang.Exception, org.aaaarch.gaaapi.NotAuthenticatedException, /* user subjconfdata (i.e. authenticationToken) is not valid */ org.aaaarch.gaaapi.NotAvailablePDPException; /* PEP could not reach PDP, or other internal error*/ where @ resourceId – Resource ID @ actions – requested actions (currently only one action) @ {subject} set of values (subjectId, subjconfdata, role, subjctx) @ subjectId - subject ID, can be null as it is not used in AuthZ @ subjconfdata - AuthN token, can be null as it is not used in policy evaluation @ role - role for the particular request @ subjctx - subject context, e.g. VO, VLab or Experiment in which role is defined b) Method #2 should either return a logical value "True" or "False", or throw the appropriate exception Boolean authorizeAction (String resourceId, String actions, String subjectId, String subjconfdata, String roles, String subjctx) throws java.lang.Exception, org.aaaarch.gaaapi.NotAuthenticatedException, /* user subjconfdata (i.e. authenticationToken) is not valid */ org.aaaarch.gaaapi.NotAvailablePDPException; /* PEP could not reach PDP, or other internal error*/ c) Method #3 should either return a valid AuthorisationTicket (or AuthorisationToken), or throw the appropriate exception String authorizeAction(String authzTicketToken, String sessionId, String resourceId, String actions) throws java.lang.Exception, org.aaaarch.gaaapi.NotAuthenticatedException, /* user subjconfdata (i.e. authenticationToken) is not valid */ org.aaaarch.gaaapi.NotAuthorizedException, /* user is not allowed to perform requested action */ org.aaaarch.gaaapi.NotAvailablePDPException; /* PEP could not reach PDP, or other internal error*/ were @ authzTicketToken – AuthZ ticket or token containing all necessary AuthZ session context @ sessionId – Session ID that can be also a Global or Local reservation ID (LRI/GRI) d) Method #4 should either return a valid AuthorisationTicket (or AuthorisationToken), or throw the appropriate exception String authorizeAction (String authzTicketToken, String sessionId, String resourceId, String actions, HashMap subjmap) throws java.lang.Exception, org.aaaarch.gaaapi.NotAuthenticatedException, /* user subjconfdata (i.e. authenticationToken) is not valid */ org.aaaarch.gaaapi.NotAuthorizedException, /* user is not allowed to perform requested action */ org.aaaarch.gaaapi.NotAvailablePDPException; /* PEP could not reach PDP, or other internal error*/ 3. Test classes and calling code examples The library contains few packages/classes designed for testing and debugging different functional components and to provide example how to work with GAAAPI/GAAA-TK library. TestGAAAPI - demonstrate operation and provides tests for different GAAAPI components and functions. TestTVS - demonstrate operation and provides tests for different TVS components and functions. 3.1. Calling GAAAPI-PEP functions 1) Prerparing input/test data //String subjectId = "WHO740@users.testbed.ist-phosphorus.eu"; //String subjconfdata = "2SeDFGVHYTY83ZXxEdsweOP8Iok"; //String roles = "researcher"; //String roles = "admin"; //String subjctx = "demo001"; HashMap subjmap = SubjectSet.getSubjSetTest(); // extracting subject attrs from the subjmap String subjectId = subjmap.get(ConstantsNS.SUBJECT_SUBJECT_ID).toString(); String subjconfdata = subjmap.get(ConstantsNS.SUBJECT_CONFDATA).toString(); String roles = subjmap.get(ConstantsNS.SUBJECT_ROLE).toString(); String subjctx = subjmap.get(ConstantsNS.SUBJECT_CONTEXT).toString(); String griprefix = "nsp-domain.uob"; String sessionId = GRIgenerator.generateGRI(32, griprefix); String resourceId = "http://testbed.ist-phosphorus.eu/resource-type/nsp"; String actions = ActionSet.NSP_CREATE_PATH; 2) Calling Methods #1 and #2 returning boolean AuthZ decision // Actual call PEP method#1 boolean decision = PEP.authorizeAction (resourceId, actions, subjmap); // Actual call PEP method#2 boolean decision = PEP.authorizeAction (resourceId, actions, subjectId, subjconfdata, roles, subjctx); 3) Calling Methods #3 and #4 that accept and return AuthZ ticket or token String azticket = PEP.authorizeAction ( (AzTicketToken or null), sessionId, resourceId, actions, subjmap); String authorizeAction(String authzTicketToken, String sessionId, String resourceId, String actions) 3.2. Calling TVS functions 1) Generating binary token To request token generation from the calling application, use these commands/methods: byte[]org.aaaarch.gaaapi.tvs.TokenKey.generateTokenKey(String gri) throws Exception byte[]org.aaaarch.gaaapi.tvs.TokenBuilder.getToken(String gri, byte[] tokenkey) throws Exception Example: byte[] tokenkey = org.aaaarch.gaaapi.tvs.TokenKey.generateTokenKey(gri); byte[] token = org.aaaarch.gaaapi.tvs.TokenBuilder.getToken(gri, null); Note: GRI can be generated using TVS package as well: String gri = "".concat(org.aaaarch.gaaapi.common.IDgenerator.generateID(20).toString()); 2) Generating XML token To request XML token generation from the calling application, use these commands/methods: byte[] org.aaaarch.gaaapi.tvs.TokenKey.generateTokenKey(String gri) throws Exception -- optionally public static String org.aaaarch.gaaapi.tvs.TokenBuilder.getXMLToken(String gri, byte[] tokenKey) throws Exception Example: String tokenxml = org.aaaarch.gaaapi.tvs.TokenBuilder.getXMLToken(gri, null); 3) Validating binary token To verify binary token, use these commands/methods: boolean validateToken (String token, String gri, byte[] tokenKey) throws Exception Example: boolean valid = org.aaaarch.gaaapi.tvs.TVS.validateToken (token, gri, null); 4) Validating XML token To verify XMLtoken, use these command/methods: boolean validateXMLToken (Document aztdoc, byte[] tokenKey) throws Exception, MalformedTokenException, NotValidAuthzTokenException boolean validateXMLToken (String authzToken, byte[] tokenKey) throws Exception, MalformedTokenException, NotValidAuthzTokenException Example: TvsXMLTokenType token = new org.aaaarch.gaaapi.tvs.TvsXMLTokenType (tokendoc); boolean timevalid = token.isTimeValid(token); 4. XACML Policy generator – XACMLPolicyMaker XACMLPolicyMaker uses the same policy generation conventions by using Access Control Table (ACT) and produce policy in the XACML format. Example ACT for simple NSP AuthZ policy Roles Admin Researcher Professor Student Create-Path 1 1 0 0 Activate-Path 1 1 1 0 Cancel 1 1 0 0 Access 0 1 1 1 5. Required libraries List of required libraries is provided below (can also be found in .classpath file of the Eclipse project snapshot) NOTE: DUe to used advanced cryptography functions, GAAA-TK library requires Java SE 6. gaaapi-nrp-v01-20080508.jar xmlsecSamples.jar dom3-xercesImpl-2.5.0.jar dom3-xml-apis-2.5.0.jar jaxrpc-sec.jar jaxrpc-1_1-fr-spec-api.jar soapprocessor.jar saaj-api.jar saaj-impl.jar bcprov-jdk15-130.jar xmldsig.jar xmlsec-1.4.1.jar commons-codec-1.3.jar joda-time-1.4.jar log4j-1.2.8.jar commons-logging-api.jar commons-logging-1.0.3.jar junit-3.8.1.jar XACML and SAML related libraries sunxacml-1.2.jar opensaml-1.1.jar opensaml-2.0-TP1-jdk-1.5.jar openws-1.0-alpha1-jdk-1.5.jar xmltooling-1.0-TP1-jdk-1.5.jar Libraries to be placed into endorsed direcroty (xalan 2.7 and xerces 2.5; Note: newer versions are incompatible with SunXACML) resolver.jar xalan-2.6.jar xercesImpl.jar xml-apis.jar xmlParserAPIs.jar xercesSamples.jar Library to support IBC (Identity Based Cryptography) IdentityBasedEncryptionJCA.1.0.38.jar jakarta-regexp-1.4.jar bcel-head.jar FieldTracker.jar Nuimcscg package for IBC tender-dev.jar ArtimaSuiteRunnerAntTask.1.1.3.jar blitz-dev.jar fault-dev.jar Artima package for IBC suiterunner-1.0beta6.jar -------------------------------------- 6. Setup and required directories 6.1. Required directories structure LOCAL_DIR_ROOT = "" - GAAAPI installation directory LOCAL_DIR_SECURITYCONFIG = LOCAL_DIR_ROOT + "data/config/"; LOCAL_DIR_KEYSTORE = LOCAL_DIR_ROOT + "etc/security/keystore/"; LOCAL_DIR_KEYSTORE_TRUSTED = LOCAL_DIR_KEYSTORE + "trusted/"; LOCAL_DIR_SYMKEYSTORE = LOCAL_DIR_KEYSTORE + "cnlsec/symkeystore/"; LOCAL_DIR_KEYSTORE_IBC = LOCAL_DIR_KEYSTORE + "ibc/"; LOCAL_DIR_POLICY = LOCAL_DIR_ROOT + "data/policy/"; LOCAL_DIR_SCHEMAS = LOCAL_DIR_ROOT + "data/schemas/"; LOCAL_DIR_AAADATA_CACHE_AZTICKETS = LOCAL_DIR_ROOT + "_aaadata/cache/aztickets/"; LOCAL_DIR_AAADATA_TMP = LOCAL_DIR_ROOT + "_aaadata/tmp/"; +-- data | +-- config | +-- docs | +-- policy | +-- schemass | +-- sql +-- +-- wsdl +-- etc | +-- security | +-- keystore | +-- ibc | +-- trusted | +-- xmlsec | +-- symkeystore +-- tvs-lib | +-- endorsed +-- x-output +-- _aaadata +-- cache | +-- aztickets +-- tmp 6.2. Setup All required directories and keys are supplied as part of Eclipse poorject snapshot. To install in Eclipse (version 3.2+) - just unpack and add as a standard Eclipse project To get all required directories structure, unzip project archive and copy directories to location where the library will be used. 7. Special suggestions for NSP Demo system Simple V0.1 implementation allows to evaluate request to NSP system for actions "create-path, activate-path, cancel, access" from a user with attributes "admin, researcher, professor, student" Simple XACML policy for this is provided. 8. Running examples The following test classes provides interactive interface for running examples and testing/debugging all system. #java testTestAuthoriseAction testTestAuthoriseAction runs test with the preset AuthZ request attributes and echoes interaction between all GAAAPI modules. #java testPEPapi testPEPapi class provides interactive tool for testing and debugging GAAAPI at the stage of debugging policy and linking PEP to application. testPDP interface provides a possibility to select one of options: 0 - test PEP/PDP local; 1 - test Send to remote PDP/GAAA; 2 - interactive test PEP/PDP; 3 - interactive test Send to remote PDP/GAAA). In interactive mode user/admin can enter list of values/attributes for the Request message [userId, jobId, role, resourceId, actionId]. There is also a possibility to use external Request message file. ======================================================================== Appendix A - XACML Policy example ======================================================================== Permit actions for Phosphorus testbed users with specific roles http://testbed.ist-phosphorus.eu/resource-type/nsp create-path admin researcher professor activate-path researcher professor cancel admin access admin professor researcher student ======================================================================== Appendix B - Printout of GAAAPI test cases ======================================================================== GAAAPI test cases printouts: Test 0 - test GAAAPI: Simple test PEP & TestPDPlocal (hard-coded policy); ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Running test for PEP/PDP Authorisation components Options (12 - view security configuration): 0 - test GAAAPI: Simple test PEP & TestPDPlocal (hard-coded policy); 1 - test GAAAPI: Test PDPXACML & booleanPEP; 2 - test GAAAPI: Test PDPXACML & azticktokPEP; 3 - test GAAAPI: Test PDPXACML & azticktokPEP(ticket) & PEP-Triage; 4 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 5 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 6 - interactive test generate Request; 0 Generated Sun XACML RequestCtx: SeDFGVHYTY83ZXxEdsweOP8Iok JobID-XPS1-212 analyst WHO740@users.collaboratory.nl http://resources.collaboratory.nl/Phillips_XPS1 ControlInstrument null PDPinputParser.parseXACMLRequest: parsing in progress Subject subjconfdata = SeDFGVHYTY83ZXxEdsweOP8Iok Subject subjctx = JobID-XPS1-212 Subject role = analyst Subject subjectId = WHO740@users.collaboratory.nl Action number 1 ControlInstrument PDP.runRBE(vector) input context: PDP Request received from user "WHO740@users.collaboratory.nl" with role(s) "analyst" to perform action(s) "ControlInstrument" in experiment "JobID-XPS1-212" on instrument "http://resources.collaboratory.nl/Phillips_XPS1" Using hard-coded policy implementing access control table: ------------------*---------*----------*-------*-------- Action - Role | analyst | customer | guest | admin ------------------*---------*----------*-------*-------- ControlExperiment * 1 0 0 0 ControlInstrument * 1 0 0 1 ViewExperiment * 1 1 1 0 ViewArchive * 1 1 0 1 AdminTask * 0 0 0 1 StartSession * 1 0 0 0 JoinSession * 1 1 1 0 ------------------*---------*----------*-------*-------- Action cost = 100 EUR; Credit limit = 120 EUR Access control in progress... TestPDPlocal.runRBE(Request) Decision = Permit Policy/Action obligations: Action: ControlInstrument; cost = 100 EUR Checking credit... Credit is OK: 1000 EUR (just for test purposes) New credit: 900 EUR Test 1 - test GAAAPI: Test PDPXACML & booleanPEP; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Running test for PEP/PDP Authorisation components Options (12 - view security configuration): 0 - test GAAAPI: Simple test PEP & TestPDPlocal (hard-coded policy); 1 - test GAAAPI: Test PDPXACML & booleanPEP; 2 - test GAAAPI: Test PDPXACML & azticktokPEP; 3 - test GAAAPI: Test PDPXACML & azticktokPEP(ticket) & PEP-Triage; 4 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 5 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 6 - interactive test generate Request; 1 Policy resolved (static, test): data/policy/nsp-policy-demo001.xml PDP Request (XACMLPDPsimple.requestPDP): WHO740@users.testbed.ist-phosphorus.eu demo001 IGhA11vwa8bUktYhuU9que+d4XLUvJFHrtDC/OE3Ui1bxtmuCxLldw== researcher http://testbed.ist-phosphorus.eu/resource-type/nsp create-path null Tracking echo (requestPDP): bijna pdp.evaluate(request) PDP Response: not null PDP Response: Permit PEPinputParser.parsePDPResponse: parsing in progress PEPinputParser: This PDPResponse is not empty PEP Response message Parser Echo: PDP Response contains decision "Permit" for resource ResourceID="http://testbed.ist-phosphorus.eu/resource-type/nsp" Status message: "null" Test GAAAPI TestPDPlocal: PDP decision is "Permit" Test 2 - test GAAAPI: Test PDPXACML & azticktokPEP; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Running test for PEP/PDP Authorisation components Options (12 - view security configuration): 0 - test GAAAPI: Simple test PEP & TestPDPlocal (hard-coded policy); 1 - test GAAAPI: Test PDPXACML & booleanPEP; 2 - test GAAAPI: Test PDPXACML & azticktokPEP; 3 - test GAAAPI: Test PDPXACML & azticktokPEP(ticket) & PEP-Triage; 4 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 5 - test GAAAPI: Test PDPXACML & azticktokPEP(token) & PEP-Triage; 6 - interactive test generate Request; 2 PDP Request (XACMLPDPsimple.requestPDP): WHO740@users.testbed.ist-phosphorus.eu demo001 IGhA11vwa8bUktYhuU9que+d4XLUvJFHrtDC/OE3Ui1bxtmuCxLldw== researcher http://testbed.ist-phosphorus.eu/resource-type/nsp create-path null Tracking echo (requestPDP): bijna pdp.evaluate(request) PDP Response: not null PDP Response: Permit PEPinputParser.parsePDPResponse: parsing in progress PEPinputParser: This PDPResponse is not empty PEP Response message Parser Echo: PDP Response contains decision "Permit" for resource ResourceID="http://testbed.ist-phosphorus.eu/resource-type/nsp" Status message: "null" log4j:WARN No appenders could be found for logger (org.apache.xml.security.Init). log4j:WARN Please initialize the log4j system properly. Wrote AuthzTicket doc to azticket-simple.xml Ticket doc is signed and saved in file:/D:/deveclipse/phosphorus-wp4-aaa/azticket-signed.xml TestGAAAPI TestPDPlocal: AuthzTicket returned: Permit WHO740@users.testbed.ist-phosphorus.euIGhA11vwa8bUktYhuU9que+d4XLUvJFHrtDC/OE3Ui1bxtmuCxLldw==researcherdemo001 http://testbed.ist-phosphorus.eu/resource-type/nsp create-path WjY+Ndf4hzVcKNNidE01Qv7gD5w= kjdUpPsVZYY2z998Foh5FK7yWX6ULiQc3Bh5NglOrMQ02YWvXpFQaCc/09AT+1RDzd/1dUtme9Yt lLLdQ/9OX1iVZOJGfq/ehfbmlerm1mNe6tSkkmwubR7FCw99ojr7GacwPFu+MH4GPfo5zsCEXYcV UR4Z/O+ENdZORv34TYk= ======================================================================== Appendix C - Printout of TVS test cases ======================================================================== Running interactive test examples for TVS API: 0 - TVS-TB: generate token of GRI - GetToken (GRI, TokenKey or null) (uses internal TokenKey or default token generation convention) 1 - TVS-TB: generate XMLtoken of GRI - generateXMLToken (GRI, TokenKey or null) 2 - TVS-TB: generate Pilot XMLtoken as a container for GRI - generatePilotXMLToken (GRI, null) 3 - TVS: validate binary token - ValidateToken (GRI, TokenValue, TokenKey?)) 4 - TVS: validate XML token - ValidateXMLToken (GRI, XMLToken, TokenKey?)) 5* - PEP-TVS: Validate Service/PEP Request with binary Token (uses token generated in option 1) 6* - PEP-TVS: Validate Service/PEP Request with XMLToken (uses XMLToken generated in option 2) 7* - Programming TVS via API: setEntryTVStable (GRI, (TokenValue | TokenKey)?, NotBefore?, NotOnOrAfter?) 8* - Programming TVS via API: deleteEntryTVStable (GRI) 9* - Programming TVS via WS/XML message: MessageSetTVS (GRI, ResourceID, (TokenValue | TokenKey)?, NotBefore?, NotOnOrAfter?) Test 1 - TVS-TB: generate XMLtoken of GRI - generateXMLToken (GRI, TokenKey or null) generateTokenXML input: GRI/SessionId = fcd440b7030b1fa129f2443c84a120f03c5611ca; Issuer = x-urn:aaa:gaaapi:TVS Valid from null to null TokenValue = ef7167f7e909a2e1d60ed26a5b253cef2a300487 XMLToken: ef7167f7e909a2e1d60ed26a5b253cef2a300487 2 - TVS-TB: generate Pilot XMLtoken as a container for GRI - generatePilotXMLToken (GRI, null) generatePilotTokenXML input: GRI/SessionId = 29e01d15a8c665f63fb8c156f27b5d73a6c11e87; Issuer = x-urn:aaa:gaaapi:TVS:token-pilot Valid from null to null TokenValue = null PilotXMLToken: