lua-symmetric

Symmetric crypto for Lua
Log | Files | Refs

README.md (1551B)


      1 A Lua wrapper for libsodium's secretbox. In simpler terms, a Lua library
      2 for symmetric encryption.
      3 
      4 
      5 Requirements
      6 ------------
      7 
      8 [libsodium]: http://doc.libsodium.org/
      9 
     10 lua >= 5.1, [libsodium][libsodium]
     11 
     12 
     13 Copying
     14 -------
     15 
     16 Many of the files in this repository have been taken from OpenBSD's
     17 tree. You should consult individual file headers for specific licensing
     18 information. More broadly, everything here is compatible with the [ISC
     19 license][ISC].
     20 
     21 [ISC]: http://en.wikipedia.org/wiki/ISC_license
     22 
     23 
     24 Installation
     25 ------------
     26 
     27 	$ luarocks install bcrypt
     28 
     29 
     30 Usage
     31 -----
     32 
     33 	local symmetric = require( "symmetric" )
     34 	
     35 	-- securely generate a random key
     36 	local key = symmetric.key()
     37 
     38 	local message = "hello"
     39 	local ciphertext = symmetric.encrypt( message, key )
     40 	assert( symmetric.decrypt( ciphertext, key ) == message )
     41 
     42 Security concerns
     43 -----------------
     44 
     45 Generated keys and ciphertexts will use the full range of ASCII values.
     46 They should be handled with care - displaying them as-is can introduce
     47 subtle flaws. For example, keys and ciphertexts can contain quotes,
     48 which makes them unsafe to insert into SQL queries<sup>1</sup>. If in
     49 doubt, base64/hex encode them. I may change my mind and encode by
     50 default in future (major) releases.
     51 
     52 [sql]: http://dc406.com/home/393-sql-injection-with-raw-md5-hashes.html
     53 
     54 <sup>1</sup>: [SQL injection with raw MD5 hashes][sql]
     55 
     56 Additionally, Lua will keep plaintext messages and encryption keys
     57 around in memory as part of its string interning mechanism. As far as
     58 I'm aware, there's nothing I can do about this.