Recent changes to Interface Functions

WikiPage Interface Functions modified by Andrew Kester

Andrew Kester — Fri, 21 Sep 2012 14:44:57 -0000

--- v3
+++ v4
@@ -1,3 +1,5 @@
+Interface Functions:
+====================
 If you wish to have greater control over the structure and interface to your database, you can create your own database functions to use with the library.
 
 All the functions listed here are required and must be specified in the configuration section of the file.
@@ -6,96 +8,43 @@
 
 The functions here will be refereed by their name in the configuration.
 
+
 get_hash_function
 -----------------
+Called using:
 
-The system will call it using this syntax:
+    function($user)
 
-    :::php
-    get_hash_function($user)
+This function is called whenever the system needs to retrieve a user's valid hash.  It should return a hash on success or false on any failure.  The database connection may not be present, so it is wise to verify it and connect if need be.
 
-Where:
-$user - the user name of the hash we would like.
-
-This function should return the hash associated with that username or FALSE to fail the login (ie if the username isn't found).
-
-db_connect_function
--------------------
-The system will call it using this syntax:
-
-    :::php
-    db_connect_function()
-
-This function should establish a connection that can be used with the other data functions or FALSE to fail.  This script is automatically called before the authentication process starts.
-
-db_close_function
------------------
-The system will call it using this syntax:
-
-    :::php
-    db_close_function()
-
-This script is called after the authentication process and should close any open database connections.
+db_connect/close_function
+-------------------------
+These functions take no arguments and are called at the start and stop of the authentication process.  They should return database handles to be used by the other interface functions or false on failure.
 
 nonce_function
 --------------
-This function must exist, however will only be used if the system is set to check nonce values (on by default, highly recommended)
-The system will call it using this syntax:
+This function handles the nonce functions of the Digest authentication.  If you are running basic authentication, insert nullFunc as the function name to disable the function.
+It is called via:
 
-    :::php
-    nonce_function($mode, $nonce, $nc)
+    function($mode, $nonce, $nc)
 
-Where:
-$mode - the mode the function should use (explained below)
-$nonce - the nonce value
-$nc - the nc value
-
-This script provides several functions relating to the nonce value that is passed to the client.  It requires 3 modes:
-**Mode 1** - The system will provide a nonce value to be stored in the nonce table.  The call will look like:
-
-    :::php
-    nonce_function(1, 'nonce', 0,)
-
-Where nonce is replaced with a random nonce the system generates.  This should return TRUE on success, FALSE on failure.
-
-**Mode 2** - The system will ask to verify a nonce.  The system will call it using:
-
-    :::php
-    nonce_function(2, 'nonce', $nc)
-
-Where nonce is again replaced and $nc is replaced by the nc value the client specified.  To combat against certain kinds of attacks, your function should make sure that the Nonce/NC combination hasn't been used (ie increment the nc value in the table with each use).  This should return TRUE on success, FALSE on failure.
-
-**Mode 3** - Mode 3 is only used if your configuration uses the 'NONCE' or 'BOTH' for session expiration.  It is used to invalidate the nonce (usually by setting a expire time in the past).  The call will look like:
-
-    :::PHP
-    nonce_function(3, 'nonce', 0)
-
-Again, nonce is replaced by the nonce string.
+$mode specifies how the function will proceed, and will be either 1 2 or 3.  Mode 1 is inserting a new nonce.  The nonce is generated, but only needs to be inserted into the database.
+Mode 2 checks the validity of a nonce/nc value.
+Mode 3 expires a nonce.
+With these functions, they should return true on success or false on failure.
 
 log_auth_function
 -----------------
-The system will call it using this syntax:
+If you are logging the authentications, this function should insert a log entry into the database.  IT is called via:
 
-    :::php
-    log_auth_function($ip, $result, $user)
+    function($ip, $result, $user)
 
-Where:
-$ip - The IP address of the user
-$result - The outcome of the auth attempt
-$user - The user name (if it should be logged).
-
-If your configuration is set to log authentication requests, this function will be called.  The result codes are: 0-Pass, 1-Fail(User error), 2-Fail(Blacklist).
+$result is the outcome of this auth.  0 is success, 1 is failure, 3 is blacklisted.  $user is only passed on successful page loads.
 
 log_check_function
 ------------------
-The system will call it using this syntax:
+This function checks to see if a user has too many recent failed auths in the log.  It is called via:
 
-    :::php
-    log_check_function($ip)
+    function($ip)
 
-Where:
-$ip - The IP address of the user
-
-This function is called if your configuration is set to log requests.  If so, this should return if the user should be allowed to continue the authentication based on previous auths.  Return TRUE to allow the auth to continue, FALSE to kill it.
-
-
+Where IP is the ip of the user.  It should return true on success or false if the user auth should fail.

WikiPage Interface Functions modified by Andrew Kester

Andrew Kester — Thu, 12 Jul 2012 00:10:18 -0000

--- v2
+++ v3
@@ -1,6 +1,8 @@
 If you wish to have greater control over the structure and interface to your database, you can create your own database functions to use with the library.
 
 All the functions listed here are required and must be specified in the configuration section of the file.
+
+Throughout any of these functions, you can make use of relevant configuration variables (for example, nonce expire times, etc).  Just be sure to include the global $CONFIG array.
 
 The functions here will be refereed by their name in the configuration.

WikiPage Interface Functions modified by Andrew Kester

Andrew Kester — Thu, 12 Jul 2012 00:00:52 -0000

--- v1
+++ v2
@@ -37,6 +37,7 @@
 
 nonce_function
 --------------
+This function must exist, however will only be used if the system is set to check nonce values (on by default, highly recommended)
 The system will call it using this syntax:
 
     :::php
@@ -47,6 +48,52 @@
 $nonce - the nonce value
 $nc - the nc value
 
-This script provides several 
+This script provides several functions relating to the nonce value that is passed to the client.  It requires 3 modes:
+**Mode 1** - The system will provide a nonce value to be stored in the nonce table.  The call will look like:
 
-
+    :::php
+    nonce_function(1, 'nonce', 0,)
+
+Where nonce is replaced with a random nonce the system generates.  This should return TRUE on success, FALSE on failure.
+
+**Mode 2** - The system will ask to verify a nonce.  The system will call it using:
+
+    :::php
+    nonce_function(2, 'nonce', $nc)
+
+Where nonce is again replaced and $nc is replaced by the nc value the client specified.  To combat against certain kinds of attacks, your function should make sure that the Nonce/NC combination hasn't been used (ie increment the nc value in the table with each use).  This should return TRUE on success, FALSE on failure.
+
+**Mode 3** - Mode 3 is only used if your configuration uses the 'NONCE' or 'BOTH' for session expiration.  It is used to invalidate the nonce (usually by setting a expire time in the past).  The call will look like:
+
+    :::PHP
+    nonce_function(3, 'nonce', 0)
+
+Again, nonce is replaced by the nonce string.
+
+log_auth_function
+-----------------
+The system will call it using this syntax:
+
+    :::php
+    log_auth_function($ip, $result, $user)
+
+Where:
+$ip - The IP address of the user
+$result - The outcome of the auth attempt
+$user - The user name (if it should be logged).
+
+If your configuration is set to log authentication requests, this function will be called.  The result codes are: 0-Pass, 1-Fail(User error), 2-Fail(Blacklist).
+
+log_check_function
+------------------
+The system will call it using this syntax:
+
+    :::php
+    log_check_function($ip)
+
+Where:
+$ip - The IP address of the user
+
+This function is called if your configuration is set to log requests.  If so, this should return if the user should be allowed to continue the authentication based on previous auths.  Return TRUE to allow the auth to continue, FALSE to kill it.
+
+

WikiPage Interface Functions modified by Andrew Kester

Andrew Kester — Wed, 11 Jul 2012 23:12:03 -0000

If you wish to have greater control over the structure and interface to your database, you can create your own database functions to use with the library. All the functions listed here are required and must be specified in the configuration section of the file. The functions here will be refereed by their name in the configuration. get_hash_function ----------------- The system will call it using this syntax: :::php get_hash_function($user) Where: $user - the user name of the hash we would like. This function should return the hash associated with that username or FALSE to fail the login (ie if the username isn't found). db_connect_function ------------------- The system will call it using this syntax: :::php db_connect_function() This function should establish a connection that can be used with the other data functions or FALSE to fail. This script is automatically called before the authentication process starts. db_close_function ----------------- The system will call it using this syntax: :::php db_close_function() This script is called after the authentication process and should close any open database connections. nonce_function -------------- The system will call it using this syntax: :::php nonce_function($mode, $nonce, $nc) Where: $mode - the mode the function should use (explained below) $nonce - the nonce value $nc - the nc value This script provides several