VERSION

version 0.005

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.

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.

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.

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 <[email protected]>

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