Deploying an XOR Machine ​

Computing directory ​

Each XOR Machine has a designated compute directory <compdir> which stores a folder for each network configuration:

# Make sure the compute directory is readable and writable by the xor application



<compdir>

<compdir>/someNetconfigA/
# Read only for the xor-machine but all private data should be written here
<compdir>/someNetconfigA/private-data/player-1/
# Scripts to run local computations should be written here
# If in production, then read-only. In development, scripts can be submitted by
# an analyst through the XOR Portal; the XOR-Machine must be granted the write
# permission.
<compdir>/someNetconfigA/processing-scripts/

Network configurations ​

Each XOR Machine contains a network configuration allowing to connect to the XOR Portal and other XOR Machines. The configuration override.conf is used to configure the XOR Machine to allow it to participate in computations. The file has the following structure:

The override.conf file must be written to <compdir>/override.conf

xorMachine {
  netconfigs {
    // someNetconfigA {
    //   playerName = "player-1"
    //   secretToken = "secretToken"
    // }
    // someNetconfigB {
    //   playerName = "player-2"
    //   secretToken = "secretToken2"
    // }
    // etc.
  }

  xorPortalClient {
    port = 8081
    host = "localhost"
  }
}

For more details on the XOR Machine Network configuration, please have a look at the Network configuration of XOR Machines.

Setting up XOR Machines ​

XOR Machine Minimum Requirements ​

Practically RAM and bandwidth will be your most limiting factors when computing with XOR.

Setting up XOR Machines via Docker ​

The fastest way to get started with the XOR is to launch 2-3 XOR Machines using Docker on your laptop or desktop computer(s). Once launched, the XOR Machines will try to establish a connection to the XOR Portal which is hosted by Inpher.

The docker container can only be downloaded by authorized parties. Please email us for more information:

$ docker login docker.public.inpher.io
# Login with your user name and password provided by inpher to pull images from the inpher docker registry. If you do not have an account, contact info@inpher.io and request access.
Username (username): xxxxxx
Password: xxxxxx

# Download the latest xor-machine image:
docker pull docker.public.inpher.io/xor-machine

Next, create a dedicated test network within docker to run the xor containers

# only if the xor containers are deployed in the same machine 
# create dedicated network container 
docker network create -d bridge --subnet=172.18.0.0/16 xor-test

Add the netconfig to xor-portal. For this example we don't generate encryption keys on the players, hence we set the useFakeKeys of the netconfig to true.

cat << EOF | curl -X POST -d @- -H 'Authorization: Bearer <token>' https://<custenv>.xor.inpher.io/v2/netconfigs -H 'content-type: application/json'
{
  "netconfigId": "myConfig",
  "peers": {
    "player-1": {
      "host":"xor1",
      "port":5555,
      "secretToken": "secretToken1"
    },
    "player-2": {
      "host":"xor2",
      "port":5556,
     "secretToken": "secretToken2"
    }
  },
  "useFakeKeys": true
}
EOF

Write the configuration file for player-1 to the expected directory

mkdir player-1
cat > player-1/override.conf << EOF
xorMachine {
  xorPortalClient {
    host = "grpc.<custenv>.xor.inpher.io"
    port = 443
  }

  netconfigs {
    myConfig {
      playerName = "player-1"
      secretToken = "secretToken1"
    }
  }
}
EOF

Then run the docker container specifying the path to the home directory as follows:

# Run docker container:
# Make sure that you use different home folders for each XOR machine when
# testing on the same machine!

#  '--network= should match the network you created in the previous step'
#  '-v maps a local folder to the docker container folder'
docker run  -d -v $PWD/player-1:/home/xor \
            --network=xor-test --hostname=xor1 \
            -p 5555:5555 \
            --restart unless-stopped \
            --name xor1 docker.public.inpher.io/xor-machine

Write the configuration file for player-2:

mkdir player-2
cat > player-2/override.conf << EOF
xorMachine {
  xorPortalClient {
    host = "grpc.<custenv>.xor.inpher.io"
    port = 443
  }

  netconfigs {
    myConfig {
      playerName = "player-2"
      secretToken = "secretToken2"
    }
  }
}
EOF

Then run the docker container for player-2:

docker run  -d -v $PWD/player-2:/home/xor/ \
            --network=xor-test --hostname=xor2 \
            -p 5556:5556 \
            --restart unless-stopped \
            --name xor2 docker.public.inpher.io/xor-machine

Finally, to check that the XOR Machines are running use:

docker ps -a # should show the xor1 as running

If there are errors, they should be logged to stdout:

# Or run the following on a running container
docker logs xor1
docker logs xor2

Then connect to the analyst portal and login using the credentials provided by your inpher account manager.

Setting up XOR Machines via Docker with encryption keys ​

In a real environment, you want the traffic between each components to be secured by encryption. This sections describes how to generate and use encryption keys with xor machines. It is very similar to the previous section with a few additional steps.

Login and pull the xor-machine docker image (it can only be downloaded by authorized parties, please email us for more information):

docker login docker.inpher.io
docker pull docker.public.inpher.io/xor-machine

Create a dedicated test network within docker to run the xor containers

docker network create -d bridge --subnet=172.18.0.0/16 xor-test

Create private and public keys for each player:

openssl genrsa 2048 >  player-1.key
openssl rsa -in player-1.key -pubout -out player-1.pub

openssl genrsa 2048 >  player-2.key
openssl rsa -in player-2.key -pubout -out player-2.pub

Create a netconfig to xor-portal. By default a netconfig will require encryption keys.

cat << EOF | curl -X POST -d @- --oauth2-bearer <token> https://<custenv>.xor.inpher.io/v2/netconfigs -H 'content-type: application/json'
{
  "netconfigId": "netconfig-with-keys",
  "peers": {
    "player-1": {
      "host":"xor1",
      "port":5555,
      "secretToken": "secretToken1"
    },
    "player-2": {
      "host":"xor2",
      "port":5556,
     "secretToken": "secretToken2"
    }
  }
}
EOF

Post the public key of each player of the netconfig:

curl -X PUT --data-binary @player-1.pub --oauth2-bearer <token> https://<custenv>.xor.inpher.io/v2/netconfigs/netconfig-with-keys/players/player-1/public-key
curl -X PUT --data-binary @player-2.pub --oauth2-bearer <token> https://<custenv>.xor.inpher.io/v2/netconfigs/netconfig-with-keys/players/player-2/public-key

Write the configuration files for each player:

mkdir player-1
cat > player-1/override.conf << EOF
xorMachine {
  xorPortalClient {
    host = "grpc.<custenv>.xor.inpher.io"
    port = 443
  }

  netconfigs {
    netconfig-with-keys {
      playerName = "player-1"
      secretToken = "secretToken1"
    }
  }
}
EOF

mkdir player-2
cat > player-2/override.conf << EOF
xorMachine {
  xorPortalClient {
    host = "grpc.<custenv>.xor.inpher.io"
    port = 443
  }

  netconfigs {
    netconfig-with-keys {
      playerName = "player-2"
      secretToken = "secretToken2"
    }
  }
}
EOF

Put the private key of each player in the container folder:

mkdir -p player-1/netconfig-with-keys/keys
cp player-1.key player-1/netconfig-with-keys/keys/netconfig-with-keys-player-1.key
mkdir -p player-2/netconfig-with-keys/keys
cp player-2.key player-2/netconfig-with-keys/keys/netconfig-with-keys-player-2.key

Then run the docker containers:

docker run  -d -v $PWD/player-1:/home/xor \
            --network=xor-test --hostname=xor1 \
            -p 5555:5555 \
            --restart unless-stopped \
            --name xor1 docker.public.inpher.io/xor-machine

docker run  -d -v $PWD/player-2:/home/xor/ \
            --network=xor-test --hostname=xor2 \
            -p 5556:5556 \
            --restart unless-stopped \
            --name xor2 docker.public.inpher.io/xor-machine

To check that everything is running:

docker ps -a # should show the xor1 and xor2 as running
docker logs xor1 # To see the logs of xor1
docker logs xor2 # To see the logs of xor2

Then connect to the analyst portal and login using the credentials provided by your inpher account manager.

Setting up XOR Machines via package manager ​

If you are running a Debian Linux distribution you may add the XOR repository to your repository sources and easily install XOR through the package manager. Note: we need to whitelist your IP in order for you to have access to our repository.

# Add xor packages repo to available apt sources
echo "deb http://packages.xor.inpher.io/ubuntu /" >\
/etc/apt/sources.list.d/inpher.list

# Add xor GPG key
wget -q -O - http://packages.xor.inpher.io/ubuntu/KEY.gpg | apt-key add -

# Update database
apt update

# Install the package
apt install xor-machine

# Start XOR machine
service xor-machine start

Setting up XOR Machines via AWS EC2 ​

This section will guide you through the process of creating an EC2 instance using the official XOR Machine AMI.

1. Select the EC2 service under the Compute section of the AWS Console.

2. Click the Launch Instance button.

3. Search for xor-machine and select the latest version of the image. Note that you will only have access to this AMI if you purchased a development or production license on the AWS Marketplace.

4. Select an instance type based on the table bellow for minimum requirements:

5. Configure the instance details as desired. Please make sure the VPC you select has outbound access to the Internet.

6. Change the EBS volume (/dev/xbdb) size based on the table bellow:

7. Add a tag service:xor-machine. This tag can be used later to facilitate dataset deployment.

8. Make sure SSH connections are allowed on the selected security group.

9. Launch the instance.

10. Once the instance is up, create a tunnel from your local computer to the XOR Config manager running on the EC2 instance:

ssh -R 3000:localhost:3000 -i private_key.pem admin@xxx.xxx.xxx.xxx

11. Browse to <http://localhost:3000> and use the XOR Config Manager to add a netconfig file with the information provided by Inpher.

12. Browse to the analyst console and go to the Settings tab. If everything is working as expected you should see the name of the netconfig on the dropdown menu.

Connectivity Tests ​

After testing locally, you can deploy the XOR Machines to a production environment. Again, you can use the docker container to deploy it to your on premise server or to a cloud provider of your choosing.

Before deploying the XOR Machines, you need to make sure that the following ports are open for the XOR machine:

In order to check if the firewall is open and the connections are possible, run the following commands from the xor-machines host.

# Test https
nc -z XXX.xor.inpher.io 443
Connection to XXX.xor.inpher.io port 443 [tcp/https] succeeded!

Outgoing:

• HTTPS (port 443)

You will also need to open firewall ports between all the XOR Machines as configured in the Network Configuration and ensure that the traffic is properly routed (e.g through NAT, or a VPN etc.).

To test whether all XOR Machines can communicate with each other, please perform a Connectivity Test.

Access Control ​

A data centric access control model can be used with XOR. Each XOR Machine can optionally maintain an Access Control List (ACL), where fine grained rules can be defined based on dataset, username and group.

The ACL can be used to restrict certain operations, or the ability to reveal the output. As in Secret Computing®, the trust model is distributed, meaning each data source should have full control over the access control policy, no central ACL is supported. It is the responsibility of the data owner, i.e the operator of the XOR Machine to define the ACL.

In case no ACL file is provided, the XOR Machine will default to allowing any computation being performed on its data.

For a rule to be valid, you need to specify at least one user or one group and one operation.

Capabilities ​

• Allow data privacy officer / data owner to define rules for authorized access to data / computations.
• Authorization on dataset

Example ACL acl.json:

{
  "dataset": [
    {
      "users": ["rick", "morty"],
      "groups": ["citadel"],
      "operations": ["linreg", "logreg"],
      "reveal": true
    },
    {
      "users": ["morty"],
      "operations": ["psi"],
      "reveal": false
    },
    {
      "users": ["rick"],
      "groups": ["ricksgroup"],
      "operations": ["colvariances"],
      "reveal": true
    }
  ],
  "otherDataset": [
    {
      "users": ["morty", "rick"],
      "operations": ["logreg", "colmeans"],
      "reveal": false
    }
  ]
}

Some notes about the acl.json format:

// The values to be set in the 'operations' array can be found in https://dev.inpher.io/xor/algorithms/
// Use the value specified in the 'REST JSON payload' algorithm.type field.

// Hierarchy:
// dataset1 => private-data/<playerName>/dataset1.csv
{
  "dataset1": [ rule1, rule2, rule3, ... ],
  "dataset2": [ rule4, rule5, rule6, ... ],
  ...
}

// A rule has the following format:
{
  "users" : <array of usernames>,
  "groups" : <array of group names>,
  "reveal" : <true | false>,
  "operations" : <array of operation names>
}

The ACL file acl.json has to be saved in the /home/xor/<netconfigId> folder.