Debian Codegraph @

doc/us/manual.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <title>MD5: Cryptographic Library for Lua</title>
6 <link rel="stylesheet" href="doc.css" type="text/css"/>
7 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14 <div id="product_logo">
15 <a href="http://keplerproject.github.io/md5/"><img alt="MD5 logo" src="md5.png"/></a>
16 </div>
17 <div id="product_name"><big><strong>MD5</strong></big></div>
18 <div id="product_description">Cryptographic Library for Lua</div>
19 </div> <!-- id="product" -->
20
21 <div id="main">
22
23 <div id="navigation">
24
25 <h1>MD5</h1>
26 <ul>
27 <li><a href="index.html">Home</a>
28 <ul>
29 <li><a href="index.html#overview">Overview</a></li>
30 <li><a href="index.html#status">Status</a></li>
31 <li><a href="index.html#download">Download</a></li>
32 <li><a href="index.html#history">History</a></li>
33 <li><a href="index.html#credits">Credits</a></li>
34 </ul>
35 </li>
36 <li><strong>Manual</strong>
37 <ul>
38 <li><a href="manual.html#introduction">Introduction</a></li>
39 <li><a href="manual.html#building">Building</a></li>
40 <li><a href="manual.html#installation">Installation</a></li>
41 <li><a href="manual.html#reference">Reference</a>
42 <ul>
43 <li><a href="manual.html#lua_api">Lua API</a></li>
44 <li><a href="manual.html#c_api">C API</a></li>
45 </ul>
46 </li>
47 </ul>
48 </li>
49 <li><a href="https://github.com/keplerproject/md5">Project</a>
50 <ul>
51 <li><a href="https://github.com/keplerproject/md5/issues">Bug Tracker</a></li>
52 <li><a href="https://github.com/keplerproject/md5">Git</a></li>
53 </ul>
54 </li>
55 <li><a href="license.html">License</a></li>
56 </ul>
57 </div> <!-- id="navigation" -->
58
59 <div id="content">
60
61 <h2><a name="introduction"></a>Introduction</h2>
62
63 <p>
64 MD5 offers basic cryptographic facilities for Lua 5.X:
65 a hash (digest) function, a pair crypt/decrypt based on MD5 and CFB,
66 and a pair crypt/decrypt based on DES with 56-bit keys.
67 </p>
68
69 <p>
70 MD5 is free software and uses the same <a href="license.html">license</a>
71 as Lua (MIT).
72 </p>
73
74 <h2><a name="building"></a>Building</h2>
75
76 <p>
77 If you are using Unix MD5 offers a Makefile and a separate configuration file,
78 <code>config</code>, which should be edited to suit the particularities of the target platform
79 before running <code>make</code>.
80 The file has some definitions like paths to the external libraries,
81 compiler options and the like. One important definition is the Lua version,
82 which is not obtained from the installed software.
83 </p>
84
85 <p>
86 If you want to build MD5 on Windows MD5 offers the equivalent <code>config.win</code>
87 and <code>Makefile.win</code> files to be used with Microsoft Visual Studio 2005.
88 </p>
89
90 <h2><a name="installation"></a>Installation</h2>
91
92 <p>
93 The easiest way to install MD5 is to use <a href="http://www.luarocks.org">LuaRocks</a>:
94 </p>
95
96 <pre class="example">
97 luarocks install md5
98 </pre>
99
100 <p>
101 If you prefer to install the files manually and are using Unix, the build generates
102 two compiled binary files, <code>core.so</code> and <code>des56.so</code>.
103 The first should be copied to a directory called <code>md5</code>
104 in your <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.cpath">C path</a>.
105 Just copy the second to a directory in your Lua C path.
106 </p>
107
108 <p>
109 In both Unix and Windows systems the file <code>md5.lua</code> should be copied to a directory in your
110 <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.path">Lua path</a>.
111 </p>
112
113 <h2><a name="reference"></a>Reference</h2>
114
115 <h3><a name="lua_api"></a>Lua API</h3>
116
117 <p>All MD5-based functions are registered inside <code>md5</code> module.</p>
118
119 <dl class="reference">
120 <dt><strong>md5.sum (message)</strong></dt>
121 <dd>Computes the MD5 message-digest of the string <code>message</code>.
122 This function takes as input a message of arbitrary length and content
123 and returns as output a 128-bit "fingerprint" (or "message digest")
124 of the input.<br />
125 The output is formatted as a binary string with 16 characters.
126 It is conjectured that it is computationally infeasible to produce
127 two messages having the same message digest, or to produce any
128 message having a given pre-specified target message digest.
129 (see <a href="https://www.ietf.org/rfc/rfc1321.txt">RFC 1321</a>)
130 </dd>
131
132 <dt><strong>md5.sumhexa (message)</strong></dt>
133 <dd>Similar to <code>md5.sum</code>, but returns its value as a
134 string of 32 hexadecimal digits.
135 </dd>
136
137 <dt><strong>md5.crypt (message, key [,seed])</strong></dt>
138 <dd>Encrypts a string, using MD5 in CFB (Cipher-feedback mode).
139 <code>message</code> is an arbitrary binary string to be encrypted.
140 <code>key</code> is an arbitrary binary string to be used as a key.
141 <code>seed</code> is an arbitrary binary string to be used as a seed;
142 Returns the cyphertext (as a binary string).<br />
143
144 If no seed is provided, the function uses the result of
145 <code>os.time()</code> as a seed. It is recommended that you use
146 different seeds for each message; the seed itself is not private,
147 and should contain no private data, because it goes plain in the
148 beginning of the encrypted message.<br />
149
150 The length of the cyphertext is the length of the message plus the
151 length of the seed plus one.<br />
152
153 Note that MD5 based encryption should not be considered a strong solution.
154 MD5 collision can cause to messages with different keys and the same seed
155 to encrypt to the same value, which can then be decrypted with either key.
156 The bigger the key the lesser the chance of this happening. More details
157 about the weaknesses involved can be found
158 <a href="http://pajhome.org.uk/crypt/md5/">here</a>.
159 </dd>
160
161 <dt><strong>md5.decrypt (message, key)</strong></dt>
162 <dd>Decrypts a string. The input <code>message</code> must be the result of
163 a previous call to <code>crypt</code>. For any <code>msg</code>,
164 <code>key</code>, and <code>seed</code>, we have that
165 <pre>md5.decrypt(md5.crypt(msg, key, seed), key) == msg</pre>
166 </dd>
167
168 <dt><strong>md5.exor (s1, s2)</strong></dt>
169 <dd>Does a bit-a-bit exclusive or of strings <code>s1</code> and <code>s2</code>.
170 Both strings must have the same length, which will be also the length of
171 the resulting string.
172 </dd>
173 </dl>
174
175 <p>The DES-based functions are registered inside <code>des56</code> module.</p>
176
177 <dl class="reference">
178 <dt><strong>des56.crypt (message, key)</strong></dt>
179 <dd>Encrypts a string, using DES with a 56-bit key.
180 <code>message</code> is an arbitrary binary string to be encrypted.
181 <code>key</code> is an 8-byte binary string to be used as a key.
182 Returns the cyphertext (as a binary string).<br />
183 </dd>
184
185 <dt><strong>des56.decrypt (message, key)</strong></dt>
186 <dd>Decrypts a string. The input <code>message</code> must be the result of
187 a previous call to <code>des56.crypt</code>. For any <code>msg</code>
188 and <code>key</code>, we have that
189 <pre>des56.decrypt(des56.crypt(msg, key), key) == msg</pre>
190 </dd>
191
192 </dl>
193
194 <h3><a name="c_api"></a>C API</h3>
195
196 <p>The following functions are declared in <code>md5.h</code></p>
197
198 <dl class="reference">
199 <dt><strong>int luaopen_md5_core (lua_State *L)</strong></dt>
200 <dd>Opens the library and registers the "md5" Lua functions in the given state.</dd>
201
202 <dt><strong>void md5 (const char *message, long len, char *output)</strong></dt>
203 <dd>Computes the MD5 message-digest of <code>message</code>.
204 <code>len</code> is the length of <code>message</code>.
205 <code>output</code> is a buffer that receives the result;
206 it must have at least 16 bytes (128 bits).
207 </dd>
208 </dl>
209
210 <p>The following function is declared in <code>ldes56.h</code></p>
211
212 <dl class="reference">
213 <dt><strong>int luaopen_des56 (lua_State *L)</strong></dt>
214 <dd>Opens the library and registers the "des56" Lua functions in the given state.</dd>
215 </dl>
216
217
218
219 </div> <!-- id="content" -->
220
221 </div> <!-- id="main" -->
222
223 <div id="about">
224 <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
225 </div> <!-- id="about" -->
226
227 </div> <!-- id="container" -->
228
229 </body>
230 </html>