=head1 NAME

md5 - MD5 cryptographic facilities (MD5)

=head1 OVERVIEW

MD5 offers basic cryptographic facilities for Lua
(L<http://www.lua.org>) 5.0 and 5.1: a hash (digest) function and a
pair crypt/decrypt.

=head1 DOWNLOAD

MD5 can be downloaded in source code from its LuaForge
(L<http://luaforge.net/projects/md5/files>) page. If you are using
LuaBinaries (L<http://luaforge.net/projects/luabinaries/>).

5.0.2 Release 2, a Windows precompiled version of MD5 can also be
found at the same LuaForge page.

=head1 BUILDING

MD5 could be built to Lua 5.0 or to Lua 5.1. In both cases, the
language library and headers files for the target version must be
installed properly.

MD5 offers a Makefile and a separate configuration file,
C<config>, which should be edited to suit the
particularities of the target platform before running
C<make>.  The file has some definitions like paths to the
external libraries, compiler options and the like. One important
definition is the Lua version, which is not obtained from the
installed software.

=head1 INSTALLATION

The compiled binary file should be copied to a directory called
C<md5> in your C path
(L<http://www.lua.org/manual/5.1/manual.html#pdf-package.cpath>) with
the name C<core.[so|dll]>. Lua 5.0 users should also install
Compat-5.1 (L<http://www.keplerproject.org/compat>).

Windows users can use the binary version of MD5 available at LuaForge
(L<http://luaforge.net/projects/md5/files>).

The file C<md5.lua> should be copied to a directory in your
Lua path (L<http://www.lua.org/manual/5.1/manual.html#pdf-package.path>).

=head1 REFERENCE - Lua API

All MD5 functions are registered inside a table C<md5>.

=head2 C<md5.sum>

  md5.sum (message)

Computes the MD5 message-digest of the string C<message>.
This function takes as input a message of arbitrary length and content
and returns as output a 128-bit "fingerprint" (or "message digest") of
the input.

The output is formated as a binary string with 16 characters.  It is
conjectured that it is computationally infeasible to produce two
messages having the same message digest, or to produce any message
having a given pre-specified target message digest.  (see RFC 1321
(L<ftp://ftp.isi.edu/in-notes/rfc1321.txt>))

=head2 C<md5.sumhexa>

  md5.sumhexa (message)

Similar to C<md5.sum>, but returns its value as a
string of 32 hexadecimal digits.

=head2 C<md5.crypt>

  md5.crypt (message, key [,seed])

Encrypts a string, using MD5 in CFB (Cipher-feedback mode).
C<message> is an arbitrary binary string to be encrypted.
C<key> is an arbitrary binary string to be used as a key.
C<seed> is an arbitrary binary string to be used as a seed;
Returns the cyphertext (as a binary string).

If no seed is provided, the function uses the result of L<os/os.time>()
as a seed. It is recommended that you use different seeds for each
message; the seed itself is not private, and should contain no private
data, because it goes plain in the beginning of the encrypted message.

The length of the cyphertext is the length of the message plus the
length of the seed plus one.

=head2 C<md5.decrypt>

  md5.decrypt (message, key)

Decrypts a string. The input C<message> must be the result of
a previous call to C<crypt>. For any C<msg>,
C<key>, and C<seed>, we have that

=head2 C<md5.decrypt>

  md5.decrypt(md5.crypt(msg, key, seed), key) == msg

=head2 C<md5.exor>

  md5.exor (s1, s2)

Does a bit-a-bit exclusive or of strings C<s1> and C<s2>.
Both strings must have the same length, which will be also the length of
the resulting string.

=head1 REFERENCE - C API

The following functions are declared in C<md5.h>

=head2 C<luaopen_md5_core>

  int luaopen_md5_core (lua_State *L)

Opens the library and registers the above Lua functions in the given
state.

=head2 C<md5>

  void md5 (const char *message, long len, char *output)

Computes the MD5 message-digest of C<message>.
C<len> is the length of C<message>.
C<output> is a buffer that receives the result;
it must have at least 16 bytes (128 bits).

=head1 VERSION

MD5 version 1.0.1 for both Lua 5.0 and Lua 5.1 is now available for
download.

=head1 HISTORY

=over 4

=item Version 1.0.1 [21/Aug/2006]

Adapted to work with both Lua 5.0 and Lua 5.1.

=item Version 1.0.0

First public version.

=back

=head1 CREDITS

MD5 was designed and implemented by Roberto Ierusalimschy and Marcela
OzE<oacute>rio Suarez.  The current distribution was packed by
TomE<aacute>s Guisasola as part of the Kepler Project
(L<http://www.keplerproject.org>).

=head1 CONTACT

For more information please contact us
(info-NO-SPAM-THANKS@keplerproject.org).  Comments are
welcome!

You can also reach other Kepler developers and users on the Kepler
Project mailing list (L<http://luaforge.net/mail/?group_id=104>).

=head1 LICENSE

MD5 is free software and uses the same license as Lua.

MD5 is free software: it can be used for both academic and commercial
purposes at absolutely no cost. There are no royalties or GNU-like
"copyleft" restrictions. MD5 qualifies as Open Source
(L<http://www.opensource.org/docs/definition.html>) software.  Its
licenses are compatible with GPL
(L<http://www.gnu.org/licenses/gpl.html>).  MD5 is not in the public
domain and PUC-Rio keeps its copyright. The legal details are below.

The spirit of the license is that you are free to use MD5 for any
purpose at no cost without having to ask us.  The only requirement is
that if you do use MD5, then you should give us credit by including
the appropriate copyright notice somewhere in your product or its
documentation.

MD5 was designed and implemented by Roberto Ierusalimschy and Marcela
OzE<oacute>rio Suarez.  The implementation is not derived from
licensed software.

~~~~~

Copyright E<copy> 2003-2006 PUC-Rio.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

~~~~~