.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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 "Authen::SCRAM::Server 3pm"
.TH Authen::SCRAM::Server 3pm "2022-12-11" "perl v5.36.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::SCRAM::Server \- RFC 5802 SCRAM Server
.SH "VERSION"
.IX Header "VERSION"
version 0.011
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Authen::SCRAM::Server;
\&    use Try::Tiny;
\&
\&    $server = Authen::SCRAM::Server\->new(
\&        credential_cb => \e&get_credentials,
\&    );
\&
\&    $username = try {
\&        # get client\-first\-message
\&
\&        $server_first = $server\->first_msg( $client_first );
\&
\&        # send to client and get client\-final\-message
\&
\&        $server_final = $server\->final_msg( $client_final );
\&
\&        # send to client
\&
\&        return $server\->authorization_id; # returns valid username
\&    }
\&    catch {
\&        die "Authentication failed!"
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the server-side \s-1SCRAM\s0 algorithm.
.SH "NAME"
Authen::SCRAM::Server \- RFC 5802 SCRAM Server
.SH "VERSION"
.IX Header "VERSION"
version 0.011
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "credential_cb (required)"
.IX Subsection "credential_cb (required)"
This attribute must contain a code reference that takes a username (as a
character string normalized by SASLprep) and returns the four user-credential
parameters required by \s-1SCRAM:\s0 \f(CW\*(C`salt\*(C'\fR, \f(CW\*(C`StoredKey\*(C'\fR, \f(CW\*(C`ServerKey\*(C'\fR, and
\&\f(CW\*(C`iteration count\*(C'\fR.  The \f(CW\*(C`salt\*(C'\fR, \f(CW\*(C`StoredKey\*(C'\fR and \f(CW\*(C`ServerKey\*(C'\fR must be
provided as octets (i.e. \fB\s-1NOT\s0\fR base64 encoded).
.PP
If the username is unknown, it should return an empty list.
.PP
.Vb 2
\&    ($salt, $stored_key, $server_key, $iterations) =
\&        $server\->credential_cb\->( $username );
.Ve
.PP
See \s-1RFC 5802: SCRAM\s0 Algorithm Overview <http://tools.ietf.org/html/rfc5802#section-3>
for details.
.SS "auth_proxy_cb"
.IX Subsection "auth_proxy_cb"
If provided, this attribute must contain a code reference that takes an
\&\fBauthentication\fR username and a \fBauthorization\fR username (both as character
strings), and return a true value if the authentication username is permitted
to act as the authorization username:
.PP
.Vb 3
\&    $bool = $server\->auth_proxy_cb\->(
\&        $authentication_user, $authorization_user
\&    );
.Ve
.PP
It will only be all called if the authentication username has successfully
authenticated.  Both usernames will have been normalized via \f(CW\*(C`SASLprep\*(C'\fR with
any transport encoding removed before being passed to this function.
.SS "digest"
.IX Subsection "digest"
Name of a digest function available via PBKDF2::Tiny.  Valid values are
\&\s-1SHA\-1, SHA\-224, SHA\-256, SHA\-384,\s0 or \s-1SHA\-512.\s0  Defaults to \s-1SHA\-1.\s0
.SS "nonce_size"
.IX Subsection "nonce_size"
Size of the client-generated nonce, in bits.  Defaults to 192.
The server-nonce will be appended, so the final nonce size will
be substantially larger.
.SS "skip_saslprep"
.IX Subsection "skip_saslprep"
A boolean that defaults to false.  If set to true, usernames and passwords will
not be normalized through SASLprep.  This is a deviation from the \s-1RFC5802\s0 spec
and is not recommended.
.SH "METHODS"
.IX Header "METHODS"
.SS "first_msg"
.IX Subsection "first_msg"
.Vb 1
\&    $server_first_msg = $server\->first_msg( $client_first_msg );
.Ve
.PP
This takes the \f(CW\*(C`client\-first\-message\*(C'\fR received from the client and returns the
\&\f(CW\*(C`server\-first\-message\*(C'\fR string to be sent to the client to continue a \s-1SCRAM\s0
session.  Calling this again will reset the internal state and initiate a new
session.  This will throw an exception should an error occur.
.SS "final_msg"
.IX Subsection "final_msg"
.Vb 1
\&    $server_final_msg = $server\->final_msg( $client_final_msg );
.Ve
.PP
This takes the \f(CW\*(C`client\-final\-message\*(C'\fR received from the client and returns the
\&\f(CW\*(C`server\-final\-message\*(C'\fR string containing the verification signature to be sent
to the client.
.PP
If an authorization identity was provided by the client, it will confirm that
the authenticating username is authorized to act as the authorization id using
the \*(L"auth_proxy_cb\*(R" attribute.
.PP
If the client credentials do not match or the authentication name is not
authorized to act as the authorization name, then an exception will be thrown.
.SS "authorization_id"
.IX Subsection "authorization_id"
.Vb 1
\&    $username = $client\->authorization_id();
.Ve
.PP
This takes no arguments and returns the authorization identity resulting from
the \s-1SCRAM\s0 exchange.  This is the client-supplied authorization identity (if one
was provided and validated) or else the successfully authenticated identity.
.SH "CHARACTER ENCODING CAVEAT"
.IX Header "CHARACTER ENCODING CAVEAT"
The \s-1SCRAM\s0 protocol mandates \s-1UTF\-8\s0 interchange.  However, all methods in this
module take and return \fBcharacter\fR strings.  You must encode to \s-1UTF\-8\s0 before
sending and decode from \s-1UTF\-8\s0 on receiving according to whatever transport
mechanism you are using.
.PP
This is done to avoid double encoding/decoding problems if your transport is
already doing \s-1UTF\-8\s0 encoding or decoding as it constructs outgoing messages or
parses incoming messages.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve