.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "DJabberd::SASL 3"
.TH DJabberd::SASL 3 2023-07-25 "perl v5.38.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
DJabberd::SASL \- Base plugin for SASL Negotiation
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This base plugin just provides the skeleton necessary for building SASL layers
within DJabberd. It provides one hook (GetSASLManager) to initiate the SASL
negotiation and return a SASL Manager object; and it hooks the SASL stanzas
to the default DJabberd::Stanza::SASL class.
.PP
See DJabberd::SASL::AuthenSASL for a concrete plugin based on
\&\fIDJabberd::SASL\fR.
.SH "HOW DOES THE DEFAULT SASL INFRASTRUCTURE WORK"
.IX Header "HOW DOES THE DEFAULT SASL INFRASTRUCTURE WORK"
When a \fIDJabberd::SASL\fR subclass is declared inside of a \fBVHost\fR, it enables
SASL negotiation for the connection.
.PP
What does that mean is that SASL will be advertised in the stream features.
Then, when the client sends a SASL stanza (see RFC 3920), they are handled
using DJabberd::Stanza::SASL class, which makes a few assumption:
.IP \(bu 4
The plugin supports the \fIGetSASLManager\fR hook that returns a 
DJabberd::SASL::ManagerBase subclass.
.IP \(bu 4
The interface to this manager and to the sasl connection
object (see later) is a superset of Authen::SASL interface.
.PP
From there, the SASL negotiation is in the hands of the configured SASL Manager.
.PP
One configuration option is common to all plugins: This is \f(CW\*(C`Optional\*(C'\fR which 
advertises to the client if SASL is optional or not. By default SASL is (and
should be) required.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 6
\&    <VHost yann.cyberion.net>
\&        <Plugin DJabberd::SASL::%Subclass%>
\&            Optional   yes
\&            %Config%
\&        </Plugin>
\&    </VHost>
.Ve
.SH "EXTENDING SASL IN DJABBERD"
.IX Header "EXTENDING SASL IN DJABBERD"
See examples.
.PP
It's fairly easy to extend the SASL phase with anything you like provided the
simple DJabberd::SASL::ManagerBase and DJabberd::SASL::Connection which
are based on Authen::SASL are repected.
.PP
Alternatively since this is just a plugin, you can also throw it away
altogether and write something from scratch. You'll have to provide a new set
of handlers for the SASL stanzas though (in replacement of
DJabberd::Stanzas::SASL.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
(c) 2009 Yann Kerherve
.PP
This module is part of the DJabberd distribution and is covered by the
distribution's overall licence.