Skip to content

Latest commit

 

History

History
296 lines (205 loc) · 5.87 KB

crypt.md

File metadata and controls

296 lines (205 loc) · 5.87 KB

crypt: cryptography module

local crypt = require "crypt"

crypt provides cryptography functions.

WARNING: Please do not rely on LuaX crypt module if you actually need strong cryptography functions.

Pseudo Random Number Generator

The LuaX pseudo random number generator is a permuted congruential generator. This generator is not a cryptographically secure pseudorandom number generator. It can be used as a repeatable generator (e.g. for repeatable tests).

LuaX has a global generator (with a global seed) and can instantiate independent generators with their own seeds.

Random number generator instance

local rng = crypt.prng([seed, incr])

returns a random number generator starting from the optional seed seed and increment incr. This object has five methods: seed([seed, incr]), clone(), int([m, [n]]), float([a, [b]]) and str(n).

Special seed and incr values:

seed Initial PRNG state incr PRNG increment
nil Random value nil Random value
-1 0x4d595df4d0f33173 -1 1442695040888963407
n n n n|1

The increment shall be an odd number (i.e. even values are added 1).

Random state and increment values are taken from some entropy sources (time, memory…).

rng:seed([seed, incr])

sets the seed of the PRNG and returns the PRNG itself. The default seed is a number based on the current time and the process id.

rng:clone()

returns a clone of the PRNG (same seed, same increment).

rng:int()

returns a random integral number between 0 and crypt.RAND_MAX.

rng:int(m)

returns a random integral number between 1 and m.

rng:int(m, n)

returns a random integral number between m and n.

rng:float()

returns a random floating point number between 0.0 and 1.0.

rng:float(a)

returns a random floating point number between 0.0 and a.

rng:float(a, b)

returns a random floating point number between a and b.

rng:str(bytes)

returns a string with bytes random bytes. If bytes is negative, str returns an empty string.

Global random number generator

crypt.seed([seed, incr])

sets the seed of the global PRNG. The default seed is a number based on the current time and the process id.

crypt.int()

returns a random integral number between 0 and crypt.RAND_MAX.

crypt.int(m)

returns a random integral number between 1 and m.

crypt.int(m, n)

returns a random integral number between m and n.

crypt.float()

returns a random floating point number between 0.0 and 1.0.

crypt.float(a)

returns a random floating point number between 0.0 and a.

crypt.float(a, b)

returns a random floating point number between a and b.

crypt.str(bytes)

returns a string with bytes random bytes. If bytes is negative, str returns an empty string.

Hexadecimal encoding

The hexadecimal encoder transforms a string into a string where bytes are coded with hexadecimal digits.

crypt.hex(data)

encodes data in hexa.

crypt.unhex(data)

decodes the hexa data.

Base64 encoding

The base64 encoder transforms a string with non printable characters into a printable string (see https://en.wikipedia.org/wiki/Base64).

crypt.base64(data)

encodes data in base64.

crypt.unbase64(data)

decodes the base64 data.

crypt.base64url(data)

encodes data in base64url.

crypt.unbase64url(data)

decodes the base64url data.

CRC32 hash

The CRC-32 algorithm has been generated by pycrc with the crc-32 algorithm.

crypt.crc32(data)

computes the CRC32 of data.

CRC64 hash

The CRC-64 algorithm has been generated by pycrc with the crc-64-xz algorithm.

crypt.crc64(data)

computes the CRC64 of data.

ARC4 encryption

ARC4 is a stream cipher (see https://en.wikipedia.org/wiki/ARC4). It is designed to be fast and simple.

crypt.arc4(data, key, [drop])
crypt.unarc4(data, key, [drop])     -- note that unarc4 == arc4

encrypts/decrypts data using the ARC4Drop algorithm and the encryption key key (drops the first drop encryption steps, the default value of drop is 768).

Fast FNV-1a hash

crypt.hash32(data)
crypt.hash(data)        -- alias for crypt.hash32

returns a 32-bit digest of data based on FNV-1a (not suitable for cryptographic usage).

crypt.hash64(data)

returns a 64-bit digest of data based on FNV-1a (not suitable for cryptographic usage).

crypt.hash128(data)

returns a 128-bit digest of data based on FNV-1a (not suitable for cryptographic usage).

Random array access

prng:choose(xs)
crypt.choose(xs)    -- using the global PRNG

returns a random item from xs

prng:shuffle(xs)
crypt.shuffle(xs)    -- using the global PRNG

returns a shuffled copy of xs

String methods

Some functions of the crypt package are added to the string module:

s:hex()             == crypt.hex(s)
s:unhex()           == crypt.unhex(s)
s:base64()          == crypt.base64(s)
s:unbase64()        == crypt.unbase64(s)
s:base64url()       == crypt.base64url(s)
s:unbase64url()     == crypt.unbase64url(s)
s:crc32()           == crypt.crc32(s)
s:crc64()           == crypt.crc64(s)
s:arc4(key, drop)   == crypt.arc4(s, key, drop)
s:unarc4(key, drop) == crypt.unarc4(s, key, drop)
s:hash()            == crypt.hash(s)
s:hash32()          == crypt.hash32(s)
s:hash64()          == crypt.hash64(s)
s:hash128()         == crypt.hash128(s)