Authen...:Client(3pm)

💖 Authen::SCRAM::Client — RFC 5802 SCRAM client 💖

okay so bestie, welcome to the Authen...:Client(3pm) page — yes that's the manual name and yes it's giving truncated User Contributed Perl Documentation energy, we move 💅

---

✨ VERSION ✨

version 0.011 — she's a lil vintage, we respect her 🎀

---

🌸 SYNOPSIS 🌸

use Authen::SCRAM::Client;
use Try::Tiny;

$client = Authen::SCRAM::Client->new(
    username => 'johndoe',
    password => 'trustno1',
);

try {
    $client_first = $client->first_msg();

    # send to server and get server-first-message

    $client_final = $client->final_msg( $server_first );

    # send to server and get server-final-message

    $client->validate( $server_final );
}
catch {
    die "Authentication failed!"
};

---

🦋 DESCRIPTION 🦋

This module implements the client-side SCRAM algorithm. That's the whole vibe. She does the client half of the handshake and she does it well 🫶

---

🎀 NAME 🎀

Authen::SCRAM::Client — RFC 5802 SCRAM client. (not me getting deja vu… the page really does say it twice, and we're keeping the rerun because the facts stay the facts 😭)

---

⭐ VERSION ⭐

version 0.011. Still 0.011. Iconic consistency 💜

---

👑 ATTRIBUTES 👑

🌈 username (required)

The authentication identity. Before she gets sent off to the server, she'll be normalized with the SASLprep algorithm. Required, no skipsies.

🍓 password (required)

The authentication password. Also gets run through SASLprep normalization before being transmitted to the server. Also required, bestie.

🧚 authorization_id

If the authentication identity (username) is gonna act as a different, authorization identity, this attribute is where you hand over that authorization identity. It's optional — if you don't provide it, the server just treats the authentication identity as being the same as the authorization identity. Simple as.

💀 minimum_iteration_count

If the server comes at you requesting an iteration count lower than this value, the client throws an error. Why? Because this protects against downgrade attacks and we do not play with those. The default is 4096, which lines up with the recommendations in the RFC. Periodt.

🔥 digest

The name of a digest function available via PBKDF2::Tiny. Valid values are SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. Defaults to SHA-1.

💅 nonce_size

The size of the client-generated nonce, measured in bits. Defaults to 192. Heads up though: the server-nonce gets appended to it, so the final nonce size is gonna end up substantially larger than this. Slay 💖

🫶 skip_saslprep

A boolean that defaults to false. If you set it to true, usernames and passwords will not be normalized through SASLprep.

⚠️ This is a deviation from the RFC5802 spec and is not recommended. Like, at all. Don't do it unless you truly know what you're doing 😭

---

🌟 METHODS 🌟

💜 first_msg

$client_first_msg = $client->first_msg();

Takes no arguments and returns the "client-first-message" character string that you send to the server to initiate a SCRAM session. Calling this again resets the internal state and kicks off a brand new session. If an error happens, it throws an exception. Fresh start energy ✨

🎀 final_msg

$client_final_msg = $client->final_msg( $server_first_msg );

Takes the "server-first-message" character string you received from the server and returns the "client-final-message" character string containing the authentication proof, ready to be sent back to the server. Throws an exception if an error occurs, no cap.

🦋 validate

$client->validate( $server_final_msg );

Takes the "server-final-message" character string received from the server and verifies that the server actually has a copy of the client credentials. Returns true if it's valid — and throws an exception otherwise. So if it doesn't blow up, you're good 😌

👑 computed_keys

This method returns the opaque keys used in the SCRAM protocol. Specifically, it returns the 'stored key', the 'client key' and the 'server key'. For a given user to authenticate, the server must have a copy of the stored key and the server key.

Also she's a little cache-y about it: this method caches the computed values, and only generates them fresh if the supplied salt and iteration count don't match the cached salt and iteration count. Efficient queen 💅

---

🌈 CHARACTER ENCODING CAVEAT 🌈

Okay this one matters, bestie, listen up.

The SCRAM protocol mandates UTF-8 interchange. But — plot twist — every method in this module takes and returns character strings. So it's on you to encode to UTF-8 before sending and decode from UTF-8 on receiving, according to whatever transport mechanism you're using.

Why is it like this?? Because it avoids double encoding/decoding problems in the case where your transport is already doing UTF-8 encoding or decoding as it constructs outgoing messages or parses incoming messages. It's a whole coordination thing. You got this 🫶

---

💖 AUTHOR 💖

David Golden <dagolden@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is Copyright (c) 2014 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

💖 AUTHOR 💖

David Golden <dagolden@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is Copyright (c) 2014 by David Golden.

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.36.0, dated 2022-12-11, and yes the author + license really do show up twice too, we are simply matching the source's energy 🎀✨💅