Crypt::Argon2(3pm)

📦
version 0.031 · 8 versions
, in ubuntu stonking

🌸 Crypt::Argon2 — the Perl interface to the Argon2 KDFs 💅

okay so this page is Crypt::Argon2(3pm), part of the User Contributed Perl Documentation, and it's literally your new bestie for turning passwords into cryptographic keys. buckle up 🎀

✨ VERSION ✨

version 0.031 — yes queen, we're on 0.031 💖

🦋 SYNOPSIS 🦋

here's the vibe, copy-paste style:

 use Crypt::Argon2 qw/argon2id_pass argon2_verify/;

 sub add_pass {
   my ($user, $password) = @_;
   my $salt = get_random(16);
   my $encoded = argon2id_pass($password, $salt, 3, '32M', 1, 16);
   store_password($user, $encoded);
 }

 sub check_password {
   my ($user, $password) = @_;
   my $encoded = fetch_encoded($user);
   return argon2_verify($encoded, $password);
 }

like, that's the whole loop: make a salt, hash the password, store it, then verify later. iconic ✨

💜 DESCRIPTION 💜

This module implements the Argon2 key derivation function, which is suitable to convert any password into a cryptographic key. most often it's used for secure storage of passwords, but ngl it can also derive an encryption key from a password. it offers variable time and memory costs as well as output size — so you get to tune it, main character energy fr fr.

To find appropriate parameters, the bundled program argon2-calibrate can be used. bestie, please use it, don't just guess 🙈

💅 FUNCTIONS 💅

⭐ argon2_pass($type, $password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

This function processes the $password with the given $salt and parameters. It encodes the resulting tag and the parameters as a password string (e.g. "$argon2id$v=19$m=65536,t=2,p=1$c29tZXNhbHQ$wWKIMhR9lyDFvRz9YTZweHKfbftvj+qf+YFY4NeBbtA").

okay so here's what each arg does 👇

  • $type — the argon2 type that is used. This must be one of 'argon2id', 'argon2i' or 'argon2d'.
  • $password — this is the password that is to be turned into a cryptographic key.
  • $salt — this is the salt that is used. It must be long enough to be unique. (no cap, uniqueness is the whole point 🧂)
  • $t_cost — this is the time-cost factor, typically a small integer that can be derived as explained above.
  • $m_factor — this is the memory costs factor. This must be given as a integer followed by an order of magnitude ("k", "M" or "G" for kilobytes, megabytes or gigabytes respectively), e.g. '64M'.
  • $parallelism — this is the number of threads that are used in computing it.
  • $tag_size — this is the size of the raw result in bytes. Typical values are 16 or 32.

🔍 argon2_verify($encoded, $password)

This verifies that the $password matches $encoded. All parameters and the tag value are extracted from $encoded, so no further arguments are necessary. slay, zero extra work 🫶

🧚 argon2_raw($type, $password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

This function processes the $password with the given $salt and parameters much like "argon2_pass", but returns the binary tag instead of a formatted string. raw bytes, no dress-up 💀

👑 argon2id_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

👑 argon2i_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

👑 argon2d_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

This function processes the $password much like "argon2_pass" does, but the $type argument is set like the function name. so like, the type is already baked in — no $type arg for you ✨

🌈 argon2id_verify($encoded, $password)

🌈 argon2i_verify($encoded, $password)

🌈 argon2d_verify($encoded, $password)

This verifies that the $password matches $encoded and the given type. All parameters and the tag value are extracted from $encoded, so no further arguments are necessary.

🍓 argon2id_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

🍓 argon2i_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

🍓 argon2d_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)

This function processes the $password much like "argon2_raw" does, but the $type argument is set like the function name.

🦋 argon2_needs_rehash($encoded, $type, $t_cost, $m_cost, $parallelism, $output_length, $salt_length)

This function checks if a password-encoded string needs a rehash. It will return true if the $type (valid values are "argon2i", "argon2id" or "argon2d"), $t_cost, $m_cost, $parallelism, $output_length or $salt_length arguments mismatches any of the parameters of the password-encoded hash.

lowkey the glow-up detector: if your stored hash's params don't match the ones you're passing in, it says "bestie, rehash time" 💅

🌸 argon2_types

This returns all supported argon2 subtypes. Currently that's 'argon2id', 'argon2i' and 'argon2d'.

⚡ argon2_implementation

This returns the implementation that is used. Possible values include "avx512", "avx2", "sse3", and "reference". it's giving "which CPU flex did we get" 🔥

🎀 ACKNOWLEDGEMENTS 🎀

This module is based on the reference implementation as can be found at <https://github.com/P-H-C/phc-winner-argon2>. credit where credit is due, periodt 👑

🌟 SEE ALSO 🌟

You will also need a good source of randomness to generate good salts. Some possible solutions include:

  • Net::SSLeay — its RAND_bytes function is OpenSSL's pseudo-randomness source.
  • Crypt::URandom — a minimalistic abstraction around OS-provided non-blocking (pseudo-)randomness.
  • "/dev/random" / "/dev/urandom" — a Linux/BSD specific pseudo-file that will allow you to read random bytes.

Implementations of other similar algorithms include:

  • Crypt::Bcrypt — an implementation of bcrypt, a battle-tested algorithm that tries to be CPU but not particularly memory intensive.
  • Crypt::ScryptKDF — an implementation of scrypt, a older scheme that also tries to be memory hard.

💖 AUTHOR 💖

Leon Timmermans <fawaka@gmail.com>

This software is Copyright (c) 2013 by Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, Samuel Neves, Thomas Pornin and Leon Timmermans.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

and that's the whole page bestie 🫶 written for perl v5.42.3, dated 2026-08-19, Crypt::Argon2(3pm) — go forth and hash responsibly, mwah 💋🌸

📦 where this page comes from