COM.CURLR.CRYPTO hash functions

With apologies that this is the fourth consecutive entry concerning the less than exciting subject of hash functions, I went to the effort of implementing them,so I guess I should make some attempt to describe the use of the curlr classes.

First, some background for the newcomer - if this is old news you can skip this primer and go straight to the details below the fold. This started with the need for an MD5 implmentation for the Flickr api. MD5 is the acronym for Message Digest alogrithm 5, which is a 128-bit cryptographic hash function defined in RFC1321.

A hash function produces a fixed-length string - called a message digest - from a string (message) of any length; the hash function produces a very different message digest as the result of a small change in the message. There are several families of algrorithm for calculating a digest, and the vulnerability of the produced digest to a security attack is essentially related to its length - in FIPS 180 the number of security bits is half the size of the digest. The MD5 digest is short enough to be attacked - and the SHA-1 algorithm of 160 bits is now considered vulnerable too. The SHA-2 functions produce longer digests, and the SHA-384 and SHA-512 handle longer message lengths too - up to 2^128 bits.

The MD5 hash function is used by the Flickr api to specify a signature for methods that require authentication. For a Flickr call, the signature is the MD5 digest of a string comprised of the method parameters and the shared secret for the api key issued for the application.

This is a typical use of a hash function - creating a digital signature from a key to verify the authenticity of the message; the recipient of the signature can confirm that it was built from the key by recreating the signature using the same function. Similarly, the integrity of a file's contents can be verified by generating and comparing a message digest of a checksum for the file.

Related to this use of hash functions are Message Authentication Codes (MACs). A MAC is generated from a secret key and the (abitrarily long) message to be authenticated. The keyed-hash message authentication code (HMAC) uses a hash function and a key in the algortihm described in FIPS PUB 198 and RFC 2104 . The construction of the HMAC iteratively compresses blocks of the message and makes a digest of them.

As announced earlier, the COM.CURLR.CRYPTO package implements the hash functions for MD5 and the SHA-1 and SH-2 algorithms, and the HMAC functions for these. Read on for notes on their usage.

The COM.CURLR.CRYPTO hash functions are implemented using the class structure of Curl's MSgDigester and MsgDigest base classes. The follwing code shows how to create the MD5 message digest for a string "abc", and how to create it when reading from a file and when writing to a file:

The class structure for each hash function is the same, so you would just replace the MD5 with SHA-1 etc.. to have the equivalent code for the other algorithms. (For usage consistency, there's an implementation of SHA-1 in the package - but obviously you can use the digester supplied in the Curl product). Clearly, you would need to add your own error handling on the file i/o, and consider such niceties as character encoding to use this in an application.

The HMAC functions are simple to use as well, but require a little more thought about what is being hashed - for example, the test cases from RFC 2202 specify the key as a hex string. The curlr function digest-from-ByteVec takes ByteVecs not Strings as its arguments, and returns the digest as a ByteVec, which in the test is converted back to a hex string - note that the digest is also available as a field in the HMAC class, but its to-lower-String method will not give a hex string.

As an added extra, there are some useful byte and bitwise functions in the package, including bit rotations functions (bit-rol, bit-ror, bit64-rol, bit64-rol) and byte conversions (int32-to-ByteVec, ByteVec-to-int32, ByteVec-to-int64, ByteVec-from-hex-string, ByteVec-to-hex-string).