The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Squid-Auth-Engine-0.04
River stage one • 1 direct dependent • 1 total dependent
++
/ Net::Squid::Auth::Engine

NAME

Net::Squid::Auth::Engine - External Credentials Authentication for Squid HTTP Cache

VERSION

Version 0.01

SYNOPSIS

Squid authentication using an external credentials repository, now implemented in Perl. If you're a sysadmin trying to use this engine to authenticate your Squid users, please read the documentation provided with the script $Config{InstallScript}/squid-auth-engine, shipped with this module.

    #!/usr/bin/perl
    use warnings;
    use strict;
    use Net::Squid::Auth::Engine;
    use IO::Handle;
    BEGIN { STDOUT->autoflush(1); }
    my $engine = Net::Squid::Auth::Engine->new( $ARGV[0] );
    $engine->run;

CONFIGURATION FILE SPECIFICATION

The configuration file currently supports two keywords, at the moment. Only one of them is useful and required:

plugin

The plugin keyword indicates which module name should be loaded as authentication back-end to this interface. The string Net::Squid::Auth::Plugin:: will be automatically appended to the module name pointed here before it's loaded.

include

The include keyword can be used to import and process another configuration file (a part of one) if required. The configuration file name should be passed as argument to the keyword.

Configuration File Example

  plugin 'UserList'

WRITING PLUGINS

A plugin for Net::Squid::Auth::Engine is a module under Net::Squid::Auth::Plugin that implements a well-stablished interface.

It is expected to keep it's own internal state and initialize only once (and not at every request, this is not a stateless protocol!).

It is also expected to implement the following methods:

new( $config_hash )

New is a constructor. It receives a hash reference containing all the keywords and values passed in the main configuration file which section is the "last" plugin module name (e.g.: for Net::Squid::Auth::Plugin::UserList, the section is named "UserList". That's case sensitive, pay attention!).

The constructor must return a blessed reference for the plugin module, that is able to keep it's internal state and implements the following methods.

initialize()

Initialization method called upon instantiation. This provides an opportunity for the plugin initialize itself, stablish database connections and ensure it have all the necessary resources to verify the credentials presented. It receives no parameters and expect no return values.

is_valid( $username, $password )

Credential verification method. This method does the real work for the credentials verification, and must return a boolean value without raising any exceptions. A true value means that the pair (username, password) is a valid credentials, and a false value means that the credentials aren't valid. Undefined values will be passed as-is to the method, which means that it's free to validate any credentials the way it sees fit.

EXAMPLE PLUGIN

As a plugin implementation example, this module depends on the Net::Squid::Auth::Plugin::UserList, the most basic plugin possible: it loads a username and password list from the configuration file and uses it to authenticate users against it. For more information, please read the Net::Squid::Auth::Plugin::UserList documentation.

OTHER IMPLEMENTATIONS

Net::Squid::Auth::Plugin::SimpleLDAP

A simple LDAP-based credentials validation plugin for Net::Squid::Auth::Engine.

FUNCTIONS

new

Constructor. Receives a configuration file name, opens and reads it, initializes the module and returns the authentication engine instance.

run

Runs the engine, that is: load and parse the configuration file; identifies the authentication module to be loaded; load and instantiate the authentication module to be used; give the authentication module a chance to initialize itself (stablishing database connections, etc.); waits for a Squid-standard credentials line in the standard input, reads it, feeds it to the authentication module instance, collects the answer and prints "OK" or "ERR" in the stdout file handle, as the Squid external authentication protocol commands. Then, waits for the next credential line to show up... you got the idea, right?

_read_config_file

Reads a configuration file, parses it, and makes it available. The underling configuration parser is Config::General.

_initialize

Internal engine initialization. Happens once, mainly instanciates the plugin and tries to initialize it properly. Die for errors, as usual.

_read_credentials

This method tryies, waits for, and reads a line from STDIN, splits it at the first whitespace found from left to right, and returns the username (to the left of the splitting whitespace) and the password (to the right of the splitting whitespace), as described by the Squid HTTP Cache documentation.

AUTHOR

Luis Motta Campos, <lmc at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-squid-auth-engine at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Squid-Auth-Engine. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

  • There are no working tests for this module (yet);

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Squid::Auth::Engine

You can also look for information at:

ACKNOWLEDGEMENTS

To William A. Knob, for the initial idea;

To Otavio Fernandes, for the documentation links;

To Lucas Mateus, for the inner loop implementation, all comments and improvements;

To Fernando Oliveira, for comments and questioning the prototype;

To Alexei Znamensky, Gabriel Viera, and Mike Tesliuk, for pointing me a design bug and helping me re-design the responsibility chain.

To Alexei Znamensky, for trying to use the module, reporting bugs, submiting patches and implementing Net::Squid::Auth::Plugin::SimpleLDAP.

COPYRIGHT & LICENSE

Copyright 2008 Luis Motta Campos, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.