# Authen::SCRAM::Server - phpMan

## NAME
    [Authen::SCRAM::Server] - RFC 5802 SCRAM Server

## VERSION
    version 0.011

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

## NAME
    [Authen::SCRAM::Server] - RFC 5802 SCRAM Server

## VERSION
    version 0.011

## 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. NOT 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
    authentication username and a authorization 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 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