JIFF

JIFF is a JavaScript library for building applications that rely on secure multi-party computation. JIFF is built to be highly flexible with a focus on usability, with the ability to be run in the browser, on mobile phones, or via Node.js. JIFF is designed so that developers need not be familiar with MPC techniques or know the details of cryptographic protocols in order to build secure applications.

Requirements

Server

Running the server requires Node and npm.

Client

For browsers, we provide a bundle including the base client side library and its dependencies (libsodium-wrappers and socket.io). Extensions have to be imported separately.

For node.js clients, npm install should install all the required dependencies.

You can use browserify or similar tools to require JIFF via npm and bundle it with your browser-side JS.

Installation

Add JIFF as a dependency to your project:

npm install jiff-mpc

Node.js

After installing JIFF via npm, you can require the server module in your server code using:

const { JIFFServer } = require('jiff-mpc');

// create the JIFF server.
const jiffServer = new JIFFServer(http, options);

// listen for connections.
http.listen(port, cb);

Similarly, you can require the client module in your node.js clients using:

const { JIFFClient } = require('jiff-mpc');

// create a jiff client.
const jiffClient = new JIFFClient("<server address>", "<computation_id>", <options>);

// perform some computation.
let shares = jiffClient.share(<secret>);
...

Client - Browser

To use our bundle, include the provided pre-built JS file in a script tag. Make sure that you set up your web-server to serve this JS file.

<!-- exposes JIFFClient to the global scope -->
<script src="/dist/jiff-client.js"></script>

Then inside a script tag (and after the page loads), initialize a JIFF object and set up a computation:

const jiffClient = new JIFFClient("<server address>", "<computation_id>", <options>);

The jiffClient object provides methods for sharing, opening, and performing operations on shares.

Alternatively, you can use the same code for both Node.js and browser-based clients, using tools such as browserify.

To do this, require JIFF from npm in your client JS code normally, e.g. using const { JIFFClient } = require('jiff-mpc');, and then build your JS code into a bundle using browserify. You can then serve that bundle via your web server, and include it in your HTML using script tags.

To see an example of this, look at this JIFF standalone example repo.

Extensions

If you want to support more complex data types, such as Fixedpoint numbers or infinite precision integers, you should apply the corresponding extension to your client and/or server JIFF instances.

The extensions can be imported via npm, bundled into web clients via browserify, or included directly via script tags into the browser.

// Server
const { JIFFServer, JIFFServerBigNumber } = require('jiff-mpc');
const jiffServer = new JIFFServer(http, options);
jiffServer.apply_extension(JIFFServerBigNumber);

// Client using node.js or browserify.
const { JIFFClient, JIFFClientBigNumber } = require('jiff-mpc');
const jiffClient = new JIFFClient("<server address>", "<computation_id>", {
  autoConnect: false,
  <other options>
});
jiffClient.apply_extension(JIFFClientBigNumber, options);
jiffClient.connect();

<!-- Plain JS without browserify -->
<!-- include the extension and any of its dependencies directly using script tags -->
<!-- make sure your web server serves these files at the corresponding URLs -->
<script src="/bignumber.js/bignumber.min.js"></script>
<script src="/lib/ext/jiff-client-bignumber.js"></script>

Project Layout

├─ demos/               Example of common jiff use-cases and functionality
├─ docs/                JSDoc config and generated docs
├─ lib/                 Libraries for both client and server-side jiff instances
│  ├─ client/           Implementation of the client side library
│  ├─ server/           Implementation of the server side library
│  ├─ ext/              Extended functionality for use cases (e.g. negative numbers): Includes server and client extensions
│  ├─ common/           Some common helpers between both client and server code
│  ├─ jiff-client.js    Main module for the client side library, include this (or the bundle under dist/) in your projects
│  └─ jiff-server.js    Main module for the server side library, include this in your server code
├─ test/                Unit testing for base Jiff, demos, and extensions
│  ├─ dev/              Limited tests for testing some features under development
│  ├─ live/             Template and setup for live coding with JIFF with nodejs's command line shell (REPL)
│  └─ suite/            Base Jiff and extension tests (See test/suite/README.md)
├─ tutorial/            Contains interactive tutorial files that can be run locally to learn JIFF!

Running Tutorials

Clone the github repo, and run npm run tutorial inside its root directory.

On your terminal, you will see a list of "Routes/Documents". Open either document in your browser to go through the tutorial.

Each document is an independent tutorial. However, beginners are encouraged to view them in order.

Running Demos and Examples

Run a sample server from one of the demos under demos in the following way:

node demos/<demo-name>/server.js

The output from the example server will direct you to open localhost:8080/demos/<demo-name>/client.html in a browser (you must open an instance in a separate window/tab for every distinct party participating in the protocol). You can then proceed with the protocol using the client interfaces.

Note that you can run Node.js parties that can also participate in the protocol by executing (e.g., a separate terminal for each party):

node demos/<demo-name>/party.js <input-value>

Documentation

The latest documentation can be viewed on the project page. The documentation can be generated using JSDoc; you will find these docs in docs/jsdocs/:

./node_modules/.bin/jsdoc -r -c docs/jsdoc.conf.json
npm run-script gen-docs # shortcut

Where to Look in the Docs

The documentation for the client side library is separated into the distinct modules, namespaces, and classes:

├─ modules
│  └─ jiff-client            Parent module: represents the exposed JIFFClient global variable
├─ classes
│  ├─ JIFFClient             Represents a client side jiff instance including the main API of JIFF
│  ├─ SecretShare            Contains the API for SecretShare objects
│  ├─ GuardedSocket          Internal wrapper around socket.io for added reliability
│  └─ Deferred               Polyfill to construct deferred from native Promises
├─ namespaces
│  ├─ protocols              Common protocols exposed by jiff client instances, suitable for preprocessing
│  ├─ bits                   Primitives for operating on bit-wise shared secrets (hybrid protocols)
│  └─ hooks                  Available hooks that can be used by users to customize behavior

Running Tests

All of the JIFF library test cases can be run in the following way:

npm test

Demos are accompanied by test cases. The following command can be used to run the demo servers and test cases:

npm run-script test-demo -- demos/<demo-name>

The command assumes that the server is located at demos/<demo-name>/server.js and the test cases are located at demos/<demo-name>/test.js See demos/run-test.sh for instructions on running test cases located in different directories or with different names.

See the testing suite framework documentation for more details on running and creating tests for the JIFF library.

Bundling

If you made changes to the library and would like to bundle it again into a single browser-friendly file, you can run this command:

npm run-script build # will override dist/jiff-client.js

Development

The JIFF libraries allow developers to customize or extend their functionality by introducing new hooks. Multiple hooks can be combined to form a library extension.

Hooks

The JIFF client and server libraries support hooks. Hooks can be provided in the options parameter during instantiation or afterwards. Hooks allow the introduction of custom functionality to be executed at critical times during the computation, or the introduction of different implementations of specified primitives and operations (e.g. using a different sharing scheme).

The client-side hooks documentation provides more details. If hooks are used to provide important reusable functionality, then it is recommended to bundle these hooks within a JIFF extension.

Extensions

JIFF supports implementing extensions on top of the base implementations that can provide additional extended functionality. Some extensions can be found under lib/ext. Two important modules are implemented and provided in this repository: bignumbers and fixed point arithmetic.

See the extensions documentation and the documentation inside src/ext/jiff-client-bignumber.js for instructions on how to create additional extensions.

Both client and server libraries support extensions. Some extensions require customizing both the server and client libraries to behave pro