Some documentation of include/auth.php.

include/auth.php

@@ -1,11 +1,23 @@
-<?php /** @file */
+<?php
-
+/**
+ * @file include/auth.php
+ * @brief Functions and inline functionality for authentication.
+ *
+ * This file provides some functions for authentication handling and inline
+ * functionality. Look for auth parameters or re-validate an existing session
+ * also handles logout.
+ * Also provides a function for OpenID identiy matching.
+ */
 
 require_once('include/security.php');
 
+/**
+ * @brief Resets the current session.
+ *
+ * @return void
+ */
 function nuke_session() {
-
+	new_cookie(0); // 0 means delete on browser exit
-	new_cookie(0);
 
 	unset($_SESSION['authenticated']);
 	unset($_SESSION['account_id']);
@@ -27,12 +39,15 @@ function nuke_session() {
 }
 
 /**
- * Verify login credentials
+ * @brief Verify login credentials.
- *
- * Returns account record on success, null on failure
  *
+ * @param string $email
+ *  The email address to verify.
+ * @param string $pass
+ *  The provided password to verify.
+ * @return array|null
+ *  Returns account record on success, null on failure.
  */
-
 function account_verify_password($email, $pass) {
 
 	$email_verify = get_config('system', 'verify_email');
@@ -51,6 +66,7 @@ function account_verify_password($email,$pass) {
 	);
 	if(! ($r && count($r)))
 		return null;
+
 	foreach($r as $record) {
 		if(($record['account_flags'] == ACCOUNT_OK)
 			&& (hash('whirlpool', $record['account_salt'] . $pass) === $record['account_password'])) {
@@ -61,7 +77,6 @@ function account_verify_password($email,$pass) {
 	$error = 'password failed for ' . $email;
 	logger($error);
 
-
 	if($record['account_flags'] & ACCOUNT_UNVERIFIED)
 		logger('Account is unverified. account_flags = ' . $record['account_flags']);
 	if($record['account_flags'] & ACCOUNT_BLOCKED)
@@ -88,14 +103,12 @@ function account_verify_password($email,$pass) {
  * also handles logout
  */
 
-
+if((isset($_SESSION)) && (x($_SESSION, 'authenticated')) &&
-if((isset($_SESSION)) && (x($_SESSION,'authenticated')) && ((! (x($_POST,'auth-params'))) || ($_POST['auth-params'] !== 'login'))) {
+	((! (x($_POST, 'auth-params'))) || ($_POST['auth-params'] !== 'login'))) {
-
 
 	// process a logout request
 
 	if(((x($_POST, 'auth-params')) && ($_POST['auth-params'] === 'logout')) || ($a->module === 'logout')) {
-	
 		// process logout request
 		$args = array('channel_id' => local_user());
 		call_hooks('logging_out', $args);
@@ -140,14 +153,13 @@ if((isset($_SESSION)) && (x($_SESSION,'authenticated')) && ((! (x($_POST,'auth-p
 	if(x($_SESSION, 'uid') || x($_SESSION, 'account_id')) {
 
 		// first check if we're enforcing that sessions can't change IP address
-
+		// @todo what to do with IPv6 addresses
 		if($_SESSION['addr'] && $_SESSION['addr'] != $_SERVER['REMOTE_ADDR']) {
 			logger('SECURITY: Session IP address changed: ' . $_SESSION['addr'] . ' != ' . $_SERVER['REMOTE_ADDR']);
 
 			$partial1 = substr($_SESSION['addr'], 0, strrpos($_SESSION['addr'], '.')); 
 			$partial2 = substr($_SERVER['REMOTE_ADDR'], 0, strrpos($_SERVER['REMOTE_ADDR'], '.')); 
 
-
 			$paranoia = intval(get_pconfig($_SESSION['uid'], 'system', 'paranoia'));
 			if(! $paranoia)
 				$paranoia = intval(get_config('system', 'paranoia'));
@@ -174,7 +186,6 @@ if((isset($_SESSION)) && (x($_SESSION,'authenticated')) && ((! (x($_POST,'auth-p
 					nuke_session();
 					goaway(z_root());
 					break;
-
 			}
 		}
 
@@ -199,9 +210,7 @@ if((isset($_SESSION)) && (x($_SESSION,'authenticated')) && ((! (x($_POST,'auth-p
 			nuke_session();
 			goaway(z_root());
 		}
-
+	} // end logged in user returning
-	}
-
 }
 else {
 
@@ -239,7 +248,6 @@ else {
 			$record = $addon_auth['user_record'];
 		}
 		else {
-
 			$record = get_app()->account = account_verify_password($_POST['username'], $_POST['password']);
 
 			if(get_app()->account) {
@@ -250,7 +258,6 @@ else {
 			}
 
 			logger('authenticate: ' . print_r(get_app()->account, true), LOGGER_DEBUG);
-
 		}
 
 		if((! $record) || (! count($record))) {
@@ -293,8 +300,22 @@ else {
 }
 
 
+/**
+ * @brief Returns the channel_id for a given openid_identity.
+ *
+ * Queries the values from pconfig configuration for the given openid_identity
+ * and returns the corresponding channel_id.
+ *
+ * @fixme How do we prevent that an OpenID identity is used more than once?
+ * 
+ * @param string $authid
+ *  The given openid_identity
+ * @return int|bool
+ *  Return channel_id from pconfig or false.
+ */
 function match_openid($authid) {
-	$r = q("select * from pconfig where cat = 'system' and k = 'openid' and v = '%s' limit 1",
+	// Query the uid/channel_id from pconfig for a given value.
+	$r = q("SELECT uid FROM pconfig WHERE cat = 'system' AND k = 'openid' AND v = '%s' LIMIT 1",
 		dbesc($authid)
 	);
 	if($r)