ORQ: An Oblivious Relational Query Engine

ORQ is a multi-party computation framework for relational analytics. For more information, see our paper at SOSP '25.

ORQ has received all SOSP artifact evaluation badges. Evaluation occurred on the sosp-artifact tag, available here. The current version of the repository has gone through a substantial cleanup for public release, but is functionally identical.

ORQ is also archived on Zenodo:

[!NOTE] (March 2026) We have been notified of an attack on the Fantastic Four protocol (to appear at Eurocrypt'26). An implementation of the fix following $\Pi_\mathrm{CheckEqs}$ (Fig. 6 of [BS26]) is currently under development. Separately, we also identified some issues with our malicious-secure opening protocol. We will push both fixes to this repository soon.

Dependencies
Building ORQ
- Single-Node
- Multi-Node
Running ORQ
Writing New ORQ Programs
Creating a Cluster

This repository is organized as follows:

bench/: source code for queries and benchmarks
doc/: documentation (available online, above)
examples/: example programs
include/: core functionality of ORQ (core/), including the implementation of MPC primitives (core/protocols/), containers (core/containers/) relational oblivious operators (core/operators/), and party communication (core/communication/), as well as the framework backend (backend/).
scripts/: various scripts for testing and benchmarking ORQ
tests/: the test suite

This README walks through each of the steps to deploy an ORQ cluster and run ORQ programs. You can also get started with writing ORQ programs and check out the examples.

Dependencies

All dependencies are installed automatically on Ubuntu by running the setup.sh or deploy.sh scripts.

To build ORQ, you will need:

C++ 20 or newer
libsodium
Your platform's threading library, such as pthread (should be installed by default)
sqlite, for optional correctness tests for queries. Ideally, you should install SQLite via your system's package manager, but it is also available on their website.

As of this writing, the complete list of ORQ dependencies is:

git cmake pkg-config build-essential manpages-dev gfortran wget libsqlite3-0 libsqlite3-dev libsodium23 libsodium-dev libopenmpi3 libopenmpi-dev openmpi-bin openmpi-common python3 python3-pip libtool autoconf automake

These are automatically installed by setup.sh. On non-Ubuntu systems (Mac, other *nix), setup.sh will not be able to install all dependencies, so you will need to install them yourself.

If you plan to use ORQ in the two-party setting, you will also need to install the following libraries for the offline phase:

libOTe for secure Beaver triples
secure-join for a two-party oblivious pseudorandom function (OPRF) with secret-shared output

Note: the above dependencies may impose additional restrictions on the environment. For example, they may not support all Linux distributions that ORQ's online phase supports.

[!IMPORTANT] You should still run setup.sh even if you install the dependencies manually, because other libraries will be compiled and built manually. You can ignore errors from, e.g. apt not being installed.

Building ORQ

There are separate instructions for single-node and multi-node systems. All instructions assume *nix systems.

Single-Node

The following applies to computation run on a single machine, where each party is a separate process. On platforms with apt (Ubuntu), simply run the setup script:

$ git clone https://github.com/CASP-Systems-BU/orq
$ cd orq
$ ./scripts/setup.sh

If you do not have apt (other Linux, macOS, etc.) you will need to install the dependencies manually (see above).

Multi-Node

[!NOTE] These instructions assume a cluster has already been created. For instructions on how to create a cluster, see below.

In a distributed deployment with multiple nodes, there is an additional setup to connect the nodes. All commands in this section should be run from node0. node0 must be able to SSH into all other nodes.

[!WARNING] Having SSH access into all other nodes, of course, compromises the non-collusion assumption of multi-party computation. We require SSH access here for ease of development and testing. However, in a real system, ORQ nodes would need to be configured out-of-band. We do not currently support this setup.

Connections between parties do not use TLS for MPC. SSH is only used for setup.

First, we run scripts/_update_hostfile.sh to write to /etc/hosts/ so that we can refer to the other servers as node0, node1, etc.
Second, we run the deployment script ./scripts/orchestration/deploy.sh with the location of the repository and the names of the servers. The following example assumes a four-party setup, although we can achieve a setup with fewer parties by simply not entering the corresponding IP address(es) and name(s). Replace <ip-X> with the IP address of nodeX.

$ git clone https://github.com/CASP-Systems-BU/orq
$ cd orq
$ ./scripts/_update_hostfile.sh -x node -i <ip-0>,<ip-1>,<ip-2>,<ip-3>
$ ./scripts/orchestration/deploy.sh ~/orq node0 node1 node2 node3

deploy.sh runs setup.sh, so we do not need to run setup.sh explicitly. If you are on a machine without apt, you will need to install dependencies manually on all machines, as specified above.

Running ORQ

This section describes the process to compile and run programs. To run programs, you must be in the build directory. You can follow standard cmake patterns for compiling ORQ programs, and we provide commands for running programs in a local or distributed fashion. Compilation is the same in either case.

Compiling ORQ Programs

The following example compiles a single program, TPCH Q1, in the replicated three-party protocol (the default).

$ mkdir build
$ cd build
$ cmake .. -DPROTOCOL=3
$ make q1

Various options can be specified to cmake.

-DPROTOCOL=N to change the protocol. We currently support
- -DPROTOCOL=1 a single-party plaintext test protocol
- -DPROTOCOL=2 ABY two party dishonest majority protocol with Beaver Triples
- -DPROTOCOL=3 Araki et al. three party replicated honest majority protocol (the default)
- -DPROTOCOL=4 Fantastic Four honest-majority malicious 4PC protocol (Note: security fix in progress)
-DNO_X86_SSE=1 to disable x86 hardware optimizations (you will get warnings otherwise if built on ARM platforms, like newer Macs)
-DPROFILE=1 enable profiling (compile with -pg)
-DEXTRA=XXX pass the additional argument XXX to make
-DCOMM=XXX enable the given communicator. Options are "MPI" "NOCOPY". If you do not specify anything, CMake will use NOCOPY.
-DTRIPLES=XXX specify the kind of Beaver triples to use for 2PC (ZERO (all zeros, for profiling the online phase), DUMMY (insecurely generated, fast), or REAL (secure)).

We provide some cmake shortcuts to make compiling multiple executables easier.

# compile everything
$ make -j
# compile tests
$ make -j tests-only
# compile all tpch queries
$ make -j tpch-queries
# compile queries for the secretflow comparison
$ make -j secretflow-queries
# compile all other queries
$ make -j other-queries

See debug/orq_debug.h and CMakeLists.txt for more information on compile options. Not all compile options are made available via CMake and instead must be manually configured within orq_debug.h.

`run_experiment.sh`

We provide an execution harness script, run_experiment.sh, which automates the compilation and execution process. This is the recommended method of running ORQ programs.

To see a comprehensive set of options for the run_experiment script, simply run it without arguments to display a help message.

Usage: ../scripts/run_experiment.sh [options] <exp_name>
  exp_name Experiment to run
OPTIONS:
  [-h]                                    Show this help
  [-p 1|2|3|4]                            Protocol; default: 3
  [-s same|lan|wan]                       Setting; default: same
  [-c mpi|nocopy]                         Communicator; default: mpi for same; nocopy otherwise"
  [-n num_comm_threads]                   [NoCopyComm only] Number of communicator threads (negative: # per worker);

Orq

Install / Use

README