Overview

Here are a few hints to get you started:

• eCAP is the interface between the host application such as a proxy server and an adapter module that implements some content analysis or adaptation (including logging, filtering, blocking, injecting, translating, decoding, or encoding). The host does not know adapter details and vice versa. The two communicate via standard eCAP interfaces.
• The libecap library available on this site implements eCAP API in C++. We also provide sample adapter implementations that use the library. Starting with v1.0, partial detailed documentation is available in the doc/ directory of the libecap source code package.
• Both the host application and the adapter module should link against the installed libecap library.
• The library itself has little "real code". Its focus is on declaring the interfaces that host and adapter software must implement to work with each other.
• If you add eCAP support to a host application, you need to implement the host::Host and host::Xaction interfaces as well as MIME-like Message wrappers. In general, implementing host support is more difficult than writing specific adapters. Fortunately, there are fewer host applications than needed adapters. Currently, eCAP support is being added to Squid proxy cache and Spicer ICAP server.
• If you are writing an eCAP adapter, you need to implement the adapter::Service and adapter::Xaction interfaces. The basics are straightforward and working samples are available. Once the required interfaces are supported, you can focus on the specifics of the adaptation service(s) provided by your adapter. Your module will work with any eCAP-enabled application.
• You can download the library, compile, and install it the same way you handle most open source packages on a Unix-like system.

Using sample adapters

Before writing your own eCAP adapter, consider getting a sample adapter working. Sample adapters are not meant for production use, but they are very useful as a starting point for eCAP developers. The following steps illustrate getting a modifying adapter from the sample collection working with Squid proxy. These instructions install eCAP and Squid software from sources so you will need a development environment (e.g., a C++ compiler such as g++, various C++ libraries and headers, make utility, etc.).

1. Download and install libecap. This example uses libecap v0.2. You may need a different libecap version, depending on your Squid version. This step should be done before building Squid.

   $ tar -xzf libecap-0.2.0.tar.gz
   $ cd libecap-0.2.0/
   $ ./configure && make && sudo make install

2. Download and install the adapter sample. This example uses sample v0.2.1. You may need a different sample version, depending on your libecap version. This step must be done after installing libecap.

   $ tar -xzf ecap_adapter_sample-0.2.1.tar.gz
   $ cd ecap_adapter_sample-0.2.1/
   $ ./configure && make && sudo make install

3. Download and install Squid. This example uses Squid v3.4 which supports libecap v0.2:

   $ tar -xzf squid-3.4.5.tar.gz
   $ cd squid-3.4.5/
   $ ./configure --enable-ecap && make && sudo make install

4. Adjust squid.conf (installed in /usr/local/squid/etc/ by default) to allow test traffic (not shown here) and to use the modifying sample adapter that you have installed in the previous step:

   loadable_modules /usr/local/lib/ecap_adapter_modifying.so
   ecap_enable on
   ecap_service ecapModifier respmod_precache \
       uri=ecap://e-cap.org/ecap/services/sample/modifying \
       victim=the \
       replacement=a
   adaptation_access ecapModifier allow all

5. Start Squid. Configure your test client (e.g., a browser) to use the installed Squid proxy and test the installation using a simple web site that does not use gzip encoding. You should see all "the" words replaced with "a" words. Note that capitalized "The" words should not be replaced. Now go to a site that usually returns compressed content. You should see no replacements. It is often possible to work around this limitation using a very invasive hack: You can add the following squid.conf line to tell Squid to strip HTTP Accept-Encoding request header that allows origin servers to respond with compressed content:

   request_header_access Accept-Encoding deny all

   Again, this is not something you want to do in a production environment. A production-quality adapter should handle compressed content. The modifying adapter sample does not.
6. If you want to test injection of some HTML and/or Javascript code, adjust squid.conf to tell the modifying adapter to load the injection text from a local file.

   ecap_enable on
   ecap_service ecapModifier respmod_precache \
       uri=ecap://e-cap.org/ecap/services/sample/modifying \
       victim=</body> \
       replacement-src=/usr/local/squid/etc/my-injection.html
   adaptation_access ecapModifier allow all

   Please note that, to preserve HTML structure, the replacement text must either start or end with the HTML tag you are replacing. For example, if you are replacing a </body> tag, as shown in the example above, the replacement text should end with </body>.
7. You can continue polishing your Squid configuration to prevent adaptation of non-HTML content, responses without bodies, etc. The adaptation_access directive shown above sends all responses to the adapter, which increases performance overheads and content corruption risks.

These instructions are meant to illustrate a basic eCAP adaptation setup. Once again, the Squid configuration excerpt shown here and the sample modifying adapter are too primitive and too invasive for production use.

Writing an antivirus adapter

Writing an eCAP AV adapter requires:

• implementing eCAP interfaces (for integration with the host application),
• implementing virus scanning functionality (usually using an existing antivirus library), and
• integrating the above two parts together.

Making virus scans non-blocking to the host application is usually required and may complicate things further, especially if the host application itself is not threaded. These tasks can be greatly simplified by using an AV SDK, available in the Downloads area. As detailed in its README file, the toolkit implements several common/generic AV scanning requirements for you, without forcing you to use a yet another library or framework on top of the eCAP and AV library dependencies you already have to deal with.

The same SDK can probably bootstrap development of adapters that scan files for purposes other than virus protection, especially if you do not mind (or can replace) AV-related terminology in SDK-produced adapter sources.

Upcoming changes

While the overall libecap design is not expected to change drastically, API and source code changes will happen as we gain more experience with real-world eCAP deployment. For the first few development releases, you may have to rewrite, hopefully small, portions of your code to stay in sync with the changes.

Here are some of the short-term improvements we work on, with completed items crossed out:

• ServiceConfig class to pass configuration information to the adapter.
• Ability to create new messages from scratch, without cloning virgin messages.
• Host-assisted blocking of messages.
• Meta-information exchange between host and adapter transactions, similar to ICAP headers.
• Migration of headers related to message structure to libecap/message or libecap/mime.
• Safer Xaction pointers using shared_ptr.
• Support for threaded adapters.
• Browsable documentation.