Crypt::...:Pelican(3)

💖 Crypt::...:Pelican(3) — the Perl manpage, but make it bestie 💖

okay so this is the Crypt::Mac::Pelican page from the User Contributed Perl Documentation, and it's genuinely iconic — it's all about the Pelican message authentication code (MAC), which is AES-based. no cap, it's a whole vibe. let's get into it 🫶

---

✨ NAME ✨

Crypt::Mac::Pelican — Message authentication code Pelican (AES based MAC). literally what it says on the tin, bestie 💅

---

🎀 SYNOPSIS 🎀

so there's two whole ways to do this, and both slay:

the functional interface (my lowkey fave)

### Functional interface:
use Crypt::Mac::Pelican qw( pelican pelican_hex pelican_b64 pelican_b64u );

# calculate MAC from string/buffer
my $pelican_raw  = pelican($key, 'data buffer');
my $pelican_hex  = pelican_hex($key, 'data buffer');
my $pelican_b64  = pelican_b64($key, 'data buffer');
my $pelican_b64u = pelican_b64u($key, 'data buffer');

the OO interface (main character energy ngl)

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

my $d = Crypt::Mac::Pelican->new($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::Pelican->new($key)->add('any data')->b64umac;

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

⚠️ okay this bit matters: once you call hexmac, that object is done. if you want a second encoding you need a fresh object (or clone it before finalizing), not the same one. it's giving "one shot only" 💀

---

🌸 DESCRIPTION 🌸

Provides an interface to the Pelican message authentication code (MAC) algorithm. that's the whole thing. short, sweet, ate ✨

---

🦋 EXPORT 🦋

Nothing is exported by default. (she's private, she's mysterious 🙈)

but you can export selected functions, like:

use Crypt::Mac::Pelican qw( pelican pelican_hex pelican_b64 pelican_b64u );

Or all of them at once, go feral:

use Crypt::Mac::Pelican ':all';

---

👑 FUNCTIONS 👑

💜 pelican

Joins all arguments into a single string and returns its Pelican message authentication code encoded as a binary string.

okay important deets about the data arguments for the functional helpers: they 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. The same rules apply to pelican_hex, pelican_b64, and pelican_b64u. iykyk 🫶

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

⭐ pelican_hex

Joins all arguments into a single string and returns its Pelican message authentication code encoded as a hexadecimal string. hex girlies rise 🌈

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

🍓 pelican_b64

Joins all arguments into a single string and returns its Pelican message authentication code encoded as a Base64 string.

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

🧚 pelican_b64u

Joins all arguments into a single string and returns its Pelican message authentication code encoded as a Base64 URL-safe string (see RFC 4648 section 5). url-safe queen 💅

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

---

🔥 METHODS 🔥

Unless noted otherwise, assume $d is an existing MAC object created via new, for example:

my $d = Crypt::Mac::Pelican->new($key);

🌟 new

my $d = Crypt::Mac::Pelican->new($key);

# $key .. [binary string] exactly 16 bytes (AES-128 key; Pelican is AES-based)

🚨 read this twice: the key is a binary string of exactly 16 bytes — that's an AES-128 key, because Pelican is AES-based. not 15, not 17. sixteen. periodt.

💫 clone

$d->clone();

makes a copy, so you can finalize twice-ish without breaking the one-shot rule. big brain move 🧠

🎀 add

Appends data to the message. Returns the object itself (for chaining). Croaks if the object has already been finalized by mac, hexmac, b64mac, or b64umac. yeah she's not gonna let you add stuff after the fact, no cap 😭

Each argument is 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 (for chaining). Croaks if the object has already been finalized by mac, hexmac, b64mac, or b64umac. file-based MAC-ing, obsessed 🦋

$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. After the first call to mac, hexmac, b64mac, or b64umac, later calls to add, addfile, or any MAC getter croak. raw bytes, no encoding, straight vibes ✨

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

⭐ hexmac

Returns the MAC encoded as a lowercase hexadecimal string and finalizes the object. After the first call to mac, hexmac, b64mac, or b64umac, later calls to add, addfile, or any MAC getter croak.

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

🍓 b64mac

Returns the MAC encoded as a Base64 string with trailing = padding and finalizes the object. After the first call to mac, hexmac, b64mac, or b64umac, later calls to add, addfile, or any MAC getter croak. yes the = padding is included, she's old school 🎀

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

🧚 b64umac

Returns the MAC encoded as a Base64 URL-safe string (no trailing =) and finalizes the object. After the first call to mac, hexmac, b64mac, or b64umac, later calls to add, addfile, or any MAC getter croak. no padding here, url-safe and unbothered 💅

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

---

🌈 SEE ALSO 🌈

• CryptX
• <https://eprint.iacr.org/2005/088.pdf>

go read the paper bestie, it's giving academic slay 📚✨

---

and that's the page!! 🎉 this was perl v5.42.0, dated 2026-05-11, from Crypt::...:Pelican(3) — mwah, love you, bye 🫶💖🎀