zenroom

Zenroomjs

Zenroomjs provides a javascript wrapper of Zenroom, a secure and small virtual machine for crypto language processing. :floppy_disk: Install • :video_game: Usage • :heart_eyes: Acknowledgements • :busts_in_silhouette: Contributing • :briefcase: License :construction: Zenroom and Zenroomjs are software in ALPHA stage and are part of the DECODE project about data-ownership and technological sovereignty. Our effort is that of improving people's awareness of how their data is processed by algorithms, as well facilitate the work of developers to create along privacy by design principles using algorithms that can be deployed in any situation without any change.

:floppy_disk: Install

yarn add zenroom

---

:video_game: Usage

To start using the zenroom module just

import zenroom from 'zenroom'

the zenroomjs module is architectured as a Revealing Module Pattern this also means that once you set some options it will remain till the object lifetime, unless you reset or overwrite them.

Another used paradigm is method chaining this means that you can chain the different methods, let's see some hello worldish example:

import zenroom from 'zenroom'

const zencode = `print("hello world from zenroom in nodejs")`
zenroom.zencode(zencode).exec()

// prints in the console.log "hello world from zenroom in nodejs"

To initialize the options there are two ways, the one with the chaining that we saw before or a handy init() method to make them in one shot

// method chaining
zenroom.zencode('print("hello world")')
       .verbosity(1)
       .success(() => { console.log('everything goes smooth') })
       .error(() => { console.error('something very bad happened') })
       .exec()
       .reset() // cleans up the session

// using the init() method
options = {
	zencode: 'print("hello world")',
	verbosity: 1,
	success: () => { console.log('everything goes smooth') },
	error: () => { console.error('something very bad happened') }
}

zenroom.init(options).exec()

All the available options and method are covered in the next API section

---

:honeybee: API

script

Set the zenroom script to run

The syntax of the zenroom scripts are extensively available at https://zenroom.dyne.org/api/tutorials/Syntax.html You may want also to look at some example in a live executable environment here https://zenroom.dyne.org/demo/

Parameters

• script string the lua script to be set

Examples

Example usage of script()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")'
zenroom.script(script).exec().reset()

Returns zenroom the zenroom module

keys

Set the keys JSON for you zenroom execution

the keys will be available in script as the KEYS variable

Parameters

• keys object the keys to be set as an object

Examples

Example usage of keys()

// returns zenroom
import zenroom from 'zenroom'

const script = `
                 keys = JSON.decode(KEYS)
                 print(keys)
`

const keys = {a: 1, b: 2}
zenroom.script(script).keys(keys).exec().reset()

Returns object the zenroom module

conf

Set the conf before your zenroom execution

by now the only conf available is the string umm that sets the minimal memory manager (64KiB max)

Parameters

• conf string the string of configuration to be set

Examples

Example usage of conf()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")'
const conf = 'umm'
zenroom.script(script).conf(conf).exec()

Returns object the zenroom module

data

Set the data for your zenroom execution

The data will be available in script as the DATA variable

Parameters

• data string

Examples

Example usage of data()

// returns zenroom
import zenroom from 'zenroom'

const script = `
                 data = JSON.decode(DATA)
                 print(data)
`

const data = {a: 1, b: 2}
zenroom.script(script).data(data).exec()

Returns object the zenroom module

print

Set the print callback to customize the behaviour of the print calls made to stdout by default it prints to the console.log

Type: Function

Examples

Example usage of print()

// returns zenroom
import zenroom from 'zenroom'

const savedLines = []
const printFunction = (text) => { savedLines.push(text) }
const script = 'print("hello")'
zenroom.print(printFunction).script(script).exec()

Returns object the zenroom module

success

Set the success callback that is executed after a successful execution of zenroom

Type: Function

Examples

Example usage of success()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")'
zenroom.script(script).success(()=>{
   pleaseRunSomeOtherMethodAfter()
}).exec()

Returns object the zenroom module

error

Set the error callback that is executed after an unsuccessful execution of zenroom

Type: Function

Examples

Example usage of error()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")';
zenroom.script(script).error(()=>{
   pleaseRunSomeOtherMethodAfterError()
}).exec()

Returns object the zenroom module

verbosity

Set the verbosity of the stderr messages outputted by the zenroom virtual machine

As per now the set of accepted value:

• 1 = INFO
• 2 = DEBUG

Parameters

• verbosity number

Examples

Example usage of success

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")'
zenroom.script(script).success(()=>{
   pleaseRunSomeOtherMethodAfter();
}).exec()

Returns object the zenroom module

exec

Execute the zenroom vm (using the previously setted options)

It is usually the last method of the chain, but like the other methods returns the zenroom module itself, so can be used for other calls if you need to make more executions in a row

Examples

Example usage of exec()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")';
zenroom.script(script).exec()

Returns object the zenroom module

init

This method allows the configuration of your call by passing one configuration option object. You can use the chain methods after this anyway.

If some attribute is already set, those will be overwritten by the new options

The following options are available:

• script
• keys
• conf
• data
• print
• success
• error
• verbosity

Parameters

• options

Examples

Example usage of init()

// returns zenroom
import zenroom from 'zenroom'

const encrypt_secret_to_many = {
 script: `keyring = ECDH.new()
           secret = str(DATA)
           keys = JSON.decode(KEYS)
           keyring:private( base64(keys.keyring.secret) )
           res = {}
           for name,pubkey in pairs(keys.recipients) do
             pub = base64(pubkey)
             enc = ECDH.encrypt(keyring,pub,secret,keyring:public())
             res[name] = str( MSG.pack( map(enc,base64) ) ):base64()
           end
           print(JSON.encode(res))`,

 keys: {
     keyring : {
       public : "BHMjcDM/aljpi8pNxFQ436R6F3J+kaB/Xk1kAVFPmkoLVyeFltDZPgiIYRquh+m2IfvPioBfet7YCd5vVXYoRTk=",
       secret : "ChW5qi5y//ISDIHKx5Fvxl+XY8IyDGVBHUfELp3PqJQ="
     },
     recipients : {
       paulus : "BBUw6Nr3A30cN65maERvAk1cEv2Ji6Vs80kSlpodOC0SCtM8ucaS7e+s158uVMSr3BsvIXVspBeafiL8Qb3kcgc=",
       mayo : "BHqBoQ2WJ3/FGVNTXzdIc+K/HzNx05bWzEhn8m58FvSsaqWVdH52jI6fQWdkdjnbqVKCJGmbjA/OCJ+IKHbiySI=",
       mark : "BFgkjrRMvN+wkJ6qA4UvMaNlYBvl37C9cNYGkqOE4w43AUzkEzcyIIdE6BrgOEUEVefhOOnO6SCBQMgXHXJUUPY=",
       francesca : "BCo102mVybieKMyhex8tnVtFM5+Wo1oP02k8JVwKF9OLIjw7w0LmofItbuAcfWl9rcoe++XLI3sySZnqljIfeyU=",
       jim : "BEs1jeqL0nVwFi7OmG4YdtlWuKADyOvZR4XHpLAEswg8ONPXQHvwJ8+PkHkphoORfSjk2045bMdYkwboU4FdG2Y=",
       jaromil : "BBZYJtHvFg0vGCxPROAWrThcGZ+vFZJj86k+uncjvbm4DysIg7cWS3J6GrcJKCY55Uf40m2KfBwfaT+T7TTO1e8="
     }
 },

 data: 'This is a secret message.'
}


zenroom.init(encrypt_secret_to_many).exec()

Returns object the zenroom module

reset

Reset the setted options already provided and cleans up the zenroom module

It is usually the last method of the chain, but like the other methods returns the zenroom module itself, so can be used for other calls if you need to make more executions in a row

Examples

Example usage of reset()

// returns zenroom
import zenroom from 'zenroom'

const script = 'print("hello")';
zenroom.script(script)
       .exec()    // This runs the script
       .reset()
       .exec()    // This does not run the script anymore

Returns object the zenroom module

:heart_eyes: Acknowledgements

Copyright (C) 2018 by Dyne.org foundation, Amsterdam

Designed, written and maintained by Puria Nafisi Azizi.

This project is receiving funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement nr. 732546 (DECODE).

---

:busts_in_silhouette: Contributing

Please first take a look at the Dyne.org - Contributor License Agreement then

1. FORK IT
2. Create your feature branch git checkout -b feature/branch
3. Commit your changes git commit -am 'Add some fooBar'
4. Push to the branch git push origin feature/branch
5. Create a new Pull Request
6. Thank you

---

:briefcase: License

 Copyright 2018 Dyne.org foundation, Amsterdam

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.