/ 
CGI-Application-Plugin-WSSE-1.0
/ CGI::Application::Plugin::WSSE

NAME

CGI::Application::Plugin::WSSE - Simple WSSE Authentication for CGI applications

SYNOPSIS

 use base 'CGI::Application';
 use CGI::Application::Plugin::WSSE;
 
 sub setup {
     ...
     
     $self->wsse_config(
         callback => sub {
             my ($self, $username) = @_;
             
             # get password associated with this username somehow

             return $password;
         },
         log      => $self->log, 
     );
 }
 
 sub runmode {

     if ( ! $self->wsse_authenticate( ) ) {
         # authentication failed.
         return $self->error( title => 'Error', msg => 'Access denied!');
     }

     # authentication worked so do stuff.
}

ABSTRACT

This plugin enables WSSE Username Token authentication in web applications using the CGI::Application framework.

VERSION

This document describes CGI::Application::Plugin::WSSE Version 1.0

DESCRIPTION

Use this module to implement WSSE Username Token authentication in your CGI::Application based module. This protocol is transported over HTTP headers and is safe to send as clear text while still providing security against password sniffing and replay attacks.

FUNCTIONS

The following functions are imported into your CGI::Application subclass.

wsse_config(%options)

This method is used to configure the way authentication is done. It takes a hash of parameters. The following parameters are valid:

callback

A code reference to a subroutine you provide in your app which sets the takes two parameters, a reference to the calling object (your CGI::Application object, and a reference to a scalar containing a username. The subroutine should use the username to look up its associated password in some application-defined way and return that password as a scalar or undef if the password is not found. This parameter is mandatory.

log

A reference to an object that supports debug, and error methods. If you are using CGI::Application::Plugin::LogDispatch, set this to $self->log. If this parameter is not specified, no logging will be done.

wsse_authenticate()

Call this method to authenticate using the WSSE Username Token protocol. It will return true if authentication was successful or false if it fails. In the case of failure, a WWW-Authenticate HTTP header is added to the response with the value WSSE profile="UsernameToken". The HTTP status is also set to an appropriate value. See DIAGNOSTICS.

DIAGNOSTICS

During the authentication process, errors can occur in certain circumstances. If an error occurs the HTTP status is set to one of the following values.

400 X-WSSE requires $part

The X-WSSE HTTP header consists of four values, Username, PasswordDigest, Nonce, and Created. If one or more of these are missing, the header is malformed and this error is returned. ($part is the first missing part encountered.)

401 X-WSSE authentication required

This error is returned if the client request does not contain an X-WSSE HTTP header. Often the client will not send X-WSSE initially but but will retry with the correct header in response to a 401 status like this.

403 Invalid login

This error is returned if either the username or password sent by the client are invalid or missing.

BUGS AND LIMITATIONS

There are no known problems with this module.

Please report any bugs or feature requests to bug-cgi-application-plugin-wsse at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-WSSE. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

WSSE Username Profile specification

THANKS

Some code lifted from XML::Atom::Client and LWP::Authen::Wsse

AUTHOR

Jaldhar H. Vyas, <jaldhar at braincells.com>

LICENSE AND COPYRIGHT

Copyright (C) 2011, Consoliated Braincells Inc. All rights reserved.

This distribution is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or

b) the Artistic License version 2.0.

The full text of the license can be found in the LICENSE file included with this distribution.