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