1[manpage_begin ripemd128 n 1.0.3] 2[moddesc {RIPEMD Message-Digest Algorithm}] 3[copyright {2004, Pat Thoyts <patthoyts@users.sourceforge.net>}] 4[titledesc {RIPEMD-128 Message-Digest Algorithm}] 5[category {Hashes, checksums, and encryption}] 6[require Tcl 8.2] 7[require ripemd128 [opt 1.0.3]] 8[description] 9[para] 10 11This package is an implementation in Tcl of the RIPEMD-128 message-digest 12algorithm (1). This algorithm takes an arbitrary quantity of data and 13generates a 128-bit message digest from the input. The RIPEMD-128 14algorithm is based upon the MD4 algorithm (2, 4) but has been 15cryptographically strengthened against weaknesses that have been found 16in MD4 (4). RIPEMD-128 has been designed to be a drop-in replacement 17for MD4 and MD5 (5). If security is the major consideration, then 18RIPEMD-160 or SHA1 should be considered. 19 20[para] 21 22This package will use [package Trf] to 23accelerate the digest computation if available. In 24the absence of an accelerator package the pure-Tcl implementation will 25be used. 26 27[section {COMMANDS}] 28 29[list_begin definitions] 30 31[call [cmd "::ripemd::ripemd128"] \ 32 [opt "[arg -hex]"] \ 33 [lb] [arg "-channel channel"] | \ 34 [arg "-file filename"] | [arg "string"] [rb]] 35 36Calculate the RIPEMD-128 digest of the data given in string. This is 37returned as a binary string by default. Giving the [arg "-hex"] option 38will return a hexadecimal encoded version of the digest. 39 40[para] 41 42The data to be hashed can be specified either as a string argument to 43the ripemd128 command, or as a filename or a pre-opened channel. If the 44[arg "-filename"] argument is given then the file is opened, the data read 45and hashed and the file is closed. If the [arg "-channel"] argument is 46given then data is read from the channel until the end of file. The 47channel is not closed. 48 49[para] 50 51Only one of [arg "-file"], [arg "-channel"] or [arg "string"] should be given. 52 53[call [cmd "::ripemd::hmac128"] \ 54 [opt "[arg -hex]"] \ 55 [arg "-key key"] \ 56 [lb] [arg "-channel channel"] | \ 57 [arg "-file filename"] | [arg "string"] [rb]] 58 59Calculate an Hashed Message Authentication digest (HMAC) using the 60RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and 61provide a RIPEMD-128 digest that includes a key. All options other 62than [arg -key] are as for the [cmd "::ripemd::ripemd128"] command. 63 64[list_end] 65 66[section {PROGRAMMING INTERFACE}] 67 68For the programmer, hash functions can be viewed as a bucket into which 69one pours data. When you have finished, you extract a value that is 70uniquely derived from the data that was poured into the bucket. The 71programming interface to the hash operates on a token (equivalent to the 72bucket). You call [cmd RIPEMD128Init] to obtain a token and then call 73[cmd RIPEMD128Update] as many times as required to add data to the hash. To 74release any resources and obtain the hash value, you then call 75[cmd RIPEMD128Final]. An equivalent set of functions gives you a keyed 76digest (HMAC). 77 78[para] 79 80If you have [package critcl] and have built the [package tcllibc] 81package then the implementation of the hashing function will be 82performed by compiled code. Alternatively if both the Trf and Memchan 83extensions are available then these will be used. Finally the package 84will revert to a pure-Tcl implementation. The programming interface 85remains the same, however. 86 87[list_begin definitions] 88 89[call [cmd "::ripemd::RIPEMD128Init"]] 90 91Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the 92remaining functions. 93 94[call [cmd "::ripemd::RIPEMD128Update"] [arg "token"] [arg "data"]] 95 96Add data to the hash identified by token. Calling 97[emph {RIPEMD128Update $token "abcd"}] is equivalent to calling 98[emph {RIPEMD128Update $token "ab"}] followed by 99[emph {RIPEMD128Update $token "cb"}]. See [sectref {EXAMPLES}]. 100 101 102[call [cmd "::ripemd::RIPEMD128Final"] [arg "token"]] 103 104Returns the hash value and releases any resources held by this 105token. Once this command completes the token will be invalid. The 106result is a binary string of 16 bytes representing the 128 bit 107RIPEMD-128 digest value. 108 109[call [cmd "::ripemd::RIPEHMAC128Init"] [arg "key"]] 110 111This is equivalent to the [cmd "::ripemd::RIPEMD128Init"] command 112except that it requires the key that will be included in the HMAC. 113 114[call [cmd "::ripemd::RIPEHMAC128Update"] [arg "token"] [arg "data"]] 115[call [cmd "::ripemd::RIPEHMAC128Final"] [arg "token"]] 116 117These commands are identical to the RIPEMD128 equivalent commands. 118 119[list_end] 120 121[section {EXAMPLES}] 122 123[example { 124% ripemd::ripemd128 -hex "Tcl does RIPEMD-128" 1253cab177bae65205d81e7978f63556c63 126}] 127 128[example { 129% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128" 130b359dc5971a05beea0be7b106b30e389 131}] 132 133[example { 134% set tok [ripemd::RIPEMD128Init] 135::ripemd::1 136% ripemd::RIPEMD128Update $tok "Tcl " 137% ripemd::RIPEMD128Update $tok "does " 138% ripemd::RIPEMD128Update $tok "RIPEMD-128" 139% ripemd::Hex [ripemd::RIPEMD128Final $tok] 1403cab177bae65205d81e7978f63556c63 141}] 142 143[section {REFERENCES}] 144 145[list_begin enumerated] 146 147[enum] 148 H. Dobbertin, A. Bosselaers, B. Preneel, 149 "RIPEMD-160, a strengthened version of RIPEMD" 150 [uri http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf] 151 152[enum] 153 Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, 154 April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) 155 156[enum] 157 Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes 158 and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 159 Proceedings, pages 303-311, Springer-Verlag, 1991. 160 161[enum] 162 Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology 163 vol 11 (4), pp. 253-271 (1998) 164 165[enum] 166 Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and 167 RSA Data Security, Inc, April 1992. 168 ([uri http://www.rfc-editor.org/rfc/rfc1321.txt]) 169 170[enum] 171 Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for 172 Message Authentication", RFC 2104, February 1997. 173 ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) 174 175[list_end] 176 177[section {BUGS, IDEAS, FEEDBACK}] 178 179This document, and the package it describes, will undoubtedly contain 180bugs and other problems. 181 182Please report such in the category [emph ripemd] of the 183[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 184 185Please also report any ideas for enhancements you may have for either 186package and/or documentation. 187 188 189[see_also md4 md5 sha1 ripemd160] 190[keywords RIPEMD md4 hashing message-digest security {rfc 1320} {rfc 1321} {rfc 2104}] 191[manpage_end] 192