Fabric
======
Fabric is a language and runtime system that supports secure federated
distributed computing. This is a quick-start manual to get you started
running some Fabric examples. A more detailed manual can be found in
the doc/manual directory of this distribution, or on the web at
<http://www.cs.cornell.edu/projects/fabric/manual/0.3.0/html/>.

More information about Fabric, including the latest release, can be
found at the Fabric website
<http://www.cs.cornell.edu/projects/fabric/>.

User support and feedback
-------------------------
If you use Fabric, we'd appreciate your letting us know. We welcome
comments, bug reports, and discussion about Fabric on the Fabric users
mailing list <http://www.cs.cornell.edu/projects/fabric/#mailing-list>.
This is a low-traffic mailing list, to which we will also post
notifications of new releases of Fabric and other related announcements.


Setting up Fabric
=================

Requirements
------------
This Fabric distribution builds on Linux and OS X. Fabric 0.3.0
builds against Jif 3.5.0 and Polyglot 2.7.1. Both
are included in the distribution. JDK 7 or later is required; we have
tested with the Oracle and the OpenJDK implementations. OpenSSL is used
to sign certificates. Fabric is compiled with the Apache Ant build tool.

The following command will install the requisite tools on an Ubuntu
12.04 or 14.04 system:

  $ sudo apt-get install openjdk-7-jdk openssl ant


Once the tools are installed, unpack the distribution in a location of
your choice and change into the distribution directory:

  $ tar zxf fabric-0.3.0.tar.gz
  $ cd fabric-0.3.0



Configuring
-----------
Before using Fabric, you must configure the scripts in the `bin`
directory.  From the top-level directory, run:

  $ ant bin

If the configurator is unable to find the JDK, Polyglot, or Jif, it
will prompt you to set the appropriate properties in
`config.properties`.


Building
--------
_This step is optional._ Fabric comes pre-compiled as Jar files in the
`lib` directory. However, if you wish to rebuild Fabric, run `ant` from
the top-level directory:

  $ ant

For other useful build targets, run `ant -p` from the top-level
directory.


Example programs
================
The `examples` directory in the distribution contains several example
Fabric programs. Each example includes a separate README describing how
to build and run the example. The Fabric nodes required to run each
example come pre-configured. We briefly list the examples here.

  - `examples/hello`: Every programmer's favorite program, ported to
    Fabric. This example creates a persistent object containing the
    message "hello world" and then outputs that message on the console.

  - `examples/sif-hello`: A demonstration of the Fabric port of the
    Servlets with Information Flow (SIF) library [3]. This example
    shows how web services can be built on top of Fabric.

  - `examples/travel`: A more complete demonstration of Fabric's
    features. This application involves coordination between an
    airline, bank, and customer to negotiate the purchase of a ticket.
    Each principal (airline, bank, and customer) also has a web-based
    user interface written using the SIF library.

  - `examples/auction`: A mobile bidding-agent program. This
    application demonstrates the mobile-code support of Fabric [1]. It
    models an auction in which participants submit confidential
    strategies for bidding and selling.

  - `examples/friendmap`: Another mobile-code demonstration. This
    program models a mash-up of social network and a mapping service to
    map a friend's confidential location.

  - `examples/OO7`: This is an implementation of the OO7 Object
    Oriented Database Benchmark [4]. It is written using FabIL, the
    intermediate language for Fabric, and thus does not benefit from
    the static information-flow checking that the full Fabric language
    provides.

  - `examples/blog`: This is a simple web application implemented in
    FabIL. It is similar in structure to the Course Management System
    that we used for evaluating performance of Fabric [2].


References
==========
[1] Owen Arden, Michael D. George, Jed Liu, K. Vikram, Aslan Askarov,
    and Andrew C. Myers. Sharing mobile code securely with information
    flow control. In Proc. IEEE 2012 Symposium on Security and Privacy,
    pages 191–205, San Francisco, CA, USA, May 2012. Software release
    at <http://www.cs.cornell.edu/projects/fabric/>.

[2] Jed Liu, Michael D. George, K. Vikram, Xin Qi, Lucas Waye, and
    Andrew C. Myers. Fabric: A platform for secure distributed
    computation and storage. In Proc. 22nd ACM Symposium on Operating
    Systems Principles (SOSP), pages 321–334, Big Sky, MT, USA, October
    2009. Software release at
          <http://www.cs.cornell.edu/projects/fabric/>.

[3] Stephen Chong, K. Vikram, and Andrew C. Myers. SIF: Enforcing
    confidentiality and integrity in web applications. In Proc. 16th
    USENIX Security Symposium, pages 1–16, Boston, MA, USA, August
    2007. See <http://www.cs.cornell.edu/jif/sif/>.

[4] Michael J. Carey, David J. DeWitt, and Jeffrey F. Naughton. The OO7
    Benchmark. In Proc. ACM SIGMOD 1993 International Conference on
    Management of Data, pages 12-21, Washington, DC, USA, May 1993.