1 2=head1 NAME 3 4Authen::SASL::Cyrus - XS SASL Authentication 5 6=head1 SYNOPSIS 7 8 use Authen::SASL; 9 10 $sasl = Authen::SASL->new( 11 mechanism => 'NAME', 12 callback => { NAME => VALUE, NAME => VALUE, ... }, 13 ); 14 15 16 $conn = $sasl->client_new(<service>, <server>); 17 18 19=head1 DESCRIPTION 20 21SASL is a generic mechanism for authentication used by several 22network protocols. B<Authen::SASL::Cyrus> provides an implementation 23framework that all protocols should be able to share. 24 25The XS framework makes calls into the existing libsasl2.so shared 26library to perform SASL client connection functionality, including 27loading existing shared library mechanisms. 28 29 30=head2 CONSTRUCTOR 31 32The contructor may be called with or without arguments. Passing arguments is 33just a short cut to calling the C<mechanism> and C<callback> methods. 34 35=item client_new( SERVICE, HOST ) 36 37Creates and returns a new connection object blessed into Authen::SASL::Cyrus. 38It is on that returned reference that the following methods are available. 39The SERVICE is the name of the service being implemented, which may be used 40by the underlying mechanism. An example service is "ldap". The HOST is the 41name of the server being contacted, which may also be used by the underlying 42mechanism. 43 44=head2 Authen::SASL::Cyrus METHODS 45 46=over 4 47 48=item callback ( NAME ) 49 50Tells if the named callback has a handler installed. The list of implemented 51callbacks is "user", "auth", and "language". Others may be implemented in 52future releases. 53 54=item callback( NAME => VALUE, NAME => VALUE, ... ) 55 56Sets the given callback(s) to the given value(s). See the C<Callbacks> section 57for a description of callback VALUEs. See above for a list of implemented 58callback NAMEs. 59 60=item client_start 61 62The initial step to be performed. Returns the initial value to pass to the server. 63 64=item client_step( CHALLENGE ) 65 66This method is called when a response from the server requires it. CHALLENGE 67is the value from the server. Returns the next value to pass to the server. 68 69=item code 70 71Returns a 1 if an error has occurred in any step along the way. See the 72C<error> method to get a better explanation of what error occurred. 73Returns a 0 if no errors have occurred. 74 75=item error 76 77Returns a string with a brief description of what caused the last error, 78AND clears the error message so that subsequent calls will return an empty 79string until another error occurs. 80 81=item host 82 83Returns the host argument that was passed to C<client_new> 84=item mechanism 85 86Returns the SASL mechanism currently in use. It should match one of the 87installed SASL shared library mechanisms (see your SASL distribution for 88a list of available mechanisms). 89 90=item property( NAME ) 91 92Gets the SASL value for the named property. Currently implemented property 93names are: "user", "ssf", "maxout", "realm", "optctx", "iplocal" | "sockname", 94"ipremote" | "peername". 95 96=item property( NAME => VALUE, NAME => VALUE, ... ) 97 98Sets the named property(ies) to the given value(s). Currently implemented 99property names are given above. 100 101=item service 102 103Returns the service argument that was passed to C<client_new> 104 105=back 106 107=head2 Callbacks 108 109There are three different ways in which a callback may be passed 110 111=over 112 113=item CODEREF 114 115If the value passed is a code reference then, when needed, it will be called 116and the connection object will be passed as the first argument. 117 118=item ARRAYREF 119 120If the value passed is an array reference, the first element in the array 121must be a code reference. When the callback is called the code reference 122will be called with the connection object passed as the first argument 123and the second value from the array passed after. The code reference 124should return a scalar value which is the answer to the callback, e.g. 125a "user" callback should return a single string which is the username of 126the client. 127 128=item SCALAR 129 130All other values passed will be returned directly to the SASL library 131as the answer to the callback. 132 133=back 134 135=head1 SEE ALSO 136 137L<Authen::SASL> 138 139=head1 AUTHOR 140 141Mark Adamson <mark@nb.net> 142 143Please report any bugs, or post any suggestions, to the author. 144 145=head1 COPYRIGHT 146 147Copyright (c) 2005 Carnegie Mellon University. All rights reserved. This 148program is free software; you can redistribute it and/or modify it under 149the same terms as Perl itself. 150 151=cut 152