README for sha2.dll v1.0 - SHA-2 DLL for mIRC
Copyright (c) 2011, David "Saturn" van Moolenbroek <saturn@quakenet.org>


1.    Description
2.    Using the DLL
3.    Acknowledgements
4.    License and source code
5.    Version history


1. Description

  This DLL implements the SHA-2 family of cryptographic hashes: SHA-224,
  SHA-256, SHA-384, SHA-512. Like mIRC's built-in MD5 and SHA-1 hash
  functions, it supports hashing of text, binary variables, and files.


2. Using the DLL

  The following aliases allow for simple use of the DLL:

    alias sha224 return $dll(sha2.dll,sha224,$calc($2) $1)
    alias sha256 return $dll(sha2.dll,sha256,$calc($2) $1)
    alias sha384 return $dll(sha2.dll,sha384,$calc($2) $1)
    alias sha512 return $dll(sha2.dll,sha512,$calc($2) $1)

  The usage of each of these aliases is just like mIRC's built-in hash
  functions:

    $sha256(text|&binvar|filename,[N])

    Returns SHA-256 hash value for the specified data, where N = 0 for plain
    text (default), 1 for &binvar, 2 for filename.

  In case of an error, nothing is returned. There are a few other minor
  behavioral differences between mIRC's built-in hashing functions and those
  implemented in this DLL, but you should not run into these when you are
  using the functions properly. For example: quoted filenames are not
  supported, and passing a nonexistent binary variable name will result in the
  hash of an empty string.

  The binary variables feature is so slow that it is only usable for small
  amounts of input data. If you have to hash a large binary variable, write it
  to a file and use the hash function on the file instead.


3. Acknowledgements

  This DLL is meant as a replacement (although not a drop-in replacement!) for
  sha256.dll by wshs, which can be found at:

    http://www.mircscripts.org/comments.php?cid=3575

  This version solves some of the shortcomings mentioned in the comments on
  that page. It is not based on that DLL's source code, but it does use the
  same original SHA-2 hashing implementation written by Olivier Gay.


4. License and source code

  The DLL, this readme and the DLL's source code are released under the BSD
  license. Part of the source is based on BSD-licensed third-party code. See
  the source files for details.

  The source and Makefile have been created for Borland Command Line Tools
  Compiler, however note that you will have to adjust the makefile to allow
  recompilation in your environment.

  The DLL has not been compiled with Unicode support. Plain text has to be
  passed in UTF-8 form to the hashing function, and by presenting itself as
  ANSI, the DLL can save itself from doing this conversion. The source code
  supports being compiled for Unicode, but will return different hash values
  for plain text input in that case.

  THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
  EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO WARRANTIES OF
  MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL THE
  AUTHOR BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING INCIDENTAL OR
  CONSEQUENTIAL DAMAGES, ARISING OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. YOU ACKNOWLEDGE THAT YOU HAVE
  READ THIS LICENSE, UNDERSTAND IT AND AGREE TO BE BOUND BY ITS TERMS.


5. Version history

  Version   Released    Description/changes

  1.0       16-10-2011  Public release
