README.markdown
1Name
2====
3
4lua-resty-string - String utilities and common hash functions for ngx_lua and LuaJIT
5
6Table of Contents
7=================
8
9* [Name](#name)
10* [Status](#status)
11* [Description](#description)
12* [Synopsis](#synopsis)
13* [Author](#author)
14* [Copyright and License](#copyright-and-license)
15* [See Also](#see-also)
16
17Status
18======
19
20This library is considered experimental and still under active development.
21
22The API is still in flux and may change without notice.
23
24Description
25===========
26
27This library requires an nginx build with OpenSSL,
28the [ngx_lua module](http://wiki.nginx.org/HttpLuaModule), and [LuaJIT 2.0](http://luajit.org/luajit.html).
29
30Synopsis
31========
32
33```lua
34 # nginx.conf:
35
36 lua_package_path "/path/to/lua-resty-string/lib/?.lua;;";
37
38 server {
39 location = /test {
40 content_by_lua_file conf/test.lua;
41 }
42 }
43
44 -- conf/test.lua:
45
46 local resty_sha1 = require "resty.sha1"
47
48 local sha1 = resty_sha1:new()
49 if not sha1 then
50 ngx.say("failed to create the sha1 object")
51 return
52 end
53
54 local ok = sha1:update("hello, ")
55 if not ok then
56 ngx.say("failed to add data")
57 return
58 end
59
60 ok = sha1:update("world")
61 if not ok then
62 ngx.say("failed to add data")
63 return
64 end
65
66 local digest = sha1:final() -- binary digest
67
68 local str = require "resty.string"
69 ngx.say("sha1: ", str.to_hex(digest))
70 -- output: "sha1: b7e23ec29af22b0b4e41da31e868d57226121c84"
71
72 local resty_md5 = require "resty.md5"
73 local md5 = resty_md5:new()
74 if not md5 then
75 ngx.say("failed to create md5 object")
76 return
77 end
78
79 local ok = md5:update("hel")
80 if not ok then
81 ngx.say("failed to add data")
82 return
83 end
84
85 -- md5:update() with an optional "len" parameter
86 ok = md5:update("loxxx", 2)
87 if not ok then
88 ngx.say("failed to add data")
89 return
90 end
91
92 local digest = md5:final()
93
94 local str = require "resty.string"
95 ngx.say("md5: ", str.to_hex(digest))
96 -- yield "md5: 5d41402abc4b2a76b9719d911017c592"
97
98 local resty_sha224 = require "resty.sha224"
99 local str = require "resty.string"
100 local sha224 = resty_sha224:new()
101 ngx.say(sha224:update("hello"))
102 local digest = sha224:final()
103 ngx.say("sha224: ", str.to_hex(digest))
104
105 local resty_sha256 = require "resty.sha256"
106 local str = require "resty.string"
107 local sha256 = resty_sha256:new()
108 ngx.say(sha256:update("hello"))
109 local digest = sha256:final()
110 ngx.say("sha256: ", str.to_hex(digest))
111
112 local resty_sha512 = require "resty.sha512"
113 local str = require "resty.string"
114 local sha512 = resty_sha512:new()
115 ngx.say(sha512:update("hello"))
116 local digest = sha512:final()
117 ngx.say("sha512: ", str.to_hex(digest))
118
119 local resty_sha384 = require "resty.sha384"
120 local str = require "resty.string"
121 local sha384 = resty_sha384:new()
122 ngx.say(sha384:update("hel"))
123 ngx.say(sha384:update("lo"))
124 local digest = sha384:final()
125 ngx.say("sha384: ", str.to_hex(digest))
126
127 local resty_random = require "resty.random"
128 local str = require "resty.string"
129 local random = resty_random.bytes(16)
130 -- generate 16 bytes of pseudo-random data
131 ngx.say("pseudo-random: ", str.to_hex(random))
132
133 local resty_random = require "resty.random"
134 local str = require "resty.string"
135 local strong_random = resty_random.bytes(16,true)
136 -- attempt to generate 16 bytes of
137 -- cryptographically strong random data
138 while strong_random == nil do
139 strong_random = resty_random.bytes(16,true)
140 end
141 ngx.say("random: ", str.to_hex(strong_random))
142
143 local aes = require "resty.aes"
144 local str = require "resty.string"
145 local aes_128_cbc_md5 = aes:new("AKeyForAES")
146 -- the default cipher is AES 128 CBC with 1 round of MD5
147 -- for the key and a nil salt
148 local encrypted = aes_128_cbc_md5:encrypt("Secret message!")
149 ngx.say("AES 128 CBC (MD5) Encrypted HEX: ", str.to_hex(encrypted))
150 ngx.say("AES 128 CBC (MD5) Decrypted: ", aes_128_cbc_md5:decrypt(encrypted))
151
152 local aes = require "resty.aes"
153 local str = require "resty.string"
154 local aes_256_cbc_sha512x5 = aes:new("AKeyForAES-256-CBC",
155 "MySalt!!", aes.cipher(256,"cbc"), aes.hash.sha512, 5)
156 -- AES 256 CBC with 5 rounds of SHA-512 for the key
157 -- and a salt of "MySalt!!"
158 -- Note: salt can be either nil or exactly 8 characters long
159 local encrypted = aes_256_cbc_sha512x5:encrypt("Really secret message!")
160 ngx.say("AES 256 CBC (SHA-512, salted) Encrypted HEX: ", str.to_hex(encrypted))
161 ngx.say("AES 256 CBC (SHA-512, salted) Decrypted: ",
162 aes_256_cbc_sha512x5:decrypt(encrypted))
163
164 local aes = require "resty.aes"
165 local str = require "resty.string"
166 local aes_128_cbc_with_iv = assert(aes:new("1234567890123456",
167 nil, aes.cipher(128,"cbc"), {iv="1234567890123456"}))
168 -- AES 128 CBC with IV and no SALT
169 local encrypted = aes_128_cbc_with_iv:encrypt("Really secret message!")
170 ngx.say("AES 128 CBC (WITH IV) Encrypted HEX: ", str.to_hex(encrypted))
171 ngx.say("AES 128 CBC (WITH IV) Decrypted: ",
172 aes_128_cbc_with_iv:decrypt(encrypted))
173
174 local aes = require "resty.aes"
175 local str = require "resty.string"
176 local enable_padding = false
177 local aes_256_cbc_with_padding = aes:new(
178 key, nil, aes.cipher(256,"cbc"), {iv = string.sub(key, 1, 16)}, nil,
179 nil, enable_padding)
180 -- AES-256 CBC (custom keygen, user padding with block_size=32)
181 local text = "hello"
182 local block_size = 32
183 local pad = block_size - #text % 32
184 local text_paded = text .. string.rep(string.char(pad), pad)
185 local encrypted = aes_256_cbc_with_padding:encrypt(text_paded)
186 ngx.say("AES-256 CBC (custom keygen, user padding with block_size=32) HEX: ",
187 str.to_hex(encrypted))
188```
189
190[Back to TOC](#table-of-contents)
191
192Author
193======
194
195Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>
196
197[Back to TOC](#table-of-contents)
198
199Copyright and License
200=====================
201
202This module is licensed under the BSD license.
203
204Copyright (C) 2012-2018, by Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, OpenResty Inc.
205
206All rights reserved.
207
208Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
209
210* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
211
212* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
213
214THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
215
216[Back to TOC](#table-of-contents)
217
218See Also
219========
220* the ngx_lua module: http://wiki.nginx.org/HttpLuaModule
221
222[Back to TOC](#table-of-contents)
223
224