Browse Source
* ๐ New documentation system (docsify)
* Moved the old docs `docs.old`
* parse mermaid within the doc system
* parse gv/dot within the doc system
* parse bibtex within the doc system (for the whitepaper)
* removed the submodules for the old doc system (webnomad/zuper)
* Ldocs
* /encrypt
* makefile to build and parse code snippets
* small fix makefiles and docgen
* fix to javascript build
small target to facilitate emsdk loading
* added CNAME for dev.zenroom.org
Co-authored-by: Jaromil <jaromil@dyne.org>, Andrea <andrea@dyne.org>
master
GitHub
179 changed files with 12621 additions and 368 deletions
@ -1,9 +1,3 @@ |
|||
[submodule "docs/article/writedown"] |
|||
path = docs/article/writedown |
|||
url = https://github.com/dyne/writedown |
|||
[submodule "docs/webnomad"] |
|||
path = docs/webnomad |
|||
url = https://github.com/dyne/webnomad |
|||
[submodule "docs/wiki"] |
|||
path = docs/wiki |
|||
path = docs.old/wiki |
|||
url = https://github.com/DECODEproject/zenroom.wiki.git |
|||
|
|||
@ -0,0 +1,44 @@ |
|||
.PHONY: article website preview |
|||
ARTICLE := Zenroom_Cryptolang_Whitepaper |
|||
DEST := pub |
|||
|
|||
all: api website |
|||
|
|||
# api output is website/docs/lua
|
|||
api: |
|||
make -C ldoc |
|||
|
|||
# output is website/site
|
|||
# download js from our CI
|
|||
# import wiki pages
|
|||
# import changelog
|
|||
website: |
|||
@if ! [ -r website/docs/js/zenroom.js -o -r website/docs/js/zenroom.wasm ]; then curl https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.wasm https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.js https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.data -o website/docs/js/zenroom.wasm -o website/docs/js/zenroom.js -o website/docs/js/zenroom.data; fi |
|||
@mkdir -p website/docs/encrypt && cp -v website/docs/js/zenroom.data website/docs/encrypt/ |
|||
@mkdir -p website/docs/wiki |
|||
@cp -v wiki/Build.md website/docs/wiki/how-to-build.md |
|||
@cp -v wiki/Execute.md website/docs/wiki/how-to-exec.md |
|||
@cp -v wiki/Embed.md website/docs/wiki/how-to-embed.md |
|||
@cp -v ../ChangeLog.md website/docs/changelog.md |
|||
@cp -v zencode_diagram.png website/docs/img |
|||
@cp -v ../test/zencode_coconut/*.zen website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.zen website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.keys website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.data website/docs/examples/ |
|||
@cp -v ../examples/*.keys ../examples/*.data ../examples/*.lua website/docs/examples/ |
|||
@cd website && mkdocs build |
|||
|
|||
map: |
|||
./parse_zencode.sh | json_pp > zencode_utterances.json |
|||
|
|||
preview: |
|||
cd website && ./mkdocs-dyne-theme/.preview |
|||
|
|||
deploy: api website |
|||
cd website && ./mkdocs-dyne-theme/.deploy |
|||
|
|||
clean: |
|||
@rm -rf website/docs/lua |
|||
@rm -rf website/docs/wiki |
|||
@rm -rf website/site |
|||
@echo "Zenroom website cleaned up" |
|||
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 2.1 KiB After Width: | Height: | Size: 2.1 KiB |
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 78 KiB |
|
Before Width: | Height: | Size: 4.4 KiB After Width: | Height: | Size: 4.4 KiB |
@ -0,0 +1,319 @@ |
|||
var ZR = (function() { |
|||
let autocompleteWords = [] |
|||
let outputBuffer = [] |
|||
let layout = null |
|||
|
|||
const initialConfig = { |
|||
settings: { |
|||
showPopoutIcon: false, |
|||
showCloseIcon: false, |
|||
}, |
|||
dimensions: { |
|||
headerHeight: 28 |
|||
}, |
|||
content: [{ |
|||
type: 'row', |
|||
content: [{ |
|||
type: 'stack', |
|||
id: 'container', |
|||
content: [{ |
|||
type: 'component', |
|||
title: 'ZENCODE', |
|||
componentName: 'ZencodeEditor', |
|||
componentState: { label: 'zencode' }, |
|||
isClosable: false, |
|||
}, { |
|||
type: 'component', |
|||
title: 'LUA', |
|||
componentName: 'CodeEditor', |
|||
componentState: { label: 'code' }, |
|||
isClosable: false, |
|||
}] |
|||
}, { |
|||
type: 'column', |
|||
content: [{ |
|||
type: 'stack', |
|||
content: [{ |
|||
type: 'component', |
|||
title: 'KEYS', |
|||
componentName: 'JsonEditor', |
|||
componentState: { label: 'keys' }, |
|||
isClosable: false, |
|||
}, { |
|||
type: 'component', |
|||
title: 'DATA', |
|||
componentName: 'JsonEditor', |
|||
componentState: { label: 'data' }, |
|||
isClosable: false, |
|||
}] |
|||
}, { |
|||
type: 'stack', |
|||
content: [{ |
|||
type: 'component', |
|||
componentName: 'OUTPUT', |
|||
componentState: { label: 'output' }, |
|||
isClosable: false, |
|||
}, { |
|||
type: 'component', |
|||
componentName: 'LOGS', |
|||
componentState: { label: 'logs' }, |
|||
isClosable: false, |
|||
}] |
|||
}] |
|||
}] |
|||
}] |
|||
} |
|||
|
|||
const loadExamples = (e) => { |
|||
const name = $(e.target).attr('id') |
|||
const extensions = {'#code': '.lua', '#data': '.data', '#keys': '.keys'} |
|||
const base_url = "/examples/" |
|||
for (var e in extensions) { |
|||
const editor = $(e)[0].env.editor |
|||
editor.setValue("") |
|||
$.get(base_url + name + extensions[e], value => { |
|||
editor.setValue(value) |
|||
}) |
|||
} |
|||
return false; |
|||
} |
|||
|
|||
|
|||
const loadZencodeExamples = (e) => { |
|||
const name = $(e.target).attr('id'); |
|||
const extensions = {'#zencode': '.zen', '#data': '.data', '#keys': '.keys'} |
|||
const base_url = "/examples/" |
|||
for (var e in extensions) { |
|||
const editor = $(e)[0].env.editor |
|||
editor.setValue("") |
|||
$.get(base_url + name + extensions[e], value => { |
|||
editor.setValue(value) |
|||
}) |
|||
} |
|||
} |
|||
|
|||
const loadCoconutExamples = (e) => { |
|||
const name = $(e.target).attr('id'); |
|||
const base_url = "https://raw.githubusercontent.com/DECODEproject/zenroom/master/test/zencode_coconut/" |
|||
const editor = $('#zencode')[0].env.editor |
|||
editor.setValue("") |
|||
$.get(base_url + name, value => { |
|||
editor.setValue(value) |
|||
}) |
|||
} |
|||
|
|||
const setupCodeEditor = editor => { |
|||
editor.setOptions({ |
|||
enableBasicAutocompletion: true, |
|||
enableLiveAutocompletion: true, |
|||
}); |
|||
editor.session.setMode("ace/mode/lua"); |
|||
editor.commands.addCommand({ |
|||
name: 'run', |
|||
bindKey: {win: 'Ctrl-Enter', mac: 'Command-Enter'}, |
|||
exec: () => { |
|||
} |
|||
}); |
|||
editor.commands.addCommand({ |
|||
name: 'clear', |
|||
bindKey: {win: 'Ctrl-l', mac: 'Ctrl-l'}, |
|||
exec: editor => { $("#output").html("") } |
|||
}); |
|||
editor.focus(); |
|||
} |
|||
|
|||
const setupCodeEditorComponent = function(container, state) { |
|||
container.getElement().html(`<div style="height:100%" id="${state.label}"></div>`) |
|||
container.on('open', ()=>{ |
|||
const editor = ace.edit(state.label); |
|||
setupCodeEditor(editor) |
|||
}) |
|||
} |
|||
|
|||
const setupZencodeEditorComponent = function(container, state) { |
|||
container.getElement().html(`<div style="height:100%" id="${state.label}"></div>`) |
|||
container.on('open', () => { |
|||
const editor = ace.edit(state.label) |
|||
editor.session.setMode("ace/mode/gherkin") |
|||
container.extendState({editor: editor}) |
|||
}) |
|||
} |
|||
|
|||
const setupJsonEditorComponent = function(container, state) { |
|||
container.getElement().html(`<div style="height:100%" id="${state.label}"></div>`) |
|||
container.on('open', () => { |
|||
const editor = ace.edit(state.label) |
|||
editor.session.setMode("ace/mode/json") |
|||
container.extendState({editor: editor}) |
|||
}) |
|||
} |
|||
|
|||
const setupOutputComponent = function(container, state) { |
|||
container.getElement().html(`<div style="height:100%" class="has-background-dark has-text-light" id="${state.label}"></div>`) |
|||
var elapsed = $('<span class="tag" id="timing">0 ms</span>') |
|||
container.on('tab', tab => { |
|||
tab.element.append(elapsed) |
|||
}) |
|||
} |
|||
|
|||
const setupLogsComponent = function(container, state) { |
|||
container.getElement().html(`<div style="height:88%" id="${state.label}"></div>`) |
|||
} |
|||
|
|||
const bindAutoFocus = function(stack) { |
|||
stack.on('activeContentItemChanged', item => { |
|||
const state = item.container.getState() |
|||
if ("editor" in state) { |
|||
state.editor.focus() |
|||
} |
|||
}); |
|||
} |
|||
|
|||
const clearOutput = () => $("#output,#logs").html(''); |
|||
|
|||
const addControls = function(stack) { |
|||
const component = stack.contentItems[0] |
|||
if (!component) |
|||
return |
|||
if (component.componentName == 'ZencodeEditor') { |
|||
const button = $($('#play-button-template').html()) |
|||
stack.header.controlsContainer.prepend(button) |
|||
button.on('click', ()=>{ |
|||
setTimeout(zenroom, 100) |
|||
}) |
|||
} |
|||
|
|||
if (component.componentName == 'OUTPUT') { |
|||
const copyButton = $($('#copy-button-template').html()) |
|||
const button = $($('#clear-button-template').html()) |
|||
stack.header.controlsContainer.prepend(copyButton) |
|||
stack.header.controlsContainer.prepend(button) |
|||
button.on('click', clearOutput) |
|||
} |
|||
} |
|||
|
|||
const loadConfig = () => { |
|||
return localStorage.getItem('savedState') || initialConfig |
|||
} |
|||
|
|||
const layoutInit = () => { |
|||
layout = new GoldenLayout(loadConfig()); |
|||
layout.registerComponent('CodeEditor', setupCodeEditorComponent) |
|||
layout.registerComponent('JsonEditor', setupJsonEditorComponent) |
|||
layout.registerComponent('ZencodeEditor', setupZencodeEditorComponent) |
|||
layout.registerComponent('OUTPUT', setupOutputComponent) |
|||
layout.registerComponent('LOGS', setupLogsComponent) |
|||
layout.on('stackCreated', bindAutoFocus) |
|||
layout.on('stackCreated', addControls) |
|||
layout.init() |
|||
} |
|||
|
|||
const init = function() { |
|||
layoutInit() |
|||
$(".examples").on('click', e => loadExamples(e)) |
|||
$(".zencode").on('click', e => loadZencodeExamples(e)) |
|||
// $(".coconut").on('click', e => loadCoconutExamples(e))
|
|||
}; |
|||
|
|||
const addAutocompletionWord = word => { |
|||
autocompleteWords.push(word) |
|||
} |
|||
|
|||
const autocompleteSetup = () => { |
|||
$.get('https://raw.githubusercontent.com/DECODEproject/zenroom/master/docs/completions.lua', data => { |
|||
Module.ccall('zenroom_exec', |
|||
'number', |
|||
['string', 'string', 'string', 'string'], |
|||
[data, null, null, null]); |
|||
Module['print'] = (function() { |
|||
return function(text) { |
|||
if (arguments.length > 1) text = Array.prototype.slice.call(arguments).join(' '); |
|||
outputBuffer.push(text) |
|||
}; |
|||
})() |
|||
const langTools = ace.require("ace/ext/language_tools"); |
|||
const cryptoCompleter = { |
|||
getCompletions: function(editor, session, pos, prefix, callback) { |
|||
if (prefix.length === 0) { callback(null, []); return } |
|||
callback(null, autocompleteWords.map(word => ({name: word, value: word, meta: 'zenroom'}))) |
|||
} |
|||
} |
|||
langTools.addCompleter(cryptoCompleter) |
|||
}) |
|||
} |
|||
|
|||
const flushOutput = () => { |
|||
renderedJson = null |
|||
if (outputBuffer.length == 1) { |
|||
try { |
|||
renderjson.set_show_to_level(2); |
|||
renderedJson = renderjson(JSON.parse(outputBuffer)) |
|||
} catch {} |
|||
} |
|||
var resultBuffer = outputBuffer.join('<br/>') |
|||
$('#output').append(renderedJson||resultBuffer) |
|||
$('#copyOutput').removeClass('has-text-grey-light'); |
|||
$('#copyOutput').off('click').on('click', function() { |
|||
$(this).addClass('has-text-grey-light') |
|||
var $temp = $("<input>"); |
|||
$("body").append($temp); |
|||
$temp.val(outputBuffer).select(); |
|||
document.execCommand("copy"); |
|||
$temp.remove(); |
|||
}) |
|||
} |
|||
|
|||
const execute_zenroom = function(code, zencode) { |
|||
const keys = ace.edit("keys").getValue() || null |
|||
const data = ace.edit("data").getValue() || null |
|||
// const conf = $('#umm').attr('checked') ? 'umm' : null
|
|||
const conf = `verbose 3` |
|||
outputBuffer = [] |
|||
clearOutput() |
|||
let t0 = performance.now() |
|||
Module.ccall(zencode ? 'zencode_exec' : 'zenroom_exec', |
|||
'number', |
|||
['string', 'string', 'string', 'string'], |
|||
[code, conf, keys, data]); |
|||
let t1 = performance.now() |
|||
// console.log(t1-t0, 'ms')
|
|||
flushOutput() |
|||
$('#timing').html(Math.ceil(t1-t0) + 'ms') |
|||
$('#output')[0].scrollTop = $('#output')[0].scrollHeight |
|||
} |
|||
|
|||
const zenroom = function() { |
|||
const activeEditor = layout.root.getItemsById('container')[0].getActiveContentItem().container.getState().label |
|||
let code = ace.edit(activeEditor).getValue() |
|||
execute_zenroom(code, (activeEditor==='zencode')) |
|||
} |
|||
|
|||
return { |
|||
init: init, |
|||
zenroom: zenroom, |
|||
addAutocompletionWord: addAutocompletionWord, |
|||
autocompleteSetup: autocompleteSetup |
|||
} |
|||
})(); |
|||
|
|||
var Module = { |
|||
preRun: [ZR.autocompleteSetup], |
|||
postRun: [], |
|||
print: (()=> { |
|||
return text => { |
|||
ZR.addAutocompletionWord(text) |
|||
} |
|||
})(), |
|||
printErr: function(text) { |
|||
let bg = '' |
|||
let elements = '#logs' |
|||
if (arguments.length > 1) text = Array.prototype.slice.call(arguments).join(' '); |
|||
if (text.startsWith('[!]')) bg = 'has-background-danger has-text-light' |
|||
if (text.startsWith('[W]')) bg = 'has-background-warning' |
|||
if (bg) elements = '#logs, #output' |
|||
|
|||
$(`<span class="${bg}">${text}</span><br>`).appendTo(elements) |
|||
}, |
|||
exec_ok: () => {}, |
|||
exec_error: () => {}, |
|||
} |
|||
@ -0,0 +1,170 @@ |
|||
<!DOCTYPE html> |
|||
<html> |
|||
|
|||
<head> |
|||
<meta charset="utf-8"> |
|||
<meta name="viewport" content="width=device-width, initial-scale=1"> |
|||
<title>Zenroom online demo</title> |
|||
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/bulma/0.7.2/css/bulma.min.css"> |
|||
<link rel="stylesheet" href="//golden-layout.com/files/latest/css/goldenlayout-base.css" /> |
|||
<link rel="stylesheet" href="//golden-layout.com/files/latest/css/goldenlayout-light-theme.css" /> |
|||
|
|||
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Montserrat:300,500"> |
|||
<script defer src="//use.fontawesome.com/releases/v5.5.0/js/all.js"></script> |
|||
<script src="//code.jquery.com/jquery-3.3.1.min.js" integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=" crossorigin="anonymous"></script> |
|||
<script src="//golden-layout.com/files/latest/js/goldenlayout.min.js"></script> |
|||
<script src="//cdnjs.cloudflare.com/ajax/libs/ace/1.3.1/ace.js"></script> |
|||
<script src="//cdnjs.cloudflare.com/ajax/libs/ace/1.3.1/ext-language_tools.js"></script> |
|||
<script src="//rawgit.com/caldwell/renderjson/master/renderjson.js"></script> |
|||
<script src="./shell.js"></script> |
|||
<style> |
|||
body { font-family: Montserrat, sans-serif; font-size: 16px; } |
|||
#logs, #output { font-family: "Monaco", "Menlo", "Ubuntu Mono", "Consolas", "source-code-pro", monospace; overflow: auto; padding: 5px; } |
|||
#logs { overflow: scroll } |
|||
#zenbar .navbar-start a.navbar-item::before { content: " "; height: 10px; width: 10px; background-color: #33e986; margin-right: 10px; display: inline-block; } |
|||
#zenbar .navbar-start a.navbar-item:hover::before { background-color: #ff00ff; } |
|||
#zenbar .navbar-item { padding-left: 1em; padding-right: 1em; } |
|||
#zenbar .navbar-item img { padding-left: 1em; padding-right: 2em; } |
|||
.navbar-item .examples { background-color: #efefef } |
|||
.lm_header .lm_tab { font-family: Montserrat; font-size: 14px; height: 21px; } |
|||
.lm_header .lm_controls>li, .icon { height: 28px; width: 40px; } |
|||
.lm_controls > li { background-size: 15px; } |
|||
.renderjson { background-color: transparent; height: 100%;} |
|||
.renderjson a { text-decoration: none; } |
|||
.renderjson .disclosure { color: crimson; } |
|||
.renderjson .syntax { color: grey; } |
|||
.renderjson .string { color: red; } |
|||
.renderjson .number { color: cyan; padding:0; font-size: inherit; background-color: transparent; height: auto; } |
|||
.renderjson .boolean { color: plum; } |
|||
.renderjson .key { color: lightblue; } |
|||
.renderjson .keyword { color: lightgoldenrodyellow; } |
|||
.renderjson .object.syntax { color: lightseagreen; } |
|||
.renderjson .array.syntax { color: lightsalmon; } |
|||
#timing { height: auto; position: relative; bottom: 6px; margin-left: 4px; } |
|||
#play-button { font-size:18px; right:14px; opacity: .6 } |
|||
๏ฟผ #play-button svg { margin-left: 2px; } |
|||
</style> |
|||
</head> |
|||
|
|||
<body> |
|||
<template type="text/html" id="play-button-template"> |
|||
<li title="Run (โ/Ctrl + Enter)"> |
|||
<span class="icon has-text-success"> |
|||
RUN <i class="fas fa-play-circle"></i> |
|||
</span> |
|||
</li> |
|||
</template> |
|||
<template type="text/html" id="clear-button-template"> |
|||
<li> |
|||
<span class="icon has-text-grey-light"> |
|||
<i class="fas fa-toilet-paper"></i> |
|||
</span> |
|||
</li> |
|||
</template> |
|||
<template type="text/html" id="copy-button-template"> |
|||
<li id="copyOutput"> |
|||
<span class="icon"> |
|||
<i class="fas fa-copy"></i> |
|||
</span> |
|||
</li> |
|||
</template> |
|||
<div class="container is-fluid"> |
|||
<nav class="navbar" role="navigation" aria-label="main navigation"> |
|||
<div class="navbar-brand"> |
|||
<a class="navbar-item" href="https://dev.zenroom.org/"> |
|||
Zenroom <img src="/img/zenroom_logo-sm.jpg"> <!-- width="112" height="28"> --> |
|||
secure crypto language VM - in-browser demo |
|||
</a> |
|||
<a role="button" class="navbar-burger burger" aria-label="menu" aria-expanded="false" data-target="zenbar"> |
|||
<span aria-hidden="true"></span> |
|||
<span aria-hidden="true"></span> |
|||
<span aria-hidden="true"></span> |
|||
</a> |
|||
</div> |
|||
|
|||
<div id="zenbar" class="navbar-menu"> |
|||
<div class="navbar-start"> |
|||
<a class="navbar-item" href="https://dyne.org/"> |
|||
software by <img src="/img/dyne-big.png" height="28" alt="Dyne.org" /> |
|||
</a> |
|||
|
|||
<!-- <a class="navbar-item" href="https://milagro.apache.org/"> --> |
|||
<!-- powered by <img src="/img/milagro.svg" height="28" alt="Milagro" /> --> |
|||
<!-- </a> --> |
|||
<!-- </div> --> |
|||
|
|||
<!-- <div class="navbar-end"> --> |
|||
<div class="navbar-item has-dropdown is-hoverable"> |
|||
<a class="navbar-link"> |
|||
Examples |
|||
</a> |
|||
<div class="navbar-dropdown"> |
|||
<a class="navbar-item zencode" id="RNG01">Generate many random cryptographic objects</a> |
|||
<a class="navbar-item zencode" id="SYM02">Encrypt a message using a password</a> |
|||
<a class="navbar-item zencode" id="SYM03">Decrypt a secret message using a password</a> |
|||
<a class="navbar-item zencode" id="AES01">Generate a keypair</a> |
|||
<a class="navbar-item zencode" id="AES05">Encrypt a message for a public key recipient</a> |
|||
<a class="navbar-item zencode" id="AES07">Decrypt a secret message using a-symmetric encryption</a> |
|||
<a class="navbar-item zencode" id="DSA01">Sign a message using public-key encryption</a> |
|||
<a class="navbar-item zencode" id="DSA02">Verify a signature using public-key encryption</a> |
|||
<hr class="navbar-divider"> |
|||
<a class="navbar-item examples" id="hello">Hello world in hex and base64</a> |
|||
<a class="navbar-item examples" id="keygen">Generate a new pair of public / privatekeys</a> |
|||
<a class="navbar-item examples" id="symmetric-crypto-pin">Protect a secret using a password</a> |
|||
<a class="navbar-item examples" id="keygen-multi">Generate a keyring with multiple recipients</a> |
|||
<a class="navbar-item examples" id="crypt-to-multi">Encrypt a secret to multiple recipients</a> |
|||
<a class="navbar-item examples" id="iotdev-to-dashboard">IoT sensor encode and send with key</a> |
|||
<a class="navbar-item examples" id="dashboard-from-iotdev">Receive and decode IoT sensor messages</a> |
|||
</div> |
|||
</div> |
|||
<!-- <div class="navbar-item"> |
|||
<div class="buttons"> |
|||
<input id="umm" class="form-check-input" type="checkbox" value=""> minimal memory manager (64KiB max) |
|||
</div> |
|||
</div> --> |
|||
</div> |
|||
</div> |
|||
</nav> |
|||
</div> |
|||
<section id="ide"></section> |
|||
<div class="modal is-active"> |
|||
<div class="modal-background"></div> |
|||
<div class="modal-card"> |
|||
<header class="modal-card-head"> |
|||
<p class="modal-card-title">Disclaimer</p> |
|||
<button class="delete close" aria-label="close"></button> |
|||
</header> |
|||
<section class="modal-card-body"> |
|||
Zenroom โ secure crypto language VM<br/> |
|||
Copyright (C) 2017-2020 โ <a href="https://dyne.org">Dyne.org foundation</a>, Amsterdam<br/> |
|||
For the original source code and documentation go to <a href="https://zenroom.org">zenroom.org</a><br/> |
|||
Zenroom is free software: you can redistribute it and/or modify |
|||
it under the terms of the GNU Affero General Public License as |
|||
published by the Free Software Foundation, either version 3 of the |
|||
License, or (at your option) any later version.<br/> |
|||
Zenroom is distributed in the hope that it will be useful, |
|||
but WITHOUT ANY WARRANTY; without even the implied warranty of |
|||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|||
GNU Affero General Public License for more details. |
|||
You should have received a copy of the GNU Affero General Public License |
|||
along with this program. If not, see <a href="http://www.gnu.org/licenses/">www.gnu.org/licenses</a>. |
|||
</section> |
|||
<footer class="modal-card-foot"> |
|||
<button class="button is-success close">I'm aware</button> |
|||
</footer> |
|||
</div> |
|||
</div> |
|||
|
|||
{{{ SCRIPT }}} |
|||
<script> |
|||
ZR.init() |
|||
$(document).ready(function() { |
|||
$(".navbar-burger").click(() => { |
|||
$(".navbar-burger").toggleClass("is-active"); |
|||
$(".navbar-menu").toggleClass("is-active"); |
|||
}); |
|||
$(".close").on('click', ()=>{ $(".modal").removeClass("is-active")}) |
|||
}); |
|||
</script> |
|||
</body> |
|||
</html> |
|||
|
Before Width: | Height: | Size: 6.1 KiB After Width: | Height: | Size: 6.1 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 79 KiB After Width: | Height: | Size: 79 KiB |
@ -0,0 +1 @@ |
|||
dev.zenroom.org |
|||
@ -1,44 +1,33 @@ |
|||
.PHONY: article website preview |
|||
ARTICLE := Zenroom_Cryptolang_Whitepaper |
|||
DEST := pub |
|||
.PHONY: website preview |
|||
|
|||
all: api website |
|||
all: api map website |
|||
|
|||
# api output is website/docs/lua
|
|||
# api output is _media/lua
|
|||
api: |
|||
make -C ldoc |
|||
make -C pages/ldoc |
|||
|
|||
# output is website/site
|
|||
# download js from our CI
|
|||
# import wiki pages
|
|||
# import changelog
|
|||
website: |
|||
@if ! [ -r website/docs/js/zenroom.js -o -r website/docs/js/zenroom.wasm ]; then curl https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.wasm https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.js https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.data -o website/docs/js/zenroom.wasm -o website/docs/js/zenroom.js -o website/docs/js/zenroom.data; fi |
|||
@mkdir -p website/docs/encrypt && cp -v website/docs/js/zenroom.data website/docs/encrypt/ |
|||
@mkdir -p website/docs/wiki |
|||
@cp -v wiki/Build.md website/docs/wiki/how-to-build.md |
|||
@cp -v wiki/Execute.md website/docs/wiki/how-to-exec.md |
|||
@cp -v wiki/Embed.md website/docs/wiki/how-to-embed.md |
|||
@cp -v ../ChangeLog.md website/docs/changelog.md |
|||
@cp -v zencode_diagram.png website/docs/img |
|||
@cp -v ../test/zencode_coconut/*.zen website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.zen website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.keys website/docs/examples/ |
|||
@cp -v ../test/zencode_simple/*.data website/docs/examples/ |
|||
@cp -v ../examples/*.keys ../examples/*.data ../examples/*.lua website/docs/examples/ |
|||
@cd website && mkdocs build |
|||
@if ! [ -r _media/js/zenroom.js -o -r _media/js/zenroom.wasm ]; then curl https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.wasm https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.js https://sdk.dyne.org:4443/view/zenroom/job/zenroom-web/lastSuccessfulBuild/artifact/build/web/zenroom.data -o _media/js/zenroom.wasm -o _media/js/zenroom.js -o _media/js/zenroom.data; fi |
|||
@ln -s _media/js/zenroom.data . |
|||
@cp -v ../examples/*.keys ../examples/*.data ../examples/*.lua _media/examples/ |
|||
|
|||
map: |
|||
./parse_zencode.sh | json_pp > zencode_utterances.json |
|||
./_media/scripts/parse_zencode.sh _media/zencode_utterances.yaml |
|||
|
|||
preview: |
|||
cd website && ./mkdocs-dyne-theme/.preview |
|||
docsify serve . |
|||
|
|||
deploy: api website |
|||
deploy: api map website |
|||
cd website && ./mkdocs-dyne-theme/.deploy |
|||
|
|||
clean: |
|||
@rm -rf website/docs/lua |
|||
@rm -rf website/docs/wiki |
|||
@rm -rf website/site |
|||
@echo "Zenroom website cleaned up" |
|||
make -C pages/ldoc clean |
|||
@rm -f _media/examples/*.data |
|||
@rm -f _media/examples/*.keys |
|||
@rm -f _media/examples/*.lua |
|||
@rm -f _media/js/zenroom.* |
|||
@rm -f _media/zencode_utterances.yaml |
|||
@rm -f zenroom.data |
|||
@echo "Zenroom docs cleaned up" |
|||
|
|||
@ -0,0 +1,46 @@ |
|||
# Zenroom Crypto VM |
|||
|
|||
## Intro |
|||
|
|||
Zenroom is a **secure language interpreter** of both Lua and its own |
|||
secure domain specific language (DSL) to execute fast cryptographic |
|||
operations using elliptic curve arithmetics. |
|||
|
|||
The Zenroom VM is very small, has **no external dependency**, is fully |
|||
deterministic and ready to run **end-to-end encryption** on any platform: |
|||
desktop, embedded, mobile, cloud and even web browsers. |
|||
|
|||
**Zencode** is the name of the DSL executed by Zenroom: it is similar |
|||
to human language and can process large data structures while |
|||
operating cryptographic transformations and basic logical operations |
|||
on them. |
|||
|
|||
## Quickstart |
|||
|
|||
|
|||
1. Download the [Zenroom binary](https://zenroom.org/#downloads) that works for your system |
|||
1. Download the smart contract [credential_keygen.zen](https://raw.githubusercontent.com/DECODEproject/zenRoom/master/test/zencode_coconut/credential_keygen.zen) |
|||
1. (On Linux/Mac) Run: `zenroom -z credential_keygen.zen | tee keypair.json` |
|||
|
|||
If everything went well, in the file `keypair.json` you will see something like this: |
|||
|
|||
|
|||
```json |
|||
{ |
|||
"Alice":{ |
|||
"credential_keypair":{ |
|||
"private":"AZNuDnEujJlccuejLIHihxFeKzzuReL3mwikvtcCVHlFaYo7rCdR", |
|||
"public":"AhMBC4woNICc0OZyQS3kPE5q6EVlwyn5VTsBKG1ulsxmDfN1f9Kmqc0fgWUsRxRSIhSsJnSsP1CUjNk" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Quicklinks |
|||
|
|||
|
|||
Checkout the [developer website](https://dev.zenroom.org/), the [product website](http://zenroom.org/) or the [zenCode whitepaper](https://files.dyne.org/zenroom/zenRoom_Whitepaper.pdf) |
|||
|
|||
|
|||
|
|||
**zenRoom is licensed as AGPLv3; we are happy to discuss dual-licensing on a commercial base.** |
|||
@ -0,0 +1,25 @@ |
|||
<!-- _coverpage.md --> |
|||
<span class="small-caps"> </span> |
|||
|
|||
 |
|||
|
|||
|
|||
- |
|||
<span class="small-caps">zenroom</span> is a **secure language interpreter** of both Lua and its own secure domain specific language <span class="small-caps">zencode</span> to <a href="https://zenroom.org/#features" target="_blank" alt="Features" style="font-weight: bold; text-decoration:underline !important;">execute cryptographic operations</a> and execute smart contracts in a multiplatform environment. |
|||
|
|||
|
|||
|
|||
<!-- |
|||
- The <span class="small-caps">zenroom vm</span> is very small, has **no external dependency**, is fully deterministic and ready to run **end-to-end encryption** on any platform: |
|||
desktop, embedded, mobile, cloud and even web browsers. |
|||
|
|||
|
|||
- **zenCode** is the name of the <span class="small-caps">dsl</span> executed by <span class="small-caps">zenroom</span>: it is similar to human language and can process large data structures while operating cryptographic transformations and basic logical operations on them. |
|||
|
|||
|
|||
|
|||
<span class="small-caps">zenroom</span> _is licensed as <span class="small-caps">agpl</span>v3 we are happy to discuss dual-licensing on a commercial base._ |
|||
--> |
|||
|
|||
[๐ Downloads](http://zenroom.org/#downloads) |
|||
[Quickstart](#quickstart) |
|||
@ -0,0 +1,6 @@ |
|||
|
|||
This document explains the nature of the Zenroom software component for the DECODE Project. It establishes guidelines and requirements for the implementation of an execution engine for a new domain specific language. |
|||
|
|||
DECODE's language is an external DSL implemented using a Syntax-Directed Translation. Its Semantic Model leads to coarse-grained tasks to be executed by the nodes on the peer to peer network. |
|||
|
|||
This is a living document and its latest version can be found on zenroom.dyne.org. |
|||
@ -0,0 +1,255 @@ |
|||
|
|||
# Introduction |
|||
|
|||
The main way to communicate with a DECODE node and operate its functions is via a language, rather than an API. All read and write operations affecting entitlements and accessing attributes can be expressed in a smart-rule language, which we intend to design and develop to become a robust open standard for authorisation around personal data. The DECODE smart-rule language will aim to naturally avoid complex constructions and define sets of transformations that can be then easily represented with visual metaphors; in terms of programming language it will be deterministic and side effect-free in order to better prove its correctness. |
|||
|
|||
At this stage of the research, this document is split in 3 sections: |
|||
|
|||
1. a brief "state of the art" analysis, considering existing blockchain-based languages and in particular the most popular "Solidity" supported by the Ethereum virtual machine. |
|||
|
|||
2. a brief enumeration of the characteristics of this implementation and an abstraction from it, to individuate the fundamental features a smart-rule language should have in the context of permissionless, distributed computing. |
|||
|
|||
3. a set of technical recommendations for the development of smart-rules in DECODE |
|||
|
|||
This document is not speculative, but is companion to an actual implementation being developed during the course of DECODE's project: the ["zenroom" (link)](https://decodeproject.github.io/lua-zenroom/). |
|||
|
|||
|
|||
## A new memory model |
|||
|
|||
In computing science the concepts of HEAP and STACK are well known and represent the different areas of memory in which a single computer can store code, address it while executing it and store data on which the code can read and write. With the advent of "virtual machines" (abstract computing machines like JVM or BEAM, not virtualised operating systems) the implementation of logic behind the HEAP and STACK became more abstract and not anymore bound to a specific hardware architecture, therefore leaving more space for the portability of code and creative memory management practices (like garbage collection). It is also thanks to the use of virtual machines that high level languages became closer to the way humans think, rather than the way machines work, benefitting creativity, awareness and auditability [@mccartney2002rethinking]. This is an important vector of innovation for the language implementation in DECODE, since it is desirable for this project to implement a language that is close to the way humans think. |
|||
|
|||
With the advent of distributed computing technology and blockchain implementations there is a growing necessity to conceive the HEAP and STACK differently [@DBLP:conf/ipps/PizkaR02], mostly because there are many more different conditions for memory bound to its persistence, read/write speed, mutability, distribution etc. |
|||
|
|||
The underpinning of this document, elaborated on the term "blockchain language", is that a new "distributed ledger", as collective and immutable memory space, can be addressed with code running on different machines. |
|||
|
|||
A "blockchain language" then is a language designed to interact with a "distributed ledger". A distributed ledger is a log of "signed events" whose authenticity can be verified by any node being part of the network; taking part of a network can be regulated by permissions (in a so called "permissioned blockchain") or completely open to any participant complying to the protocol (so called "permissionless blockchain"). |
|||
|
|||
This document intentionally leaves aside considerations about the consensus algorithm of a blockchain-based network, which are very specific issues concerning the implementation of a blockchain and are covered by other research tasks in DECODE. While assuming an ideal condition for fault tolerance will be provided by other research tasks in DECODE, this research will continue focusing on the function that the distributed ledger has for the distributed computation of a language, assuming the most interesting case of a permissionless blockchain (an open network) since that is the most ambitious research goal for DECODE as stated for the development of Chainspace [@al2017chainspace]. |
|||
|
|||
|
|||
|
|||
# 1. Blockchain languages |
|||
|
|||
This section is a brief exploration of the main language implementations working on blockchains. Far from being an exhaustive overview, it highlights the characteristics of these implementations and most importantly the approach followed in building virtual machines that are based on assembler-like operation codes and languages that compile to these. |
|||
|
|||
The conclusion of this section is that the blockchain languages so far existing are designed with a product-oriented mindset, starting from the implementation of a virtual machine that can process OP_CODEs. Higher level languages build upon it, parsing higher level syntactics and semantics and compiling them into a series of OP_CODEs. This is the natural way most languages like ASM, C and C++ have evolved through the years. |
|||
|
|||
Arguably, a task-oriented mindset should be assumed when re-designing a new blockchain language for DECODE: that would be the equivalent of a human-centered research and design process. The opportunity for innovating the field lies in abandoning the OP_CODE approach and instead build an External Domain Specific Language [@fowler2010domain] using an existing grammar to do the Syntax-Directed Translation. The Semantic Model can be then a coarse-grained implementation that can sync computations with blockchain-based deterministic conditionals. |
|||
|
|||
## Bitcoin's SCRIPT |
|||
|
|||
Starting with the "SCRIPT" implementation in Bitcoin [@nakamoto2008bitcoin] and ending with the Ethereum Virtual Machine implementation, it is clear that blockchain technologies were developed with the concept of "distributed computation" in mind. The scenario is that of a network of computers that, at any point in time, can execute the same code on a part of the distributed ledger and that execution would yield to the same results, making the computation completely deterministic. |
|||
|
|||
The distributed computation is made by blockchain nodes that act as sort of "virtual machines" and process "operation codes" (OP_CODE) just like a computer does. These OP_CODES in fact resemble assembler language operations. |
|||
|
|||
In Bitcoin the so called SCRIPT implementation had an unfinished number of "OP_CODE" commands (operation codes) at the time of its popularisation and, around the 0.6 release, the feature was in large part deactivated to ensure the security of the network, since it was assessed by most developers involved that the Bitcoin implementation of SCRIPT was unfinished and represented threats to the network. Increasing the complexity of code that can be executed by nodes of an open network is always a risk, since code can contain arbitrary operations and commands that may lead to unpredictable results affecting both the single node and the whole network. The shortcomings of the SCRIPT in Bitcoin were partially addressed: its space for OP_RETURN [@roio2015d4] became the contested ground for payloads [@sward2017data] that could be interpreted by other VMs, as well the limit was partially circumvented by moving more complex logic in touch with the Bitcoin blockchain [@aron2012bitcoin], for instance using the techniques adopted by Mastercoin [@mastercoin2013willett] and "sidechains" as Counterparty [@bocek2018smart] or "pegged sidechains" [@back2014enabling] implementations. All these are implementations of VMs that run in parallel to Bitcoin, can "peg" their results on the main Bitcoin blockchain and still execute more complex operations in another space, where tokens and conditions can be created and affect different memory spaces and distributed ledgers. |
|||
|
|||
Languages implemented so far for this task are capable of executing single OP_CODEs: implementations are very much "machine-oriented" and focused on reproducing the behaviour of a turing-complete machine [@DBLP:conf/birthday/WegnerEB12] capable of executing generic computing tasks. |
|||
|
|||
|
|||
## The Ethereum VM |
|||
|
|||
The Ethereum Virtual Machine is arguably the most popular implementation of a language that can be computed by a distributed and decentralised network of virtual machines that have all their own HEAP and STACK, but all share the same immutable distributed ledger on which "global" values and the code (contracts) manipulating them can be inscribed and read from. |
|||
|
|||
Computation in the EVM is done using a stack-based bytecode language that is like a cross between Bitcoin Script, traditional assembly and Lisp (the Lisp part being due to the recursive message-sending functionality). A program in EVM is a sequence of opcodes, like this: |
|||
``` |
|||
PUSH1 0 CALLDATALOAD SLOAD NOT PUSH1 9 JUMPI STOP JUMPDEST PUSH1 32 CALLDATALOAD PUSH1 0 CALLDATALOAD SSTORE |
|||
``` |
|||
The purpose of this particular contract is to serve as a name registry; anyone can send a message containing 64 bytes of data, 32 for the key and 32 for the value. The contract checks if the key has already been registered in storage, and if it has not been then the contract registers the value at that key. The address of the new contract is deterministic and calculated on the sending address and the number of times that the sending account has made a transaction before. |
|||
|
|||
The EVM is a simple stack-based architecture. The word size of the machine (and thus size of stack item) is 256-bit. This was chosen to fit a simple word-addressed byte array. The stack has a maximum size of 1024. The machine also has an independent storage model; this is similar in concept to the memory but rather than a byte array, it is a word- addressable word array. Unlike memory, which is volatile, storage is nonvolatile and is maintained as part of the system state. All locations in both storage and memory are well-defined initially as zero. |
|||
|
|||
The machine does not follow the standard von Neumann architecture. Rather than storing program code in generally-accessible memory or storage, it is stored separately in a virtual ROM that can only be interacted with via a specific instruction. The machine can have exceptional execution for several reasons, including stack underflows and invalid instructions. Like the out-of-gas (OOG) exception, they do not leave state changes intact. Rather, the machine halts immediately and reports the issue to the execution agent (either the transaction processor or, recursively, the spawning execution environment) which will deal with it separately [@wood2014ethereum]. |
|||
|
|||
The resulting implementation consists of a list of OP_CODEs whose execution requires a "price" to be paid (Ethereum's currency for the purpose is called "gas"). This way an incentive is created for running nodes: a fee is paid to nodes for computing the contracts and confirming the outcomes of their execution. This feature technically defines the Ethereum VM as implementing an almost Turing-complete machine since its execution is conditioned by the availability of funds for computation. This approach relies on the fact that each operation is executed at a constant unit of speed. |
|||
|
|||
On top of these OP_CODEs the "Solidity" language was developed as a high-level language that compiles to OP_CODE sequences. Solidity aims to make it easier for people to program "smart contracts". But it is arguable that the Solidity higher-level language, widely present in all Ethereum related literature, carries several problems: the shortcomings of its design can be indirectly related to some well-known disasters provoked by flaws in published contracts. To quickly summarise some flaws: |
|||
|
|||
- there is no garbage collector nor manual memory management |
|||
- floating point numbers are not supported |
|||
- there are known security flaws in the compiler |
|||
- the syntax of loops and arrays is confusing |
|||
- every type is 256bits wide, including bytes |
|||
- there is no string manipulation support |
|||
- functions can return only statically sized arrays |
|||
|
|||
To overcome the shortcomings and create some shared base of reliable implementations, programmers using Solidity currently adopt "standard" token implementation libraries with basic functions that are proven to be working reliably: known as ERC20, the standard is made for tokens to be supported across different wallets and to be reliable. Yet even with a recent update to a new version (ERC232) the typical code constructs that are known to be working are full of checks (assert calls) to insure the reliability of the calling code. For example, typical arithmetic operations need to be implemented in Solidity as: |
|||
|
|||
```c |
|||
|
|||
function times(uint a, uint b) constant private returns (uint) { |
|||
uint c = a * b; |
|||
assert(a == 0 || c / a == b); |
|||
return c; |
|||
} |
|||
|
|||
function minus(uint a, uint b) constant private returns (uint) { |
|||
assert(b <= a); |
|||
return a - b; |
|||
} |
|||
|
|||
function plus(uint a, uint b) constant private returns (uint) { |
|||
uint c = a + b; |
|||
assert(c>=a); |
|||
return c; |
|||
} |
|||
``` |
|||
|
|||
It must be also noted that the EVM allows calling external contracts that can take over the control flow and make changes to data that the calling function wasn't expecting. This class of bug can take many forms and all of major bugs that led to the DAO's collapse [@o2017smart] were bugs of this sort. |
|||
|
|||
Despite the shortcomings, nowadays Solidity is widely used: it is the most used "blockchain language" supporting "smart-contracts" in the world. |
|||
|
|||
# 2. Language Security |
|||
|
|||
This chapter will quickly establish the underpinnings of a smart rule language in DECODE, starting from its most theoretical assumptions, to conclude with specific requirements. The chapter will concentrate on the recent corpus developed by research on language-theoretic security" (LangSec). Here below we include a brief explanation condensed from the information material of the LangSec.org project hosted at IEEE, which is informed by the collective experience of the exploit development community, since exploitation is a practical exploration of the space of unanticipated state, its prevention or containment. |
|||
|
|||
"In a nutshell [...] LangSec is the idea that many security issues can be avoided by applying a standard process to input processing and protocol design: the acceptable input to a program should be well-defined (i.e., via a grammar), as simple as possible (on the Chomsky scale of syntactic complexity), and fully validated before use (by a dedicated parser of appropriate but not excessive power in the Chomsky hierarchy of automata)." [@DBLP:conf/secdev/MomotBHP16] |
|||
|
|||
LangSec is a design and programming philosophy that focuses on formally correct and verifiable input handling throughout all phases of the software development lifecycle. In doing so, it offers a practical method of assurance of software free from broad and currently dominant classes of bugs and vulnerabilities related to incorrect parsing and interpretation of messages between software components (packets, protocol messages, file formats, function parameters, etc.). |
|||
|
|||
This design and programming paradigm begins with a description of valid inputs to a program as a formal language (such as a grammar). The purpose of such a disciplined specification is to cleanly separate the input-handling code and processing code. A LangSec-compliant design properly transforms input-handling code into a recognizer for the input language; this recognizer rejects non-conforming inputs and transforms conforming inputs to structured data (such as an object or a tree structure, ready for type- or value-based pattern matching). The processing code can then access the structured data (but not the raw inputs or parsers temporary data artifacts) under a set of assumptions regarding the accepted inputs that are enforced by the recognizer. |
|||
|
|||
This approach leads to several advantages: |
|||
|
|||
1. produce verifiable recognizers, free of typical classes of ad-hoc parsing bugs |
|||
2. produce verifiable, composable implementations of distributed systems that ensure equivalent parsing of messages by all components and eliminate exploitable differences in message interpretation by the elements of a distributed system |
|||
3. mitigate the common risks of ungoverned development by explicitly exposing the processing dependencies on the parsed input. |
|||
|
|||
As a design philosophy, LangSec focuses on a particular choice of verification trade-offs: namely, correctness and computational equivalence of input processors. |
|||
|
|||
|
|||
## Threats when developing a language |
|||
|
|||
As one engages the task of developing a language there are four main threats to be identified, well described in LangSec literature: |
|||
|
|||
### Ad-hoc notions of input validity |
|||
|
|||
Formal verification of input handlers is impossible without formal language-theoretic specification of their inputs, whether these inputs are packets, messages, protocol units, or file formats. Therefore, design of an input-handling program must start with such a formal specification. Once specified, the input language should be reduced to the least complex class requiring the least computational power to recognize. Considering the tendency of hand-coded programs to admit extra state and computation paths, computational power susceptible to crafted inputs should be minimized whenever possible. Whenever the input language is allowed to achieve Turing-complete power, input validation becomes undecidable; such situations should be avoided. For example, checking 'benignness' of arbitrary Javascript or even an HTML5+CSS page is a losing proposition. |
|||
|
|||
### Parser differentials |
|||
|
|||
Mutual misinterpretation between system components. Verifiable composition is impossible without the means of establishing parsing equivalence between different components of a distributed system. Different interpretation of messages or data streams by components breaks any assumptions that components adhere to a shared specification and so introduces inconsistent state and unanticipated computation [@DBLP:conf/secdev/MomotBHP16]. In addition, it breaks any security schemes in which equivalent parsing of messages is a formal requirement, such as the contents of a certificate or of a signed message being interpreted identically, for example a X.509 Certificate Signing Request as seen by a Certificate Authority vs. the signed certificates as seen by the clients or signed app package contents as seen by the signature verifier versus the same content as seen by the installer (as in the recent Android Master Key bug [@freeman2013exploit]). An input language specification stronger than deterministic context-free makes the problem of establishing parser equivalence undecidable. Such input languages and systems whose trustworthiness is predicated on the component parser equivalence should be avoided. Logical programming using Prolog for instance, or languages like Scheme derived from LISP, or OCaml or Erlang would match then our requirements, but they aren't as usable as desired. As a partial solution to this problem the DECODE language parser (and all its components and eventually linked shared libraries) should be self-contained and clearly versioned and hashed and its hash verified before every computation. |
|||
|
|||
### Mixing of input recognition and processing |
|||
|
|||
Mixing of basic input validation ("sanity checks") and logically subsequent processing steps that belong only after the integrity of the entire message has been established makes validation hard or impossible. As a practical consequence, unanticipated reachable state exposed by such premature optimization explodes. This explosion makes principled analysis of the possible computation paths untenable. LangSec-style separation of the recognizer and processor code creates a natural partitioning that allows for simpler specification-based verification and management of code. In such designs, effective elimination of exploit-enabling implicit data flows can be achieved by simple systems memory isolation primitives. |
|||
|
|||
### Language specification drift |
|||
|
|||
A common practice encouraged by rapid software development is the unconstrained addition of new features to software components and their corresponding reflection in input language specifications. Expressing complex ideas in hastily written code is a hallmark of such development practices. In essence, adding new input feature requirements to an already-underspecified input language compounds the explosion of state and computational paths. |
|||
|
|||
# 3. Smart-rules language |
|||
|
|||
In light of our study of blockchain languages, use-cases and privacy by design guidelines in DECODE, this section lists three functional requirements and three usability requirements influencing the design patterns for our language. |
|||
|
|||
The conclusion of this section is best described adopting once again the DSL terminology and the patterns established by Fowler. The DECODE smart-rule language is an external DSL implemented using a Syntax-Directed Translation. Its Semantic Model leads to coarse-grained tasks to be executed on the network, perhaps following a Dependency Network approach. |
|||
|
|||
A tempting alternative can be that of a Production Rule System, but this way we would hide too much the internal processes in DECODE, which should be transparent and comprehensible to anyone with a beginner knowledge of programming. |
|||
|
|||
An addition to this approach can be that of equipping the language with tools for constraint programming and even a context of Satisfiability Modulo Theories [@barrett2009satisfiability] to check satisfying Program Termination Proofs [@bonfante2001algorithms]. |
|||
|
|||
|
|||
|
|||
|
|||
## Functional requirements |
|||
|
|||
On the basis of the design considerations made in the previous chapters, here are listed the main requirements identified for the implementation of a smart-rule language in DECODE. |
|||
|
|||
### Deterministic |
|||
|
|||
This is an important feature common to all blockchain language implementations in use: that the language limits its operations to access only a fully deterministic environment. This means that, in any possible moment in time, any node can join the network and start computing contracts leading to results that are verifiable and confirmed by other nodes. |
|||
|
|||
In other words, the environment accessed by the language is available to all nodes, there aren't variables that are "private" to a single node and may change the result by a change of their value. |
|||
|
|||
The deterministic trait must be common also to the DECODE blockchain language for smart-rules, since it verifies a basic and necessary condition for blockchain based computing: that other nodes can verify and sign the results, reproducing them in their own execution environment. The computation leads to the same results that can be determined in different conditions, because all nodes have access to the same information necessary to the computation. |
|||
|
|||
### Trustless |
|||
|
|||
We define as trustless a language (also known as untrusted language) that allows the virtual machine to fence its execution, as in a "sandbox" or isolated execution environment, blocking access to unauthorised parts of the system. |
|||
|
|||
A language that can be run on a "permissionless" (public) blockchain is a language that can be interpreted by any node. In any moment a new node may claim the capacity to do so. This means that its parser, semantics and actions on the system must be designed to handle unknowns: any deviance and malevolent code should not affect the system. |
|||
|
|||
### Strict |
|||
|
|||
The language and the semantic model adopted by Zenroom are designed to allow the sandboxing of untrusted code and to provide security partitioning. Any process of execution is strictly limited in what it can do, first and foremost in terms of memory and computational cycles used. |
|||
|
|||
The objective is that any function or data passed to a Zenroom process cannot break the sandbox in ways the participants did not intend. If an error occurs the Zenroom engine will not continue further, rather exit with a meaningful error message and dispose of all the memory used via garbage collection. For sensitive data structures the use of a declarative schema validation is provided as a security guard, to allow scripts to easily recognise the data they are passing to functions. |
|||
|
|||
|
|||
## Usability requirements |
|||
|
|||
Here are listed the requirements emerging from an analysis of priorities about the human-machine interaction scenarios emerging from DECODE. |
|||
|
|||
### Simple, graphical representation |
|||
|
|||
A visual programming environment (VPE) facilitates participants to directly re-configure the rules governing their data: this is highly desirable in DECODE, where such code must be transparent and understandable. The event-based blocks graphical metaphor seems the most desirable for the sort of processing in DECODE: it involves letting participants manipulate a series of graphical elements (blocks) that snap onto one another and that execute sequential programs. |
|||
|
|||
### Test environment |
|||
|
|||
A reliable test environment is a fundamental component for a language deployed in mission critical situations, but also for a language dealing with the distribution of its computation and wide adoption by communities of developers in different fields. Languages that improve the developer's experience when writing and testing code directly impact the quality of the code produced. |
|||
|
|||
For the Zenroom work is in progress to provide a testing environment designed from the start to facilitate its growth at the same pace of the language itself. Also, a more advanced framework for testing that goes beyond the simple usage of asserts and data validations is planned: while being very ambitious, the implementation of solid proof of termination mechanisms that are internal to the language should be contemplated on the long term. |
|||
|
|||
### First-class data |
|||
|
|||
This is a long-term requirement that should take into consideration the trade-off between feasibility, security and convenience. A data type is considered first-class in a programming language if instances of that type can be |
|||
|
|||
- the value of a variable |
|||
- a member of an aggregate (array, list, etc.) |
|||
- an argument (input) to a procedure |
|||
- the value returned by a procedure |
|||
- used without having a name (being the value of a variable) |
|||
|
|||
For example, numbers are first-class in every language. Text strings are first-class in many languages, but not in C, in which the relevant first-class type is โpointer to a characterโ. |
|||
|
|||
In Zenroom any important data structure needs to be validated at start and become a first-class citizen to be seamlessly processed by other scripted functions. Following a declarative and non-imperative approach, developers can concentrate on the script while at the same time producing part of the documentation needed to define its data structures and functional constraints. |
|||
|
|||
|
|||
# Conclusion |
|||
|
|||
This document is a very dense representation of language patterns and requirements to be adopted while implementing DECODE's language. Its feasibility has been verified with an extensive survey on available tools that can be used to implement this execution engine and are compatible with the DECODE licensing model. |
|||
|
|||
This conclusion provides a brief list of components that can be used. |
|||
|
|||
## Syntax-Directed Translation |
|||
|
|||
Lua is an interpreted, cross-platform, embeddable, performant and low-footprint language. Lua's popularity is on the rise in the last couple of years [@costin2017lua]. Simple design and efficient usage of resources combined with its performance make it attractive for production web applications, even to big organizations such as Wikipedia, CloudFlare and GitHub. In addition to this, Lua is one of the preferred choices for programming embedded and IoT devices. This context allows an assumption of a large and growing Lua codebase yet to be assessed. This growing Lua codebase could be potentially driving production servers and an extremely large number of devices, some perhaps with mission-critical function for example in automotive or home-automation domains. |
|||
|
|||
Lua stability has been extensively tested through a number of public applications including the adoption by the gaming industry for untrusted language processing in "World of Warcraft" scripting. It is ideal for implementing an external DSL using C or Python as a host language. |
|||
|
|||
Lua is also tooled with a working VPE implementation for code visualisation in blocks, allowing the project to jump-start into an early phase of prototyping DECODE's smart-rules in a visual way and directly involving pilot participants. |
|||
|
|||
## Satisfiability Modulo theories |
|||
|
|||
Satisfiability Modulo theories (SMT) is an area of automated deduction that studies methods for checking the satisfiability of first-order formulas with respect to some logical theory of interest [@barrett2009satisfiability]. It differs from general automated deduction in that the background theory need not be finitely or even first-order axiomatizable, and specialized inference methods are used for each theory. By being theory-specific and restricting their language to certain classes of formulas (such as, typically but not exclusively, quantifier-free formulas), these specialized methods can be implemented in solvers that are more efficient in practice than general-purpose theorem provers. |
|||
|
|||
While SMT techniques have been traditionally used to support deductive software verification, they are now finding applications in other areas of computer science such as planning, model checking and automated test generation. Typical theories of interest in these applications include formalizations of arithmetic, arrays, bit vectors, algebraic datatypes, equality with uninterpreted functions, and various combinations of these. |
|||
|
|||
Constraint-satisfaction is crucial to software and hardware verification and static program analsysis [@de2011satisfiability] among the other possible applications. |
|||
|
|||
DECODE will benefit from including SMT capabilities into the design at an early stage: even if not immediately exploited, their inclusion will keep the horizons for language development open while permitting its application in mission critical roles. The best implementation to start from in this experimentation seems to be the free and open source software "Yices SMT Solver" published by the Computer Science Laboratory of the Stanford Research Institute (SRI International). |
|||
|
|||
<!-- |
|||
## Ontology |
|||
|
|||
Considering the overall project schedule and the advancement of other deliverables at current stage in the DECODE project, it is an ill-advised choice to indicate that this document may include an ontology. The scheduled deliverable D3.5 still mentions the publication of an "initial ontology and smart-rules" and it is a more realistic estimation of delivery for this topic. Meanwhile this document represents a complete overview on smart-rule language requirements. |
|||
|
|||
--> |
|||
|
|||
<!-- |
|||
SDT |
|||
http://minikanren.org/ |
|||
http://www.gecode.org/ |
|||
https://github.com/handsomecheung/miniKanren.lua |
|||
https://github.com/SRI-CSL/yices2 |
|||
|
|||
|
|||
python: |
|||
https://wiki.python.org/moin/SandboxedPython |
|||
https://github.com/dsagal/pynbox |
|||
https://github.com/RealTimeWeb/blockpy |
|||
|
|||
|
|||
|
|||
|
|||
--> |
|||
@ -0,0 +1 @@ |
|||
decode_language_patterns.md |
|||
@ -0,0 +1,261 @@ |
|||
|
|||
@article{roio2015d4, |
|||
title={Design of Social Digital Currency}, |
|||
author={Roio, Denis and Sachy, Marco and Lucarelli, Stefano and Lietaer, Bernard and Bria, Francesca}, |
|||
year={2015}, |
|||
publisher={EU-FP7/D-CENT} |
|||
} |
|||
|
|||
|
|||
@article{sward2017data, |
|||
title={Data Insertion in Bitcoin's Blockchain}, |
|||
author={Sward, Andrew and OP\_0, Vecna and Stonedahl, Forrest}, |
|||
year={2017} |
|||
} |
|||
|
|||
|
|||
@InProceedings{DBLP:conf/birthday/WegnerEB12, |
|||
author = {Peter Wegner and Eugene Eberbach and Mark Burgin}, |
|||
title = {Computational Completeness of Interaction Machines |
|||
and Turing Machines}, |
|||
year = 2012, |
|||
booktitle = {Turing-100 - The Alan Turing Centenary, Manchester, |
|||
UK, June 22-25, 2012}, |
|||
pages = {405-414}, |
|||
url = {http://www.easychair.org/publications/paper/106520}, |
|||
crossref = {DBLP:conf/birthday/2012turing}, |
|||
timestamp = {Tue, 25 Jul 2017 11:35:36 +0200}, |
|||
biburl = {http://dblp.org/rec/bib/conf/birthday/WegnerEB12}, |
|||
bibsource = {dblp computer science bibliography, http://dblp.org} |
|||
} |
|||
|
|||
@proceedings{DBLP:conf/birthday/2012turing, |
|||
editor = {Andrei Voronkov}, |
|||
title = {Turing-100 - The Alan Turing Centenary, Manchester, UK, June 22-25, |
|||
2012}, |
|||
series = {EPiC Series in Computing}, |
|||
volume = {10}, |
|||
publisher = {EasyChair}, |
|||
year = {2012}, |
|||
url = {http://www.easychair.org/publications/?page=1900403647}, |
|||
timestamp = {Thu, 16 Jun 2016 17:11:03 +0200}, |
|||
biburl = {http://dblp.org/rec/bib/conf/birthday/2012turing}, |
|||
bibsource = {dblp computer science bibliography, http://dblp.org} |
|||
} |
|||
|
|||
@InProceedings{DBLP:conf/ipps/PizkaR02, |
|||
author = {Markus Pizka and Christian Rehn}, |
|||
title = {Heaps and Stacks in Distributed Shared Memory}, |
|||
year = 2002, |
|||
booktitle = {16th International Parallel and Distributed |
|||
Processing Symposium {(IPDPS} 2002), 15-19 April |
|||
2002, Fort Lauderdale, FL, USA, CD-ROM/Abstracts |
|||
Proceedings}, |
|||
doi = {10.1109/IPDPS.2002.1016494}, |
|||
url = {https://doi.org/10.1109/IPDPS.2002.1016494}, |
|||
crossref = {DBLP:conf/ipps/2002}, |
|||
timestamp = {Wed, 24 May 2017 08:28:14 +0200}, |
|||
biburl = {http://dblp.org/rec/bib/conf/ipps/PizkaR02}, |
|||
bibsource = {dblp computer science bibliography, http://dblp.org} |
|||
} |
|||
|
|||
@proceedings{DBLP:conf/ipps/2002, |
|||
title = {16th International Parallel and Distributed Processing Symposium {(IPDPS} |
|||
2002), 15-19 April 2002, Fort Lauderdale, FL, USA, CD-ROM/Abstracts |
|||
Proceedings}, |
|||
publisher = {{IEEE} Computer Society}, |
|||
year = {2002}, |
|||
url = {http://ieeexplore.ieee.org/xpl/mostRecentIssue.jsp?punumber=7926}, |
|||
isbn = {0-7695-1573-8}, |
|||
timestamp = {Fri, 01 Aug 2014 14:26:10 +0200}, |
|||
biburl = {http://dblp.org/rec/bib/conf/ipps/2002}, |
|||
bibsource = {dblp computer science bibliography, http://dblp.org}} |
|||
|
|||
@article{al2017chainspace, |
|||
title={Chainspace: A Sharded Smart Contracts Platform}, |
|||
author={Al-Bassam, Mustafa and Sonnino, Alberto and Bano, Shehar and Hrycyszyn, Dave and Danezis, George}, |
|||
journal={arXiv preprint arXiv:1708.03778}, |
|||
year={2017} |
|||
} |
|||
|
|||
@InProceedings{DBLP:conf/sp/WoodH15, |
|||
author = {Kerry N. Wood and Richard E. Harang}, |
|||
title = {Grammatical Inference and Language Frameworks for |
|||
{LANGSEC}}, |
|||