Usage

The core Zenroom virtual machine exposes two primary functions by which cryptographic operations may be invoked:

• zenroom_exec which takes as input a script, as well as optional keys and data fields, and when invoked the output of the script is written to stdout.
• zenroom_exec_tobuf which takes the same basic parameters, but the output is written to a buffer provided by the caller.

For use in a library, this secondary function is the one that this library attempts to expose, simplified slightly to expose a more idiomatically Pythonic API surface.

Executing a simple script

The library only exposes a single function called execute, which passes its input parameters into the Zenroom VM, so to execute a simple script that does not require any data or keys, the library can be used simply as follows:

from zenroom import zenroom

script = b'print("Hello world!")'

output = zenroom.execute(script)

print(output)

This is a trite example obviously, but we wanted to demonstrate the simplest possible Zencode script execution, that a caller can capture.

Important

Note that the script value that is passed into the execute function must be a byte string. This is also true for any data or keys that are passed into Zenroom.

Executing a script with keys and data

The example below is more involved, and shows how we can execute a script with keys and data that must be fed into Zenroom to enable the script.

from zenroom import zenroom

script = b"""
-- define data schema
msg = SCHEMA.Record {
   msg = SCHEMA.String
}

-- read and validate the data
data = read_json(DATA, msg)

-- read keys without validating
keys = read_json(KEYS)

-- now import recipient public key
recipient_key = ECDH.new()
recipient_key:public(base64(keys.recipient_public))

-- now import our own private key (we are the data subject)
own = ECDH.new()
own:private(base64(keys.own_private))


-- encrypt the fields
out = {}
out = LAMBDA.map(data,function(k,v)
  header = MSG.pack({key=k, pubkey=own:public()})
  enc = ECDH.encrypt(own,recipient_key,str(v), header)
  oct = MSG.pack( map(enc,base64) )
  return str(oct):base64()
end)

-- print out result
print(JSON.encode(out))
"""

keys = b"""
{
  "own_private": "DYgWghvJuClxvHVCQSAfDpWQmeMQ4zh1/mGoNjM8UX0=",
  "own_public": "BAXRFKfMNSMge11U/cP+mCW2al166qIAY/cETmToEGmqe+4JnMdhmJ1FURvtUU+gA4QiEP+C7QFy/eoH+FDSRbw=",
  "recipient_public": "BCj962CsLq0Ey9Ibe6DEFSak4KqnQ5FhbNMv7MaMr6OzZZsnncUVOTrFK4Ym9WItAEMbpkGIOIjgfPESblAKlbw="
}
"""

data = b'{"msg":"top secret"}'

result = zenroom.execute(script, keys=keys, data=data)

# Here we'd actually do something with the output
print(result)

Note that the script parameter is the single required parameter, so here I pass it it first as a positional argument; keys and data in contrast are optional, so we choose to pass them as keyword arguments meaning we can label them when calling the function, so reducing the risk of getting the parameters in the wrong order.