GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  AUTHEN::SCRAM::SERVER (3)

.ds Aq ’

NAME

Authen::SCRAM::Server - RFC 5802 SCRAM Server

CONTENTS

VERSION

version 0.005

SYNOPSIS



    use Authen::SCRAM::Server;
    use Try::Tiny;

    $server = Authen::SCRAM::Server->new(
        credential_cb => \&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!"
    };



DESCRIPTION

This module implements the server-side SCRAM algorithm.

ATTRIBUTES

    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 SCRAM: salt, StoredKey, ServerKey, and iteration count. The salt, StoredKey and ServerKey must be provided as octets (i.e. <B>NOTB> base64 encoded).

If the username is unknown, it should return an empty list.



    ($salt, $stored_key, $server_key, $iterations) =
        $server->credential_cb->( $username );



See RFC 5802: SCRAM Algorithm Overview <http://tools.ietf.org/html/rfc5802#section-3> for details.

    auth_proxy_cb

If provided, this attribute must contain a code reference that takes an <B>authenticationB> username and a <B>authorizationB> username (both as character strings), and return a true value if the authentication username is permitted to act as the authorization username:



    $bool = $server->auth_proxy_cb->(
        $authentication_user, $authorization_user
    );



It will only be all called if the authentication username has successfully authenticated. Both usernames will have been normalized via SASLprep with any transport encoding removed before being passed to this function.

    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



    $server_first_msg = $server->first_msg( $client_first_msg );



This takes the client-first-message received from the client and returns the server-first-message string to be sent to the client to continue 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



    $server_final_msg = $server->final_msg( $client_final_msg );



This takes the client-final-message received from the client and returns the server-final-message string containing the verification signature to be sent to the client.

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 auth_proxy_cb attribute.

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.

    authorization_id



    $username = $client->authorization_id();



This takes no arguments and returns the authorization identity resulting from the SCRAM exchange. This is the client-supplied authorization identity (if one was provided and validated) or else the successfully authenticated identity.

CHARACTER ENCODING CAVEAT

The SCRAM protocol mandates UTF-8 interchange. However, all methods in this module take and return <B>characterB> 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



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 AUTHEN::SCRAM::SERVER (3) 2014-10-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.