Crypt::Mac::XCBC(3)

💖 Crypt::Mac::XCBC — the perl manual but make it make sense 💖

okay so bestie, welcome to the Crypt::Mac::XCBC(3) page — it's giving message authentication code energy, and honestly? iconic. this is XCBC, the MAC algorithm from RFC 3566, and we're gonna walk through it together 🫶

---

✨ NAME ✨

Crypt::Mac::XCBC — Message authentication code XCBC (RFC 3566). literally that's the whole vibe.

---

🌸 SYNOPSIS 🌸

okay so you can go two ways with this: the functional interface or the OO interface. both slay, pick your fighter 💅

functional interface 🎀

### Functional interface:
use Crypt::Mac::XCBC qw( xcbc xcbc_hex xcbc_b64 xcbc_b64u );

# calculate MAC from string/buffer
my $xcbc_raw  = xcbc($cipher_name, $key, 'data buffer');
my $xcbc_hex  = xcbc_hex($cipher_name, $key, 'data buffer');
my $xcbc_b64  = xcbc_b64($cipher_name, $key, 'data buffer');
my $xcbc_b64u = xcbc_b64u($cipher_name, $key, 'data buffer');

OO interface 👑

### OO interface:
use Crypt::Mac::XCBC;

my $d = Crypt::Mac::XCBC->new($cipher_name, $key);
$d->add('any data');
my $result_hex = $d->hexmac;   # finalizes the object

# for another output encoding use a fresh object (or clone before finalizing)
my $result_b64u = Crypt::Mac::XCBC->new($cipher_name, $key)->add('any data')->b64umac;

# or MAC a file instead
my $file_result_raw = Crypt::Mac::XCBC->new($cipher_name, $key)->addfile('filename.dat')->mac;

---

🦋 DESCRIPTION 🦋

so basically this module gives you an interface to the XCBC message authentication code (MAC) algorithm. no cap, that's the whole thing. ✨

---

🌈 EXPORT 🌈

nothing is exported by default. like, it's not gonna just show up uninvited bestie 🙈

you can export selected functions though:

use Crypt::Mac::XCBC qw( xcbc xcbc_hex xcbc_b64 xcbc_b64u );

or, if you're feeling unhinged, all of them at once:

use Crypt::Mac::XCBC ':all';

---

💜 FUNCTIONS 💜

⭐ xcbc

joins all the arguments into a single string and returns its XCBC message authentication code, encoded as a binary string. honestly? raw. 💀

🎀 data arguments for the functional helpers get converted to byte strings using Perl's usual scalar stringification. defined scalars — including numbers and string-overloaded objects — are accepted. undef is treated as an empty string and may emit Perl's usual "uninitialized value" warning. same rules apply to xcbc_hex, xcbc_b64, and xcbc_b64u, fr fr.

my $xcbc_raw = xcbc($cipher_name, $key, 'data buffer');
#or
my $xcbc_raw = xcbc($cipher_name, $key, 'any data', 'more data', 'even more data');

💅 xcbc_hex

same deal — joins all arguments into one string, returns the XCBC MAC as a hexadecimal string. cute and readable, we love that.

my $xcbc_hex = xcbc_hex($cipher_name, $key, 'data buffer');
#or
my $xcbc_hex = xcbc_hex($cipher_name, $key, 'any data', 'more data', 'even more data');

🍓 xcbc_b64

joins all arguments into a single string, returns the XCBC MAC encoded as a Base64 string. slay ✨

my $xcbc_b64 = xcbc_b64($cipher_name, $key, 'data buffer');
#or
my $xcbc_b64 = xcbc_b64($cipher_name, $key, 'any data', 'more data', 'even more data');

🧚 xcbc_b64u

joins all arguments into one string, returns the XCBC MAC as a Base64 URL-safe string (see RFC 4648 section 5, iykyk). the u is for URL-safe, not for "u" as in "you're welcome" 😭

my $xcbc_b64url = xcbc_b64u($cipher_name, $key, 'data buffer');
#or
my $xcbc_b64url = xcbc_b64u($cipher_name, $key, 'any data', 'more data', 'even more data');

---

👑 METHODS 👑

unless noted otherwise, just assume $d is an existing MAC object created via new, like so:

my $d = Crypt::Mac::XCBC->new($cipher_name, $key);

🌸 new

my $d = Crypt::Mac::XCBC->new($cipher_name, $key);

# $cipher_name .. [string] one of 'AES', 'Camellia', 'Twofish', 'Serpent', etc.
#                 any <NAME> for which there is a Crypt::Cipher::<NAME> module
# $key .......... [binary string] key of valid length for the chosen cipher (e.g. 16/24/32 bytes for AES)

so $cipher_name is a string — it can be 'AES', 'Camellia', 'Twofish', 'Serpent', etc., or literally any <NAME> that has a Crypt::Cipher::<NAME> module out there in the wild 🦋. and $key is a binary string that needs to be a valid length for whichever cipher you picked (like 16/24/32 bytes for AES, bestie, don't forget).

🎀 clone

$d->clone();

makes a copy. periodt. 💅

🔥 add

appends data to the message. returns the object itself, so you can chain like the main character you are 👑. croaks if the object has already been finalized by mac, hexmac, b64mac, or b64umac — like, it's done, leave it alone 😭

each argument gets converted to bytes using Perl's usual scalar stringification. defined scalars — including numbers and string-overloaded objects — are accepted. undef is treated as an empty string and may emit Perl's usual "uninitialized value" warning.

$d->add('any data');
#or
$d->add('any data', 'more data', 'even more data');

🫶 addfile

reads the file content and appends it to the message. returns the object itself (chaining again 💖). croaks if the object was already finalized by mac, hexmac, b64mac, or b64umac — same rule as add, no exceptions.

$d->addfile('filename.dat');
#or
my $filehandle = ...; # existing binary-mode filehandle
$d->addfile($filehandle);

⭐ mac

returns the binary MAC (raw bytes) and finalizes the object. once you've called mac, hexmac, b64mac, or b64umac even once, any later add, addfile, or MAC getter call will croak. that's the vibe check — finalized means finalized 🚫

my $result_raw = $d->mac();

💜 hexmac

returns the MAC as a lowercase hexadecimal string and finalizes the object. same deal: after the first mac / hexmac / b64mac / b64umac call, later add, addfile, or MAC getter calls croak. no cap.

my $result_hex = $d->hexmac();

🌈 b64mac

returns the MAC as a Base64 string with trailing = padding, and finalizes the object. and yeah — after the first mac, hexmac, b64mac, or b64umac call, later add, addfile, or any MAC getter croaks. 😤

my $result_b64 = $d->b64mac();

🧚 b64umac

returns the MAC as a Base64 URL-safe string with no trailing =, and finalizes the object. same finalization rules as the others — once you call mac, hexmac, b64mac, or b64umac, every later add, addfile, or MAC getter call croaks. 💀

my $result_b64url = $d->b64umac();

---

🌟 SEE ALSO 🌟

• CryptX — the parent vibe 💖
• <https://www.rfc-editor.org/rfc/rfc3566> — the source material, go read it bestie 📖

---

okay that's the whole page !! you officially know XCBC now, and honestly? ate. 💅✨

🌸 cute little sign-off: this was perl v5.42.0, dated 2026-05-11, and it lives happily at Crypt::Mac::XCBC(3). go forth and MAC responsibly, bestie 🫶💖