lua-bcrypt

Secure password hashing for Lua
Log | Files | Refs | README

README.md (1604B)


      1 A Lua wrapper for OpenBSD's bcrypt.
      2 
      3 
      4 Requirements
      5 ------------
      6 
      7 lua >= 5.1
      8 
      9 
     10 Copying
     11 -------
     12 
     13 Many of the files in this repository have been taken from OpenBSD's
     14 tree. You should consult individual file headers for specific licensing
     15 information. More broadly, everything here is compatible with the [ISC
     16 license][ISC].
     17 
     18 [ISC]: http://en.wikipedia.org/wiki/ISC_license
     19 
     20 
     21 Installation
     22 ------------
     23 
     24 	$ luarocks install bcrypt
     25 
     26 
     27 Usage
     28 -----
     29 
     30 	local bcrypt = require( "bcrypt" )
     31 	
     32 	-- Bigger numbers here will make your digest exponentially harder to compute
     33 	local log_rounds = 9
     34 	
     35 	local digest = bcrypt.digest( "password", log_rounds )
     36 	assert( bcrypt.verify( "password", digest ) )
     37 
     38 
     39 Security concerns
     40 -----------------
     41 
     42 Lua will keep plaintext passwords around in memory as part of its string
     43 interning mechanism. As far as I'm aware, there's nothing I can do about
     44 this.
     45 
     46 
     47 Tuning
     48 ------
     49 
     50 If you would like to automatically tune the number of rounds to your
     51 hardware, you can include a function like:
     52 
     53 	function bcrypt.tune( t )
     54 		local SAMPLES = 10
     55 		local rounds = 5
     56 	
     57 		while true do
     58 			local total = 0
     59 	
     60 			for i = 1, SAMPLES do
     61 				local start = os.clock()
     62 				bcrypt.digest( "asdf", rounds )
     63 				local delta = os.clock() - start
     64 	
     65 				total = total + delta
     66 			end
     67 	
     68 			if ( total / SAMPLES ) * 1000 >= t then
     69 				return rounds - 1
     70 			end
     71 	
     72 			rounds = rounds + 1
     73 		end
     74 	end
     75 
     76 This function returns the largest load factor such that `bcrypt.digest(
     77 str, work )` takes less than `t` milliseconds (assuming your CPU isn't
     78 dodgy).
     79 
     80 Note that this will take at least `2 * SAMPLES * t` ms to evaluate.