view release on metacpan or  search on metacpan

Cyrus.pod  view on Meta::CPAN

=head1 NAME

Authen::SASL::Cyrus - XS SASL Authentication

=head1 SYNOPSIS

 use Authen::SASL;

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


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


=head1 DESCRIPTION

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

The XS framework makes calls into the existing libsasl2.so shared 
library to perform SASL client connection functionality, including
loading existing shared library mechanisms.


=head2 CONSTRUCTOR

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

=item client_new( SERVICE, HOST )

Creates and returns a new connection object blessed into Authen::SASL::Cyrus.
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.

=head2 Authen::SASL::Cyrus METHODS

=over 4

=item callback ( NAME )

Tells if the named callback has a handler installed. The list of implemented
callbacks is "user", "auth", and "language". Others may be implemented in
future releases.

=item callback( NAME => VALUE,  NAME => VALUE, ... )

Sets the given callback(s) to the given value(s). See the C<Callbacks> section
for a description of callback VALUEs. See above for a list of implemented
callback NAMEs.

=item client_start

The initial step to be performed. Returns the initial value to pass to the server.

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

=item code

Returns a 1 if an error has occurred in any step along the way. See the
C<error> method to get a better explanation of what error occurred. 
Returns a 0 if no errors have occurred.

=item error

Returns a string with a brief description of what caused the last error,
AND clears the error message so that subsequent calls will return an empty
string until another error occurs.

=item host

Returns the host argument that was passed to C<client_new>
=item mechanism

Returns the SASL mechanism currently in use. It should match one of the 
installed SASL shared library mechanisms (see your SASL distribution for
a list of available mechanisms).

=item property( NAME )

Gets the SASL value for the named property. Currently implemented property
names are: "user", "ssf", "maxout", "realm", "optctx", "iplocal" | "sockname", 
"ipremote" | "peername". 

=item property( NAME => VALUE, NAME => VALUE, ... )

Sets the named property(ies) to the given value(s). Currently implemented 
property names are given above.

=item service

Returns the service argument that was passed to C<client_new>

=back

=head2 Callbacks

There are three different ways in which a callback may be passed

=over