view release on metacpan or  search on metacpan

XS.pod  view on Meta::CPAN

=head1 NAME

Authen::SASL::XS	- XS code to glue Perl SASL to Cyrus SASL

=head1 SYNOPSIS

  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>);

=head1 DESCRIPTION

SASL is a generic mechanism for authentication used by several
network protocols. B<Authen::SASL::XS> provides an implementation
framework that all protocols should be able to share.

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.

=head1 CONSTRUCTOR

The constructor may be called with or without arguments. Passing arguments is
just a short cut to calling the C<mechanism> and C<callback> methods.

You have to use the C<Authen::SASL> new-constructor to create a SASL object.
The C<Authen::SASL> object then holds all necessary variables and callbacks, which
you gave when creating the object.
C<client_new> and C<server_new> will retrieve needed information from this
object.

=pod

=head1 CALLBACKS

Callbacks are very important. It depends on the mechanism which callbacks
have to be set. It is not a failure to set callbacks even they aren't used.
(e.g. password-callback when using GSSAPI or KERBEROS_V4)

The Cyrus-SASL library uses callbacks when the application
needs some information. Common reasons are getting
usernames and passwords.

Authen::SASL::XS allows Cyrus-SASL to use perl-variables and perl-subs
as callback-targets.

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

B<Remark>: All callbacks, which have to return some values (e.g.: **result in
C<sasl_getsimple_t>) do this by returning the value(s). See example below.

=over 4

=item user (client)

=item auth (client)

=item language (client)

This callbacks represent the C<sasl_getsimple_t> from the library.

Input: none

Output: C<username>, C<authname> or C<language>

=item password (client)

=item pass (client)

This callbacks represent the C<sasl_getsecret_t> from the library.

Input: none

Output: C<password>

=item realm <client>

This callback represents the C<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).

=item checkpass (server, SASL v2 only)

This callback represents the C<sasl_server_userdb_checkpass_t> from the
library.

Input: C<username>, C<password>

Output: true or false


=item getsecret (server, SASL v1 only)

This callback represents the C<sasl_server_getsecret_t> from the library. Sasl
will check if the passwords are matching.

Input: C<mechanism>, C<username>, C<default_realm>

Output: C<secret_phrase (password)>

B<Remark>: Programmers that are using should specify both callbacks (getsecret and checkpass).
Then, depending on you Cyrus SASL library either the one or the other is called. Cyrus SASL v1
ignores checkpass and Cyrus SASL v2 ignores getsecret.

=item putsecret (SASL v1) and setpass (SASL v2)

are currently not supported (and won't be, unless someone needs it).

=item canonuser (server/client in SASL v2, server only in SASL v1)

This callback name represents the C<sasl_canon_user_t> from the library.

Input: C<Type of principal>, C<principal>, C<userrealm> and maximal allowed length of the output.

Output: canonicalised C<principal>

C<Type of principal> is "AUTHID" for Authentication ID or "AUTHZID"
for Authorisation ID.

B<Remark>: This callback is ideal to get the username of the user using your service.
If C<Authen::SASL::XS> 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.

=item authorize (server)

This callback represents the C<sasl_authorize_t> from the library.

Input: C<authenticated_username>, C<requested_username>, (C<default_realm> SASL v2 only)

Output: C<canonicalised_username> SASL v1 resp. true or false when using SASL v2 lib
There is something TODO, I think.

=item setpass (server, SASL v2 only)

This callback represents the C<sasl_server_userdb_setpass_t> from the library.

Input: C<username>, C<new_password>, C<flags> (0x01 CREATE, 0x02 DISABLE,
0x04 NOPLAIN)

Out: true or false

=back

=head2 Ways to pass a callback

Authen::SASL::XS supports three different ways to pass a callback

=over 4

=item CODEREF

If the value passed is a code reference then, when needed, it will be called.

=item 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.

=item SCALAR
All other values passed will be returned directly to the SASL library
as the answer to the callback.

=back

=head2 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;
}

=head1 Authen::SASL::XS METHODS

=over 4

=item server_new ( SERVICE , HOST = "" , IPLOCALPORT , IPREMOTEPORT )

Constructor for creating server-side sasl contexts.

Creates and returns a new connection object blessed into Authen::SASL::XS.
It is on that returned reference that the following methods are available.
The SERVICE is the name of the service being implemented, which may be used
by the underlying mechanism. An example service therefore is "ldap".

=item client_new ( SERVICE , HOST , IPLOCALPORT , IPREMOTEPORT )

Constructor for creating server-side sasl contexts.

Creates and returns a new connection object blessed into Authen::SASL::XS.
It is on that returned reference that the following methods are available.
The SERVICE is the name of the service being implemented, which may be used
by the underlying mechanism. An example service is "ldap". The HOST is the
name of the server being contacted, which may also be used
by the underlying mechanism.

=back

B<Remark>:
This and the C<server_new> function are called by L<Authen::SASL> when using
its C<*_new> function. Since the user has to use Authen::SASL anyway, normally
it is not necessary to call this function directly.

IPLOCALPORT and IPREMOTEPORT arguments are only available, when ASC is