Automatically re-hash passwords over time when necessary

.editorconfig

@@ -0,0 +1,9 @@
+# editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = tab
+trim_trailing_whitespace = true
+end_of_line = lf
+insert_final_newline = true

Database/MySQL.sql

@@ -1,12 +1,3 @@
-SET SQL_MODE = "NO_AUTO_VALUE_ON_ZERO";
-SET time_zone = "+00:00";
-
-/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
-/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
-/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
-/*!40101 SET NAMES utf8 */;
-
-
 CREATE TABLE IF NOT EXISTS `users` (
   `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
   `email` varchar(254) NOT NULL,
@@ -17,7 +8,7 @@ CREATE TABLE IF NOT EXISTS `users` (
   `last_login` int(10) unsigned DEFAULT NULL,
   PRIMARY KEY (`id`),
   UNIQUE KEY `email` (`email`)
-) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
+) ENGINE=MyISAM DEFAULT CHARSET=utf8;
 
 CREATE TABLE IF NOT EXISTS `users_confirmations` (
   `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
@@ -28,7 +19,7 @@ CREATE TABLE IF NOT EXISTS `users_confirmations` (
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `email_expires` (`email`,`expires`)
-) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
+) ENGINE=MyISAM DEFAULT CHARSET=utf8;
 
 CREATE TABLE IF NOT EXISTS `users_remembered` (
   `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
@@ -39,7 +30,7 @@ CREATE TABLE IF NOT EXISTS `users_remembered` (
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `user` (`user`)
-) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
+) ENGINE=MyISAM DEFAULT CHARSET=utf8;
 
 CREATE TABLE IF NOT EXISTS `users_resets` (
   `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
@@ -50,7 +41,7 @@ CREATE TABLE IF NOT EXISTS `users_resets` (
   PRIMARY KEY (`id`),
   UNIQUE KEY `selector` (`selector`),
   KEY `user` (`user`)
-) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
+) ENGINE=MyISAM DEFAULT CHARSET=utf8;
 
 CREATE TABLE IF NOT EXISTS `users_throttling` (
   `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
@@ -60,8 +51,4 @@ CREATE TABLE IF NOT EXISTS `users_throttling` (
   `attempts` mediumint(8) unsigned NOT NULL DEFAULT '1',
   PRIMARY KEY (`id`),
   UNIQUE KEY `action_type_selector_time_bucket` (`action_type`,`selector`,`time_bucket`)
-) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
-
-/*!40101 SET CHARACTER_SET_CLIENT=@OLD_CHARACTER_SET_CLIENT */;
-/*!40101 SET CHARACTER_SET_RESULTS=@OLD_CHARACTER_SET_RESULTS */;
-/*!40101 SET COLLATION_CONNECTION=@OLD_COLLATION_CONNECTION */;
+) ENGINE=MyISAM DEFAULT CHARSET=utf8;

README.md

@@ -1,6 +1,8 @@
 # Auth
 
-Secure authentication for PHP, once and for all, really simple to use.
+Authentication for PHP. Simple, lightweight and secure.
+
+Written once, to be used everywhere.
 
 Completely framework-agnostic and database-agnostic.
 
@@ -44,11 +46,17 @@ Completely framework-agnostic and database-agnostic.
 // $db = new PDO('mysql:dbname=database;host=localhost;charset=utf8', 'username', 'password');
 // $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
 
-$auth = new Delight\Auth\Auth($db);
+$auth = new \Delight\Auth\Auth($db);
 ```
 
 If you have an open `PDO` connection already, just re-use it.
 
+If you do enforce HTTPS on your site, pass `true` as the second parameter to the constructor. This is optional and the default is `false`.
+
+Only in the very rare case that you need access to your cookies from JavaScript, pass `true` as the third argument to the constructor. This is optional and the default is `false`. There is almost always a *better* solution than enabling this, however.
+
+If your web server is behind a proxy server and `$_SERVER['REMOTE_ADDR']` only contains the proxy's IP address, you must pass the user's real IP address to the constructor in the fourth argument. The default is `null`.
+
 ### Sign up a new user (register)
 
 ```php
@@ -59,20 +67,22 @@ try {
 
     // we have signed up a new user with the ID `$userId`
 }
-catch (Delight\Auth\InvalidEmailException $e) {
+catch (\Delight\Auth\InvalidEmailException $e) {
     // invalid email address
 }
-catch (Delight\Auth\InvalidPasswordException $e) {
+catch (\Delight\Auth\InvalidPasswordException $e) {
     // invalid password
 }
-catch (Delight\Auth\UserAlreadyExistsException $e) {
+catch (\Delight\Auth\UserAlreadyExistsException $e) {
     // user already exists
 }
-catch (Delight\Auth\TooManyRequestsException $e) {
+catch (\Delight\Auth\TooManyRequestsException $e) {
     // too many requests
 }
 ```
 
+The username in the third parameter is optional. You can pass `null` here if you don't want to manage usernames.
+
 For email verification, you should build an URL with the selector and token and send it to the user, e.g.:
 
 ```php
@@ -89,20 +99,22 @@ try {
 
     // user is logged in
 }
-catch (Delight\Auth\InvalidEmailException $e) {
+catch (\Delight\Auth\InvalidEmailException $e) {
     // wrong email address
 }
-catch (Delight\Auth\InvalidPasswordException $e) {
+catch (\Delight\Auth\InvalidPasswordException $e) {
     // wrong password
 }
-catch (Delight\Auth\EmailNotVerifiedException $e) {
+catch (\Delight\Auth\EmailNotVerifiedException $e) {
     // email not verified
 }
-catch (Delight\Auth\TooManyRequestsException $e) {
+catch (\Delight\Auth\TooManyRequestsException $e) {
     // too many requests
 }
 ```
 
+The third parameter controls whether the login is persistent with a long-lived cookie. This is known as the "remember me" feature. Set this to `false` to disable the feature. Otherwise, ask the user if they want to enable "remember me". This is usually done with a checkbox in your user interface. Then use their input to decide between `false` and `true` here. This is optional and the default is `false`.
+
 ### Perform email verification
 
 Extract the selector and token from the URL that the user clicked on in the verification email.
@@ -113,13 +125,13 @@ try {
 
     // email address has been verified
 }
-catch (Delight\Auth\InvalidSelectorTokenPairException $e) {
+catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
     // invalid token
 }
-catch (Delight\Auth\TokenExpiredException $e) {
+catch (\Delight\Auth\TokenExpiredException $e) {
     // token expired
 }
-catch (Delight\Auth\TooManyRequestsException $e) {
+catch (\Delight\Auth\TooManyRequestsException $e) {
     // too many requests
 }
 ```
@@ -134,10 +146,10 @@ try {
 
     // password has been changed
 }
-catch (Delight\Auth\NotLoggedInException $e) {
+catch (\Delight\Auth\NotLoggedInException $e) {
     // not logged in
 }
-catch (Delight\Auth\InvalidPasswordException $e) {
+catch (\Delight\Auth\InvalidPasswordException $e) {
     // invalid password(s)
 }
 ```
@@ -150,6 +162,81 @@ $auth->logout();
 // user has been signed out
 ```
 
+### Check if the user is signed in
+
+```php
+if ($auth->isLoggedIn()) {
+    // user is signed in
+}
+else {
+    // user is *not* signed in yet
+}
+```
+
+A shorthand/alias for this method is `$auth->check()`.
+
+### Get the user's ID
+
+```php
+$id = $auth->getUserId();
+```
+
+If the user is not currently signed in, this returns `null`.
+
+A shorthand/alias for this method is `$auth->id()`.
+
+### Get the user's email address
+
+```php
+$email = $auth->getEmail();
+```
+
+If the user is not currently signed in, this returns `null`.
+
+### Get the user's display name
+
+```php
+$email = $auth->getUsername();
+```
+
+Remember that usernames are optional and there is only a username if you supplied it during registration.
+
+If the user is not currently signed in, this returns `null`.
+
+### Check if the user was "remembered"
+
+```php
+if ($auth->isRemembered()) {
+    // user did not sign in but was logged in through their long-lived cookie
+}
+else {
+    // user signed in manually
+}
+```
+
+If the user is not currently signed in, this returns `null`.
+
+### Get the user's IP address
+
+```php
+$ip = $auth->getIpAddress();
+```
+
+### Utilities
+
+#### Create a random string
+
+```php
+$length = 24;
+$randomStr = \Delight\Auth\Auth::createRandomString($length);
+```
+
+#### Create a UUID v4 as per RFC 4122
+
+```php
+$uuid = \Delight\Auth\Auth::createUuid();
+```
+
 ## Features
 
  * registration
@@ -167,6 +254,7 @@ $auth->logout();
  * logout
    * full and reliable destruction of session
  * session management
+   * protection against session hijacking
    * protection against session fixation attacks
  * throttling
    * per IP address
@@ -175,6 +263,10 @@ $auth->logout();
    * prevents clickjacking
    * prevent content sniffing (MIME sniffing)
    * disables caching of potentially sensitive data
+ * miscellaneous
+   * ready for both IPv4 and IPv6
+   * works behind proxy servers as well
+   * privacy-friendly (e.g. does *not* save readable IP addresses)
 
 ## Exceptions
 
@@ -201,7 +293,7 @@ All contributions are welcome! If you wish to contribute, please create an issue
 ## License
 
 ```
-Copyright 2015 delight.im <info@delight.im>
+Copyright (c) delight.im <info@delight.im>
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

composer.json

@@ -1,6 +1,6 @@
 {
 	"name": "delight-im/auth",
-	"description": "Secure authentication for PHP, once and for all, really simple to use",
+	"description": "Authentication for PHP. Simple, lightweight and secure.",
 	"require": {
 		"php": ">=5.5.0"
 	},

src/Auth.php

@@ -1,7 +1,7 @@
 <?php
 
-/**
- * Copyright 2015 delight.im <info@delight.im>
+/*
+ * Copyright (c) delight.im <info@delight.im>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ namespace Delight\Auth;
 require __DIR__.'/Base64.php';
 require __DIR__.'/Exceptions.php';
 
-/** Secure authentication for PHP, once and for all, really simple to use */
+/** Base class that provides all methods, properties and utilities for secure authentication */
 class Auth {
 
 	const SESSION_FIELD_LOGGED_IN = 'auth_logged_in';
@@ -289,6 +289,12 @@ class Auth {
 			$userData = $stmt->fetch(\PDO::FETCH_ASSOC);
 			if ($userData !== false) {
 				if (password_verify($password, $userData['password'])) {
+					// if the password needs to be re-hashed to keep up with improving password cracking techniques
+					if (password_needs_rehash($userData['password'], PASSWORD_DEFAULT)) {
+						// create a new hash from the password and update it in the database
+						$this->updatePassword($userData['id'], $password);
+					}
+
 					if ($userData['verified'] == 1) {
 						$this->onLoginSuccessful($userData['id'], $email, $userData['username'], false);
 
@@ -745,7 +751,7 @@ class Auth {
 	 * @throws TooManyRequestsException if the number of allowed attempts/requests has been exceeded
 	 * @throws AuthError if an internal problem occurred (do *not* catch)
 	 */
-	public function throttle($actionType, $customSelector = null) {
+	private function throttle($actionType, $customSelector = null) {
 		// if a custom selector has been provided (e.g. username, user ID or confirmation token)
 		if (isset($customSelector)) {
 			// use the provided selector for throttling

src/Base64.php

@@ -1,7 +1,7 @@
 <?php
 
-/**
- * Copyright 2015 delight.im <info@delight.im>
+/*
+ * Copyright (c) delight.im <info@delight.im>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Exceptions.php

@@ -1,7 +1,7 @@
 <?php
 
-/**
- * Copyright 2015 delight.im <info@delight.im>
+/*
+ * Copyright (c) delight.im <info@delight.im>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

tests/index.php

@@ -1,7 +1,7 @@
 <?php
 
-/**
- * Copyright 2015 delight.im <info@delight.im>
+/*
+ * Copyright (c) delight.im <info@delight.im>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@ $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
 
 require __DIR__.'/../src/Auth.php';
 
-$auth = new Delight\Auth\Auth($db);
+$auth = new \Delight\Auth\Auth($db);
 
 $result = processRequestData($auth);
 
@@ -38,7 +38,7 @@ else {
 	showGuestUserForm();
 }
 
-function processRequestData(Delight\Auth\Auth $auth) {
+function processRequestData(\Delight\Auth\Auth $auth) {
 	if (isset($_POST)) {
 		if (isset($_POST['action'])) {
 			if ($_POST['action'] === 'login') {
@@ -47,16 +47,16 @@ function processRequestData(Delight\Auth\Auth $auth) {
 
 					return 'ok';
 				}
-				catch (Delight\Auth\InvalidEmailException $e) {
+				catch (\Delight\Auth\InvalidEmailException $e) {
 					return 'wrong email address';
 				}
-				catch (Delight\Auth\InvalidPasswordException $e) {
+				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'wrong password';
 				}
-				catch (Delight\Auth\EmailNotVerifiedException $e) {
+				catch (\Delight\Auth\EmailNotVerifiedException $e) {
 					return 'email not verified';
 				}
-				catch (Delight\Auth\TooManyRequestsException $e) {
+				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
 			}
@@ -83,16 +83,16 @@ function processRequestData(Delight\Auth\Auth $auth) {
 
 					return $auth->register($_POST['email'], $_POST['password'], $_POST['username'], $callback);
 				}
-				catch (Delight\Auth\InvalidEmailException $e) {
+				catch (\Delight\Auth\InvalidEmailException $e) {
 					return 'invalid email address';
 				}
-				catch (Delight\Auth\InvalidPasswordException $e) {
+				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'invalid password';
 				}
-				catch (Delight\Auth\UserAlreadyExistsException $e) {
+				catch (\Delight\Auth\UserAlreadyExistsException $e) {
 					return 'user already exists';
 				}
-				catch (Delight\Auth\TooManyRequestsException $e) {
+				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
 			}
@@ -102,13 +102,13 @@ function processRequestData(Delight\Auth\Auth $auth) {
 
 					return 'ok';
 				}
-				catch (Delight\Auth\InvalidSelectorTokenPairException $e) {
+				catch (\Delight\Auth\InvalidSelectorTokenPairException $e) {
 					return 'invalid token';
 				}
-				catch (Delight\Auth\TokenExpiredException $e) {
+				catch (\Delight\Auth\TokenExpiredException $e) {
 					return 'token expired';
 				}
-				catch (Delight\Auth\TooManyRequestsException $e) {
+				catch (\Delight\Auth\TooManyRequestsException $e) {
 					return 'too many requests';
 				}
 			}
@@ -118,10 +118,10 @@ function processRequestData(Delight\Auth\Auth $auth) {
 
 					return 'ok';
 				}
-				catch (Delight\Auth\NotLoggedInException $e) {
+				catch (\Delight\Auth\NotLoggedInException $e) {
 					return 'not logged in';
 				}
-				catch (Delight\Auth\InvalidPasswordException $e) {
+				catch (\Delight\Auth\InvalidPasswordException $e) {
 					return 'invalid password(s)';
 				}
 			}
@@ -139,7 +139,7 @@ function processRequestData(Delight\Auth\Auth $auth) {
 	return null;
 }
 
-function showDebugData(Delight\Auth\Auth $auth, $result) {
+function showDebugData(\Delight\Auth\Auth $auth, $result) {
 	echo '<pre>';
 
 	echo 'Last operation'."\t\t\t\t";
@@ -171,9 +171,9 @@ function showDebugData(Delight\Auth\Auth $auth, $result) {
 	echo "\n";
 
 	echo 'Auth::createRandomString()'."\t\t";
-	var_dump(Delight\Auth\Auth::createRandomString());
+	var_dump(\Delight\Auth\Auth::createRandomString());
 	echo 'Auth::createUuid()'."\t\t\t";
-	var_dump(Delight\Auth\Auth::createUuid());
+	var_dump(\Delight\Auth\Auth::createUuid());
 
 	echo '</pre>';
 }