Cyrus(3pm)

📦 version 0.13-server, in ubuntu jammy

okay bestie, welcome to the Authen::SASL::Cyrus manual page 💖 this is part 1, so buckle up, we're getting into the XS glue that makes Perl SASL talk to Cyrus SASL. no cap. 🦋

💖 NAME 💖

Authen::SASL::Cyrus — XS code to glue Perl SASL to Cyrus SASL. that's the whole vibe. ✨

🌸 SYNOPSIS 🌸

here's the quick lil' peek at how you use it, bestie: 💅

         use Authen::SASL;

         my $sasl = Authen::SASL->new(
                mechanism => 'NAME',
                callback => { NAME => VALUE, NAME => VALUE, ... },
         );

         my $conn = $sasl->client_new(<service>, <server>, <iplocalport>, <ipremoteport>);

         my $conn = $sasl->server_new(<service>, <host>, <iplocalport>, <ipremoteport>);

✨ DESCRIPTION ✨

SASL? it's a generic mechanism for authentication used by several network protocols. Authen::SASL::Cyrus provides an implementation framework that all protocols should be able to share. literally, it's giving shared framework energy. 💅

The XS framework makes calls into the existing libsasl.so resp. libsasl2 shared library to perform SASL client connection functionality, including loading existing shared library mechanisms. it's lowkey doing a lot. 🔥

🎀 CONSTRUCTOR 🎀

okay so the constructor can be called with or without arguments. passing arguments is just a short cut to calling the mechanism and callback methods. no biggie. 🎀

You have to use the Authen::SASL new-constructor to create a SASL object. the Authen::SASL object then holds all necessary variables and callbacks, which you gave when creating the object. client_new and server_new will retrieve needed information from this object. it's giving main character energy, periodt. 👑

💅 CALLBACKS 💅

callbacks are very important, bestie. it depends on the mechanism which callbacks have to be set. and it is not a failure to set callbacks even if they aren't used. (e.g. password-callback when using GSSAPI or KERBEROS_V4). so don't stress. 🙈

The Cyrus-SASL library uses callbacks when the application needs some information. common reasons are getting usernames and passwords. like, it's literally asking for the tea. 🍵

Authen::SASL::Cyrus allows Cyrus-SASL to use perl-variables and perl-subs as callback-targets. so you can pass scalars, coderefs, arrayrefs... we'll get to that. 💖

Currently Authen::SASL::Cyrus supports the following Callback types: (for a more detailed description on what the callback type is used for see the respective man pages)

Remark: All callbacks, which have to return some values (e.g.: **result in sasl_getsimple_t) do this by returning the value(s). See example below. 💅
  • user (client), auth (client), language (client) — these callbacks represent the sasl_getsimple_t from the library. ✨
    • Input: none
    • Output: username, authname or language
  • password (client), pass (client) — these callbacks represent the sasl_getsecret_t from the library. 🔐
    • Input: none
    • Output: password
  • realm <client> — this callback represents the sasl_getrealm_t from the library. 🦋
    • Input: a list of available realms
    • Output: the chosen realm
    • (This has nothing to do with GSSAPI or KERBEROS_V4 realm).
  • checkpass (server, SASL v2 only) — this callback represents the sasl_server_userdb_checkpass_t from the library. ✅
    • Input: username, password
    • Output: true or false
  • getsecret (server, SASL v1 only) — this callback represents the sasl_server_getsecret_t from the library. Sasl will check if the passwords are matching. 🔍
    • Input: mechanism, username, default_realm
    • Output: secret_phrase (password)
    • Remark: Programmers that are using should specify both callbacks (getsecret and checkpass). Then, depending on your Cyrus SASL library either the one or the other is called. Cyrus SASL v1 ignores checkpass and Cyrus SASL v2 ignores getsecret. 💅
  • putsecret (SASL v1) and setpass (SASL v2) — are currently not supported (and won't be, unless someone needs it). 💀
  • canonuser (server/client in SASL v2, server only in SASL v1) — this callback name represents the sasl_canon_user_t from the library. 🦋
    • Input: Type of principal, principal, userrealm and maximal allowed length of the output.
    • Output: canonicalised principal
    • Type of principal is AUTHID for Authentication ID or AUTHZID for Authorisation ID.
    • Remark: This callback is ideal to get the username of the user using your service. If Authen::SASL::Cyrus is linked to Cyrus SASL v1, which doesn't have a canonuser callback, it will simulate this callback by using the authorize callback internally. Don't worry, the authorize callback is available anyway. 💖
  • authorize (server) — this callback represents the sasl_authorize_t from the library. 👑
    • Input: authenticated_username, requested_username, (default_realm SASL v2 only)
    • Output: canonicalised_username SASL v1 resp. true or false when using SASL v2 lib There is something TODO, I think. 🤔
  • setpass (server, SASL v2 only) — this callback represents the sasl_server_userdb_setpass_t from the library. 🔐
    • Input: username, new_password, flags (0x01 CREATE, 0x02 DISABLE, 0x04 NOPLAIN)
    • Out: true or false

🦋 Ways to pass a callback 🦋

Authen::SASL::Cyrus supports three different ways to pass a callback. pick your fighter. 💅

CODEREF

If the value passed is a code reference then, when needed, it will be called. it's giving sub { ... } energy. ✨

ARRAYREF

If the value passed is an array reference, the first element in the array must be a code reference. When the callback is called the code reference will be called with the value from the array passed after. so like [ \&code, @args ]. 🎀

SCALAR

All other values passed will be returned directly to the SASL library as the answer to the callback. simple as that. 💖

✨ Example of setting callbacks ✨

$sasl = new Authen::SASL (
  mechanism => "PLAIN",
    callback => {
      # Scalar
      user => "mannfred",
      pass => $password,
      language => 1,

      # Coderef
      auth => sub { return "klaus", }
      realm => \&getrealm,

      # Arrayref
      canonuser => [ \&canon, $self ],
   }
);

The last example is ideal for using object methods as callback functions. Then you can do something like this:

sub canon {
  my ($this,$type,$realm,$maxlen,$user) = @_;
  $this->{_username} = $user if ($type eq "AUTHID");
  return $user; }

✨ METHODS ✨

Okay bestie, this is the part where the actual doing stuff happens. Every method below lives on the connection object you got back from the constructors, so like, keep that reference close to your heart 🫶

  • server_new ( SERVICE , HOST = "" , IPLOCALPORT , IPREMOTEPORT ) — the constructor for making server-side sasl contexts.

It creates a brand new connection object and blesses it into Authen::SASL::Cyrus, then hands it back to you. And it's on that returned reference that all the methods below are available, okurrr? SERVICE is the name of the service you're implementing, and the underlying mechanism might peek at it. A super classic example of a service is "ldap".

  • client_new ( SERVICE , HOST , IPLOCALPORT , IPREMOTEPORT ) — constructor for creating server-side sasl contexts. (No fr, that's literally what the docs say for this one too, we're just relaying it 💀)

Same deal: creates and returns a new connection object blessed into Authen::SASL::Cyrus, and that returned reference is where all the following methods hang out. SERVICE is the name of the service being implemented, which the underlying mechanism may use — an example service is "ldap". HOST is the name of the server being contacted, and the underlying mechanism might use that too.

Peep the SYNOPSIS for an example.

Remark: this function and server_new get called by Authen::SASL when you use its *_new function. And since you have to use Authen::SASL anyway, bestie, normally you do not need to call this one directly. Periodt.

IPLOCALPORT and IPREMOTEPORT arguments are only available when ASC is linked against Cyrus SASL 2.x. These arguments are needed for KERBEROS_V4 and CS 2.x on the server side. Don't know if it's necessary for the client side (that's the original author's uncertainty, not mine, I'm just the messenger 🙈). The format of these arguments in an IPv4 environment should be:

a.b.c.d;port

See sasl_server_new(3) for details.

  • server_start ( CHALLENGE ) — server_start kicks off the authentication using the chosen mechanism. If the installed Cyrus-SASL doesn't support that mechanism, it fails. And because some mechanisms need the client to start the negotiation, you're allowed to pass the client challenge in as a parameter.
  • client_start ( ) — the very first step to be performed. Returns the initial value you pass over to the server. The client has to start the negotiation always — no skipping, no exceptions 💅
  • server_step ( CHALLENGE ) — server_step does the next step in the negotiation process. The first parameter you hand it is the client's challenge/response.
  • client_step ( CHALLENGE )
Remark: client_start, client_step, server_start and server_step will return the respective sasl response or undef. The returned value says nothing about the current negotiation status. It is absolutely possible that one of these functions returns undef and everything is completely fine for SASL — there's just another step needed. So don't panic, babes 😭

So that means you have to check need_step and code during negotiation. See the example below.

  • listmech( START , SEPARATOR , END ) — listmech returns a string containing all the mechanisms allowed for the user set by user. START is the token that gets put at the beginning of the string, SEPARATOR is the token used to separate the mechanisms, and END is the token that gets put at the end of the returned string ✨
  • setpass(user, newpassword, oldpassword, flags)
  • checkpass(user, password)

setpass and checkpass are only available when using the Cyrus-SASL 2.x library.

setpass sets a new password (it depends on the mechanism whether the setpass callback gets called). checkpass checks a password for the user (it calls the checkpass callback).

For both functions, go read the man pages of Cyrus SASL for a detailed description.

Both functions return true on success, false otherwise.

  • global_listmech ( ) — only available when using the Cyrus-SASL 2.x library.

It returns an array with all mechanisms loaded by the library.

  • encode ( STRING )
  • decode ( STRING )

The Cyrus-SASL developers suggest using the encode and decode functions for every bit of traffic that will run over the network after a successful authentication. Protect your data bestie 🔐

encode returns the encrypted string generated from STRING. decode returns the decrypted string generated from STRING.

It depends on the mechanism you're using how secure that encryption will actually be 👀

  • error ( ) — error returns an array with all known error messages. Basicly the sasl_errstring function is called with the current error_code. When using the Cyrus-SASL 2.x library, the string returned by sasl_errdetail is also given back. On top of that, the special Authen::SASL::Cyrus advice is returned if it's been set. And heads up: after you call the error function, the error code and the special advice get thrown away. Gone. Poof 💨
  • code ( ) — code returns the current Cyrus-SASL error code.
  • mechanism ( ) — mechanism returns the current authentication mechanism being used.
  • need_step ( ) — need_step returns true if the SASL library needs another step. Otherwise false is returned. You can also just use code == 1, but honestly need_step looks smarter I think. That's why we're all using perl, eh? 😌

🌸 EXAMPLE 🌸

Server-side

# The example uses Cyrus-SASL v2
# Set the SASL_PATH to the location of the SASL-Plugins
# default is /usr/lib/sasl2
$ENV{'SASL_PATH'} = "/opt/products/sasl/2.1.15/lib/sasl2";

#
my $sasl = Authen::SASL->new (
   mechanism => "PLAIN",
   callback => {
     checkpass => \&checkpass,
     canonuser => \&canonuser,
   }
);

# Creating the Authen::SASL::Cyrus object
my $conn = $sasl->server_new("service","","ip;port local","ip;port remote");

# Clients first string (maybe "", depends on mechanism)
# Client has to start always
sendreply( $conn->server_start( &getreply() ) );

while ($conn->need_step) {
   sendreply( $conn->server_step( &getreply() ) );
}

if ($conn->code == 0) {
   print "Negotiation succeeded.\n";
} else {
   print "Negotiation failed.\n";
}

Client-side

# The example uses Cyrus-SASL v2
# Set the SASL_PATH to the location of the SASL-Plugins
# default is /usr/lib/sasl2
$ENV{'SASL_PATH'} = "/opt/products/sasl/2.1.15/lib/sasl2";

#
my $sasl = Authen::SASL->new (
   mechanism => "PLAIN",
   callback => {
     user => \&getusername,
     pass => \&getpassword,
   }
);

# Creating the Authen::SASL::Cyrus object
my $conn = $sasl->client_new("service", "hostname.domain.tld");

# Client begins always
sendreply($conn->client_start());

while ($conn->need_step) {
   sendreply($conn->client_step( &getreply() ));
}

if ($conn->code == 0) {
   print STDERR "Negotiation succeeded.\n";
} else {
   print STDERR "Negotiation failed.\n";
}

See t/plain.t for a working script. Go run it bestie, it slaps 🏃‍♀️

🧪 TESTING 🧪

I tested ASC (server and client) with the following mechanisms:

GSSAPI

Don't forget to create a keytab. Non-root keytabs can be specified through $ENV{'KRB5_KTNAME'} (Heimdal >= 0.6, MIT).

KERBEROS_V4

Available since 0.10 — you have to add IPLOCALPORT and IPREMOTEPORT to the *_new functions.

PLAIN

👀 SEE ALSO 👀

Authen::SASL

man pages for sasl_* library functions.

💖 AUTHOR 💖

Originally written by Mark Adamson <mark@nb.net>

Cyrus-SASL 2.x support by Leif Johansson

Glue for server_* and many other structural improvements by Patrick Boettcher <patrick.boettcher@desy.de>

Please report any bugs, or post any suggestions, to the authors. They want to hear from you, fr fr 🫶

🫂 THANKS 🫂

  • Guillaume Filion for testing the server part and for giving hints about some bugs (documentation).
  • Wolfgang Friebel for bother around with rpm building of test releases.

Copyright (c) 2003-5 Patrick Boettcher, DESY Zeuthen. All rights reserved. Copyright (c) 2003 Carnegie Mellon University. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie 🎀 You just read perl v5.34.0, dated 2022-02-06, from Cyrus(3pm) — iconic, no cap. Now go authenticate something responsibly 💅✨

📦 where this page comes from