Pure Lua Crypto
Lua
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

PLC - Pure Lua Crypto

A small collection of crpytographic functions, and related utilities, implemented in pure Lua (version 5.3 or above)

Recent changes

April-2018

  • Added Morus, a finalist (round 4) in the CAESAR competition for authenticated encryption.

  • Adding Gimli, cryptographic functions based on the Gimli permutation (Dan Bernstein et al., 2017, https://gimli.cr.yp.to/). Work in progress - at the moment, only the core permutation has been implemented.

  • Added Base85, including the ZeroMQ variant of Ascii85 encoding.

December-2017

  • Added SipHash, a very fast pseudorandom function (or keyed hash) optimized for speed on short messages. It can be used as a MAC and has been extensively used as a robust string hash function, as a defense against hash-flooding DoS attacks.

August-2017

June-2017

  • Added MD5.

Objective

Collect in one place standalone implementation of well-known, and/or useful, and/or interesting cryptographic algorithms.

Users should be able to pickup any file and just drop it in their project:

  • All the files are written in pure Lua, version 5.3 and above (tested on 5.3.4). Lua 5.3 is required since bit operators and string pack/unpack are extensively used.

  • The files should not require any third-party library or C extension beyond the standard Lua 5.3 library.

  • The files should not define any global. When required, they should just return a table with the algorithm's functions and constants.

Contributions, fixes, bug reports and suggestions are welcome.

What this collection is not:

  • a complete, structured cryptographic library - no promise is made about consistent API structure and documentation. This is not a library - just a collection of hopefully useful snippets of crypto source code.

  • high performance, heavy-duty cryptographic implementations -- after all, this is pure Lua... :-)

  • memory-efficient implementations (see above)

  • memory-safe algorithms -- Lua immutable strings are used and garbage-collected as needed. No guarantee is made that information, and in particular key material, is properly erased when no longer needed or do not leak.

Functions

Encryption

  • Morus, an amazingly fast (see performance below) authenticated encryption algorithm with associated data (AEAD). Morus is a finalist (round 4) in the CAESAR competition - see http://www3.ntu.edu.sg/home/wuhj/research/caesar/caesar.html

  • NORX, a very fast authenticated encryption algorithm with associated data (AEAD). NORX is a 3rd-round candidate to CAESAR. This Lua code implements the default NORX 64-4-1 variant (state is 16 64-bit words, four rounds, no parallel execution, key and nonce are 256 bits) - see https://norx.io/

  • NORX32, a variant of NORX intended for smaller architectures (32-bit and less). Key and nonce are 128 bits. (Note that this NORX32 Lua implementation is half as fast as the default 64-bit NORX. It is included here only for compatibility with other implementations - In Lua, use the default NORX implementation!)

  • Rabbit, a fast stream cipher, selected in the eSTREAM portfolio along with Salsa20, and defined in RFC 4503 (128-bit key, 64-bit IV - see more information and links in rabbit.lua)

  • Chacha20, Poly1305 and authenticated stream encryption, as defined in RFC 7539

  • Salsa20, a fast encryption algorithm and the NaCl secretbox() API for authenticated encryption (with Salsa20 and Poly1305 - see box.lua) Salsa20, Poly1305 and the NaCl library have been designed by Dan Bernstein, Tanja Lange et al. http://nacl.cr.yp.to/.

  • RC4 - for lightweight, low strength encryption. Can also be used as a simple pseudo-random number generator.

Public key

  • Elliptic curve cryptography based on curve ec25519 by Dan Bernstein, Tanja Lange et al., http://nacl.cr.yp.to/. File ec25519.lua includes the core scalar multiplication operation. File box.lua includes the NaCl box() API which combines ECDH key exchange and authenticated encryption.

Hash

  • Blake2b - Blake was a final round candidate in the NIST SHA-3 selection process. Blake2b is an improved version of Blake. See https://blake2.net/. It has been specified in RFC 7693

  • SHA2 cryptographic hash family (only sha256 for the moment)

  • SHA3 cryptographic hash family (formerly known as Keccak - 256-bit and 512-bit versions)

  • MD5, as specified in RFC 1321

  • Non-cryptographic checksums (CRC-32, Adler-32), ...

Some (un)related utilities:

  • Base64, Base58, Base85 (Z85, the ZeroMQ variant of Ascii85) and Hex encoding/decoding.

In the future...

Implementations that may come some day:

  • XChacha20 (ie. Chacha20 with a 24-byte nonce)

  • SHA2-512

  • better documentation in each file :-)

Performance

These crude numbers give an idea of the relative performance of the algorithms. They correspond to the encryption or the hash of a 10 MB string (10 * 1024 * 1024 bytes).

They have been collected on a laptop with Linux x86_64, CPU i5 M430 @ 2.27 GHz. Lua version is 5.3.3 (ELF 64 bits) - see file 'test_perf.lua'; uncomment whatever test you want to run at the end.

Plain text size: 10 MBytes. Elapsed time in seconds

Encryption

	- morus                     1.7
	- norx                      4
	- norx32                    8   

	- rabbit                    5
	- chacha20                  8
	- salsa20                   8
	- rc4                       8
	- xtea ctr                 11  
	- xor8                      1

Hash
	- blake2b-512               9
	
	- sha2-256                 17
	- sha3-256                 23
	- sha3-512                 43
	- md5                       4
	
	- poly1305 hmac             1

	- adler-32                  1 
	- crc-32                    2 

Test vectors, tests, and disclaimer

Some simplistic tests can be run (test_all.lua). Individual test files are provided in the 'test' directory.

The implementations should pass the tests, but beyond that, there is no guarantee that these implementations conform to anything :-) -- Use at your own risk!

License and credits

All the files included here are distributed under the MIT License (see file LICENSE)

The salsa20 and box/secretbox implementations are contributed by Pierre Chapuis - https://github.com/catwell