Initial Commit

database/perl/vendor/lib/Authen/SASL.pod

@@ -0,0 +1,241 @@
+
+=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