md5(n)

💖 md5(n) — the MD5 Message-Digest Algorithm, bestie edition 💖

okay so like. hi. you're looking at md5(n), the Tcllib page for the MD5 Message-Digest Algorithm, and honestly? she's an icon, she's a legend, and she's been through some stuff. let's get into it 🫶

---

✨ NAME ✨

md5 — MD5 Message-Digest Algorithm. that's her. that's the whole name. no notes 💅

---

✨ SYNOPSIS ✨

first things first, you gotta have the right stuff installed, so:

package require Tcl 8.5 9

package require md5 ?2.0.9?

then the main character commands themselves:

::md5::md5 ?-hex? [ -channel channel | -file filename | string ]

::md5::hmac ?-hex? -key key [ -channel channel | -file filename | string ]

::md5::MD5Init

::md5::MD5Update token data

::md5::MD5Final token

::md5::HMACInit key

::md5::HMACUpdate token data

::md5::HMACFinal token

---

✨ DESCRIPTION ✨

so this package is a Tcl implementation of the MD5 message-digest algorithm, exactly as described in RFC 1321 (1). what does it do? it takes an arbitrary amount of data — like, however much you want, she's not picky — and generates a 128-bit message digest from all that input. MD5 is related to the MD4 algorithm (2), but she got strengthened against certain types of potential attack. so basically: for new applications, use MD5 instead of MD4. periodt. ✨

now, the tea on performance: if you have critcl and you've built the tcllibc package, then the hashing function gets done by compiled code. alternatively, if you have either cryptkit or Trf, then either of those gets used to accelerate the digest computation. and if no suitable compiled package is available? then it falls back to the pure-Tcl implementation. the beautiful part: the programming interface stays the exact same in all cases. no cap. 💜

heads up: the previous version of this package always returned a hex encoded string. that got changed — to simplify the programming interface and to make this version more compatible with other implementations. so if you want the old behavior, either explicitly specify package version 1, or use the -hex option to the md5 command. iykyk 🎀

BEWARE the commands in this package expect binary data as their input. when a -file is provided, this is ensured by the commands themselves, because they open the referenced file in binary mode. but when literal data, or a -channel, are provided instead — then it's your responsibility, bestie. the caller of the command is responsible for ensuring this fact. the necessary conversion command is encoding convertto utf-8 $string. 🚨

ATTENTION there is a Tcl 9 COMPATIBILITY ISSUE here. and it's giving... messy.

• Tcl 8.x silently mishandles non-binary input by cutting it internally to size. i.e. by only using the low byte of a higher unicode point. no error is thrown — the result is simply wrong. 😭
• Tcl 9 throws an error instead, i.e.

expected byte sequence but character <location> was ...

---

✨ COMMANDS ✨

::md5::md5 ?-hex? [ -channel channel | -file filename | string ]

calculate the MD5 digest of the binary data given in string. by default she hands you back a binary string. if you give the -hex option, you get a hexadecimal encoded version of the digest instead. slay.

so where does the data come from? you've got options, literally:

• as a string argument straight to the md5 command
• as a filename
• or as a pre-opened channel

if the -filename argument is given, then the file gets opened, the data gets read and hashed, and the file gets closed. clean. if the -channel argument is given, then data is read from the channel until end of file — and the channel is not closed. respect. 🦋

only one of -file, -channel or string should be given. pick a lane bestie 💅

::md5::hmac ?-hex? -key key [ -channel channel | -file filename | string ]

calculate a Hashed Message Authentication digest (HMAC) using the MD5 digest algorithm. HMACs are described in RFC 2104 (3) and they give you an MD5 digest that includes a key. 🔑 every option other than -key works exactly like the ::md5::md5 command. same vibe, extra key.

---

✨ PROGRAMMING INTERFACE ✨

okay here's the mental model, and honestly it eats: for the programmer, the MD5 hash can be viewed as a bucket into which you pour data. 🪣 when you're done pouring, you extract a value that's derived from everything you put in. the programming interface to the MD5 hash operates on a token — and that token is basically the bucket. you call MD5Init to obtain a token, then you call MD5Update as many times as you need to add data to the hash. to release any resources and obtain the hash value, you call MD5Final. and there's an equivalent set of functions that gives you a keyed digest (HMAC). no cap, it's the same energy with a key. 🔥

::md5::MD5Init

begins a new MD5 hash. returns a token ID that must be used for the remaining functions. hold onto that token like it's your iced coffee 🧊

::md5::MD5Update token data

add data to the hash identified by token. and here's a cute little equivalence for you: calling MD5Update $token "abcd" is equivalent to calling MD5Update $token "ab" followed by MD5Update $token "cb". see EXAMPLES. 🌸

::md5::MD5Final token

returns the hash value and releases any resources held by this token. once this command completes, the token will be invalid — she's gone, don't text her 💀. the result is a binary string of 16 bytes representing the 128 bit MD5 digest value.

::md5::HMACInit key

this is equivalent to the ::md5::MD5Init command, except that it requires the key that will be included in the HMAC. 🔑

::md5::HMACUpdate token data

::md5::HMACFinal token

these commands are identical to the MD5 equivalent commands. literally the same, just keyed. 💅

---

✨ EXAMPLES ✨

live footage of it working, bestie:

% md5::md5 -hex "Tcl does MD5"
8AAC1EE01E20BB347104FABB90310433

% md5::hmac -hex -key Sekret "Tcl does MD5"
35BBA244FD56D3EDF5F3C47474DACB5D

% set tok [md5::MD5Init]
::md5::1
% md5::MD5Update $tok "Tcl "
% md5::MD5Update $tok "does "
% md5::MD5Update $tok "MD5"
% md5::Hex [md5::MD5Final $tok]
8AAC1EE01E20BB347104FABB90310433

look at that consistency. obsessed. 🌈

---

✨ REFERENCES ✨

1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data Security, Inc, April 1992. (http://www.rfc-editor.org/rfc/rfc1321.txt)
2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)
3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. (http://www.rfc-editor.org/rfc/rfc2104.txt)

---

✨ BUGS, IDEAS, FEEDBACK ✨

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. it's a whole thing. please report such in the category md5 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. also please report any ideas for enhancements you may have for either the package and/or the documentation — we wanna hear it fr fr 🫶

when proposing code changes, please provide unified diffs, i.e the output of diff -u. 👑

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. it's giving very specific instructions but we believe in you 💅

---

✨ SEE ALSO ✨

md4, sha1 — go give them a visit, they're family 💖

---

✨ KEYWORDS ✨

hashing, md5, message-digest, rfc 1320, rfc 1321, rfc 2104, security 🔐

---

✨ CATEGORY ✨

Hashes, checksums, and encryption 🎀

---

✨ COPYRIGHT ✨

Copyright (c) 2003, Pat Thoyts <patthoyts@users.sourceforge.net>

---

and that's the whole page bestie!! this was tcllib version 2.0.9, dated the classic md5(n) era, and honestly she ate. go hash something responsibly — and remember: binary input, or she will absolutely do you dirty 😭💜 ✨