ECL Gateway is an entity that connects ECL network with LionShare network. The main feature of the gateway is to allow ECL users to search and download objects from LionShare network. The gateway should be able to convert the incoming search query from ECL clients to LionShare search and propagate it on LionShare network. Security in the gateway should take care of all the necessary checks mentioned in the design document for ECL gateway and allow them to happen without sacrificing any security.

Below are the major implementation decisions that should be taken care of:

1. Keys and Certificate management on Gateway

   1. Certificates coming from ECL Client side

      When the ECL Client requests some object via ECL/LionShare Gateway, the deliver message has to be signed and encrypted. This is the ECL Client certificate, and should be checked as Holder-of-key against the SAMLAssertion that is in ECL Deliver message.

   2. Certificates and keys to communicate on LionShare side

      When the Holder-of-key is verified by the Gateway, for secured resource, it has to communicate with the LionShare network to retrieve the requested object. To communicate on LionShare network, ECL Gateway should have been authenticated on LionShare network, and should be able to provide the certificates along with the download request. It should be noted that when the Gateway sends signed and encrypted search response back to ECL Client, only the opaque certificate obtained from LionShare SASL-CA should be used to sign and encrypt. This certificate is included as one of the Holder-of-key in SAMLAssertion sent by ECL Client's Identity Provider to obtain the secure resource.

   3. Certificates and keys of its own if required

      This is in most cases not required. Gateway could use the opaque certificate obtained by LionShare SASL-CA as its own certificate and key pair.

2. Algorithm to deal with the incoming Assertion

   SAMLAssertion is required along with the download request for secured objects from LionShare network. LionShare client code fulfills the download request in asynchronous fashion. Gateway calls download method on SearchResults from LionShare API. It is not possible to pass the SAMLAssertion along with the download request to the LionShare code. LionShare code probes the implemented SecurityManager for SAMLAssertion when its ready to send an actual download request to the network. This causes a need to map each incoming SAMLAssertion to be mapped to correct download request.

   One way of doing this is by implementing a queue on the gateway. When ECL Client sends SAMLAssertion along with the download request, gateway should verifiy the SAMLAssertion and put it in a queue. When the LionShare client code probes the SecurityManager for SAMLAssertion, the SecurityManager implementation could poll the queue for the SAMLAssertion.

   It should be noted that it is possible that LionShare client code probs the SecurityManager more than once for same download request. To prevent possible mismatch, Gateway could implements another HashMap, when the LionShare code probs the SecurityManager for the first time it caches the SAMLAssertion against the GUID of the request. When LionShare code probes the SecurityManager, it provides the GUID, which makes it easy then to map the SAMLAssertion to the correct request.

3. Caching search results, and other java object required for secured download

   LionShare API represents each search result with corresponding edu.psu.its.lionshare.search.SearchResult object returned by the matching host. Gateway should cache all the edu.psu.its.lionshare.search.SearchResult objects. When ECL Client sends a download request for one of them, corresponding edu.psu.its.lionshare.search.SearchResult object should be pulled from the cache, and call its download method to download the object. Gateway should have proper algorithm in place to map each incoming request to correct download object from LionShare network. Gateway should clear up the edu.psu.its.lionshare.search.SearchResult cache periodically to make sure that it does not run out of memory.

   LionShare code maintains two kind of directories for download. An incomplete download directory, and a download directory. Once the download is complete it moves the object to download directories. Gateway should be able to access objects from these directories.

   LionShare code checks periodically in incomplete directory to see if there are incomplete download waiting to be completed, if so, it tries to download the object automatically. This would cause the SAMLAssertion queue mismatch if the incomplete object is secured. In order to prevent this, Gateway should clear the incomplete directory periodically.

   Also, once the secure object is download on gateway and delivered to ECL Client, Gateway should delete the object from its download directory.

4. Misc

   1. Metadata Formating

      LionShare network returns the search results in Dublin Core format, where as ECL Client understands IEEE LOM metadata format only. It is necessary the Gateway takes care of converting the incoming DC metadata to IEEE LOM metadata.

      1. Technical Location

         It is necessary that Gateway modifies the technical location of the resulting IEEE LOM metadata so that ECL Client could perform a ECL Deliver for metadata. The technical location should follow below rules:

         1. Put the protocol as "ecl://"

         2. Append the service key for the service that could deliver this particular object. If the object is protected by attributes, service key for secure ECL LionShare gateway should be appended. If the object is not protected by attributes, service key for non-secure ECL LionShare gateway should be appended. e.g. "ecl://requestServiceKey="ServiceKey"

         3. Append attributes : object URN and search Id for the object this metadata refers. Each attributes separated by "&" A sample technical location would look like ecl://requestServiceKey=747F9A20-5BEC66C&urn=urn:sha1:7YGBUTJ&searchId=2

      2. Required Attributes

         If the object for which the metadata is being modified is protected, the information of required attributes to access this object should be places in

         Each required attribute is separated by "#" delimiter

         A sample looks like

         urn:mace:dir:attribute-def:eduPersonScopedAffiliation#urn:mace:dir:attribute-def:eduName

   1. Manage Properties

      Gateway should modify the ShareManager.properties file for LionShare code, and specify its SecurityManager Implementation.