Table of Contents ----------------- 1. Introduction 2. Release notes 3. License and source code 4. How to test mkroesti 5. How to generate the documentation 6. How to extend mkroesti 7. Dependencies 8. Python versions 9. Limitations 10. Why mkroesti (the motivation)? 11. Why "mkroesti" (the name)? Introduction ------------ mkroesti is a hash generator written in Python. mkroesti can be used both as a command line utility and as a web tool. It takes an input (e.g. a file, or a password) and generates different kinds of hashes from that input. The hashes to generate are selected by naming them on the command line, or ticking the corresponding checkboxes in the web GUI. mkroesti provides no hash algorithm implementations of its own. Instead it consists of a collection of front-ends to hash algorithms available in the Python Standard Library, and from a number of third-party modules. See the section "Dependencies" for details. mkroesti also defines a couple of interfaces that allow third parties to inject new front-ends to previously unavailable hash algorithms. For more information on how this extension mechanism works, please read the section "How to extend mkroesti". Release notes ------------- This is mkroesti 0.4. Changes in this release: - mkroesti now has a web front-end; a demo installation is located here: http://www.herzbube.ch/cgi-bin/mkroesti.cgi - Internally, aliases now have an available/not available state; this is used by the web front-end, but has not yet had any effect on the command line utility For more details see the ChangeLog document. License and source code ----------------------- mkroesti is licensed under the GNU General Public License (GPLv3). You should have received a copy of the license along with the mkroesti module distribution (see the file COPYING inside the distribution). If not, see . The source code for mkroesti can be downloaded from its website http://www.herzbube.ch/mkroesti/. The source files are packaged into a tar ball using the Distutils Python module. Alternatively you may also get the source code (including project files to hack mkroesti in Eclipse) from this git respository: http://herzbube.ch/git/mkroesti/ How to test mkroesti -------------------- See the TESTING file. How to generate the documentation --------------------------------- The MANUAL file is marked up using reStructured text. I am using pandoc to generate a man page and a HTML page like this: cat MANUAL | pandoc -s -f rst -t man mkroesti.1 cat MANUAL | pandoc -s -f rst -t html MANUAL.html To view the man page on screen (using the ISO Latin-1 character set): cat mkroesti.1 | groff -mandoc -Tlatin1 | less How to extend mkroesti ---------------------- mkroesti is labelled "extensible", so how can new hashing algorithms be added to mkroesti by third parties? The cook book answer is: - Create a class that implements AlgorithmInterface. It is not necessary to subclass AlgorithmInterface, although you may find it useful to inherit from AbstractAlgorithm, in which case you automatically also inherit from AlgorithmInterface. - Create a class that implements ProviderInterface. It is not necessary to subclass ProviderInterface, although you may find it useful to inherit from AbstractProvider or AliasAbstractProvider, in which case you automatically also inherit from ProviderInterface. - Create a module-level callable named "getProviders" (usually a function) that returns a list of instances of your algorithm provider classes (a list with one element if you have only one provider class). When you run mkroesti on the command line, you can specify the module that contains the callable in this fashion: mkroesti --providers mymodule [...] - mkroesti invokes the callable and registers the provider instances it gets in its internal system, just as it does for its own built-in providers. For the gritty details: - Use pydoc to view the API documentation inside the modules mkroesti.algorithm and mkroesti.provider. - Have a look at an example, a good one would be mkroesti.algorithm.Base64Algorithms and mkroesti.provider.Base64Provider. - The man page has a more details on how to run mkroesti from the command line. Dependencies ------------ mkroesti depends on other modules to provide actual hash algorithms. This section documents these dependencies. Note that most dependencies are "soft", meaning that mkroesti will continue to work if a "soft-dependant" module is missing. In such a case, mkroesti simply flags the hash algorithms provided by the absent module as "unavailable", but will happily continue producing hashes for the remaining algorithms. The Python Standard Library - Provides a couple of modules under the heading "Cryptographic Services" [1] - From these mkroesti uses only the "hashlib" module because it provides all the algorithms of the other modules, and more: - Always present in hashlib: md5, sha-1, sha-224, sha-256, sha-384, sha-512 - Presence of the following depends on the version of the underlying OpenSSL: ripemd-160, sha-0, md2, md4 - Provides a couple of encoding (i.e. not cryptographic) modules - "base64" module: provides base16, base32, base64 - Provides the "crypt" module with access to the system's crypt(3) function The module "smbpasswd" [2] - Debian package "python-smbpasswd" - The module provides these algorithms: windows-lm, windows-nt The module "mhash" [3] - There is no Debian package, the package needs to be built manually - The module is a wrapper for the mhash library - How to get/build the package - download - unpack tar ball - install dependencies (Debian packages python-dev, libmhash-dev) - ./setup.py build - ./setup.py install - The library/python module provides the following algorithms: - haval-128, haval-160, haval-192, haval-224, haval-256 (3 rounds variant) - ripemd-128, ripemd-256, ripemd-320 - tiger-128, tiger-160, tiger-192 - whirlpool - snefru-128, snefru-256 - gost The module "bcrypt" [4] - Debian package "python-bcrypt" - The module provides this algorithm: crypt-blowfish The module "aprmd5" [5] - Debian package "python-aprmd5" - The module is a wrapper around the MD5 routines that are part of the aprutil library - The module provides this algorithm: crypt-apr1 [1] http://www.python.org/doc/current/library/crypto.html [2] http://barryp.org/software/py-smbpasswd/ [3] http://labix.org/python-mhash [4] http://www.mindrot.org/projects/py-bcrypt/ [5] http://www.herzbube.ch/python-aprmd5 Note: An abbreviated list of dependencies can also be found in the MANUAL document. Python versions --------------- The minimum requirement for running a current version of mkroesti is Python 2.6 (tests were made with Python 2.6.2). It should also run fine with Python 3. Older versions: - mkroesti 0.1 requires Python 2.5 but does not run with Python 3 Limitations ----------- Not all hash algorithms advertised on the man page are actually provided. Use "mkroesti --list" to find out which algorithms are actually available on your system. mkroesti is not good at handling large files, because it tries to read a file's entire content into memory before hash generation commences. The handling of encodings is probably incomplete, and certainly awkward in some situations. You may find it easier to ignore encodings in mkroesti altogether, and instead use a different tool that is better at handling encodings, to pre-process your input data. The --codec option was added mainly to handle the border case where binary input needs to be converted into string data to satisfy algorithms such as crypt-des, which in Python 3 take string data as their input. The --codec option was also added to enable unit tests to specify an encoding for the input they provide to mkroesti.main.main(), to cover the case where the locale-based encoding of the user who runs the tests differs from the encoding of the file that contains the string literal used by the test. Now that --codec has been implemented, it proves to be a major nuisance, because its usage remains obscure in many situations. Why mkroesti (the motivation)? ------------------------------ First and foremost, mkroesti is my "learning Python" project. So I beg your forgiveness if you spot any "uncommon" implementation practices. The reason why I chose "generate hashes" as my learning project's theme can be traced back to the time when I was making an effort to integrate Samba with LDAP on my home-brew Linux server. I found that Samba wants to store a user's password in the LDAP directory both as an NT password hash and an LM password hash. I was then looking for information on how to generate these two kinds of hashes, but could find no readily available tool, and so decided that I would simply write my own utility - taking the opportunity to learn Python, which was then for me a new programming language. Soon after that I discovered that my self-assigned task had already been implemented by the "smbpasswd" Python module, and I also found some web-based hash generators that implemented a wide variety of hashing algorithms. By that time, though, I was too deeply entangled in the fascination of learning a new programming language to simply give up. So I shifted my focus towards a tool that is more general in nature - the primary reason being that none of the web-based hash generators seemed to have an open sourced implementations - and thus mkroesti came into being. Why "mkroesti" (the name)? -------------------------- Basically it's just another convoluted pun made up by a programmer with a weird sense of humor. This is an attempt at decryption :-) - "roesti" is transcribed from "Rösti", which contains the German umlaut "ö" (the double-quoted character should appear the same as the HTML entity reference "ö"; if it doesn't, you might need to re-open this file in a text editor with the proper encoding, which is UTF-8) - Rösti is a potato dish from Switzerland. I associate Rösti with the English translation "hash browns", therefore, "make hashes" for me is "make rösti" :-) - the name "mkroesti" therefore boils down to saying "make hashes" - also see these Wikipedia references: http://en.wikipedia.org/wiki/R%C3%B6sti http://en.wikipedia.org/wiki/Hash_browns