[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
SF.net SVN: ledger-smb:[3374] trunk
- Subject: SF.net SVN: ledger-smb:[3374] trunk
- From: ..hidden..
- Date: Tue, 28 Jun 2011 16:14:58 +0000
Revision: 3374
http://ledger-smb.svn.sourceforge.net/ledger-smb/?rev=3374&view=rev
Author: einhverfr
Date: 2011-06-28 16:14:57 +0000 (Tue, 28 Jun 2011)
Log Message:
-----------
Doc strings in Session.sql
Doc strings in LedgerSMB/Auth.pm
Doc strongs in LedgerSMB/Auth/DB.pm
Slight refactoring of the auth framework
Modified Paths:
--------------
trunk/LedgerSMB/Auth/DB.pm
trunk/LedgerSMB/Auth.pm
trunk/sql/modules/Session.sql
Modified: trunk/LedgerSMB/Auth/DB.pm
===================================================================
--- trunk/LedgerSMB/Auth/DB.pm 2011-06-28 13:50:02 UTC (rev 3373)
+++ trunk/LedgerSMB/Auth/DB.pm 2011-06-28 16:14:57 UTC (rev 3374)
@@ -1,32 +1,21 @@
-#=====================================================================
-# LedgerSMB
-# Small Medium Business Accounting software
-# http://www.ledgersmb.org/
-#
-#
-# Copyright (C) 2006
-# This work contains copyrighted information from a number of sources all used
-# with permission. It is released under the GNU General Public License
-# Version 2 or, at your option, any later version. See COPYRIGHT file for
-# details.
-#
-#
-#======================================================================
-#
-# This file has undergone whitespace cleanup.
-#
-#======================================================================
-# This package contains session related functions:
-#
-# check - checks validity of session based on the user's cookie and login
-#
-# create - creates a new session, writes cookie upon success
-#
-# destroy - destroys session
-#
-# password_check - compares the password with the stored cryted password
-# (ver. < 1.2) and the md5 one (ver. >= 1.2)
-#====================================================================
+
+=pod
+
+=head1 NAME
+
+LedgerSMB::Auth.pm, Standard DB module.
+
+=head1 SYNOPSIS
+
+This is the standard DB-based module for authentication. Uses HTTP basic
+authentication.
+
+=head1 METHODS
+
+=over
+
+=cut
+
package LedgerSMB::Auth;
use MIME::Base64;
use LedgerSMB::Sysconfig;
@@ -35,6 +24,14 @@
my $logger = Log::Log4perl->get_logger('LedgerSMB');
+=item session_check
+
+Checks to see if a session exists based on current logged in credentials.
+
+Handles failure by creating a new session, since credentials are now separate.
+
+=cut
+
sub session_check {
use Time::HiRes qw(gettimeofday);
my ( $cookie, $form ) = @_;
@@ -129,6 +126,13 @@
}
}
+=item session_create
+
+Creates a new session, sets $lsmb->{session_id} to that session, sets cookies,
+etc.
+
+=cut
+
sub session_create {
my ($lsmb) = @_;
my $path = ($ENV{SCRIPT_NAME});
@@ -236,49 +240,11 @@
$lsmb->{dbh}->commit;
}
-sub http_error {
- my ($errcode, $msg_plus) = @_;
+=item session_destry
- my $err = {
- '500' => {status => '500 Internal Server Error',
- message => 'An error occurred. Information on this error has been logged.',
- others => {}},
- '403' => {status => '403 Forbidden',
- message => 'You are not allowed to access the specified resource.',
- others => {}},
- '401' => {status => '401 Unauthorized',
- message => 'Please enter your credentials',
- others => {'WWW-Authenticate' => "Basic realm=\"LedgerSMB\""}
- },
- '404' => {status => '404 Resource not Found',
- message => "The following resource was not found, $msg_plus",
- },
- '454' => {status => '454 Database Does Not Exist',
- message => 'Database Does Not Exist' },
- };
- # Ordinarily I would use $cgi->header to generate the headers
- # but this doesn't seem to be working. Although it is generally desirable
- # to create the headers using the package, I think we should print them
- # manually. -CT
- my $status;
- if ($err->{$errcode}->{status}){
- $status = $err->{$errcode}->{status};
- } elsif ($errcode) {
- $status = $errcode;
- } else {
- print STDERR "Tried to generate http error without code!\n";
- http_error('500');
- }
- print "Status: $status\n";
- for my $h (keys %{$err->{$errcode}->{others}}){
- print "$h: $err->{$errcode}->{others}->{$h}\n";
- }
- print "Content-Type: text/plain\n\n";
- print "Status: $status\n$err->{$errcode}->{message}\n";
- exit;
-
+Destroys a session and removes it from the db.
-}
+=cut
sub session_destroy {
@@ -310,6 +276,15 @@
}
+=item get_credentials
+
+Gets credentials from the 'HTTP_AUTHORIZATION' environment variable which must
+be passed in as per the standards of HTTP basic authentication.
+
+Returns a hashref with the keys of login and password.
+
+=cut
+
sub get_credentials {
# Handling of HTTP Basic Auth headers
my $auth = $ENV{'HTTP_AUTHORIZATION'};
@@ -331,11 +306,19 @@
}
+=item credential_prompt
+
+Sends a 401 error to the browser popping up browser credential prompt.
+
+=cut
+
sub credential_prompt{
http_error(401);
}
-sub password_check {
+sub password_check { # Old routine, leaving in at the moment
+ # As a reference regarding checking passwords
+ # for a password migration app. --CT
use Digest::MD5;
@@ -409,4 +392,20 @@
}
}
+=back
+
+=head1 COPYRIGHT
+
+# Small Medium Business Accounting software
+# http://www.ledgersmb.org/
+#
+#
+# Copyright (C) 2006-2011
+# This work contains copyrighted information from a number of sources all used
+# with permission. It is released under the GNU General Public License
+# Version 2 or, at your option, any later version. See COPYRIGHT file for
+# details.
+
+=cut
+
1;
Modified: trunk/LedgerSMB/Auth.pm
===================================================================
--- trunk/LedgerSMB/Auth.pm 2011-06-28 13:50:02 UTC (rev 3373)
+++ trunk/LedgerSMB/Auth.pm 2011-06-28 16:14:57 UTC (rev 3374)
@@ -1,23 +1,127 @@
-#=====================================================================
-# LedgerSMB
+=pod
+
+=head1 NAME
+
+LedgerSMB::Auth.pm
+
+=head1 SYNOPSIS
+
+This routine provides an abstraction layer for session management and
+authentication. The current application only ships with a simple authentication
+layer using database-native accounts. Other authentication methods are quite
+possible though currently every LedgerSMB user must be a database user.
+
+=head1 METHODS
+
+Each plugin library must provide the following methods.
+
+=over
+
+=item session_check
+
+Check whether a session exists and handle failure appropriately.
+
+Modules are free to define how failure should be addressed.
+
+=item session_create
+
+Create a session
+
+=item session_destroy
+
+Destroy a session.
+
+=item get_credentials
+
+Get credentials and return them to the application.
+
+Must return a hashref with the following entries:
+
+login
+password
+
+=item credential_prompt
+
+Prompt user for credentials
+
+=back
+
+=head1 METHODS PROVIDED IN COMMON
+
+=over
+
+=item http_error
+
+Send an http error to the browser.
+
+=back
+
+=cut
+
+use LedgerSMB::Sysconfig;
+
+if ( !${LedgerSMB::Sysconfig::auth} ) {
+ ${LedgerSMB::Sysconfig::auth} = 'DB';
+}
+
+require "LedgerSMB/Auth/" . ${LedgerSMB::Sysconfig::auth} . ".pm";
+
+sub http_error {
+ my ($errcode, $msg_plus) = @_;
+
+ my $err = {
+ '500' => {status => '500 Internal Server Error',
+ message => 'An error occurred. Information on this error has been logged.',
+ others => {}},
+ '403' => {status => '403 Forbidden',
+ message => 'You are not allowed to access the specified resource.',
+ others => {}},
+ '401' => {status => '401 Unauthorized',
+ message => 'Please enter your credentials',
+ others => {'WWW-Authenticate' => "Basic realm=\"LedgerSMB\""}
+ },
+ '404' => {status => '404 Resource not Found',
+ message => "The following resource was not found, $msg_plus",
+ },
+ '454' => {status => '454 Database Does Not Exist',
+ message => 'Database Does Not Exist' },
+ };
+ # Ordinarily I would use $cgi->header to generate the headers
+ # but this doesn't seem to be working. Although it is generally desirable
+ # to create the headers using the package, I think we should print them
+ # manually. -CT
+ my $status;
+ if ($err->{$errcode}->{status}){
+ $status = $err->{$errcode}->{status};
+ } elsif ($errcode) {
+ $status = $errcode;
+ } else {
+ print STDERR "Tried to generate http error without code!\n";
+ http_error('500');
+ }
+ print "Status: $status\n";
+ for my $h (keys %{$err->{$errcode}->{others}}){
+ print "$h: $err->{$errcode}->{others}->{$h}\n";
+ }
+ print "Content-Type: text/plain\n\n";
+ print "Status: $status\n$err->{$errcode}->{message}\n";
+ exit;
+
+
+}
+
+=head1 COPYRIGHT
+
# Small Medium Business Accounting software
# http://www.ledgersmb.org/
#
#
-# Copyright (C) 2006
+# Copyright (C) 2006-2011
# This work contains copyrighted information from a number of sources all used
# with permission. It is released under the GNU General Public License
# Version 2 or, at your option, any later version. See COPYRIGHT file for
# details.
-# This is a simple abstraction layer allowing other session handling mechanisms
-# (For example Kerberos tickets) as the application progresses.
-package LedgerSMB::Auth;
+=cut
-use LedgerSMB::Sysconfig;
-
-if ( !${LedgerSMB::Sysconfig::auth} ) {
- ${LedgerSMB::Sysconfig::auth} = 'DB';
-}
-
-require "LedgerSMB/Auth/" . ${LedgerSMB::Sysconfig::auth} . ".pm";
+1;
Modified: trunk/sql/modules/Session.sql
===================================================================
--- trunk/sql/modules/Session.sql 2011-06-28 13:50:02 UTC (rev 3373)
+++ trunk/sql/modules/Session.sql 2011-06-28 16:14:57 UTC (rev 3374)
@@ -8,6 +8,10 @@
WHERE f.session_id = $1 and f.id = $2 and u.username = SESSION_USER;
$$ language sql SECURITY DEFINER;
+COMMENT ON FUNCTION form_check(in_session_id int, in_form_id int) IS
+$$ This checks to see if an open form (record in open_forms) exists with
+the form_id and session_id provided. Returns true if exists, false if not.$$;
+
CREATE OR REPLACE FUNCTION form_close(in_session_id int, in_form_id int)
RETURNS BOOL AS
$$
@@ -26,6 +30,12 @@
END;
$$ language plpgsql SECURITY DEFINER;
+COMMENT ON FUNCTION form_close(in_session_id int, in_form_id int) IS
+$$ Closes out the form by deleting it from the open_forms table.
+
+Returns true if found, false if not.
+$$;
+
CREATE OR REPLACE FUNCTION check_expiration() RETURNS bool AS
$$
DECLARE test_result BOOL;
@@ -52,6 +62,13 @@
END;
$$ LANGUAGE PLPGSQL SECURITY DEFINER; -- run by public, but no input from user.
+COMMENT ON FUNCTION check_expiration() IS
+$$ This checks whether the user needs to be notified of a pending expiration of
+his/her password. Returns true if needed, false if not.
+
+The function also records the next time when the notification will again need to
+be displayed. $$;
+
CREATE OR REPLACE FUNCTION form_open(in_session_id int)
RETURNS INT AS
$$
@@ -71,6 +88,9 @@
END;
$$ LANGUAGE PLPGSQL SECURITY DEFINER;
+COMMENT ON FUNCTION form_open(in_session_id int) IS
+$$ This opens a form, and returns the id of the form opened.$$;
+
CREATE OR REPLACE FUNCTION session_check(in_session_id int, in_token text)
RETURNS session AS
$$
@@ -117,7 +137,9 @@
$$ LANGUAGE PLPGSQL;
COMMENT ON FUNCTION session_check(int, text) IS
-$$ Return code is 0 for failure, 1 for success. $$;
+$$ Returns a session row. If no session exists, creates one.
+The row returned is the current, active session.
+ $$;
CREATE OR REPLACE FUNCTION unlock_all() RETURNS BOOL AS
$$
@@ -131,6 +153,12 @@
END;
$$ LANGUAGE PLPGSQL;
+COMMENT ON FUNCTION unlock_all() IS
+$$Releases all pessimistic locks against transactions. These locks are again
+only advisory, and the application may choose to handle them or not.
+
+Returns true if any transactions were unlocked, false otherwise.$$;
+
CREATE OR REPLACE FUNCTION unlock(in_id int) RETURNS BOOL AS $$
BEGIN
UPDATE transactions SET locked_by = NULL WHERE id = in_id
@@ -139,3 +167,12 @@
RETURN FOUND;
END;
$$ LANGUAGE PLPGSQL;
+
+COMMENT ON FUNCTION unlock(in_id int) IS
+$$Releases a pessimistic locks against a transaction, if that transaciton, as
+identified by in_id exists, and if it is locked by the current session.
+These locks are again only advisory, and the application may choose to handle
+them or not.
+
+Returns true if the transaction was unlocked by this routine, false
+otherwise.$$;
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.