aes(n)

✨ aes — the Advanced Encryption Standard, but make it Tcl 💅

okay bestie, welcome to aes(n), the Tcllib manual page for AES, the Advanced Encryption Standard. it's a block cipher, it's iconic, it's literally the government-approved way to keep your secrets secret 👑

---

🌸 NAME 🌸

aes — Implementation of the AES block cipher

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require aes ?1.2.2?

::aes::aes  ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv
vector? ?-hex? ?-out channel? ?-chunksize size? [  -in  channel  |  ?--?
data ]

::aes::Init mode keydata iv

::aes::Encrypt Key data

::aes::Decrypt Key data

::aes::Reset Key iv

::aes::Final Key

---

💖 DESCRIPTION 💖

so this is a Tcl implementation of the Advanced Encryption Standard (AES), as published by the U.S. National Institute of Standards and Technology [1]. no cap, it's the real one.

AES is a 128-bit block cipher with a variable key size of 128, 192 or 256 bits. this implementation supports ECB and CBC modes. that's the whole vibe ✨

---

👑 COMMANDS 👑

• ::aes::aes ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-hex? ?-out channel? ?-chunksize size? [ -in channel | ?--? data ] — run the aes algorithm on either the data you hand it as an argument, or on the data it reads from the -in channel. if you give it an -out channel, the result gets written there instead. 🫶

the -key option is not optional, bestie — you must give it. this parameter takes a binary string of either 16, 24 or 32 bytes in length, and it's what generates the key schedule.

the -mode and -dir options are optional and default to cbc mode and encrypt respectively. the initialization vector -iv takes a 16 byte binary argument, and it defaults to all zeros. head to MODES OF OPERATION for more about the available modes and what they're for.

AES is a 128-bit block cipher, which means the data has to come in units that are a multiple of 16 bytes. no partial blocks, we don't do that here 💀

---

🧚 PROGRAMMING INTERFACE 🧚

internal state lives in an opaque structure that the Init function hands back to you. in ECB mode that state isn't affected by the input at all, but for CBC mode some input-dependent state is maintained — and you can reset it by calling the Reset function with a new initialization vector value.

• ::aes::Init mode keydata iv — construct a brand new AES key schedule using the key data you specify and the initialization vector you give it. the iv isn't used with ECB mode but it's important for CBC mode. see MODES OF OPERATION for the deets on cipher modes.
• ::aes::Encrypt Key data — use a prepared key you got from calling Init to encrypt the data you pass in. the data argument should be a binary array that's a multiple of the AES block size of 16 bytes. the result is a binary array the same size as the input, full of encrypted data. slay 🔥
• ::aes::Decrypt Key data — decipher data using the key. note that the same key may be used to encrypt and decrypt data, as long as the initialization vector is reset appropriately for CBC mode. (iykyk — that reset is the whole game.)
• ::aes::Reset Key iv — reset the initialization vector. this lets the programmer re-use a key and skip the cost of regenerating the key schedule when the same key data is being used multiple times. efficiency, we love her 💅
• ::aes::Final Key — call this to clean up the resources associated with Key. once this function has been called, the key may not be used again. like, ever. it's gone, she's retired 🫡

---

🌈 MODES OF OPERATION 🌈

💜 Electronic Code Book (ECB)

ECB is the basic mode of all block ciphers. each block gets encrypted independently, which means identical plain text produces identical output when encrypted with the same key. any encryption errors will only affect a single block — but bestie, this one is vulnerable to known plaintext attacks. 🙈

🩵 Cipher Block Chaining (CBC)

CBC mode uses the output of the last block encryption to affect the current block. an initialization vector of the same size as the cipher block size is used to handle the first block. that initialization vector should be chosen randomly and transmitted as the first block of the output. errors in encryption affect the current block and the next block, after which the cipher corrects itself. CBC is the most commonly used mode in software encryption, and it's the default mode of operation for this module. main character energy, fr fr 👑

---

⭐ EXAMPLES ⭐

% set nil_block [string repeat \\0 16]
% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
66e94bd4ef8a2c3b884cfa59ca342b2e

set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
append ciphertext [aes::Encrypt $Key $plaintext]
append ciphertext [aes::Encrypt $Key $additional_plaintext]
aes::Final $Key

look at that hex output, absolutely ate 🍓

---

🦋 REFERENCES 🦋

• [1] "Advanced Encryption Standard", Federal Information Processing Standards Publication 197, 2001 (http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf)

---

💐 AUTHORS 💐

Thorsten Schloermann, Pat Thoyts

---

💀 BUGS, IDEAS, FEEDBACK 💀

this document, and the package it describes, will undoubtedly contain bugs and other problems. (not me being self-aware 😭) please report such in the category aes of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation.

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. 🎀

---

🔍 SEE ALSO 🔍

blowfish(n), des(n), md5(n), sha1(n)

---

🏷️ KEYWORDS 🏷️

aes, block cipher, data integrity, encryption, security

---

🗂️ CATEGORY 🗂️

Hashes, checksums, and encryption

---

©️ COPYRIGHT ©️

Copyright (c) 2005, Pat Thoyts <patthoyts@users.sourceforge.net>
Copyright (c) 2012-2014, Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the page, bestie 🫶 this was tcllib version 1.2.2, page aes(n). go forth and encrypt responsibly, and remember: never reuse your IV. periodt 💖✨