1 2[//000000001]: # (md5 \- MD5 Message\-Digest Algorithm) 3[//000000002]: # (Generated from file 'md5\.man' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2003, Pat Thoyts <patthoyts@users\.sourceforge\.net>) 5[//000000004]: # (md5\(n\) 2\.0\.7 tcllib "MD5 Message\-Digest Algorithm") 6 7<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 8href="../../../toc.md">Table Of Contents</a> | <a 9href="../../../../index.md">Keyword Index</a> | <a 10href="../../../../toc0.md">Categories</a> | <a 11href="../../../../toc1.md">Modules</a> | <a 12href="../../../../toc2.md">Applications</a> ] <hr> 13 14# NAME 15 16md5 \- MD5 Message\-Digest Algorithm 17 18# <a name='toc'></a>Table Of Contents 19 20 - [Table Of Contents](#toc) 21 22 - [Synopsis](#synopsis) 23 24 - [Description](#section1) 25 26 - [COMMANDS](#section2) 27 28 - [PROGRAMMING INTERFACE](#section3) 29 30 - [EXAMPLES](#section4) 31 32 - [REFERENCES](#section5) 33 34 - [Bugs, Ideas, Feedback](#section6) 35 36 - [See Also](#seealso) 37 38 - [Keywords](#keywords) 39 40 - [Category](#category) 41 42 - [Copyright](#copyright) 43 44# <a name='synopsis'></a>SYNOPSIS 45 46package require Tcl 8\.2 47package require md5 ?2\.0\.7? 48 49[__::md5::md5__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \]](#1) 50[__::md5::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \]](#2) 51[__::md5::MD5Init__](#3) 52[__::md5::MD5Update__ *token* *data*](#4) 53[__::md5::MD5Final__ *token*](#5) 54[__::md5::HMACInit__ *key*](#6) 55[__::md5::HMACUpdate__ *token* *data*](#7) 56[__::md5::HMACFinal__ *token*](#8) 57 58# <a name='description'></a>DESCRIPTION 59 60This package is an implementation in Tcl of the MD5 message\-digest algorithm as 61described in RFC 1321 \(1\)\. This algorithm takes an arbitrary quantity of data 62and generates a 128\-bit message digest from the input\. The MD5 algorithm is 63related to the MD4 algorithm \(2\) but has been strengthened against certain types 64of potential attack\. MD5 should be used in preference to MD4 for new 65applications\. 66 67If you have __critcl__ and have built the __tcllibc__ package then the 68implementation of the hashing function will be performed by compiled code\. 69Alternatively if you have either __cryptkit__ or __Trf__ then either of 70these can be used to accelerate the digest computation\. If no suitable compiled 71package is available then the pure\-Tcl implementation wil be used\. The 72programming interface remains the same in all cases\. 73 74*Note* the previous version of this package always returned a hex encoded 75string\. This has been changed to simplify the programming interface and to make 76this version more compatible with other implementations\. To obtain the previous 77usage, either explicitly specify package version 1 or use the *\-hex* option to 78the __md5__ command\. 79 80# <a name='section2'></a>COMMANDS 81 82 - <a name='1'></a>__::md5::md5__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \] 83 84 Calculate the MD5 digest of the data given in string\. This is returned as a 85 binary string by default\. Giving the *\-hex* option will return a 86 hexadecimal encoded version of the digest\. 87 88 The data to be hashed can be specified either as a string argument to the 89 __md5__ command, or as a filename or a pre\-opened channel\. If the 90 *\-filename* argument is given then the file is opened, the data read and 91 hashed and the file is closed\. If the *\-channel* argument is given then 92 data is read from the channel until the end of file\. The channel is not 93 closed\. 94 95 Only one of *\-file*, *\-channel* or *string* should be given\. 96 97 - <a name='2'></a>__::md5::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \] 98 99 Calculate an Hashed Message Authentication digest \(HMAC\) using the MD5 100 digest algorithm\. HMACs are described in RFC 2104 \(3\) and provide an MD5 101 digest that includes a key\. All options other than *\-key* are as for the 102 __::md5::md5__ command\. 103 104# <a name='section3'></a>PROGRAMMING INTERFACE 105 106For the programmer, the MD5 hash can be viewed as a bucket into which one pours 107data\. When you have finished, you extract a value that is derived from the data 108that was poured into the bucket\. The programming interface to the MD5 hash 109operates on a token \(equivalent to the bucket\)\. You call __MD5Init__ to 110obtain a token and then call __MD5Update__ as many times as required to add 111data to the hash\. To release any resources and obtain the hash value, you then 112call __MD5Final__\. An equivalent set of functions gives you a keyed digest 113\(HMAC\)\. 114 115 - <a name='3'></a>__::md5::MD5Init__ 116 117 Begins a new MD5 hash\. Returns a token ID that must be used for the 118 remaining functions\. 119 120 - <a name='4'></a>__::md5::MD5Update__ *token* *data* 121 122 Add data to the hash identified by token\. Calling *MD5Update $token 123 "abcd"* is equivalent to calling *MD5Update $token "ab"* followed by 124 *MD5Update $token "cb"*\. See [EXAMPLES](#section4)\. 125 126 - <a name='5'></a>__::md5::MD5Final__ *token* 127 128 Returns the hash value and releases any resources held by this token\. Once 129 this command completes the token will be invalid\. The result is a binary 130 string of 16 bytes representing the 128 bit MD5 digest value\. 131 132 - <a name='6'></a>__::md5::HMACInit__ *key* 133 134 This is equivalent to the __::md5::MD5Init__ command except that it 135 requires the key that will be included in the HMAC\. 136 137 - <a name='7'></a>__::md5::HMACUpdate__ *token* *data* 138 139 - <a name='8'></a>__::md5::HMACFinal__ *token* 140 141 These commands are identical to the MD5 equivalent commands\. 142 143# <a name='section4'></a>EXAMPLES 144 145 % md5::md5 -hex "Tcl does MD5" 146 8AAC1EE01E20BB347104FABB90310433 147 148 % md5::hmac -hex -key Sekret "Tcl does MD5" 149 35BBA244FD56D3EDF5F3C47474DACB5D 150 151 % set tok [md5::MD5Init] 152 ::md5::1 153 % md5::MD5Update $tok "Tcl " 154 % md5::MD5Update $tok "does " 155 % md5::MD5Update $tok "MD5" 156 % md5::Hex [md5::MD5Final $tok] 157 8AAC1EE01E20BB347104FABB90310433 158 159# <a name='section5'></a>REFERENCES 160 161 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data 162 Security, Inc, April 1992\. 163 \([http://www\.rfc\-editor\.org/rfc/rfc1321\.txt](http://www\.rfc\-editor\.org/rfc/rfc1321\.txt)\) 164 165 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. 166 \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) 167 168 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message 169 Authentication", RFC 2104, February 1997\. 170 \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) 171 172# <a name='section6'></a>Bugs, Ideas, Feedback 173 174This document, and the package it describes, will undoubtedly contain bugs and 175other problems\. Please report such in the category *md5* of the [Tcllib 176Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 177for enhancements you may have for either package and/or documentation\. 178 179When proposing code changes, please provide *unified diffs*, i\.e the output of 180__diff \-u__\. 181 182Note further that *attachments* are strongly preferred over inlined patches\. 183Attachments can be made by going to the __Edit__ form of the ticket 184immediately after its creation, and then using the left\-most button in the 185secondary navigation bar\. 186 187# <a name='seealso'></a>SEE ALSO 188 189[md4](\.\./md4/md4\.md), [sha1](\.\./sha1/sha1\.md) 190 191# <a name='keywords'></a>KEYWORDS 192 193[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), 194[md5](\.\./\.\./\.\./\.\./index\.md\#md5), 195[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc 1961320](\.\./\.\./\.\./\.\./index\.md\#rfc\_1320), [rfc 1971321](\.\./\.\./\.\./\.\./index\.md\#rfc\_1321), [rfc 1982104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), 199[security](\.\./\.\./\.\./\.\./index\.md\#security) 200 201# <a name='category'></a>CATEGORY 202 203Hashes, checksums, and encryption 204 205# <a name='copyright'></a>COPYRIGHT 206 207Copyright © 2003, Pat Thoyts <patthoyts@users\.sourceforge\.net> 208