@cipherstash/ore-rs

ore-rs

ore-rs: Node bindings for ore.rs.

This project was bootstrapped by create-neon.

Installing ore-rs

Installing ore-rs requires a supported version of Node and Rust.

You can install the project with npm. In the project directory, run:

$ npm install

This fully installs the project, including installing any dependencies and running the build.

Building ore-rs

If you have already installed the project and only want to run the build, run:

$ npm run build

This command performs 2 steps:

1. It uses the cargo-cp-artifact utility to run the Rust build and copy the built library into ./index.node.
2. It compiles the TypeScript code (in src/index.ts) with the output being stored in dist

Exploring ore-rs

After building ore-rs, you can explore its exports at the TS Node REPL:

$ npm install
$ npx ts-node
> const ORE = require('.')
> import { ORE } from './src/index'
> let k1 = Buffer.from("1216a6700004fe46c5c07166025e681e", "hex")
> let k2 = Buffer.from("3f13a569d5d2c6ce8d2a85cb9e347804", "hex")
> let cipher = new ORE(k1, k2)
> let cipher = ORE.init(k1, k2)
> cipher.encrypt(100)

Comparison

To compare two encrypted ciphertext values, you can use the ORE.compare function which returns -1, 0 or 1 if the first operand is less-than, equal-to or greater than the second operand respectively.

Internally, this uses cmp.

let a = ore.encrypt(100)
let b = ore.encrypt(1560)
ORE.compare(a, b) // => -1

Data Types

ore-rs can encrypt the following types:

Number

JavaScript numbers are 64-bit floats which the underlying ORE library converts into an order-preserving integer. The underlying value no longer represents the source number (unlike f64::from(i)) but guarantees ordering is preserved.

// All valid
cipher.encrypt(456)
cipher.encrypt(3.14159)
cipher.encrypt(-100)

BigInt

BigInt value can also be encrypted but this will throw an error if the number requires more than 64-bits of storage. Neon doesn't actually support BigInt so the conversion is done in TypeScript using the writeBigUInt64BE function (see node.js docs so this will fail for negative numbers or values larger than 2n ** 64n - 1n.

cipher.encrypt(299792458n) // OK
cipher.encrypt(-100n) // fails!
cipher.encrypt(1180591620717411303424n) // fails!

Buffer

An 8-byte buffer can be encrypted directly. If the input is not exactly 8-bytes long, the operation will fail.

cipher.encrypt(Buffer.from([0x00, 0x12, 0x15, 0xfa, 0xcf, 0x1a, 0xdb, 0x38]) // OK
cipher.encrypt(Buffer.from([0x00, 0x12, 0x15]) // Fails!

Available Scripts

In the project directory, you can run:

npm install

Installs the project, including running npm run build.

npm build

Builds the Node addon (index.node) from source and compiles the TypeScript wrapper files.

Additional cargo build arguments may be passed to npm build and npm build-* commands. For example, to enable a cargo feature:

npm run build -- --feature=beetle

npm build-debug

Alias for npm build.

npm build-release

Same as npm build but, builds the module with the release profile. Release builds will compile slower, but run faster.

npm test

Runs the unit tests in Rust by calling cargo test and in TypeScript (Jest) by calling npx jest.

Project Layout

The directory structure of this project is:

ore-rs/
├── Cargo.toml
├── README.md
├── index.node
├── package.json
├── native/
|   └── lib.rs
├── src/
|   └── index.ts
|   └── index.test.ts
└── target/

Cargo.toml

The Cargo manifest file, which informs the cargo command.

README.md

This file.

index.node

The Node addon—i.e., a binary Node module—generated by building the project. This is the main module for this package, as dictated by the "main" key in package.json.

Under the hood, a Node addon is a dynamically-linked shared object. The "build" script produces this file by copying it from within the target/ directory, which is where the Rust build produces the shared object.

package.json

The npm manifest file, which informs the npm command.

native/

The directory tree containing the Rust source code for the project.

native/lib.rs

The Rust library's main module.

src/

TypeScript wrapper files - clients call this code rather than calling the functions in index.node directly.

target/

Binary artifacts generated by the Rust build.

Learn More

To learn more about Neon, see the Neon documentation.

To learn more about Rust, see the Rust documentation.

To learn more about Node, see the Node documentation.