242 lines
5.6 KiB
Plaintext
242 lines
5.6 KiB
Plaintext
|
|
=head1 NAME
|
|
|
|
Authen::SASL - SASL Authentication framework
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Authen::SASL;
|
|
|
|
$sasl = Authen::SASL->new(
|
|
mechanism => 'CRAM-MD5 PLAIN ANONYMOUS',
|
|
callback => {
|
|
pass => \&fetch_password,
|
|
user => $user,
|
|
}
|
|
);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SASL is a generic mechanism for authentication used by several
|
|
network protocols. B<Authen::SASL> provides an implementation
|
|
framework that all protocols should be able to share.
|
|
|
|
The framework allows different implementations of the connection
|
|
class to be plugged in. At the time of writing there were two such
|
|
plugins.
|
|
|
|
=over 4
|
|
|
|
=item Authen::SASL::Perl
|
|
|
|
This module implements several mechanisms and is implemented
|
|
entirely in Perl.
|
|
|
|
=item Authen::SASL::XS
|
|
|
|
This module uses the Cyrus SASL C-library (both version 1 and 2
|
|
are supported).
|
|
|
|
=item Authen::SASL::Cyrus
|
|
|
|
This module is the predecessor to L<Authen::SASL::XS>. It is reccomended
|
|
to use L<Authen::SASL::XS>
|
|
|
|
=back
|
|
|
|
By default the order in which these plugins are selected is
|
|
Authen::SASL::XS, Authen::SASL::Cyrus and then Authen::SASL::Perl.
|
|
|
|
If you want to change it or want to specifically use one
|
|
implementation only simply do
|
|
|
|
use Authen::SASL qw(Perl);
|
|
|
|
or if you have another plugin module that supports the Authen::SASL API
|
|
|
|
use Authen::SASL qw(My::SASL::Plugin);
|
|
|
|
=head2 CONTRUCTOR
|
|
|
|
=over 4
|
|
|
|
=item new ( OPTIONS )
|
|
|
|
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.
|
|
|
|
=over 4
|
|
|
|
=item callback =E<gt> { NAME => VALUE, NAME => VALUE, ... }
|
|
|
|
Set the callbacks.
|
|
See the L<callback|/callback> method for details.
|
|
|
|
=item mechanism =E<gt> NAMES
|
|
|
|
=item mech =E<gt> NAMES
|
|
|
|
Set the list of mechanisms to choose from.
|
|
See the L<mechanism|/mechanism> method for details.
|
|
|
|
=item debug =E<gt> VALUE
|
|
|
|
Set the debug level bit-value to C<VALUE>
|
|
|
|
Debug output will be sent to C<STDERR>. The
|
|
bits of this value are:
|
|
|
|
1 Show debug messages in the Perl modules for the mechanisms.
|
|
(Currently only used in GSSAPI)
|
|
4 With security layers in place show information on packages read.
|
|
8 With security layers in place show information on packages written.
|
|
|
|
The default value is 0.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
=head2 METHODS
|
|
|
|
=over 4
|
|
|
|
=item mechanism ( )
|
|
|
|
Returns the current list of mechanisms
|
|
|
|
=item mechanism ( NAMES )
|
|
|
|
Set the list of mechanisms to choose from. C<NAMES> should be a space separated string
|
|
of the names.
|
|
|
|
=item callback ( NAME )
|
|
|
|
Returns the current callback associated with C<NAME>.
|
|
|
|
=item callback ( NAME => VALUE, NAME => VALUE, ... )
|
|
|
|
Sets the given callbacks to the given values
|
|
|
|
=item client_new ( SERVICE, HOST, SECURITY )
|
|
|
|
Creates and returns a new connection object for a client-side connection.
|
|
|
|
=item server_new ( SERVICE, HOST, OPTIONS )
|
|
|
|
Creates and returns a new connection object for a server-side connection.
|
|
|
|
=item error ( )
|
|
|
|
Returns any error from the last connection
|
|
|
|
=back
|
|
|
|
=head1 The Connection Class
|
|
|
|
=over 4
|
|
|
|
=item server_start ( CHALLENGE )
|
|
|
|
server_start begins the authentication using the chosen mechanism.
|
|
If the mechanism is not supported by the installed SASL it fails.
|
|
Because for some mechanisms the client has to start the negotiation,
|
|
you can give the client challenge as a parameter.
|
|
|
|
=item server_step ( CHALLENGE )
|
|
|
|
server_step performs the next step in the negotiation process. The
|
|
first parameter you give is the clients challenge/response.
|
|
|
|
=item client_start ( )
|
|
|
|
The initial step to be performed. Returns the initial value to pass to the server
|
|
or an empty list on error.
|
|
|
|
=item client_step ( CHALLENGE )
|
|
|
|
This method is called when a response from the server requires it. CHALLENGE
|
|
is the value from the server. Returns the next value to pass to the server or an
|
|
empty list on error.
|
|
|
|
=item need_step ( )
|
|
|
|
Returns true if the selected mechanism requires another step before completion
|
|
(error or success).
|
|
|
|
=item answer ( NAME )
|
|
|
|
The method will return the value returned from the last call to the callback NAME
|
|
|
|
=item property ( NAME )
|
|
|
|
Returns the property value associated with C<NAME>.
|
|
|
|
=item property ( NAME => VALUE, NAME => VALUE, ... )
|
|
|
|
Sets the named properties to their associated values.
|
|
|
|
=item service ( )
|
|
|
|
Returns the service argument that was passed to *_new-methods.
|
|
|
|
=item host ( )
|
|
|
|
Returns the host argument that was passed to *_new-methods.
|
|
|
|
=item mechanism ( )
|
|
|
|
Returns the name of the chosen mechanism.
|
|
|
|
=item is_success ( )
|
|
|
|
Once need_step() returns false, then you can check if the authentication
|
|
succeeded by calling this method which returns a boolean value.
|
|
|
|
=back
|
|
|
|
=head2 Callbacks
|
|
|
|
There are three different ways in which a callback may be passed
|
|
|
|
=over
|
|
|
|
=item CODEREF
|
|
|
|
If the value passed is a code reference then, when needed, it will be called
|
|
and the connection object will be passed as the first argument. In addition
|
|
some callbacks may be passed additional arguments.
|
|
|
|
=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 connection object passed as the first argument
|
|
and all other values from the array passed after.
|
|
|
|
=item SCALAR
|
|
|
|
All other values passed will be used directly. ie it is the same as
|
|
passing an code reference that, when called, returns the value.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<Authen::SASL::Perl>, L<Authen::SASL::XS>, L<Authen::SASL::Cyrus>
|
|
|
|
=head1 AUTHOR
|
|
|
|
Graham Barr <gbarr@pobox.com>
|
|
|
|
Please report any bugs, or post any suggestions, to the perl-ldap mailing list
|
|
<perl-ldap@perl.org>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (c) 1998-2005 Graham Barr. All rights reserved. This program is
|
|
free software; you can redistribute it and/or modify it under the same
|
|
terms as Perl itself.
|
|
|
|
=cut
|