[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

SF.net SVN: ledger-smb:[3374] trunk



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.