Commit 42b93932 authored by Jaromil's avatar Jaromil
Browse files

documentation updates for release

parent efa8c35c
# Zenroom ChangeLog
## 0.7.0
### August 2018
Adopted AES-GCM as default encryption method, downgraded CBC as weak.
Fixes to the exposed API for complete usage in Zenroom-studio. Added
seccomp kernel-level protection and insured unikernel functionality
with provable isolation from network and filesystem access. Added
language bindings, a Python module is now provided.
Switched to BLS383 curve for ECP operations and upgraded Milagro to
version 4.12.0. Implemented arithmetic operations on BIG numbers and
improved the language design around ECP, ECDH and OCTET. Exposed and
improved objects for HASH and RNG. Added curves GOLDILOCKS and
SECP256K1 for use in ECDH and Base58 for OCTET. Added support for
MSGPACK binary serialization format.
Updated tests and examples, added new simple implementation for
ElGamal with ZKP using ECP primitives. Started ECP2 twisted curve
implementation. Improved build system; added python, java and esp32
targets. Updated API documentation.
## 0.6.0
### June 2018
......
......@@ -6,18 +6,18 @@ Zenroom is a brand new, small and portable virtual machine for cryptographic ope
Zencode is the name of the language executed by Zenroom: it is simple to understand and can process large data structures while operating cryptographic transformations on them. Zencode is a Domain Specific Language whose design is informed by pilot use-cases in DECODE.
## Latest stable release is 0.6.0:
## Latest stable release is 0.7.0:
<ul class="center">
<li class="fab fa-node-js"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.6.0-javascript.zip">Javscript (nodeJS and WASM)</a></li>
<li class="fab fa-node-js"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.7.0-javascript.zip">Javscript (nodeJS and WASM)</a></li>
<li class="fab fa-linux"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.6.0-linux.zip">Linux (ARM and x86)</a></li>
<li class="fab fa-linux"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.7.0-linux.zip">Linux (ARM and x86)</a></li>
<li class="fab fa-windows"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.6.0-windows.zip">Windows (EXE and DLL)</li>
<li class="fab fa-windows"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.7.0-windows.zip">Windows (EXE and DLL)</li>
<li class="fab fa-apple"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.6.0-apple.zip">Apple (OSX and iOS)</li>
<li class="fab fa-apple"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.7.0-apple.zip">Apple (OSX and iOS)</li>
<li class="far fa-file-archive"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.6.0.tar.gz">Source Code</a></li>
<li class="far fa-file-archive"><a href="https://files.dyne.org/zenroom/releases/Zenroom-0.7.0.tar.gz">Source Code</a></li>
<li class="fab fa-github"><a href="https://github.com/decodeproject/zenroom">Git repository</a></li>
......
......@@ -27,6 +27,8 @@ file={
'../../src/zen_octet.c',
'../../src/zen_ecdh.c',
'../../src/zen_ecp.c',
'../../src/zen_ecp2.c',
'../../src/zen_big.c',
'../../src/lua/functional.lua',
'math.lua',
'string.lua',
......
Subproject commit af1e2a1d7a696d8c34e594f86ceeea8a9a17b8df
Subproject commit 0563bac91b2096b61d970e5f644fa6b1e7677c9b
......@@ -39,7 +39,7 @@
//
// The values of each number can be imported using big:hex() and big:base64() methods.
//
// @module big
// @module BIG
// @author Denis "Jaromil" Roio
// @license GPLv3
// @copyright Dyne.org foundation 2017-2018
......@@ -88,13 +88,13 @@ int big_destroy(lua_State *L) {
}
/***
Create a new Big number. Set it to zero if no argument is present, else import the value from @{octet}.
Create a new Big number. Set it to zero if no argument is present, else import the value from @{OCTET}.
@param[opt] octet value of the big number
@return a new Big number set to the given value or Zero if none
@function big:new(octet)
@see octet:hex
@see octet:base64
@function BIG.new(octet)
@see OCTET:hex
@see OCTET:base64
*/
static int newbig(lua_State *L) {
HERE();
......
......@@ -22,14 +22,10 @@
// Asymmetric public/private key encryption technologies.
//
// ECDH encryption functionalities are provided with all standard
// functions by this extension, which has to be required explicitly:
//
// <code>ecdh = require'ecdh'</code>
//
// After requiring the extension it is possible to create keyring
// functions by this extension. It is possible to create keyring
// instances using the new() method:
//
// <code>keyring = ecdh.new()</code>
// <code>keyring = ECDH.new()</code>
//
// One can create more keyrings in the same script and call them with
// meaningful variable names to help making code more
......@@ -39,7 +35,7 @@
// represented by each keyring, giving them names as 'Alice' or
// 'Bob'.
//
// @module ecdh
// @module ECDH
// @author Denis "Jaromil" Roio, Enrico Zimuel
// @license GPLv3
// @copyright Dyne.org foundation 2017-2018
......@@ -71,8 +67,8 @@
// from zen_ecdh_factory.h to setup function pointers
extern ecdh *ecdh_new_curve(lua_State *L, const char *curve);
/// Global ECDH extension
// @section ecdh.globals
/// Global ECDH functions
// @section ECDH.globals
/***
Create a new ECDH encryption keyring using a specified curve or
......@@ -85,8 +81,7 @@ extern ecdh *ecdh_new_curve(lua_State *L, const char *curve);
@return a new ECDH keyring
@function new(curve)
@usage
ecdh = require'ecdh'
keyring = ecdh.new('ed25519')
keyring = ECDH.new('ed25519')
-- generate a keypair
keyring:keygen()
*/
......@@ -138,7 +133,7 @@ int ecdh_destroy(lua_State *L) {
return 0;
}
/// Keyring Methods
/// Instance Methods
// @type keyring
/**
......@@ -150,8 +145,8 @@ int ecdh_destroy(lua_State *L) {
necessary.
@function keyring:keygen()
@treturn[1] octet public key
@treturn[1] octet private key
@treturn[1] OCTET public key
@treturn[1] OCTET private key
*/
static int ecdh_keygen(lua_State *L) {
HERE();
......
......@@ -28,14 +28,14 @@
// primitives and work the same across different curves.
//
// It is possible to create ECP points instances using the @{new}
// method. The values of each coordinate can be imported using @{big}
// methods from @{big:hex} or @{big:base64}.
// method. The values of each coordinate can be imported using @{BIG}
// methods `BIG.hex()` or `BIG.base64()`.
//
// Once ECP numbers are created this way, the arithmetic operations
// of addition, subtraction and multiplication can be executed
// normally using overloaded operators (+ - *).
//
// @module ecp
// @module ECP
// @author Denis "Jaromil" Roio
// @license GPLv3
// @copyright Dyne.org foundation 2017-2018
......@@ -119,13 +119,13 @@ int ecp_destroy(lua_State *L) {
}
/***
Create a new ECP point from two X,Y @{big} arguments. If no X,Y arguments are specified then the ECP points to the curve's @{generator} coordinates. If the first argument is an X coordinate on the curve and Y is just a number 0 or 1 then Y is calculated from the curve equation according to the given sign (plus or minus).
Create a new ECP point from two X,Y @{BIG} arguments. If no X,Y arguments are specified then the ECP points to the curve's @{generator} coordinates. If the first argument is an X coordinate on the curve and Y is just a number 0 or 1 then Y is calculated from the curve equation according to the given sign (plus or minus).
@param[opt=big] X a big number on the curve
@param[opt=big] Y a big number on the curve, 0 or 1 to calculate it
@param[opt=BIG] X a BIG number on the curve
@param[opt=BIG] Y a BIG number on the curve, 0 or 1 to calculate it
@return a new ECP point on the curve at X,Y coordinates or Infinity
@function new(X,Y)
@see big:new
@see BIG:new
*/
static int lua_new_ecp(lua_State *L) {
if(lua_isnoneornil(L, 1)) { // no args: set to generator
......@@ -159,8 +159,11 @@ static int lua_new_ecp(lua_State *L) {
return 0;
}
/// Instance Methods
// @type ecp
/***
Make an existing ECP point affine with the curve
Make an existing ECP point affine with its curve
@function affine()
*/
static int ecp_affine(lua_State *L) {
......@@ -193,10 +196,10 @@ static int ecp_isinf(lua_State *L) {
}
/***
Map a @{big} number to a point of the curve, where the big number should be the output of some hash function.
Map a @{BIG} number to a point of the curve, where the BIG number should be the output of some hash function.
@param big number resulting from an hash function
@function mapit(big)
@param BIG number resulting from an hash function
@function mapit(BIG)
*/
static int ecp_mapit(lua_State *L) {
const big *b = big_arg(L,1); SAFE(b);
......@@ -288,7 +291,7 @@ static int ecp_double(lua_State *L) {
static int ecp_mul(lua_State *L) {
ecp *e = ecp_arg(L,1); SAFE(e);
ecp *out = ecp_dup(L,e); SAFE(out);
// implicitly convert scalar numbers to big
// implicitly convert scalar numbers to BIG
int tn;
lua_Number n = lua_tonumberx(L, 2, &tn);
if(tn) {
......@@ -323,7 +326,7 @@ static int ecp_eq(lua_State *L) {
}
/***
Sets or returns an octet containing a @{big} number composed by both x,y coordinates of an ECP point on the curve. It can be used to port the value of an ECP point into @{octet:hex} or @{octet:base64} encapsulation, to be later set again into an ECP point using this same call.
Sets or returns an octet containing a @{BIG} number composed by both x,y coordinates of an ECP point on the curve. It can be used to port the value of an ECP point into @{OCTET:hex} or @{OCTET:base64} encapsulation, to be later set again into an ECP point using this same call.
@param ecp[opt=octet] the octet to be imported, none if to be exported
@function octet(ecp)
......@@ -347,11 +350,11 @@ static int ecp_octet(lua_State *L) {
Gives the order of the curve, a BIG number contained in an octet.
@function order()
@return a big containing the curve's order
@return a BIG containing the curve's order
*/
static int ecp_order(lua_State *L) {
big *res = big_new(L); SAFE(res);
// big is an array of int32_t on chunk 32 (see rom_curve)
// BIG is an array of int32_t on chunk 32 (see rom_curve)
// curve order is ready-only so we need a copy for norm() to work
BIG_copy(res->val,(chunk*)CURVE_Order);
......@@ -359,10 +362,10 @@ static int ecp_order(lua_State *L) {
}
/***
Gives the X coordinate of the ECP point as a single @{big} number.
Gives the X coordinate of the ECP point as a single @{BIG} number.
@function x()
@return a big number indicating the X coordinate of the point on curve.
@return a BIG number indicating the X coordinate of the point on curve.
*/
static int ecp_get_x(lua_State *L) {
ecp *e = ecp_arg(L, 1); SAFE(e);
......@@ -375,10 +378,10 @@ static int ecp_get_x(lua_State *L) {
}
/***
Gives the Y coordinate of the ECP point as a single @{big} number.
Gives the Y coordinate of the ECP point as a single @{BIG} number.
@function y()
@return a big number indicating the Y coordinate of the point on curve.
@return a BIG number indicating the Y coordinate of the point on curve.
*/
static int ecp_get_y(lua_State *L) {
ecp *e = ecp_arg(L, 1); SAFE(e);
......
......@@ -30,14 +30,14 @@
// pairing.
//
// It is possible to create ECP2 points instances using the @{new}
// method. The values of each coordinate can be imported using @{big}
// methods from @{big:hex} or @{big:base64}.
// method. The values of each coordinate can be imported using @{BIG}
// methods from `BIG.hex()` or `BIG.base64()`.
//
// Once ECP2 points are created this way, the arithmetic operations
// of addition, subtraction and multiplication can be executed
// normally using overloaded operators (+ - *).
//
// @module ecp2
// @module ECP2
// @author Denis "Jaromil" Roio
// @license GPLv3
// @copyright Dyne.org foundation 2017-2018
......@@ -100,17 +100,22 @@ int ecp2_destroy(lua_State *L) {
return 0;
}
/// Global ECP2 functions
// @section ECP2.globals
/***
Create a new ECP2 point from four X,Xi,Y,Yi @{big} arguments. If no arguments are specified then the ECP points to the curve's @{generator} coordinates. If only the first two arguments are provided (X and Xi), then Y and Yi are calculated from them.
@param[opt=big] X a big number on the curve
@param[opt=big] Xi imaginary part of the X (big number)
@param[opt=big] Y a big number on the curve
@param[opt=big] Yi imaginary part of the Y (big number)
@return a new ECP2 point on the curve at X,Xi,Y,Yi coordinates or Infinity
@function new(X,Xi,Y,Yi)
@see big:new
Create a new ECP2 point from four X,Xi,Y,Yi @{BIG} arguments.
If no arguments are specified then the ECP points to the curve's **generator** coordinates.
If only the first two arguments are provided (X and Xi), then Y and Yi are calculated from them.
@param X a BIG number on the curve
@param Xi imaginary part of the X (BIG number)
@param Y a BIG number on the curve
@param Yi imaginary part of the Y (BIG number)
@return a new ECP2 point on the curve at X,Xi,Y,Yi coordinates or the curve's Generator
@function ECP2.new(X,Xi,Y,Yi)
*/
static int lua_new_ecp2(lua_State *L) {
if(lua_isnoneornil(L, 1)) { // no args: set to generator
......@@ -157,10 +162,13 @@ static int lua_new_ecp2(lua_State *L) {
return 0;
}
/// Class methods
// @type ecp2
/***
Make an existing ECP2 point affine with the curve
@function affine()
@function ecp2:affine()
@return affine version of the ECP2 point
*/
static int ecp2_affine(lua_State *L) {
ecp2 *in = ecp2_arg(L,1); SAFE(in);
......
......@@ -18,31 +18,24 @@
* Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/// <h1>Base data type for cryptography</h1>
/// <h1>Base data type for cryptographic opearations</h1>
//
// Octets are <a
// href="https://en.wikipedia.org/wiki/First-class_citizen">first-class
// citizens</a> in Zenroom. They consist of arrays of bytes (8bit)
// compatible with all cryptographic functions and methods. They are
// implemented to avoid any buffer overflow and their maximum size is
// known at the time of instantiation. The are provided by the
// 'octet' extension which has to be required explicitly:
//
// <code>octet = require'octet'</code>
//
// After requiring the extension it is possible to create keyring
// known at the time of instantiation. It is possible to create OCTET
// instances using the new() method:
//
// <code>message = octet.new()</code>
// <code>message = octet.new(64) -- creates a 64 bytes long octet</code>
//
// Octets can import and export their contents to portable formats as
// sequences of :base64() or :hex() numbers just using their
// appropriate methods. Without an argument, these methods export
// contents in the selected format, when there is an argument that is
// considered to be of the selected format and its contents are
// converted to bytes and imported.
// Octets can export their contents to portable formats as sequences
// of @{base64} or @{base58} or @{hex} strings just using their
// appropriate methods. They can also be exported to Lua's @{array}
// format.
//
// @module octet
// @module OCTET
// @author Denis "Jaromil" Roio
// @license GPLv3
// @copyright Dyne.org foundation 2017-2018
......@@ -161,7 +154,7 @@ int o_destroy(lua_State *L) {
}
/// Global Octet Functions
// @section octet
// @section OCTET
//
// So called "global functions" are all prefixed by <b>octet.</b>,
// operate on one or more octet objects and always return a new octet
......@@ -178,14 +171,9 @@ Create a new octet with a specified maximum size, or a default if
omitted. All operations exceeding the octet's size will truncate
excessing data. Octets cannot be resized.
@function octet.new(length)
@function OCTET.new(length)
@int[opt=4096] length maximum length in bytes
@return octet newly instantiated octet
@usage
var2k = octet.new(2048) -- create an octet of 2KB
-- create another octet at default size
var4k = octet.new()
*/
static int newoctet (lua_State *L) {
const int len = luaL_optinteger(L, 1, MAX_OCTET);
......@@ -199,14 +187,15 @@ static int newoctet (lua_State *L) {
}
/***
Bitwise XOR operation on two octets, returns a new octet. This is
also executed when using the '<b>~</b>' operator between two
octets. Results in a newly allocated octet, does not change the
contents of any other octet involved.
Bitwise XOR operation on two octets, returns a new octet. This is also
executed when using the '<b>~</b>' operator between two
octets. Results in a newly allocated octet, does not change the
contents of any other octet involved.
@param dest leftmost octet used in XOR operation
@param source rightmost octet used in XOR operation
@function octet.xor(dest, source)
@function OCTET.xor(dest, source)
@return a new octet resulting from the operation
*/
static int xor_n(lua_State *L) {
......@@ -288,14 +277,13 @@ static int from_hex(lua_State *L) {
}
/***
Concatenate two octets, returns a new octet. This is also executed
when using the '<b>..</b>' operator btween two octets. It results
in a newly allocated octet, does not change the contents of other
octets.
Concatenate two octets, returns a new octet. This is also executed
when using the '<b>..</b>' operator btween two octets. It results in a
newly allocated octet, does not change the contents of other octets.
@param dest leftmost octet will be overwritten by result
@param source rightmost octet used in XOR operation
@function octet.concat(dest, source)
@function OCTET.concat(dest, source)
@return a new octet resulting from the operation
*/
static int concat_n(lua_State *L) {
......@@ -342,28 +330,28 @@ static int concat_n(lua_State *L) {
// octet:<span class="global">method</span>(<span class="string">args</span>)
// </pre>
//
// Octet contents are changed by the method "in-place" on "this"
// object, instead of returning a new octet. This is the main
// difference from using global functions in the octet namespace.
// @see globals
// above we could use @type octet but rendering is ugly
// Octet contents are never changed: the methods always return a new
// octet with the requested changes applied.
//
/***
Print an octet in base64 notation
Print an octet in base64 notation.
@function octet:base64()
@return a string representing the octet's contents in base64
@see octet:hex
@usage
-- This method as well :string() and :hex() can be used both to set
-- from and print out in particular formats.
-- create an octet from a string:
OCTET.string("my message to be encoded in base64")
msg = OCTET.string("my message to be encoded in base64")
-- print the message in base64 notation:
print(msg:base64())
*/
static int to_base64 (lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
......@@ -383,17 +371,17 @@ static int to_base64 (lua_State *L) {
/***
Print an octet in base58 notation
Print an octet in base58 notation.
This encoding uses the same alphabet as Bitcoin addresses. Why base58 instead of standard base64 encoding?
This encoding uses the same alphabet as Bitcoin addresses. Why
base58 instead of standard base64 encoding?
- Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking data.
- A string with non-alphanumeric characters is not as easily accepted as input.
- E-mail usually won't line-break if there's no punctuation to break at.
- Double-clicking selects the whole string as one word if it's all alphanumeric.
- Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking data.
- A string with non-alphanumeric characters is not as easily accepted as input.
- E-mail usually won't line-break if there's no punctuation to break at.
- Double-clicking selects the whole string as one word if it's all alphanumeric.
@string data a base58 string whose contents are imported
@function octet:base58(data)
@function octet:base58()
@return a string representing the octet's contents in base58
*/
static int to_base58(lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
......@@ -418,6 +406,13 @@ static int to_base58(lua_State *L) {
return 1;
}
/***
Converts an octet into an array of bytes, compatible with Lua's transformations on <a href="https://www.lua.org/pil/11.1.html">arrays</a>.
@function octet:array()
@return an array as Lua's internal representation
*/
static int to_array(lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
if(!o->len || !o->val) {
......@@ -437,11 +432,10 @@ static int to_array(lua_State *L) {
}
/***
Print an octet as string or import a string inside the octet.
Print an octet as string.
@string[opt] data_str a string whose contents in bytes are imported
@function octet:string(data_str)
@see octet:base64
@function octet:string()
@return a string representing the octet's contents
*/
static int to_string(lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
......@@ -456,10 +450,12 @@ static int to_string(lua_State *L) {
/***
Return a string of hexadecimal numbers representing the octet's content.
Converts an octet into a string of hexadecimal numbers representing its contents.
This is the default format when `print()` is used on an octet.
@function octet:hex(hex)
@see octet:base64
@function octet:hex()
@return a string of hexadecimal numbers
*/
static int to_hex(lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
......@@ -480,6 +476,7 @@ static int to_hex(lua_State *L) {
maximum size.
@int[opt=octet:max] length pad to this size, will use maximum octet size if omitted
@return new octet padded at length
@function octet:pad(length)
*/
static int pad(lua_State *L) {
......@@ -512,6 +509,7 @@ static int zero(lua_State *L) {
Compare two octets to see if contents are equal.
@function octet:eq(first, second)
@return true if equal, false otherwise
*/
static int eq(lua_State *L) {
......@@ -530,13 +528,6 @@ static int eq(lua_State *L) {
return 1;
}
/***
Bitwise XOR operation on this octet and another one. Operates
in-place, overwriting contents of this octet.
@param const octet used in XOR operation
@function octet:xor(const)
*/
static int size(lua_State *L) {
octet *o = o_arg(L,1); SAFE(o);
lua_pushinteger(L,o->len);
......@@ -549,27 +540,12 @@ static int max(lua_State *L) {
return 1;
}
// static int name(lua_State *L) {
// octet *o = o_arg(L,1); SAFE(o);
// char n[MAX_STRING];
// if(!lua_getobjname ((lua_Object*)o, &n)) {
// ERROR();
// return lerror("Name not found for object"); }
// lua_pushstring(L,n);
// return 1;
// }
int luaopen_octet(lua_State *L) {
const struct luaL_Reg octet_class[] = {
{"new",newoctet},
{"concat",concat_n},
{"xor",xor_n},
{"from_base64",from_base64},
{"from_base58",from_base58},
{"from_string",from_string},
{"from_hex",from_hex},
{"base64",from_base64},
{"base58",from_base58},
{"string",from_string},
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment