README.md

OPRF

Oblivious pseudo-random function over an elliptic curve (Ristretto255)

Installation

For node.js, use:

npm install oprf

For the browser, include a script tag targeting either dist/oprf.js or dist/oprf.slim.js.

Bundle vs slim

For browsers, we provide two built files: dist/oprf.js and dist/oprf.slim.js.

The first includes both OPRF bundled with libsodium-wrappers-sumo version 0.7.6. The second includes only OPRF.

You can use the slim version for cases where your browser-side code uses a more recent version of libsodium, or if you want to load libsodium asynchronously to reduce page load time.

The API for both versions is identical, except that the slim OPRF constructor expects a sodium instance to be passed in as a parameter, while the bundled constructor does not expect any parameters.

In node.js, the slim OPRF is not exposed.

const OPRF = require('oprf');
const oprf = new OPRF(); // will require('libsodium-wrappers-sumo');

Initialization

OPRF is not safe to use until sodium is done loading.

const oprf = new OPRF();
await oprf.ready; // wait for dependencies to load

Security Guarantees

A client has input x while a server holds key k. The client receives the output of f_k(x) for some pseudorandom function family f_k. The server learns nothing.

The implementation uses Ristretto255, and does not suffer from small cofactor attacks.

Public Interface

Contains a masked point and the mask that was applied to it

export interface IMaskedData {
  readonly point: Uint8Array;
  readonly mask: Uint8Array;
}

Public Functions

hashToPoint: maps string input to a point on the elliptic curve

public hashToPoint(input: string): Uint8Array

isValidPoint: returns whether the given point exists on the elliptic curve

public isValidPoint(point: Uint8Array): boolean

maskInput: hashes string input as a point on an elliptic curve and applies a random mask to it

public maskInput(input: string): IMaskedData

maskPoint: applies a random mask to an elliptic curve point

public maskPoint(point: Uint8Array): IMaskedData

unmaskPoint: applies the multiplicative inverse of the mask to the masked point

public unmaskPoint(maskedPoint: Uint8Array, mask: Uint8Array): Uint8Array

generateRandomScalar: generates a uniform random 32-byte number in [1, order of curve)

public generateRandomScalar(): Uint8Array

scalarMult: salts a point using a key as a scalar

public scalarMult(point: Uint8Array, key: Uint8Array): Uint8Array

encodePoint: encodes a point representation to a string with either 'ASCII' or 'UTF-8' encoding

public encodePoint(point: Uint8Array, encoding: string): string

decodePoint: decode elliptic curve point from a string

public decodePoint(code: string, encoding: string): Uint8Array

addPoints: add two points on an elliptic curve

public addPoints(pointA: Uint8Array, pointB: Uint8Array): Uint8Array

subtractPoints: subtract two points on an elliptic curve

public subtractPoints(pointA: Uint8Array, pointB: Uint8Array): Uint8Array

OPRF Steps

1.) Client: hash input and mask it using a randomly generated 32-byte number

const input = 'hello world';
const masked = oprf.maskInput(input);

// Send masked.point to server,
// Do not send masked.mask to the server.
send(oprf.encodePoint(masked.point, 'UTF-8'));

2.) Server: salt the masked point using a secret key

// Note: your actual secret key should be fixed.
// Do not generate a new scalar for each OPRF
// application unless you have a specific use case for doing so.
const secretKey = oprf.generateRandomScalar();

const maskedPoint = oprf.decodePoint(receive(), 'UTF-8');
const salted = oprf.scalarMult(maskedPoint, secretKey);

// Send salted back to the client
send(oprf.encodePoint(salted, 'UTF-8'));

3.) Client: unmask the salted point from the server to get a high-entropy output

// Make sure that masked.mask corresponds to the original mask used.
// Otherwise, this will not give you the correct output.
const salted = oprf.decodePoint(receive(), 'UTF-8');
const unmasked = oprf.unmaskPoint(salted, masked.mask);

---

Implementation inspired by Burns et. al. https://pdfs.semanticscholar.org/5d33/ea1d3fda454875a6a6ee7c535c80c74af512.pdf