1Authen::SASL(3) User Contributed Perl Documentation Authen::SASL(3)
2
6 Authen::SASL - SASL Authentication framework
7
9 version 2.1700
10
12 use Authen::SASL;
13 $sasl = Authen::SASL->new(
15 mechanism => 'CRAM-MD5 PLAIN ANONYMOUS',
16 callback => {
17 pass => \&fetch_password,
18 user => $user,
19 }
20 );
21
23 SASL is a generic mechanism for authentication used by several network
24 protocols. Authen::SASL provides an implementation framework that all
25 protocols should be able to share.
26 The framework allows different implementations of the connection class
28 to be plugged in. At the time of writing there were two such plugins.
29 Authen::SASL::Perl
31 This module implements several mechanisms and is implemented
32 entirely in Perl.
33 Authen::SASL::XS
35 This module uses the Cyrus SASL C-library (both version 1 and 2 are
36 supported).
37 Authen::SASL::Cyrus
39 This module is the predecessor to Authen::SASL::XS.
40 Until version 2.16, Authen::SASL::Cyrus was loaded as an
42 alternative to Authen::SASL::XS.
43 By default Authen::SASL tries to load Authen::SASL::XS first, followed
45 by Authen::SASL::Perl on failure. If you want to change the order or
46 want to specifically use one implementation only simply do
47 use Authen::SASL qw(Perl);
49 or if you have another plugin module that supports the Authen::SASL API
51 use Authen::SASL qw(My::SASL::Plugin);
53 CONTRUCTOR
55 new ( OPTIONS )
56 The constructor may be called with or without arguments. Passing
57 arguments is just a short cut to calling the "mechanism" and
58 "callback" methods.
59 callback => { NAME => VALUE, NAME => VALUE, ... }
61 Set the callbacks. See the callback method for details.
62 mechanism => NAMES
64 mech => NAMES
65 Set the list of mechanisms to choose from. See the mechanism
66 method for details.
67 debug => VALUE
69 Set the debug level bit-value to "VALUE"
70 Debug output will be sent to "STDERR". The bits of this value
72 are:
73 1 Show debug messages in the Perl modules for the mechanisms.
75 (Currently only used in GSSAPI)
76 4 With security layers in place show information on packages read.
77 8 With security layers in place show information on packages written.
78 The default value is 0.
80 METHODS
82 mechanism ( )
83 Returns the current list of mechanisms
84 mechanism ( NAMES )
86 Set the list of mechanisms to choose from. "NAMES" should be a
87 space separated string of the names.
88 callback ( NAME )
90 Returns the current callback associated with "NAME".
91 callback ( NAME => VALUE, NAME => VALUE, ... )
93 Sets the given callbacks to the given values
94 client_new ( SERVICE, HOST, SECURITY )
96 Creates and returns a new connection object for a client-side
97 connection.
98 server_new ( SERVICE, HOST, OPTIONS )
100 Creates and returns a new connection object for a server-side
101 connection.
102 error ( )
104 Returns any error from the last connection
105
107 server_start ( CHALLENGE )
108 server_start begins the authentication using the chosen mechanism.
109 If the mechanism is not supported by the installed SASL it fails.
110 Because for some mechanisms the client has to start the
111 negotiation, you can give the client challenge as a parameter.
112 server_step ( CHALLENGE )
114 server_step performs the next step in the negotiation process. The
115 first parameter you give is the clients challenge/response.
116 client_start ( )
118 The initial step to be performed. Returns the initial value to pass
119 to the server or an empty list on error.
120 client_step ( CHALLENGE )
122 This method is called when a response from the server requires it.
123 CHALLENGE is the value from the server. Returns the next value to
124 pass to the server or an empty list on error.
125 need_step ( )
127 Returns true if the selected mechanism requires another step before
128 completion (error or success).
129 answer ( NAME )
131 The method will return the value returned from the last call to the
132 callback NAME
133 property ( NAME )
135 Returns the property value associated with "NAME".
136 property ( NAME => VALUE, NAME => VALUE, ... )
138 Sets the named properties to their associated values.
139 service ( )
141 Returns the service argument that was passed to *_new-methods.
142 host ( )
144 Returns the host argument that was passed to *_new-methods.
145 mechanism ( )
147 Returns the name of the chosen mechanism.
148 is_success ( )
150 Once need_step() returns false, then you can check if the
151 authentication succeeded by calling this method which returns a
152 boolean value.
153 Callbacks
155 There are three different ways in which a callback may be passed
156 CODEREF
158 If the value passed is a code reference then, when needed, it will
159 be called and the connection object will be passed as the first
160 argument. In addition some callbacks may be passed additional
161 arguments.
162 ARRAYREF
164 If the value passed is an array reference, the first element in the
165 array must be a code reference. When the callback is called the
166 code reference will be called with the connection object passed as
167 the first argument and all other values from the array passed
168 after.
169 SCALAR
171 All other values passed will be used directly. ie it is the same as
172 passing an code reference that, when called, returns the value.
173
175 Authen::SASL::Perl, Authen::SASL::XS, Authen::SASL::Cyrus
176
178 Erik Huelsmann <ehuels@gmail.com>
179
181 Graham Barr <gbarr@pobox.com>
182
184 Please report any bugs, or any suggestions, in the GitHub project at
185 <https://github.com/gbarr/perl-authen-sasl/issues>.
186
188 Copyright (c) 2023 Erik Huelsmann
189 Copyright (c) 1998-2005 Graham Barr.
190 All rights reserved. This program is free software; you can
192 redistribute it and/or modify it under the same terms as Perl itself.
193perl v5.38.0 2023-08-21 Authen::SASL(3)