[otrs-cvs] otrs/Kernel/cpan-lib/Authen SASL.pm, 1.6, 1.7 SASL.pod, 1.6, 1.7

Comments:
Update of /home/cvs/otrs/Kernel/cpan-lib/Authen
In directory lancelot:/tmp/cvs-serv3537/Authen

Modified Files:
	SASL.pm SASL.pod 
Log Message:
Updated CPAN module Authen::SASL to version 2.16.

Author: mh

Index: SASL.pm
===================================================================
RCS file: /home/cvs/otrs/Kernel/cpan-lib/Authen/SASL.pm,v
retrieving revision 1.6
retrieving revision 1.7
diff -2 -u -d -r1.6 -r1.7
--- SASL.pm	22 Jun 2010 09:42:53 -0000	1.6
+++ SASL.pm	15 Jan 2013 12:29:01 -0000	1.7
@@ -9,5 +9,5 @@
 use Carp;
 
-$VERSION = "2.15";
+$VERSION = "2.16";
 
 @Plugins = qw(

Author: mh

Index: SASL.pod
===================================================================
RCS file: /home/cvs/otrs/Kernel/cpan-lib/Authen/SASL.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -2 -u -d -r1.6 -r1.7
--- SASL.pod	30 Oct 2012 13:08:03 -0000	1.6
+++ SASL.pod	15 Jan 2013 12:29:01 -0000	1.7
@@ -1,130 +1,241 @@
-# Copyright (c) 2004-2006 Graham Barr <[email protected]>. All rights reserved.
-# This program is free software; you can redistribute it and/or
-# modify it under the same terms as Perl itself.
 
-package Authen::SASL;
+=head1 NAME
 
-use strict;
-use vars qw($VERSION @Plugins);
-use Carp;
+Authen::SASL - SASL Authentication framework
 
-$VERSION = "2.16";
+=head1 SYNOPSIS
 
-@Plugins = qw(
-	Authen::SASL::XS
-	Authen::SASL::Cyrus
-	Authen::SASL::Perl
-);
+ use Authen::SASL;
 
+ $sasl = Authen::SASL->new(
+   mechanism => 'CRAM-MD5 PLAIN ANONYMOUS',
+   callback => {
+     pass => \&fetch_password,
+     user => $user,
+   }
+ );
 
-sub import {
-  shift;
-  return unless @_;
+=head1 DESCRIPTION
 
-  local $SIG{__DIE__};
-  @Plugins = grep { /^[:\w]+$/ and eval "require $_" } map { /::/ ? $_ : "Authen::SASL::$_" } @_
-    or croak "no valid Authen::SASL plugins found";
-}
+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.
 
-sub new {
-  my $pkg = shift;
-  my %opt = ((@_ % 2 ? 'mechanism' : ()), @_);
+=over 4
 
-  my $self = bless {
-    mechanism => $opt{mechanism} || $opt{mech},
-    callback  => {},
-    debug => $opt{debug},
-  }, $pkg;
+=item Authen::SASL::Perl
 
-  $self->callback(%{$opt{callback}}) if ref($opt{callback}) eq 'HASH';
+This module implements several mechanisms and is implemented
+entirely in Perl.
 
-  # Compat
-  $self->callback(user => ($self->{user} = $opt{user})) if exists $opt{user};
-  $self->callback(pass => $opt{password}) if exists $opt{password};
-  $self->callback(pass => $opt{response}) if exists $opt{response};
+=item Authen::SASL::XS
 
-  $self;
-}
+This module uses the Cyrus SASL C-library (both version 1 and 2 
+are supported).
 
+=item Authen::SASL::Cyrus
 
-sub mechanism {
-  my $self = shift;
-  @_ ? $self->{mechanism} = shift
-     : $self->{mechanism};
-}
+This module is the predecessor to L<Authen::SASL::XS>. It is reccomended
+to use L<Authen::SASL::XS>
 
-sub callback {
-  my $self = shift;
+=back
 
-  return $self->{callback}{$_[0]} if @_ == 1;
+By default the order in which these plugins are selected is 
+Authen::SASL::XS, Authen::SASL::Cyrus and then Authen::SASL::Perl.
 
-  my %new = @_;
-  @{$self->{callback}}{keys %new} = values %new;
+If you want to change it or want to specifically use one
+implementation only simply do
 
-  $self->{callback};
-}
+ use Authen::SASL qw(Perl);
 
-# The list of packages should not really be hardcoded here
-# We need some way to discover what plugins are installed
+or if you have another plugin module that supports the Authen::SASL API
 
-sub client_new { # $self, $service, $host, $secflags
-  my $self = shift;
+ use Authen::SASL qw(My::SASL::Plugin);
 
-  my $err;
-  foreach my $pkg (@Plugins) {
-    if (eval "require $pkg" and $pkg->can("client_new")) {
-      if ($self->{conn} = eval { $pkg->client_new($self, @_) }) {
-        return $self->{conn};
-      }
-      $err = $@;
-    }
-  }
+=head2 CONTRUCTOR
 
-  croak $err || "Cannot find a SASL Connection library";
-}
+=over 4
 
-sub server_new { # $self, $service, $host, $secflags
-  my $self = shift;
+=item new ( OPTIONS )
 
-  my $err;
-  foreach my $pkg (@Plugins) {
-    if (eval "require $pkg" and $pkg->can("server_new")) {
-      if ($self->{conn} = eval { $pkg->server_new($self, @_) } ) {
-        return $self->{conn};
-      }
-      $err = $@;
-    }
-  }
-  croak $err || "Cannot find a SASL Connection library for server-side authentication";
-}
+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.
 
-sub error {
-  my $self = shift;
-  $self->{conn} && $self->{conn}->error;
-}
+=over 4
 
-# Compat.
-sub user {
-  my $self = shift;
-  my $user = $self->{callback}{user};
-  $self->{callback}{user} = shift if @_;
-  $user;
-}
+=item callback =E<gt> { NAME => VALUE, NAME => VALUE, ... }
 
-sub challenge {
-  my $self = shift;
-  $self->{conn}->client_step(@_);
-}
+Set the callbacks.
+See the L<callback|/callback> method for details.
 
-sub initial {
-  my $self = shift;
-  $self->client_new($self)->client_start;
-}
+=item mechanism =E<gt> NAMES
 
-sub name {
-  my $self = shift;
-  $self->{conn} ? $self->{conn}->mechanism : ($self->{mechanism} =~ /(\S+)/)[0];
-}
+=item mech =E<gt> NAMES
 
-1;
+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 <[email protected]>
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[email protected]>
+
+=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
---------------------------------------------------------------------
OTRS mailing list: cvs-log - Webpage: http://otrs.org/
Archive: http://lists.otrs.org/pipermail/cvs-log
To unsubscribe: http://lists.otrs.org/cgi-bin/listinfo/cvs-log