.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Cyrus 3pm"
.TH Cyrus 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::SASL::Cyrus	\- XS code to glue Perl SASL to Cyrus SASL
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Authen::SASL;
\&
\&  my $sasl = Authen::SASL\->new(
\&         mechanism => \*(AqNAME\*(Aq,
\&         callback => { NAME => VALUE, NAME => VALUE, ... },
\&  );
\&
\&  my $conn = $sasl\->client_new(<service>, <server>, <iplocalport>, <ipremoteport>);
\&
\&  my $conn = $sasl\->server_new(<service>, <host>, <iplocalport>, <ipremoteport>);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1SASL\s0 is a generic mechanism for authentication used by several
network protocols. \fBAuthen::SASL::Cyrus\fR provides an implementation
framework that all protocols should be able to share.
.PP
The \s-1XS\s0 framework makes calls into the existing libsasl.so resp. libsasl2
shared library to perform \s-1SASL\s0 client connection functionality, including
loading existing shared library mechanisms.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
The constructor may be called with or without arguments. Passing arguments is
just a short cut to calling the \f(CW\*(C`mechanism\*(C'\fR and \f(CW\*(C`callback\*(C'\fR methods.
.PP
You have to use the \f(CW\*(C`Authen::SASL\*(C'\fR new-constructor to create a \s-1SASL\s0 object.
The \f(CW\*(C`Authen::SASL\*(C'\fR object then holds all necessary variables and callbacks, which
you gave when creating the object.
\&\f(CW\*(C`client_new\*(C'\fR and \f(CW\*(C`server_new\*(C'\fR will retrieve needed information from this
object.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
Callbacks are very important. It depends on the mechanism which callbacks
have to be set. It is not a failure to set callbacks even they aren't used.
(e.g. password-callback when using \s-1GSSAPI\s0 or \s-1KERBEROS_V4\s0)
.PP
The Cyrus-SASL library uses callbacks when the application
needs some information. Common reasons are getting
usernames and passwords.
.PP
Authen::SASL::Cyrus allows Cyrus-SASL to use perl-variables and perl-subs
as callback-targets.
.PP
Currently Authen::SASL::Cyrus supports the following Callback types:
(for a more detailed description on what the callback type is used for
see the respective man pages)
.PP
\&\fBRemark\fR: All callbacks, which have to return some values (e.g.: **result in
\&\f(CW\*(C`sasl_getsimple_t\*(C'\fR) do this by returning the value(s). See example below.
.IP "user (client)" 4
.IX Item "user (client)"
.PD 0
.IP "auth (client)" 4
.IX Item "auth (client)"
.IP "language (client)" 4
.IX Item "language (client)"
.PD
This callbacks represent the \f(CW\*(C`sasl_getsimple_t\*(C'\fR from the library.
.Sp
Input: none
.Sp
Output: \f(CW\*(C`username\*(C'\fR, \f(CW\*(C`authname\*(C'\fR or \f(CW\*(C`language\*(C'\fR
.IP "password (client)" 4
.IX Item "password (client)"
.PD 0
.IP "pass (client)" 4
.IX Item "pass (client)"
.PD
This callbacks represent the \f(CW\*(C`sasl_getsecret_t\*(C'\fR from the library.
.Sp
Input: none
.Sp
Output: \f(CW\*(C`password\*(C'\fR
.IP "realm <client>" 4
.IX Item "realm <client>"
This callback represents the \f(CW\*(C`sasl_getrealm_t\*(C'\fR from the library.
.Sp
Input: a list of available realms
.Sp
Output: the chosen realm
.Sp
(This has nothing to do with \s-1GSSAPI\s0 or \s-1KERBEROS_V4\s0 realm).
.IP "checkpass (server, \s-1SASL\s0 v2 only)" 4
.IX Item "checkpass (server, SASL v2 only)"
This callback represents the \f(CW\*(C`sasl_server_userdb_checkpass_t\*(C'\fR from the
library.
.Sp
Input: \f(CW\*(C`username\*(C'\fR, \f(CW\*(C`password\*(C'\fR
.Sp
Output: true or false
.IP "getsecret (server, \s-1SASL\s0 v1 only)" 4
.IX Item "getsecret (server, SASL v1 only)"
This callback represents the \f(CW\*(C`sasl_server_getsecret_t\*(C'\fR from the library. Sasl
will check if the passwords are matching.
.Sp
Input: \f(CW\*(C`mechanism\*(C'\fR, \f(CW\*(C`username\*(C'\fR, \f(CW\*(C`default_realm\*(C'\fR
.Sp
Output: \f(CW\*(C`secret_phrase (password)\*(C'\fR
.Sp
\&\fBRemark\fR: Programmers that are using should specify both callbacks (getsecret and checkpass).
Then, depending on you Cyrus \s-1SASL\s0 library either the one or the other is called. Cyrus \s-1SASL\s0 v1
ignores checkpass and Cyrus \s-1SASL\s0 v2 ignores getsecret.
.IP "putsecret (\s-1SASL\s0 v1) and setpass (\s-1SASL\s0 v2)" 4
.IX Item "putsecret (SASL v1) and setpass (SASL v2)"
are currently not supported (and won't be, unless someone needs it).
.IP "canonuser (server/client in \s-1SASL\s0 v2, server only in \s-1SASL\s0 v1)" 4
.IX Item "canonuser (server/client in SASL v2, server only in SASL v1)"
This callback name represents the \f(CW\*(C`sasl_canon_user_t\*(C'\fR from the library.
.Sp
Input: \f(CW\*(C`Type of principal\*(C'\fR, \f(CW\*(C`principal\*(C'\fR, \f(CW\*(C`userrealm\*(C'\fR and maximal allowed length of the output.
.Sp
Output: canonicalised \f(CW\*(C`principal\*(C'\fR
.Sp
\&\f(CW\*(C`Type of principal\*(C'\fR is \*(L"\s-1AUTHID\*(R"\s0 for Authentication \s-1ID\s0 or \*(L"\s-1AUTHZID\*(R"\s0
for Authorisation \s-1ID.\s0
.Sp
\&\fBRemark\fR: This callback is ideal to get the username of the user using your service.
If \f(CW\*(C`Authen::SASL::Cyrus\*(C'\fR is linked to Cyrus \s-1SASL\s0 v1, which doesn't have a canonuser callback,
it will simulate this callback by using the authorize callback internally. Don't worry, the
authorize callback is available anyway.
.IP "authorize (server)" 4
.IX Item "authorize (server)"
This callback represents the \f(CW\*(C`sasl_authorize_t\*(C'\fR from the library.
.Sp
Input: \f(CW\*(C`authenticated_username\*(C'\fR, \f(CW\*(C`requested_username\*(C'\fR, (\f(CW\*(C`default_realm\*(C'\fR \s-1SASL\s0 v2 only)
.Sp
Output: \f(CW\*(C`canonicalised_username\*(C'\fR \s-1SASL\s0 v1 resp. true or false when using \s-1SASL\s0 v2 lib
There is something \s-1TODO, I\s0 think.
.IP "setpass (server, \s-1SASL\s0 v2 only)" 4
.IX Item "setpass (server, SASL v2 only)"
This callback represents the \f(CW\*(C`sasl_server_userdb_setpass_t\*(C'\fR from the library.
.Sp
Input: \f(CW\*(C`username\*(C'\fR, \f(CW\*(C`new_password\*(C'\fR, \f(CW\*(C`flags\*(C'\fR (0x01 \s-1CREATE,\s0 0x02 \s-1DISABLE,\s0
0x04 \s-1NOPLAIN\s0)
.Sp
Out: true or false
.SS "Ways to pass a callback"
.IX Subsection "Ways to pass a callback"
Authen::SASL::Cyrus supports three different ways to pass a callback
.IP "\s-1CODEREF\s0" 4
.IX Item "CODEREF"
If the value passed is a code reference then, when needed, it will be called.
.IP "\s-1ARRAYREF\s0" 4
.IX 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 value from the array passed after.
.IP "\s-1SCALAR\s0 All other values passed will be returned directly to the \s-1SASL\s0 library as the answer to the callback." 4
.IX Item "SCALAR All other values passed will be returned directly to the SASL library as the answer to the callback."
.SS "Example of setting callbacks"
.IX Subsection "Example of setting callbacks"
\&\f(CW$sasl\fR = new Authen::SASL (
  mechanism => \*(L"\s-1PLAIN\*(R",\s0
    callback => {
      # Scalar
      user => \*(L"mannfred\*(R",
      pass => \f(CW$password\fR,
      language => 1,
.PP
.Vb 3
\&      # Coderef
\&      auth => sub { return "klaus", }
\&      realm => \e&getrealm,
\&
\&      # Arrayref
\&      canonuser => [ \e&canon, $self ],
\&   }
\&);
.Ve
.PP
The last example is ideal for using object methods as callback functions.
Then you can do something like this:
.PP
sub canon
{
  my ($this,$type,$realm,$maxlen,$user) = \f(CW@_\fR;
  \f(CW$this\fR\->{_username} = \f(CW$user\fR if ($type eq \*(L"\s-1AUTHID\*(R"\s0);
  return \f(CW$user\fR;
}
.SH "Authen::SASL::Cyrus METHODS"
.IX Header "Authen::SASL::Cyrus METHODS"
.ie n .IP "server_new ( \s-1SERVICE , HOST\s0 = """" , \s-1IPLOCALPORT , IPREMOTEPORT\s0 )" 4
.el .IP "server_new ( \s-1SERVICE , HOST\s0 = ``'' , \s-1IPLOCALPORT , IPREMOTEPORT\s0 )" 4
.IX Item "server_new ( SERVICE , HOST = """" , IPLOCALPORT , IPREMOTEPORT )"
Constructor for creating server-side sasl contexts.
.Sp
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 \s-1SERVICE\s0 is the name of the service being implemented, which may be used
by the underlying mechanism. An example service therefore is \*(L"ldap\*(R".
.IP "client_new ( \s-1SERVICE , HOST , IPLOCALPORT , IPREMOTEPORT\s0 )" 4
.IX Item "client_new ( SERVICE , HOST , IPLOCALPORT , IPREMOTEPORT )"
Constructor for creating server-side sasl contexts.
.Sp
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 \s-1SERVICE\s0 is the name of the service being implemented, which may be used
by the underlying mechanism. An example service is \*(L"ldap\*(R". The \s-1HOST\s0 is the
name of the server being contacted, which may also be used
by the underlying mechanism.
.Sp
See \s-1SYNOPSIS\s0 for an example.
.PP
\&\fBRemark\fR:
This and the \f(CW\*(C`server_new\*(C'\fR function are called by Authen::SASL when using
its \f(CW*_new\fR function. Since the user has to use Authen::SASL anyway, normally
it is not necessary to call this function directly.
.PP
\&\s-1IPLOCALPORT\s0 and \s-1IPREMOTEPORT\s0 arguments are only available, when \s-1ASC\s0 is
linked against Cyrus \s-1SASL 2\s0.x. This arguments are needed for \s-1KERBEROS_V4\s0
and \s-1CS 2\s0.x on the server side. Don't know if it necessary for the client
side. Format of this arguments in an IPv4 environment should be: a.b.c.d;port.
See \fBsasl_server_new\fR\|(3) for details.
.IP "server_start ( \s-1CHALLENGE\s0 )" 4
.IX Item "server_start ( CHALLENGE )"
\&\f(CW\*(C`server_start\*(C'\fR begins the authentication using the chosen mechanism.
If the mechanism is not supported by the installed Cyrus-SASL it fails.
Because for some mechanisms the client has to start the negotiation,
you can give the client challenge as a parameter.
.IP "client_start ( )" 4
.IX Item "client_start ( )"
The initial step to be performed. Returns the initial value to pass to the server.
Client has to start the negotiation always.
.IP "server_step ( \s-1CHALLENGE\s0 )" 4
.IX Item "server_step ( CHALLENGE )"
\&\f(CW\*(C`server_step\*(C'\fR performs the next step in the negotiation process. The
first parameter you give is the clients challenge/response.
.IP "client_step ( \s-1CHALLENGE\s0 )" 4
.IX Item "client_step ( CHALLENGE )"
.PP
\&\fBRemark\fR:
\&\f(CW\*(C`client_start\*(C'\fR, \f(CW\*(C`client_step\*(C'\fR, \f(CW\*(C`server_start\*(C'\fR and \f(CW\*(C`server_step\*(C'\fR
will return the respective sasl response or undef. The returned value
says nothing about the current negotiation status. It is absolutely possible
that one of these functions return undef and everything is fine for \s-1SASL,\s0
there is only another step needed.
.PP
Therefore you have to check \f(CW\*(C`need_step\*(C'\fR and \f(CW\*(C`code\*(C'\fR during negotiation.
.PP
See example below.
.IP "listmech( \s-1START , SEPARATOR , END\s0 )" 4
.IX Item "listmech( START , SEPARATOR , END )"
\&\f(CW\*(C`listmech\*(C'\fR returns a string containing all mechanisms allowed for the user
set by \f(CW\*(C`user\*(C'\fR. \s-1START\s0 is the token which will be put at the beginning of the
string, \s-1SEPARATOR\s0 is the token which will be used to separate the mechanisms
and \s-1END\s0 is the token which will be put at the end of returned string.
.IP "setpass(user, newpassword, oldpassword, flags)" 4
.IX Item "setpass(user, newpassword, oldpassword, flags)"
.PD 0
.IP "checkpass(user, password)" 4
.IX Item "checkpass(user, password)"
.PD
\&\f(CW\*(C`setpass\*(C'\fR and \f(CW\*(C`checkpass\*(C'\fR is only available when using Cyrus-SASL 2.x library.
.Sp
\&\f(CW\*(C`setpass\*(C'\fR sets a new password (depends on the mechanism if the setpass callback
is called). \f(CW\*(C`checkpass\*(C'\fR checks a password for the user (calls the checkpass
callback).
.Sp
For both function see the man pages of the Cyrus \s-1SASL\s0 for a detailed description.
.Sp
Both functions return true on success, false otherwise.
.IP "global_listmech ( )" 4
.IX Item "global_listmech ( )"
\&\f(CW\*(C`global_listmech\*(C'\fR is only available when using Cyrus-SASL 2.x library.
.Sp
It returns an array with all mechanisms loaded by the library.
.IP "encode ( \s-1STRING\s0 )" 4
.IX Item "encode ( STRING )"
.PD 0
.IP "decode ( \s-1STRING\s0 )" 4
.IX Item "decode ( STRING )"
.PD
Cyrus-SASL developers suggest using the \f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR functions
for every traffic which will run over the network after a successful authentication
.Sp
\&\f(CW\*(C`encode\*(C'\fR returns the encrypted string generated from \s-1STRING.\s0
\&\f(CW\*(C`decode\*(C'\fR returns the decrypted string generated from \s-1STRING.\s0
.Sp
It depends on the used mechanism how secure the encryption will be.
.IP "error ( )" 4
.IX Item "error ( )"
\&\f(CW\*(C`error\*(C'\fR returns an array with all known error messages.
Basicly the sasl_errstring function is called with the current error_code.
When using Cyrus-SASL 2.x library also the string returned by sasl_errdetail
is given back. Additionally the special Authen::SASL::Cyrus advise is
returned if set.
After calling the \f(CW\*(C`error\*(C'\fR function, the error code and the special advice
are thrown away.
.IP "code ( )" 4
.IX Item "code ( )"
\&\f(CW\*(C`code\*(C'\fR returns the current Cyrus-SASL error code.
.IP "mechanism ( )" 4
.IX Item "mechanism ( )"
\&\f(CW\*(C`mechanism\*(C'\fR returns the current used authentication mechanism.
.IP "need_step ( )" 4
.IX Item "need_step ( )"
\&\f(CW\*(C`need_step\*(C'\fR returns true if another step is need by the \s-1SASL\s0 library. Otherwise
false is returned. You can also use \f(CW\*(C`code == 1\*(C'\fR but it looks smarter I think.
That's why we all using perl, eh?
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.SS "Server-side"
.IX Subsection "Server-side"
.Vb 4
\& # The example uses Cyrus\-SASL v2
\& # Set the SASL_PATH to the location of the SASL\-Plugins
\& # default is /usr/lib/sasl2
\& $ENV{\*(AqSASL_PATH\*(Aq} = "/opt/products/sasl/2.1.15/lib/sasl2";
\&
\& #
\& my $sasl = Authen::SASL\->new (
\&    mechanism => "PLAIN",
\&    callback => {
\&      checkpass => \e&checkpass,
\&      canonuser => \e&canonuser,
\&    }
\& );
\&
\& # Creating the Authen::SASL::Cyrus object
\& my $conn = $sasl\->server_new("service","","ip;port local","ip;port remote");
\&
\& # Clients first string (maybe "", depends on mechanism)
\& # Client has to start always
\& sendreply( $conn\->server_start( &getreply() ) );
\&
\& while ($conn\->need_step) {
\&    sendreply( $conn\->server_step( &getreply() ) );
\& }
\&
\& if ($conn\->code == 0) {
\&    print "Negotiation succeeded.\en";
\& } else {
\&    print "Negotiation failed.\en";
\& }
.Ve
.SS "Client-side"
.IX Subsection "Client-side"
.Vb 4
\& # The example uses Cyrus\-SASL v2
\& # Set the SASL_PATH to the location of the SASL\-Plugins
\& # default is /usr/lib/sasl2
\& $ENV{\*(AqSASL_PATH\*(Aq} = "/opt/products/sasl/2.1.15/lib/sasl2";
\&
\& #
\& my $sasl = Authen::SASL\->new (
\&    mechanism => "PLAIN",
\&    callback => {
\&      user => \e&getusername,
\&      pass => \e&getpassword,
\&    }
\& );
\&
\& # Creating the Authen::SASL::Cyrus object
\& my $conn = $sasl\->client_new("service", "hostname.domain.tld");
\&
\& # Client begins always
\& sendreply($conn\->client_start());
\&
\& while ($conn\->need_step) {
\&    sendreply($conn\->client_step( &getreply() ) );
\& }
\&
\& if ($conn\->code == 0) {
\&    print STDERR "Negotiation succeeded.\en";
\& } else {
\&    print STDERR "Negotiation failed.\en";
\& }
.Ve
.PP
See t/plain.t for working script.
.SH "TESTING"
.IX Header "TESTING"
I tested \s-1ASC\s0 (server and client) with the following mechanisms:
.IP "\s-1GSSAPI\s0" 4
.IX Item "GSSAPI"
Don't forget to create keytab. Non-root keytabs can be specify through \f(CW$ENV\fR{'\s-1KRB5_KTNAME\s0'} (Heimdal >= 0.6, \s-1MIT\s0).
.IP "\s-1KERBEROS_V4\s0" 4
.IX Item "KERBEROS_V4"
Available since 0.10, you have to add \s-1IPLOCALPORT\s0 and \s-1IPREMOTEPORT\s0 to *_new functions.
.IP "\s-1PLAIN\s0" 4
.IX Item "PLAIN"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Authen::SASL
.PP
man pages for sasl_* library functions.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Mark Adamson <mark@nb.net>
.PP
Cyrus-SASL 2.x support by Leif Johansson
.PP
Glue for server_* and many other structural improvements by Patrick Boettcher <patrick.boettcher@desy.de>
.PP
Please report any bugs, or post any suggestions, to the authors.
.SH "THANKS"
.IX Header "THANKS"
.Vb 3
\& \- Guillaume Filion for testing the server part and for giving hints about
\&   some bugs (documentation).
\& \- Wolfgang Friebel for bother around with rpm building of test releases.
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003\-5 Patrick Boettcher, \s-1DESY\s0 Zeuthen. All rights reserved.
Copyright (c) 2003 Carnegie Mellon University. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.