PSA-lib

This javascript library was developed for building arbitrary PSA applications.

Compatibility

The library supports both CommonJS and ES Modules and runs in Node environments as well as in browsers.

Installation instructions

To install the library one just needs to execute

$ npm install psa-lib

in the project root. Import the library with

var PSA = require('psa-lib');

or

import PSA from 'psa-lib';

for CommonJS or ES Modules syntax, respectively.

Usage

When retrieving the context with either getClientContext or getServerContext, one should provide the polymodulus degree and the plaintext modulus.

The polymodulus degree can be one of:

• 4096
• 8192
• 16384

The plaintext modulus can be set arbitrarily. However, applications in the past, using the library, were using 33 bit.

For users who don't know how to choose the parameters, we recommend using 8192 as the polymodulus degree and 33 as the plaintext modulus. If the noise budget gets consumed, try using the next higher polymodulus degree .

Note: The application may run out of memory, depending on the polymodulus degree. A solution could be to specify a different compression mode such as 'none' or the slower 'zlib' over the default 'zstd'. In addition, you may need to increase the JavaScript heap size by adding --max-old-space-size=4096 for NodeJS.

Masking and differential privacy

The PSA library supports masking and a differential privacy. A user can use Hamming weight masking, binary masking and differential privacy by specifying it in the configuration object which is passed to the getClientContext/getServerContext call in the beginning.

Caveats

The library assumes that both parties agree on a set of parameters. The same parameters have to be passed into the getClientContext/getServerContext calls via a config object. A sample config object is provided here:

const psaConf = {
  polyModulusDegree: 8192,          -> degree of the polynomial modulus
  plainModulusBitSize: 33,          -> plaintext modulus bitcount
  securityLevel: 128,               -> security bits
  compression: 'zstd',              -> compression method
  maskHW: true,                     -> hamming weight masking enabled
  minHW: BigInt(100),               -> minimum hamming weight required by the client vector
  maskBin: true,                    -> binary masking enabled
  createGkIndices: true,            -> using galois indices for key creation
  diffPriv: true,                   -> differential privacy enabled
  sensitivity: 1,                   -> sensitivity parameter for differential privacy
  epsilon: 1.0                      -> epsilon parameter for differential privacy
};

It does not pose a security risk if one party uses different parameters. However, system failures will occur.

Contributing

We are happy to welcome everyone who is willing to contribute. The workflow is as follows:

1. Write your code in .mjs files, use ES Modules syntax and always document the code in JSDoc style
2. Transpile the files to CommonJS module syntax with npm run build
3. Apply code formatting with Prettier with npm run format
4. Generate documentation with npm run docs
5. Create a Pull Request in GitHub, so we can review the changes and apply them

API docs

Table of Contents

• getClientContext
  • Parameters
• getServerContext
  • Parameters
• clientEncrypt
  • Parameters
• clientDecrypt
  • Parameters
• serverCompute
  • Parameters
• stringify
  • Parameters
• parse
  • Parameters

getClientContext

This asynchronous function return the client context object.

Parameters

• psaConf Object an configuration object holding all configurations needed for execution (same as server config)
  • psaConf.polyModulusDegree number the polymodulus degree (optional, default 8192)
  • psaConf.plainModulusBitSize number the bit size of the plaintext modulus prime that will be generated (optional, default 33)
  • psaConf.securityLevel (128 | 192 | 256) the security level in bits (default = 128) (optional, default 128)
  • psaConf.compressionMode ("none" | "zlib" | "zstd") Optional compression mode for serialization (default = zstd) (optional, default 'zstd')
  • psaConf.maskHW boolean whether Hamming weight masking should be applied (optional, default true)
  • psaConf.minHW BigInt smallest allowed Hamming weight (optional, default BigInt(100))
  • psaConf.maskBin boolean whether binary masking should be applied (optional, default true)
  • psaConf.createGkIndices (optional, default true)

Returns Object a context object necessary for client side actions

getServerContext

This asynchronous function return the server context object.

Parameters

• psaConf Object an configuration object holding all configurations needed for execution (same as client config)
  • psaConf.polyModulusDegree number the polymodulus degree (optional, default 8192)
  • psaConf.plainModulusBitSize number the bit size of the plaintext modulus prime that will be generated (optional, default 33)
  • psaConf.securityLevel (128 | 192 | 256) the security level in bits (default = 128) (optional, default 128)
  • psaConf.compressionMode ("none" | "zlib" | "zstd") Optional compression mode for serialization (default = zstd) (optional, default 'zstd')
  • psaConf.maskHW boolean whether Hamming weight masking should be applied (optional, default true)
  • psaConf.minHW BigInt smallest allowed Hamming weight (optional, default BigInt(100))
  • psaConf.maskBin boolean whether binary masking should be applied (optional, default true)
  • psaConf.diffPriv boolean whether differential privacy should be applied (optional, default false)
  • psaConf.createGkIndices (optional, default true)
  • psaConf.sensitivity (optional, default Number.MAX_SAFE_INTEGER/2)
  • psaConf.epsilon (optional, default 1.0)

Returns Object a context object necessary for client side actions

clientEncrypt

This function encrypts the client's input vector and returns an object ready to be sent to the server.

Parameters

• inputArray Array<number> 1D array of numbers
• clientContext Object client side context
• serialize Object true if output should be stringified (optional, default true)

Returns (Object | string) Context object in optionally unstringified form to be sent to server for serverCompute()

clientDecrypt

This function decrypts the server response object. The result will be in the first n cells, if the matrix was of dimension (m x n).

Parameters

• serverResponseObject (Object | string) server response object (JSON string or Object), received from the server
• clientContext Object client side context

Returns Array<BigUint64Array> resulting array

serverCompute

This function computes the dot product between the encrypted client vector and the server matrix. Constraints: If vector is of dimensions (1 x m), then matrix has to be of (m x n).

Parameters

• clientRequestObject (string | Object) client request object (JSON string or Object), received from client
• matrix Array<number> a 2D array of Numbers.
• serverContext Object server side context
• serialize boolean true if output should be stringified

Returns Promise Promise returning a context object in optionally unstringified form to be sent to client for decryption with clientDecrypt()

stringify

This function is a replacement for JSON.stringify() since it is missing the functionality to stringify BigInts.

Parameters

• value Object the object to be stringified

Returns string the resulting JSON string

parse

This function is a replacement for JSON.parse() and adds the functionality to parse BigInts, since this is necessary for this protocol.

Parameters

• text string JSON string

Returns Object the parsed object

Acknowledgements

This project has received funding from the European Union’s Horizon 2020 research and innovation program under grant agreement No 825225.