Browse Source

๐Ÿ“ Improved and organize docs (#97)

* improved and split docs

	modified:   docs/_sidebar.md
	new file:   docs/pages/zencode-list.md
	modified:   docs/pages/zencode.md

* ๐Ÿ“ Update utterances. Syntax highlight. Typos.

Co-authored-by: Puria Nafisi Azizi <puria@dyne.org>
master
Andrea D'Intino 3 years ago
committed by GitHub
parent
commit
c77e6d6cf5
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 4
      docs/_media/css/style.css
  2. 4
      docs/_media/zencode_utterances.yaml
  3. 1
      docs/_sidebar.md
  4. 2
      docs/examples/crypt-to-multi.lua
  5. 2
      docs/examples/dashboard-from-iotdev.lua
  6. 2
      docs/examples/iotdev-to-dashboard.lua
  7. 8
      docs/examples/symmetric-crypto-pin.lua
  8. 12
      docs/examples/zencode_coconut/aggregate_signature.zen
  9. 8
      docs/examples/zencode_coconut/create_request.zen
  10. 6
      docs/examples/zencode_coconut/credential_keygen.zen
  11. 6
      docs/examples/zencode_coconut/issuer_keygen.zen
  12. 12
      docs/examples/zencode_coconut/issuer_sign.zen
  13. 6
      docs/examples/zencode_coconut/publish_verifier.zen
  14. 8
      docs/examples/zencode_simple/AES01.zen
  15. 6
      docs/examples/zencode_simple/AES02.zen
  16. 14
      docs/examples/zencode_simple/AES05.zen
  17. 12
      docs/examples/zencode_simple/DSA01.zen
  18. 14
      docs/examples/zencode_simple/DSA02.zen
  19. 6
      docs/examples/zencode_simple/SYM01.zen
  20. 18
      docs/examples/zencode_simple/SYM02.zen
  21. 10
      docs/examples/zencode_simple/SYM03.zen
  22. 2
      docs/pages/ldoc/o/README.md
  23. 4
      docs/pages/ldoc/o/examples/crypt-to-multi.lua.html
  24. 2
      docs/pages/ldoc/o/examples/keygen.lua.html
  25. 91
      docs/pages/ldoc/o/modules/AES.html
  26. 2
      docs/pages/ldoc/o/modules/BIG.html
  27. 2
      docs/pages/ldoc/o/modules/ECDH.html
  28. 2
      docs/pages/ldoc/o/modules/ECP.html
  29. 2
      docs/pages/ldoc/o/modules/HASH.html
  30. 2
      docs/pages/ldoc/o/modules/INSPECT.html
  31. 2
      docs/pages/ldoc/o/modules/OCTET.html
  32. 2
      docs/pages/ldoc/o/modules/String.html
  33. 2
      docs/pages/ldoc/o/modules/Table.html
  34. 2
      docs/pages/ldoc/o/modules/ZEN.html
  35. 125
      docs/pages/zencode-list.md
  36. 292
      docs/pages/zencode.md

4
docs/_media/css/style.css

@ -318,7 +318,7 @@ footer span {
/****** COPY TO CLIPBOARD ******/
.docsify-copy-code-button {
font-size: 0.5em !important;
font-size: 0.8em !important;
}
@ -410,4 +410,4 @@ section.cover p {
#main .mermaid .cluster rect {
fill: #f8f8f8 !important;
stroke: var(--theme-color) !important;
}
}

4
docs/_media/zencode_utterances.yaml

@ -50,6 +50,8 @@ when:
- when: I insert the '' in ''
- when: the '' is not found in ''
- when: the '' is found in ''
- when: I split the rightmost '' bytes of ''
- when: I split the leftmost '' bytes of ''
- when: I set '' as '' with ''
- when: I append '' as '' to ''
- when: I write '' as '' in ''
@ -104,6 +106,6 @@ coconut:
### [dp3t_when]
dp3t:
- when: I renew the secret day key to a new day
- when: I create the ephemeral ids for each moment of the day
- when: I create the ephemeral ids for today
- when: I create the proximity tracing of infected ids
### [dp3t_when]

1
docs/_sidebar.md

@ -8,6 +8,7 @@
- Programming
- [Zencode](/pages/zencode.md "Zencode")
- [Zencode command list](/pages/zencode-list.md "Zencode command list")
- [Lua](/pages/lua.md "in Lua")
- [Lua full reference](/pages/ldoc/o/README.md "in Lua")

2
docs/examples/crypt-to-multi.lua

@ -26,7 +26,7 @@ for name,pubkey in pairs(keys.recipients) do
out = { header = "encoded using zenroom " .. VERSION.original}
-- encrypt the message with the session key
out.text, out.checksum =
ECDH.aead_encrypt(KDF(session), secret, iv, out.header)
AES.gcm_encrypt(KDF(session), secret, iv, out.header)
-- insert results in final json array
res[name] = url64( JSON.encode(out) )

2
docs/examples/dashboard-from-iotdev.lua

@ -10,7 +10,7 @@ commsec = O.from_url64(keys.community_seckey)
devpub = O.from_url64(decode.header.device_pubkey)
session = ECDH.session(commsec, devpub)
decode.text, decode.checksum =
ECDH.aead_decrypt(KDF(session), O.from_url64(data.text),
AES.gcm_decrypt(KDF(session), O.from_url64(data.text),
O.from_url64(decode.header.iv), data.header)
assert(data.checksum == data.checksum)

2
docs/examples/iotdev-to-dashboard.lua

@ -33,7 +33,7 @@ header.iv = O.random(32):url64()
local session = ECDH.session(devkey.private, O.from_url64(keys.community_pubkey))
local out = { header = url64(JSON.encode(header)) }
out.text, out.checksum =
ECDH.aead_encrypt(KDF(session), JSON.encode(payload), header.iv, out.header)
AES.gcm_encrypt(KDF(session), JSON.encode(payload), header.iv, out.header)
-- content(output) -- uncomment for debug
print( JSON.encode( out ) ) -- map(output, url64) ) )

8
docs/examples/symmetric-crypto-pin.lua

@ -13,8 +13,8 @@ key = HASH.pbkdf2(hash, secrets.pin, secrets.salt, secrets.kdf_iterations, 32)
local cipher = { header = O.from_str("my header"),
iv = O.random(16) }
cipher.text, cipher.checksum =
ECDH.aead_encrypt(key, secrets.text,
cipher.iv, cipher.header)
AES.gcm_encrypt(key, secrets.text,
cipher.iv, cipher.header)
-- I.print(cipher)
-- output = map(cipher, hex)
@ -25,8 +25,8 @@ print(JSON.encode(cipher))
local decode = { header = cipher.header }
decode.text, decode.checksum =
ECDH.aead_decrypt(key, cipher.text,
cipher.iv, cipher.header)
AES.gcm_decrypt(key, cipher.text,
cipher.iv, cipher.header)
-- this needs to be checked, can also be in the host application
-- if checksums are different then the data integrity is corrupted

12
docs/examples/zencode_coconut/aggregate_signature.zen

@ -1,7 +1,7 @@
Scenario coconut: aggregate signature
Given that I am known as 'Alice'
and I have my valid 'credential keypair'
and I have a valid 'credential signature'
When I create the credentials
Then print my 'credentials'
and print my 'credential keypair'
Given that I am known as 'Alice'
and I have my valid 'credential keypair'
and I have a valid 'credential signature'
When I create the credentials
Then print my 'credentials'
and print my 'credential keypair'

8
docs/examples/zencode_coconut/create_request.zen

@ -1,5 +1,5 @@
Scenario coconut: create request
Given that I am known as 'Alice'
and I have my valid 'credential keypair'
When I create the credential request
Then print my 'credential request'
Given that I am known as 'Alice'
and I have my valid 'credential keypair'
When I create the credential request
Then print my 'credential request'

6
docs/examples/zencode_coconut/credential_keygen.zen

@ -1,4 +1,4 @@
Scenario coconut: credential keygen
Given that I am known as 'Alice'
When I create the credential keypair
Then print my 'credential keypair'
Given that I am known as 'Alice'
When I create the credential keypair
Then print my 'credential keypair'

6
docs/examples/zencode_coconut/issuer_keygen.zen

@ -1,4 +1,4 @@
Scenario coconut: issuer keygen
Given that I am known as 'MadHatter'
When I create the issuer keypair
Then print my 'issuer keypair'
Given that I am known as 'MadHatter'
When I create the issuer keypair
Then print my 'issuer keypair'

12
docs/examples/zencode_coconut/issuer_sign.zen

@ -1,7 +1,7 @@
Scenario coconut: issuer sign
Given that I am known as 'MadHatter'
and I have my valid 'issuer keypair'
and I have a valid 'credential request'
When I create the credential signature
Then print the 'credential signature'
and print the 'verifier'
Given that I am known as 'MadHatter'
and I have my valid 'issuer keypair'
and I have a valid 'credential request'
When I create the credential signature
Then print the 'credential signature'
and print the 'verifier'

6
docs/examples/zencode_coconut/publish_verifier.zen

@ -1,4 +1,4 @@
Scenario coconut: publish verifier
Given that I am known as 'MadHatter'
and I have my valid 'verifier'
Then print my 'verifier'
Given that I am known as 'MadHatter'
and I have my valid 'verifier'
Then print my 'verifier'

8
docs/examples/zencode_simple/AES01.zen

@ -1,6 +1,4 @@
Scenario 'simple': Create the keypair
Given that I am known as 'Alice'
When I create the keypair
Then print my data
Given that I am known as 'Alice'
When I create the keypair
Then print my data

6
docs/examples/zencode_simple/AES02.zen

@ -1,4 +1,4 @@
Scenario 'simple': Publish the public key
Given that I am known as 'Alice'
and I have my valid 'public key'
Then print my data
Given that I am known as 'Alice'
and I have my valid 'public key'
Then print my data

14
docs/examples/zencode_simple/AES05.zen

@ -1,9 +1,9 @@
Rule check version 1.0.0
Scenario 'simple': Alice encrypts a message for Bob
Given that I am known as 'Alice'
and I have my valid 'keypair'
and I have a valid 'public key' from 'Bob'
When I write 'This is my secret message.' in 'message'
and I write 'This is the header' in 'header'
and I encrypt the message for 'Bob'
Then print the 'secret message'
Given that I am known as 'Alice'
and I have my valid 'keypair'
and I have a valid 'public key' from 'Bob'
When I write 'This is my secret message.' in 'message'
and I write 'This is the header' in 'header'
and I encrypt the message for 'Bob'
Then print the 'secret message'

12
docs/examples/zencode_simple/DSA01.zen

@ -1,8 +1,8 @@
Rule check version 1.0.0
Scenario 'simple': Alice signs a message for Bob
Given that I am known as 'Alice'
and I have my valid 'keypair'
When I write 'This is my signed message to Bob.' in 'draft'
and I create the signature of 'draft'
Then print my 'signature'
and print my 'draft'
Given that I am known as 'Alice'
and I have my valid 'keypair'
When I write 'This is my signed message to Bob.' in 'draft'
and I create the signature of 'draft'
Then print my 'signature'
and print my 'draft'

14
docs/examples/zencode_simple/DSA02.zen

@ -1,9 +1,9 @@
rule check version 1.0.0
Scenario 'simple': Bob verifies the signature from Alice
Given that I am known as 'Bob'
and I have a valid 'public key' from 'Alice'
and I have a valid 'signature' from 'Alice'
and I have a 'draft'
When I verify the 'draft' is signed by 'Alice'
Then print 'signature' 'correct' as 'string'
and print as 'string' the 'draft'
Given that I am known as 'Bob'
and I have a valid 'public key' from 'Alice'
and I have a valid 'signature' from 'Alice'
and I have a 'draft'
When I verify the 'draft' is signed by 'Alice'
Then print 'signature' 'correct' as 'string'
and print as 'string' the 'draft'

6
docs/examples/zencode_simple/SYM01.zen

@ -1,5 +1,5 @@
rule check version 1.0.0
Scenario simple: Generate a random password
Given nothing
When I create a random 'password'
Then print the 'password'
Given nothing
When I create a random 'password'
Then print the 'password'

18
docs/examples/zencode_simple/SYM02.zen

@ -1,10 +1,10 @@
Scenario simple: Encrypt a message with the password
Given nothing
# only inline input, no KEYS or DATA passed
When I write 'my secret word' in 'password'
and I write 'a very short but very confidential message' in 'whisper'
and I write 'for your eyes only' in 'header'
# header is implicitly used when encrypt
and I encrypt the secret message 'whisper' with 'password'
# anything introduced by 'the' becomes a new variable
Then print the 'secret message'
Given nothing
# only inline input, no KEYS or DATA passed
When I write 'my secret word' in 'password'
and I write 'a very short but very confidential message' in 'whisper'
and I write 'for your eyes only' in 'header'
# header is implicitly used when encrypt
and I encrypt the secret message 'whisper' with 'password'
# anything introduced by 'the' becomes a new variable
Then print the 'secret message'

10
docs/examples/zencode_simple/SYM03.zen

@ -1,6 +1,6 @@
Scenario simple: Decrypt the message with the password
Given I have a valid 'secret message'
When I write 'my secret word' in 'password'
and I decrypt the secret message with 'password'
Then print as 'string' the 'text' inside 'message'
and print as 'string' the 'header' inside 'message'
Given I have a valid 'secret message'
When I write 'my secret word' in 'password'
and I decrypt the secret message with 'password'
Then print as 'string' the 'text' inside 'message'
and print as 'string' the 'header' inside 'message'

2
docs/pages/ldoc/o/README.md

@ -189,7 +189,7 @@ href="https://zenroom.org">Zenroom.org</a>.</p>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

4
docs/pages/ldoc/o/examples/crypt-to-multi.lua.html

@ -85,7 +85,7 @@ res = {}
out = { header = <span class="string">"encoded using zenroom "</span> .. VERSION.original}
<span class="comment">-- encrypt the message with the session key
</span> out.text, out.checksum =
ECDH.aead_encrypt(KDF(session), secret, iv, out.header)
AES.gcm_encrypt(KDF(session), secret, iv, out.header)
<span class="comment">-- insert results in final json array
</span> res[name] = url64( JSON.encode(out) )
@ -99,7 +99,7 @@ res = {}
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/examples/keygen.lua.html

@ -68,7 +68,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

91
docs/pages/ldoc/o/modules/AES.html

@ -0,0 +1,91 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>Zenroom LUA</title>
<link rel="stylesheet" href="" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>Zenroom</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/OCTET.html">OCTET</a></li>
<li><a href="../modules/HASH.html">HASH</a></li>
<li><strong>AES</strong></li>
<li><a href="../modules/ECDH.html">ECDH</a></li>
<li><a href="../modules/ECP.html">ECP</a></li>
<li><a href="../modules/String.html">String</a></li>
<li><a href="../modules/Table.html">Table</a></li>
<li><a href="../modules/INSPECT.html">INSPECT</a></li>
<li><a href="../modules/ZEN.html">ZEN</a></li>
<li><a href="../modules/BIG.html">BIG</a></li>
</ul>
<h2>Examples</h2>
<ul class="nowrap">
<li><a href="../examples/keygen.lua.html">keygen.lua</a></li>
<li><a href="../examples/crypt-to-multi.lua.html">crypt-to-multi.lua</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>AES</code></h1>
<p>
<h1>Advanced Encryption Standard (AES)</h1>
<p> AES Block cipher in varoius modes.</p>
</p>
<p> AES encryption and decryption functionalities are provided by
this module.</p>
<h3>Info:</h3>
<ul>
<li><strong>Copyright</strong>: Dyne.org foundation 2017-2020</li>
<li><strong>License</strong>: AGPLv3</li>
<li><strong>Author</strong>: Denis "Jaromil" Roio</li>
</ul>
<br/>
<br/>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>

2
docs/pages/ldoc/o/modules/BIG.html

@ -212,7 +212,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/ECDH.html

@ -288,7 +288,7 @@ signature = ECDH.sign(kp.private, m)
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/ECP.html

@ -560,7 +560,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/HASH.html

@ -290,7 +290,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/INSPECT.html

@ -180,7 +180,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/OCTET.html

@ -456,7 +456,7 @@ newly allocated octet, does not change the contents of other octets.
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/String.html

@ -659,7 +659,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/Table.html

@ -278,7 +278,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/pages/ldoc/o/modules/ZEN.html

@ -127,7 +127,7 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-04-07 15:58:34 </i>
<i style="float:right;">Last updated 2020-04-16 01:32:19 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

125
docs/pages/zencode-list.md

@ -0,0 +1,125 @@
# Zencode command list
Start reading here to understand how Zencode smart contracts are written and the philosophy behind the technology.
# Smart contract setup
First we'll look at **phases, scenarios, rules and configuration**.
*Phases*: let's rememeber that Zencode contracts operate in 3 phases:
1. **Given** - validates the input
2. **When** - processes the contents
3. **Then** - prints out the results
So each Zencode smart contract will contain at least three lines, each begining with one of the 3 keywords, in the given order.
## Scenarios
Scenarios are set in the beginning of a script and they make Zenroom use a certain set of rules to interpretate the Zencode contained in the smart contract. Different scenarios will typically contain different keywords. The syntax to set a scenario is:
```gherkin
Scenario 'simple': Create the keypair
```
The scenario setting happens before the ```:```, everything right of that isn't processed by Zenroom and can be used as a title to the smart contract.
## Rules
Rules are *optional*, they are used to define input and output formats of the smart contract, they have to be set after the scenario and before the rest of the smart contracts. Current rules:
```txt
rule input encoding [ url64 | base64 | hex | bin ]
rule input format [ json | cbor ]
```
For example, a valid config is:
```gherkin
rule input encoding hex
rule output encoding hex
```
A rule can be set also check that Zenroom is at a certain version: if the rule is not satisfied, Zenroom will stop.
```gherkin
rule check version 1.0.0
```
## Configurations
You can pass to Zenroom a configuration file, using the parameter ```-c```, description will follow soon.
---
# *Given*
This affects **my** statements
```gherkin
Given I introduce myself as ''
Given I am known as ''
Given I am ''
Given I have my ''
Given I have my valid ''
```
Data provided as input (from **data** and **keys**) is all imported
automatically from **JSON** or [CBOR](https://tools.ietf.org/html/rfc7049) binary formats.
Scenarios can add Schema for specific data validation mapped to **words** like: **signature**, **proof** or **secret**.
**Data input**
```gherkin
Given I have a ''
Given I have a valid ''
Given I have a '' inside ''
Given I have a valid '' inside ''
Given I have a '' from ''
Given I have a valid '' from ''
Given the '' is valid
```
or check emptiness:
```gherkin
Given nothing
```
all the list of valid `given` statements are:
[](../_media/zencode_utterances.yaml ':include :fragment=given :type=code yaml')
When **valid** is specified then extra checks are made on input value,
mostly according to the **scenario**
# *When*
Processing data is done in the when block. Also scenarios add statements to this block.
Without extensions, these are the basic functions available
[](../_media/zencode_utterances.yaml ':include :fragment=when :type=code yaml')
with the `simple` extension the following statementa are valid
[](../_media/zencode_utterances.yaml ':include :fragment=simple_when :type=code yaml')
with the `coconut` extension the following statementa are valid
[](../_media/zencode_utterances.yaml ':include :fragment=coconut_when :type=code yaml')
# *Then*
Output is all exported in JSON or CBOR
[](../_media/zencode_utterances.yaml ':include :fragment=then :type=code yaml')
Settings:
```txt
rule output encoding [ url64 | base64 | hex | bin ]
rule output format [ json | cbor ]
```

292
docs/pages/zencode.md

@ -1,14 +1,16 @@
# Smart contracts in human language
Zenroom is software inspired by the [language-theoretical security](http://langsec.org) research and it allows to express cryptographic operations in a readable domain-specific language called **Zencode**.
Zenroom's development is heavily inspired by the [language-theoretical security](http://langsec.org) research and the [BDD Language](https://en.wikipedia.org/wiki/Behavior-driven_development).
For the theoretical background see the [Zencode Whitepaper](https://files.dyne.org/zenroom/Zencode_Whitepaper.pdf).
Zenroom can execute smart contracts written in the domain-specific language **Zencode**, which reads in a [natural English-like fashion](https://decodeproject.eu/blog/smart-contracts-english-speaker), and allows to perform cryptographic operations as long as more traditional data manipulation.
For an introduction see this blog post: [Smart contracts for the English speaker](https://decodeproject.eu/blog/smart-contracts-english-speaker).
For the theoretical background see the [Zencode Whitepaper](https://files.dyne.org/zenroom/Zencode_Whitepaper.pdf).
Here we go with the <span class="big">**tutorial to learn the Zencode language!**</span>
# Syntax and Memory model
# Intro: Syntax and Memory model
Zencode contracts operate in 3 phases:
@ -33,58 +35,12 @@ rule check version 1.0.0
---
# Symmetric encryption
# Cryptography
This is a simple technique to hide a secret using a common password known to all participants.
A quick run to get you started with cryptography in Zencode.
The algorithm used is
[AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) with a random IV and an optional authenticated header ([AEAD](https://en.wikipedia.org/wiki/Authenticated_encryption))
The encryption is applied using 3 arguments:
- `password` can be any string (or file) used to lock and unlock the secret
- `message` can be any string (or file) to be encrypted and decrypted
- `header` is a fixed name and optional argument to indicate an authenticated header
These 3 arguments can be written or imported, but must given before using the `I encrypt` block:
[](../_media/examples/zencode_simple/SYM02.zen ':include :type=code gherkin')
The output is returned in `secret message` and it looks like:
```json
{"secret_message":{"iv":"u64:-tU2gbox9kATCeC2k_zkhYM-PBA3IzvN7HtfyVXdzB4",
"header":"u64:dGhpc19pc19mb3JfQm9i",
"text":"u64:cw4M3FBO3zaPRAB26d6y8SMPGgAo_0AmJUrhg5dmKwoEB7BWLAAD_A2h",
"checksum":"u64:UugLrIuxRX46BETc1-XkrA"}}
```
To decode make sure to have that secret password and that a valid `secret message` is given, then use:
[](../_media/examples/zencode_simple/SYM03.zen ':include :type=code gherkin')
So let's imagine I want to share a secret with someone and send secret messages encrypted with it:
```mermaid
sequenceDiagram
participant A as Anon1
participant B as Anon2
A->>A: Think of a secret password
A->>B: Tell the password to a friend
A->>A: Encrypt a secret message with the password
A->>B: Send the secret message to the friend
B->>B: Decrypts the secret message with the password
```
Of course the password must be known by all participants and that's the
dangerous part, since it could be stolen.
We mitigate this risk using **public-key cryptography**, also known as
**a-symmetric encryption**, explained below.
---
# Asymmetric encryption
## Asymmetric cryptography
We use [asymmetric encryption (or public key
cryptography)](https://en.wikipedia.org/wiki/Public-key_cryptography)
@ -96,7 +52,7 @@ Fortunately it is pretty simple to do using Zencode in 2 steps
- Key generation and exchange ([SETUP](https://en.wikipedia.org/wiki/Key_exchange))
- Public-key Encryption or signature ([ECDH](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman) and [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm))
## Key generation and exchange
### Key generation and exchange
In this phase each participant will create his/her own keypair, store it and communicate the public key to the other.
@ -140,32 +96,8 @@ After both Alice and Bob have their own keypairs and they both know
each other public key we can move forward to do asymmetric encryption
and signatures.
[](../_media/examples/zencode_simple/AES01.zen ':include :type=code gherkin')
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
```json
"Alice": {
"keypair": {
"private_key": "u64:F_NaS3Y6Xw6BW...",
"public_key": "u64:BLG0OGDwzP_gY41TZgGpUB4lTYCgpx9BJVScxSQAfwqEi..."
}
}
```
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
[](../_media/examples/zencode_simple/AES02.zen ':include :type=code gherkin')
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
```json
"Alice": {
@ -175,7 +107,7 @@ and signatures.
The advantage of using Zencode here is the use of the `valid` keyword which effectively parses the `public key` object and verifies it as valid, in this case as being a valid point on the elliptic curve in use. This greatly reduces the possibility of common mistakes.
## Public-key Encryption (ECDH)
### Public-key Encryption (ECDH)
Public key encryption is similar to the [asymmetric
encryption](#asymmetric-encryption) explained in the previous section,
@ -198,12 +130,6 @@ So with an input separated between DATA and KEYS or grouped together in an array
]
```
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
<span class="mdi mdi-arrow-down"></span>
[](../_media/examples/zencode_simple/AES05.zen ':include :type=code gherkin')
which encrypts and stores results in `secret message`; also in this case `header` may be given, then is included in the encryption as an authenticated clear-text section.
@ -237,15 +163,15 @@ the private key of Alice and the public key of Bob (or
vice versa).
```gherkin
When I write 'my secret for you' in 'message'
and I write 'an authenticated message' in 'header'
When I write 'my secret for you' in 'message'
and I write 'an authenticated message' in 'header'
```
The decryption will always check that the header hasn't changed,
maintaining the integrity of the string which may contain important
public information that accompany the secret.
## Public-key Signature (ECDSA)
### Public-key Signature (ECDSA)
Public-key signing allows to verify the integrity of a message by
knowing the public key of all those who have signed it.
@ -258,15 +184,15 @@ The one signing only needs his/her own keypair, so the key setup will
be made by the lines:
```gherkin
Given that I am known as 'Alice'
and I have my valid 'keypair'
Given that I am known as 'Alice'
and I have my valid 'keypair'
```
then assuming that the document to sign is in `draft`, Alice can
proceed signing it with:
```gherkin
and I create the signature of 'draft'
and I create the signature of 'draft'
```
which will produce a new object `signature` to be printed along the
@ -276,7 +202,7 @@ On the other side Bob will need Alice's public key to verify the
signature with the line:
```gherkin
When I verify the 'draft' is signed by 'Alice'
When I verify the 'draft' is signed by 'Alice'
```
which will fail in case the signature is invalid or the document has
@ -299,30 +225,82 @@ Here we continue assuming that the keyrings are already prepared with
public/private keypairs and the public keypair of the correspondent.
**1. Alice signs a message for Bob**
[](../_media/examples/zencode_simple/DSA01.zen ':include :type=code gherkin')
**1. Bob verifies the signed message from Alice**
[](../_media/examples/zencode_simple/DSA02.zen ':include :type=code gherkin')
In this example Alice uses her private key to sign and authenticate a
message. Bob or anyone else can use Alice's public key to prove that
the integrity of the message is kept intact and that she signed it.
## Symmetric cryptography
This is a simple technique to hide a secret using a common password known to all participants.
The algorithm used is
[AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) with a random IV and an optional authenticated header ([AEAD](https://en.wikipedia.org/wiki/Authenticated_encryption))
The encryption is applied using 3 arguments:
- `password` can be any string (or file) used to lock and unlock the secret
- `message` can be any string (or file) to be encrypted and decrypted
- `header` is a fixed name and optional argument to indicate an authenticated header
These 3 arguments can be written or imported, but must given before using the `I encrypt` block:
[](../_media/examples/zencode_simple/SYM02.zen ':include :type=code gherkin')
The output is returned in `secret message` and it looks like:
```json
{"secret_message":{"iv":"u64:-tU2gbox9kATCeC2k_zkhYM-PBA3IzvN7HtfyVXdzB4",
"header":"u64:dGhpc19pc19mb3JfQm9i",
"text":"u64:cw4M3FBO3zaPRAB26d6y8SMPGgAo_0AmJUrhg5dmKwoEB7BWLAAD_A2h",
"checksum":"u64:UugLrIuxRX46BETc1-XkrA"}}
```
To decode make sure to have that secret password and that a valid `secret message` is given, then use:
[](../_media/examples/zencode_simple/SYM03.zen ':include :type=code gherkin')
So let's imagine I want to share a secret with someone and send secret messages encrypted with it:
```mermaid
sequenceDiagram
participant A as Anon1
participant B as Anon2
A->>A: Think of a secret password
A->>B: Tell the password to a friend
A->>A: Encrypt a secret message with the password
A->>B: Send the secret message to the friend
B->>B: Decrypts the secret message with the password
```
Of course the password must be known by all participants and that's the
dangerous part, since it could be stolen.
We mitigate this risk using **public-key cryptography**, also known as
**a-symmetric encryption**, explained below.
---
# Attribute Based Credentials
# The *Coconut* flow: ZKP and ABC
In this chapter we'll look at some more advanced cryptography, namely the 'Attribute Based Credentials' and the 'Zero Knowledge Proof': this is powerful and complex feature
implemented using the [Coconut crypto scheme](https://arxiv.org/pdf/1802.07344.pdf).
![Alice in Wonderland](../_media/images/alice_with_cards-sm.jpg)
'ABC' and 'ZKP' are among the most complex functionality available in Zenroom, this chapter will give an idea one their purpose, how they work and show how Zencode simplifies them greatly.
Attribute Based Credentials are a powerful and complex feature
implemented using the [Coconut crypto
scheme](https://arxiv.org/pdf/1802.07344.pdf). This is the most
complex functionality available in Zenroom and it will show how the
Zencode language really simplifies it.
## Attribute Based Credentials
![Alice in Wonderland](../_media/images/alice_with_cards-sm.jpg)
Let's imagine 3 different subjects for our scenarios:
1. **Mad Hatter** is a well known **issuer** in Wonderland
1. **Mad Hatter** is a well known **credential issuer** in Wonderland
2. **Wonderland** is an open space (a blockchain!) and all inhabitants can check the validity of **proofs**
3. **Alice** just arrived: to create **proofs** she'll request a **credential** to the issuer **MadHatter**
@ -515,14 +493,14 @@ print the results all together!
```gherkin
Scenario coconut
Given that I am known as 'Issuer'
When I create the issuer keypair
and I create the credential keypair
and I create the credential request
and I create the credential signature
and I create the credentials
Then print the 'credentials'
and print the 'credential keypair'
Given that I am known as 'Issuer'
When I create the issuer keypair
and I create the credential keypair
and I create the credential request
and I create the credential signature
and I create the credentials
Then print the 'credentials'
and print the 'credential keypair'
```
This will produce **credentials** that anyone can take and run. Just
@ -531,22 +509,7 @@ maliciously keep the **credential keypair** and impersonate the
**Holder**.
## Try it on your system!
Impatient to give it a spin? run Zencode scripts locally to see what
are the files produced!
Make sure that Zenroom is installed on your PC
and then go to the...
[Online Interactive Demo](/demo)
[Shell Script Examples](/pages/shell_scripts)
---
# Zero Knowledge Proofs
## Zero Knowledge Proofs
There is more to this of course: Zencode supports several features
based on pairing elliptic curve arithmetics and in particular:
@ -573,84 +536,3 @@ Three more are in the work and they are:
3. Private credential revocation
---
# Import, validate and transform data
## Given
### Self introduction
This affects **my** statements
```gherkin
Given I introduce myself as ''
Given I am known as ''
Given I am ''
Given I have my ''
Given I have my valid ''
```
Data provided as input (from **data** and **keys**) is all imported
automatically from **JSON** or [CBOR](https://tools.ietf.org/html/rfc7049) binary formats.
Scenarios can add Schema for specific data validation mapped to **words** like: **signature**, **proof** or **secret**.
**Data input**
```gherkin
Given I have a ''
Given I have a valid ''
Given I have a '' inside ''
Given I have a valid '' inside ''
Given I have a '' from ''
Given I have a valid '' from ''
Given the '' is valid
```
or check emptiness:
```gherkin
Given nothing
```
all the list of valid `given` statements are:
[](../_media/zencode_utterances.yaml ':include :fragment=given :type=code yaml')
When **valid** is specified then extra checks are made on input value,
mostly according to the **scenario**
**Settings**
```txt
rule input encoding [ url64 | base64 | hex | bin ]
rule input format [ json | cbor ]
```
## When
Processing data is done in the when block. Also scenarios add statements to this block.
Without extensions, these are the basic functions available
[](../_media/zencode_utterances.yaml ':include :fragment=when :type=code yaml')
with the `simple` extension the following statementa are valid
[](../_media/zencode_utterances.yaml ':include :fragment=simple_when :type=code yaml')
with the `coconut` extension the following statementa are valid
[](../_media/zencode_utterances.yaml ':include :fragment=coconut_when :type=code yaml')
## Then
Output is all exported in JSON or CBOR
[](../_media/zencode_utterances.yaml ':include :fragment=then :type=code yaml')
Settings:
```txt
rule output encoding [ url64 | base64 | hex | bin ]
rule output format [ json | cbor ]
```

Loadingโ€ฆ
Cancel
Save