README.md
1A Lua wrapper for OpenBSD's bcrypt.
2
3
4Requirements
5------------
6
7lua >= 5.1
8
9
10Copying
11-------
12
13Many of the files in this repository have been taken from OpenBSD's
14tree. You should consult individual file headers for specific licensing
15information. More broadly, everything here is compatible with the [ISC
16license][ISC].
17
18[ISC]: http://en.wikipedia.org/wiki/ISC_license
19
20
21Installation
22------------
23
24 $ luarocks install bcrypt
25
26
27Usage
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
39Security concerns
40-----------------
41
42Lua will keep plaintext passwords around in memory as part of its string
43interning mechanism. As far as I'm aware, there's nothing I can do about
44this.
45
46
47Tuning
48------
49
50If you would like to automatically tune the number of rounds to your
51hardware, 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
76This function returns the largest load factor such that `bcrypt.digest(
77str, work )` takes less than `t` milliseconds (assuming your CPU isn't
78dodgy).
79
80Note that this will take at least `2 * SAMPLES * t` ms to evaluate.
81
82
83Chroot
84------
85
86[lua-setuid]: https://github.com/mikejsavage/lua-setuid
87[test-chroot]: https://github.com/mikejsavage/lua-bcrypt/blob/master/test-chroot.lua
88
89Some operating systems do not provide a method for reliably getting
90random data from inside a chroot. One workaround for this is to chroot
91after initialising lua-bcrypt, for example by using
92[lua-setuid][lua-setuid].
93
94 local setuid = require( "setuid" )
95 local bcrypt = require( "bcrypt" )
96
97 assert( setuid.chroot( "." ) )
98 assert( not io.open( "/etc/passwd", "r" ) )
99
100 print( bcrypt.digest( "adsf", 5 ) )
101
102There are also operating system specific workarounds. On
103non-bleeding-edge (earlier than 3.17) Linux kernels, you can run:
104
105 mkdir /path/to/chroot/dev
106 mknod -m 644 /path/to/chroot/dev/urandom c 1 9
107
108I have included a test script in [`test-chroot.lua`][test-chroot].
109