|
@@ -1,7 +1,11 @@
|
1
|
1
|
# DECODE lang
|
2
|
2
|
|
3
|
3
|
Restricted execution environment for LUA based blockchain language
|
4
|
|
-implementation. For more information see [docs](docs/article).
|
|
4
|
+implementation. For more information see [docs](docs).
|
|
5
|
+
|
|
6
|
+This implementation has no threading support, so no parallel
|
|
7
|
+execution: the binary produced is fully static and designed to be
|
|
8
|
+executed as a new process for each new script.
|
5
|
9
|
|
6
|
10
|
## Build instructions
|
7
|
11
|
|
|
@@ -21,6 +25,168 @@ Then at last run the build command:
|
21
|
25
|
make
|
22
|
26
|
```
|
23
|
27
|
|
|
28
|
+## Crypto functionalities
|
|
29
|
+
|
|
30
|
+This interpreter includes statically the following cryptographic
|
|
31
|
+primitives, extracted from the NaCl library and included via the
|
|
32
|
+monocypher/luanacha implementation:
|
|
33
|
+
|
|
34
|
+- Authenticated encryption with Chacha20 stream encryption (more precisely Xchacha20, ie. Chacha with a 24-byte nonce) and Poly1305 MAC,
|
|
35
|
+- Curve25519-based key exchange and public key encryption,
|
|
36
|
+- Blake2b hash function,
|
|
37
|
+- Ed25519-based signature function using Blake2b hash instead of sha512,
|
|
38
|
+- Argon2i, a modern key derivation function based on Blake2b. Like scrypt, it is designed to be expensive in both CPU and memory.
|
|
39
|
+
|
|
40
|
+### Crypto API
|
|
41
|
+
|
|
42
|
+Here a summary of calls available.
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+```
|
|
46
|
+randombytes(n)
|
|
47
|
+ return a string containing n random bytes
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+--- Authenticated encryption
|
|
51
|
+
|
|
52
|
+lock(key, nonce, plain [, prefix]) => crypted
|
|
53
|
+ authenticated encryption using Xchacha20 and a Poly1305 MAC
|
|
54
|
+ key must be a 32-byte string
|
|
55
|
+ nonce must be a 24-byte string
|
|
56
|
+ plain is the text to encrypt as a string
|
|
57
|
+ prefix is an optional string. If it is provided, it is prepended
|
|
58
|
+ to the encrypted text. The prefix can be use for example to
|
|
59
|
+ store the nonce, and avoid extra string allocation and copying in
|
|
60
|
+ Lua applications. The prefix defaults to the empty string.
|
|
61
|
+ Return the encrypted text as a string. The encrypted text includes
|
|
62
|
+ the 16-byte MAC. So #crypted == #plain + 16 + #prefix
|
|
63
|
+
|
|
64
|
+ Note: the prefix is not an "additional data" in the AEAD sense.
|
|
65
|
+ The MAC is computed over only the encrypted text. It does not include
|
|
66
|
+ the prefix.
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+unlock(key, nonce, crypted [, offset]) => plain
|
|
70
|
+ authenticated decryption - verification of the Poly1305 MAC
|
|
71
|
+ and decryption with Xcahcha20.
|
|
72
|
+ key must be a 32-byte string
|
|
73
|
+ nonce must be a 24-byte string
|
|
74
|
+ crypted is the text to decrypt as a string
|
|
75
|
+ offset is an optional integer. It is the length of the prefix used
|
|
76
|
+ by lock() if any. It defaults to 0.
|
|
77
|
+ Return the decrypted text as a string or nil if the MAC
|
|
78
|
+ verification fails.
|
|
79
|
+
|
|
80
|
+ Note: the responsibility of using matching prefix and offset belongs
|
|
81
|
+ to the application.
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+--- Curve25519-based key exchange
|
|
85
|
+
|
|
86
|
+public_key(sk) => pk
|
|
87
|
+ return the public key associated to a curve25519 secret key
|
|
88
|
+ sk is the secret key as a 32-byte string
|
|
89
|
+ pk is the associated public key as a 32-byte string
|
|
90
|
+
|
|
91
|
+keypair() => pk, sk
|
|
92
|
+ generates a pair of curve25519 keys (public key, secret key)
|
|
93
|
+ pk is the public key as a 32-byte string
|
|
94
|
+ sk is the secret key as a 32-byte string
|
|
95
|
+
|
|
96
|
+ Note: This is a convenience function:
|
|
97
|
+ pk, sk = keypair() --is equivalent to
|
|
98
|
+ sk = randombytes(32); pk = public_key(sk)
|
|
99
|
+
|
|
100
|
+key_exchange(sk, pk) => k
|
|
101
|
+ DH key exchange. Return a session key k used to encrypt
|
|
102
|
+ or decrypt a text.
|
|
103
|
+ sk is the secret key of the party invoking the function
|
|
104
|
+ ("our secret key").
|
|
105
|
+ pk is the public key of the other party
|
|
106
|
+ ("their public key").
|
|
107
|
+ sk, pk and k are 32-byte strings
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+--- Blake2b cryptographic hash
|
|
111
|
+
|
|
112
|
+blake2b_init([digest_size [, key]]) => ctx
|
|
113
|
+ initialize and return a blake2b context object
|
|
114
|
+ digest_size is the optional length of the expected digest. If provided,
|
|
115
|
+ it must be an integer between 1 and 64. It defaults to 64.
|
|
116
|
+ key is an optional key allowing to use blake2b as a MAC function.
|
|
117
|
+ If provided, key is a string with a length that must be between
|
|
118
|
+ 1 and 64. The default is no key.
|
|
119
|
+ ctx is a pointer to the blake2b context as a light userdata.
|
|
120
|
+
|
|
121
|
+blake2b_update(ctx, text_fragment)
|
|
122
|
+ update the hash with a new text fragment
|
|
123
|
+ ctx is a pointer to a blake2b context as a light userdata.
|
|
124
|
+
|
|
125
|
+blake2b_final(ctx) => digest
|
|
126
|
+ return the final value of the hash
|
|
127
|
+ ctx is a pointer to a blake2b context as a light userdata.
|
|
128
|
+ The digest is returned as a string. The length of the digest
|
|
129
|
+ has been defined at the context creation (see blake2b_init()).
|
|
130
|
+ It defaults to 64.
|
|
131
|
+
|
|
132
|
+blake2b(text) => digest
|
|
133
|
+ compute the hash of a string.
|
|
134
|
+ Returns a 64-byte digest.
|
|
135
|
+ This is a convenience function which combines the init(),
|
|
136
|
+ update() and final() functions above.
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+--- Ed25519 signature
|
|
140
|
+
|
|
141
|
+sign_public_key(sk) => pk
|
|
142
|
+ return the public key associated to a secret key
|
|
143
|
+ sk is the secret key as a 32-byte string
|
|
144
|
+ pk is the associated public key as a 32-byte string
|
|
145
|
+
|
|
146
|
+sign_keypair() => pk, sk
|
|
147
|
+ generates a pair of ed25519 signature keys (public key, secret key)
|
|
148
|
+ pk is the public signature key as a 32-byte string
|
|
149
|
+ sk is the secret signature key as a 32-byte string
|
|
150
|
+
|
|
151
|
+ Note: This is a convenience function:
|
|
152
|
+ pk, sk = sign_keypair() --is equivalent to
|
|
153
|
+ sk = randombytes(32); pk = sign_public_key(sk)
|
|
154
|
+
|
|
155
|
+sign(sk, text) => sig
|
|
156
|
+ sign a text with a secret key
|
|
157
|
+ sk is the secret key as a 32-byte string
|
|
158
|
+ text is the text to sign as a string
|
|
159
|
+ Return the text signature as a 64-byte string.
|
|
160
|
+
|
|
161
|
+check(sig, pk, text) => is_valid
|
|
162
|
+ check a text signature with a public key
|
|
163
|
+ sig is the signature to verify, as a 64-byte string
|
|
164
|
+ pk is the public key as a 32-byte string
|
|
165
|
+ text is the signed text
|
|
166
|
+ Return a boolean indicating if the signature is valid or not.
|
|
167
|
+
|
|
168
|
+ Note: curve25519 key pairs (generated with keypair())
|
|
169
|
+ cannot be used for ed25519 signature. The signature key pairs
|
|
170
|
+ must be generated with sign_keypair().
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+--- Argon2i password derivation
|
|
174
|
+
|
|
175
|
+argon2i(pw, salt, nkb, niter) => k
|
|
176
|
+ compute a key given a password and some salt
|
|
177
|
+ This is a password key derivation function similar to scrypt.
|
|
178
|
+ It is intended to make derivation expensive in both CPU and memory.
|
|
179
|
+ pw: the password string
|
|
180
|
+ salt: some entropy as a string (typically 16 bytes)
|
|
181
|
+ nkb: number of kilobytes used in RAM (as large as possible)
|
|
182
|
+ niter: number of iterations (as large as possible, >= 10)
|
|
183
|
+ Return k, a key string (32 bytes).
|
|
184
|
+
|
|
185
|
+ For example: on a CPU i5 M430 @ 2.27 GHz laptop,
|
|
186
|
+ with nkb=100000 (100MB) and niter=10, the derivation takes ~ 1.8 sec
|
|
187
|
+
|
|
188
|
+```
|
|
189
|
+
|
24
|
190
|
|
25
|
191
|
|
26
|
192
|
## Acknowledgements
|
|
@@ -33,6 +199,10 @@ Includes code by:
|
33
|
199
|
|
34
|
200
|
- Mozilla foundation (lua_sandbox)
|
35
|
201
|
- Rich Felker, et al (musl-libc)
|
|
202
|
+- IETF Trust (blake2b)
|
|
203
|
+- Daniel J. Bernstein, Tanja Lange and Peter Schwabe (NaCl)
|
|
204
|
+- Loup Vaillant (monocypher)
|
|
205
|
+- Phil Leblanc (luanacha)
|
36
|
206
|
|
37
|
207
|
This program is free software: you can redistribute it and/or modify
|
38
|
208
|
it under the terms of the GNU Lesser General Public License as
|