.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Authen::SCRAM::Client 3pm"
.TH Authen::SCRAM::Client 3pm "2018-07-09" "perl v5.26.2" "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::Client \- RFC 5802 SCRAM client
.SH "VERSION"
.IX Header "VERSION"
version 0.011
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Authen::SCRAM::Client;
\&    use Try::Tiny;
\&
\&    $client = Authen::SCRAM::Client\->new(
\&        username => \*(Aqjohndoe\*(Aq,
\&        password => \*(Aqtrustno1\*(Aq,
\&    );
\&
\&    try {
\&        $client_first = $client\->first_msg();
\&
\&        # send to server and get server\-first\-message
\&
\&        $client_final = $client\->final_msg( $server_first );
\&
\&        # send to server and get server\-final\-message
\&
\&        $client\->validate( $server_final );
\&    }
\&    catch {
\&        die "Authentication failed!"
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the client-side \s-1SCRAM\s0 algorithm.
.SH "NAME"
Authen::SCRAM::Client \- RFC 5802 SCRAM client
.SH "VERSION"
.IX Header "VERSION"
version 0.011
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "username (required)"
.IX Subsection "username (required)"
Authentication identity.  This will be normalized with the SASLprep algorithm
before being transmitted to the server.
.SS "password (required)"
.IX Subsection "password (required)"
Authentication password.  This will be normalized with the SASLprep algorithm
before being transmitted to the server.
.SS "authorization_id"
.IX Subsection "authorization_id"
If the authentication identity (\f(CW\*(C`username\*(C'\fR) will act as a different,
authorization identity, this attribute provides the authorization identity.  It
is optional.  If not provided, the authentication identity is considered by the
server to be the same as the authorization identity.
.SS "minimum_iteration_count"
.IX Subsection "minimum_iteration_count"
If the server requests an iteration count less than this value, the client
throws an error.  This protects against downgrade attacks.  The default is
4096, consistent with recommendations in the \s-1RFC.\s0
.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
\&    $client_first_msg = $client\->first_msg();
.Ve
.PP
This takes no arguments and returns the \f(CW\*(C`client\-first\-message\*(C'\fR character
string to be sent to the server to initiate 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
\&    $client_final_msg = $client\->final_msg( $server_first_msg );
.Ve
.PP
This takes the \f(CW\*(C`server\-first\-message\*(C'\fR character string received from the
server and returns the \f(CW\*(C`client\-final\-message\*(C'\fR character string containing the
authentication proof to be sent to the server.  This will throw an exception
should an error occur.
.SS "validate"
.IX Subsection "validate"
.Vb 1
\&    $client\->validate( $server_final_msg );
.Ve
.PP
This takes the \f(CW\*(C`server\-final\-message\*(C'\fR character string received from the
server and verifies that the server actually has a copy of the client
credentials.  It will return true if valid and throw an exception, otherwise.
.SS "computed_keys"
.IX Subsection "computed_keys"
This method returns the opaque keys used in the \s-1SCRAM\s0 protocol.  It returns
the 'stored key', the 'client key' and the 'server key'.  The server must
have a copy of the stored key and server key for a given user in order to
authenticate.
.PP
This method caches the computed values \*(-- it generates them fresh only if
the supplied salt and iteration count don't match the cached salt and
iteration count.
.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