Browse Source

crypto api documentation and tests ran by make check

Jaromil 1 year ago
parent
commit
9c2b6557c4
2 changed files with 174 additions and 1 deletions
  1. 3 0
      Makefile
  2. 171 1
      README.md

+ 3 - 0
Makefile

@@ -28,6 +28,9 @@ luanacha:
28 28
 # 	if ! [ -r lib/gmp/Makefile ]; then cd lib/gmp && CC=${musl-gcc} ./configure --disable-shared --enable-static; fi
29 29
 # 	make -C lib/gmp -j2
30 30
 
31
+check:
32
+	src/decode-exec -c src/decode-exec.conf test/test_luanacha.lua
33
+
31 34
 clean:
32 35
 	rm -rf ${luasand}
33 36
 	make -C src clean

+ 171 - 1
README.md

@@ -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