node-seal v5.1.4

node-seal ·

node-seal is a homomorphic encryption library for TypeScript or JavaScript.

• Web Assembly: Fastest web implementation of the C++ Microsoft SEAL library
• Zero dependencies: Very lean, only contains a low level API which is very close to the C++ calls from Microsoft SEAL.
• Node.js, Browser: Install once, work in any server/client configuration.

Now supporting Microsoft SEAL 4.1.2

Installation

node-seal can be installed with your favorite package manager:

npm install node-seal

yarn add node-seal

Import the library using import or require syntax:

// Auto-detects browser or nodejs.
// Defaults to "node-seal/throws_wasm_node_umd" for NodeJS
// Defaults to "node-seal/throws_wasm_web_umd" for Browsers
// Defaults to "node-seal/throws_wasm_web_es" for Modules
import SEAL from 'node-seal'
const SEAL = require('node-seal')

You may also specify a deep import to target your environment better. This is useful for environments that aren't detected properly or do not support WebAssembly. In addition, there are two separate bundles for throwing on transparent ciphertexts and another for allowing transparent ciphertexts. If you're unsure what you need, start with the build that throws on transparent ciphertexts. This is also the default import that is used.

The deep import link is structured like the following:

node-seal / <throws|allows>_wasm_<node|web|worker>_<umd|es>

// Always Pick a variant which throws on transparent ciphertexts unless you
// have a specific reason to allow the use of transparent ciphertexts.
import SEAL from 'node-seal/throws_wasm_node_umd'

// Or pick a variant which allows transparent ciphertexts (only use this if you know what you're doing)
import SEAL from 'node-seal/allows_wasm_node_umd'

React-Native

React-native does not support WASM libraries; however, it is possible to run a WASM library, including node-seal by using a WebView to load both the library and a simple interface to communicate with on top of the built-in postMessage API. Instead of publicly hosting the web application to be rendered by the WebView, it is possible to bundle the mini web application into a single HTML file (with JS inlined) and load the HTML file directly to the WebView.

Demo

Go to the sandbox

This sandbox was built for users to experiment and learn how to use Microsoft SEAL featuring node-seal.

• Encryption Parameters: experiment with many settings to prototype a context.
• Keys: Create, download, upload Secret/Public Keys - even for Relinearization and Galois Keys.
• Variables: Create, download, upload PlainTexts or CipherTexts
• Functions: Create a list of HE functions to execute!
• Code Generation: After your experimentation is complete, generate working code to use!

Usage

Checkout the basics

Documentation

View the latest docs here

Examples

Check out the Sandbox to run HE functions and even generate working code!

If you'd rather read an example, take a look here.

For more exhaustive examples, view the tests.

Changes

For changes in this library, take a look here.

For changes in Microsoft SEAL, take a look at their list of changes.

Benchmarking

Microsoft SEAL has a native benchmark tool that we compile directly to WASM.

1. npm run seal:build:bench
2. npm run benchmark

Performance

Microsoft SEAL now comes with a benchmark binary that can be directly compiled to WASM. All numbers are measured in us and are ran on an arm64 system

Test specs:

• MacBook Pro (14-inch, 2021)
• MacOS Ventura 13.1 (22C65)
• Apple M1 Pro (8 performance and 2 efficiency), 32 GB

Versions:

• Microsoft SEAL v4.1.0
• Node-seal v5.1.0
• NodeJS v18.12.1
• Chrome Version 108.0.5359.124 (Official Build) (arm64)
• Firefox Version 108.0.1 (64-bit)
• Safari Version 16.2 (18614.3.7.1.5)

Caveats

Conversion from C++ to Web Assembly has some limitations:

• ±2^53 bit numbers: JavaScript uses 2^53 numbers (not true 64 bit). This means we lose some precision after cryptographic operations are computed in WASM and we want to send the results to JS for consumption (across the WASM <> JS boundary). If you're using the CKKS scheme, you need to keep this in mind. BFV users will inherently adhere to these limitations due to the Int32Array/Uint32Array TypedArrays. Recently, BFV users now have support for BigInt64Array/BigUint64Array TypedArrays but at a significant encode/decode penalty - encyption/evaluation/decryption performance is the same.

• Memory: Generating large keys and saving them in the browser could be problematic. We can control NodeJS heap size, but not inside a user's browser.

  Saving keys is very memory intensive especially for polyModulusDegreess above 16384. This is because there's currently no way (that we have found) to use io streams across JS and Web Assembly code, so the strings have to be buffered completely in RAM and they can be very, very large when using the default zstd compression. User's who are experiencing OOM exceptions when saving GaloisKeys should try specifying a compression override such as none or the less performant zlib. Ex: galoisKeys.save(seal.ComprModeType.zlib)

• Garbage Collection: Unfortunately, the typical way of cleaning up dereferenced JS objects will leave behind a the Web Assembly (C++) object in memory. There is no way to automatically call the destructors on C++ objects. JavaScript code must explicitly delete any C++ object handles it has received, or the heap will grow indefinitely.

  <instance>.delete()

Contributing

The main purpose of this library is to continue to evolve and promote the adoption of homomorphic encryption (using Microsoft SEAL) in modern web applications today. Development of node-seal happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements.

See CONTRIBUTING.md.

License

node-seal is MIT licensed.