Authen...:Server(3pm)

👑 Authen::SCRAM::Server 👑 — the RFC 5802 SCRAM Server

okay so bestie, we are diving into Authen::SCRAM::Server, straight out of the User Contributed Perl Documentation pile, and it is exactly what it sounds like: the server side of SCRAM. no cap. 💅

---

✨ VERSION ✨

version 0.011

---

🌸 SYNOPSIS 🌸

use Authen::SCRAM::Server;
use Try::Tiny;

$server = Authen::SCRAM::Server->new(
    credential_cb => \&get_credentials,
);

$username = try {
    # get client-first-message

    $server_first = $server->first_msg( $client_first );

    # send to client and get client-final-message

    $server_final = $server->final_msg( $client_final );

    # send to client

    return $server->authorization_id; # returns valid username
}
catch {
    die "Authentication failed!"
};

like. look at that. try / catch, messages flying back and forth, and then authorization_id hands you the valid username at the end. the whole glow-up arc in one snippet 🫶

---

💖 DESCRIPTION 💖

This module implements the server-side SCRAM algorithm. that's it, that's the vibe. server side only, she's not doing the client's job for her. ✨

---

🔁 NAME 🔁

Authen::SCRAM::Server — RFC 5802 SCRAM Server

yes bestie, the page genuinely says this again right here. it's giving "said it twice for emphasis" and honestly? iconic. keeping it, because the facts are the facts. 💀

---

🔁 VERSION 🔁

version 0.011

---

🎀 ATTRIBUTES 🎀

credential_cb (required) 🔥

okay so this one is mandatory, no skipping. It has to hold a code reference that takes a username — and that username is a character string already normalized by SASLprep, thank you very much — and hands back the four user-credential parameters SCRAM needs: salt, StoredKey, ServerKey, and iteration count.

big important detail: salt, StoredKey and ServerKey have to come back as octets, aka NOT base64 encoded. do not come in here with base64, she will know. 😭

and if the username is unknown? return an empty list. that's the move.

($salt, $stored_key, $server_key, $iterations) =
    $server->credential_cb->( $username );

for the full lore, go see RFC 5802: SCRAM Algorithm Overview <http://tools.ietf.org/html/rfc5802#section-3>. it's giving required reading. 📚

auth_proxy_cb

if you provide this one, it has to hold a code reference that takes an authentication username and an authorization username (both character strings) and returns a true value if the authentication username is allowed to act as the authorization username:

$bool = $server->auth_proxy_cb->(
    $authentication_user, $authorization_user
);

the way this one only gets called if the authentication username has already successfully authenticated? gatekeeping done right, honestly. 🔒 and both usernames will have been normalized via SASLprep with any transport encoding stripped off before they ever reach this function. clean. ✨

digest

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.

pick your fighter. SHA-1 is the default, no judgment (okay, a little judgment, but it's what the module does, not me). 💅

nonce_size

Size of the client-generated nonce, in bits. Defaults to 192. The server-nonce will be appended, so the final nonce size will be substantially larger.

she's 192 bits by default and then the server adds more on top, because more is more. 🦋

skip_saslprep

A boolean that defaults to false. If set to true, usernames and passwords will not be normalized through SASLprep. This is a deviation from the RFC5802 spec and is not recommended.

🚨 bestie. this is a deviation from the RFC5802 spec and it is not recommended. i'm not saying don't, i'm saying the manpage said don't and i'm a messenger. 🙈

---

🌈 METHODS 🌈

first_msg

$server_first_msg = $server->first_msg( $client_first_msg );

This takes the client-first-message received from the client and returns the server-first-message string to send back to the client so the SCRAM session can keep going. Calling this again resets the internal state and kicks off a whole new session — it's giving "fresh start, new me." This will throw an exception should an error occur. 😤

final_msg

$server_final_msg = $server->final_msg( $client_final_msg );

This takes the client-final-message received from the client and returns the server-final-message string containing the verification signature to send to the client.

If an authorization identity was provided by the client, it will confirm that the authenticating username is authorized to act as the authorization id using the auth_proxy_cb attribute.

and if the client credentials do not match, or the authentication name is not authorized to act as the authorization name? exception thrown. no vibes passed. 💀

authorization_id

$username = $client->authorization_id();

This takes no arguments and returns the authorization identity resulting from the SCRAM exchange. That's the client-supplied authorization identity (if one was provided and validated) or else the successfully authenticated identity. she took zero arguments and still gave you a whole answer. main character energy. 👑

---

🧚 CHARACTER ENCODING CAVEAT 🧚

The SCRAM protocol mandates UTF-8 interchange. However, all methods in this module take and return character strings. You must encode to UTF-8 before sending and decode from UTF-8 on receiving according to whatever transport mechanism you are using.

and why, you ask? This is done to avoid double encoding/decoding problems if your transport is already doing UTF-8 encoding or decoding as it constructs outgoing messages or parses incoming messages.

🔥 real talk: encode on the way out, decode on the way in, and let your transport do its thing. do NOT double-dip the UTF-8, bestie, it gets messy. 🍓

---

💜 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, twice-repeated sections and all, because we keep every detail around here. 💖

mwah, love you, bye — this was perl v5.36.0, dated 2022-12-11, and yes, the title at the top and the footer at the bottom were both Authen...:Server(3pm) (the truncation is real, she's shy). go authenticate something. slay. ✨🎀🦋