NAME

       Authen::SCRAM::Client - RFC 5802 SCRAM client

VERSION

       version 0.011

SYNOPSIS

           use Authen::SCRAM::Client;
           use Try::Tiny;

           $client = Authen::SCRAM::Client->new(
               username => 'johndoe',
               password => 'trustno1',
           );

           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!"
           };

DESCRIPTION

       This module implements the client-side SCRAM algorithm.

NAME

       Authen::SCRAM::Client - RFC 5802 SCRAM client

VERSION

       version 0.011

ATTRIBUTES

   username (required)
       Authentication identity.  This will be normalized with the SASLprep algorithm before being
       transmitted to the server.

   password (required)
       Authentication password.  This will be normalized with the SASLprep algorithm before being
       transmitted to the server.

   authorization_id
       If the authentication identity ("username") 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.

   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 RFC.

   digest
       Name of a digest function available via PBKDF2::Tiny.  Valid values are SHA-1, SHA-224,
       SHA-256, SHA-384, or SHA-512.  Defaults to SHA-1.

   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.

   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 RFC5802 spec and is not
       recommended.

METHODS

   first_msg
           $client_first_msg = $client->first_msg();

       This takes no arguments and returns the "client-first-message" character string to be sent
       to the server to initiate a SCRAM session.  Calling this again will reset the internal
       state and initiate a new session.  This will throw an exception should an error occur.

   final_msg
           $client_final_msg = $client->final_msg( $server_first_msg );

       This takes the "server-first-message" character string received from the server and
       returns the "client-final-message" character string containing the authentication proof to
       be sent to the server.  This will throw an exception should an error occur.

   validate
           $client->validate( $server_final_msg );

       This takes the "server-final-message" 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.

   computed_keys
       This method returns the opaque keys used in the SCRAM 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.

       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.

CHARACTER ENCODING CAVEAT

       The SCRAM protocol mandates UTF-8 interchange.  However, all methods in this module take
       and return character strings.  You must encode to UTF-8 before sending and decode from
       UTF-8 on receiving according to whatever transport mechanism you are using.

       This is done to avoid double encoding/decoding problems if your transport is already doing
       UTF-8 encoding or decoding as it constructs outgoing messages or parses incoming messages.

AUTHOR

       David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2014 by David Golden.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

AUTHOR

       David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2014 by David Golden.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004