DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: TYPO3 Security - Salted user password hashes

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed by:Marcus Krause
Changed:2009-01-06T00:53:05
Classification:t3sec_saltedpw
Description:The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ----
Keywords:forAdmins, forDevelopers
Author:Marcus Krause
Email:marcus#exp2009@t3sec.info
Info 4:
Language:en

img-1 img-2 EXT: TYPO3 Security - Salted user password hashes - t3sec_saltedpw

EXT: TYPO3 Security - Salted user password hashes

Extension Key: t3sec_saltedpw

Language: en

Keywords: forAdmins, forDevelopers

Copyright 2008-2017, Marcus Krause, <marcus#exp2009@t3sec.info>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.org

Table of Contents

EXT: TYPO3 Security - Salted user password hashes 1

`Introduction 3 <#1.1.Introduction|outline>`_

What does it do? 3

Screenshots 3

`Administration 5 <#1.2.Administration|outline>`_

Installation 5

Extension configuration 5

Update existing records 5

`Configuration 6 <#1.3.Configuration|outline>`_

TypoScript 6

`Extension Developers 7 <#1.4.Extension%20Developers|outline>`_

`Known problems 8 <#1.5.Known%20problems|outline>`_

`To-Do list 9 <#1.6.To-Do%20list|outline>`_

`ChangeLog 10 <#1.7.ChangeLog|outline>`_

`Credits 11 <#1.8.Credits|outline>`_

`Licenses 12 <#1.9.Licenses|outline>`_

Introduction

What does it do?

This extension uses Portable PHP password hashing framework for storing salted password hashes for either FE user records or BE user records or both. Furthermore this extension adds new authentication services for FE and BE so that the salted password hashes can be used for authentication.

The extension integrates into following extensions:

  • sysext felogin (FE authentication, “forgot password” functionality)
  • ext feuser_admin (FE user registration, FE user editing, “forgot password” functionality)

By using this extension, you get rid of plain-text passwords or md5 password hashes for user records in TYPO3. An attacker who might get (admin) access to your TYPO3 backend (by exploiting a vulnerability) will not be able to reuse the passwords any longer. Restoring plain text passwords will only work when using wordlist entries as passwords. So please ask your users to use arbitrary complex non- wordlist passwords/passphrases. You might also consider to regularly run wordlist tests against the salted password hashes stored in your database to ensure the quality of chosen plain-text passwords.

Using this extension requires to send plain-text passwords. Therefore I'd like to encourage the use of SSL to secure authentication in special and data transfer in general.

Portable PHP password hashing framework is currently being used in – amongst others – Drupal and Wordpress .

Screenshots

Salted password hashes are of a 34/35 character length. Proper generated salted password hashes will start with “$P$”; those that have been converted from plain-text passwords or md5 hashes will start with either “C$P$” or “M$P$” indicating that they will need to transparently recomputed during an user authentication.

img-3 Image 1: Example salted password hash of a FE user record

img-4 Image 2: Converting existing passwords to salted password hashes by update function in the extension manager.

img-5 Image 3: Unit Tests regarding Portable PHP password hashing framework

Administration

Installation

After installing the extension you have to decide if you would like to use salted password hashes for the frontend, for the backend or both.

If you would like to use salted password hashes in the frontend, please set:

$TYPO3_CONF_VARS['FE']['loginSecurityLevel'] = 'normal';

Either insert it directly into file localconf.php or use the install tool for that. Setting this configuration will mean that passwords are sent plain-text. Use SSL to secure authentication.

If you would like to use salted password hashes in the backend, please set:

$TYPO3_CONF_VARS['BE']['loginSecurityLevel'] = 'normal';

Either insert it directly into file localconf.php or use the install tool for that. Setting this configuration will mean that passwords are sent plain-text. Use SSL to secure authentication.

Any change to these configuration values will need you to clear TYPO3's configuration cache!

Extension configuration

The extension can be configured with following settings:

# If enabled and authentication fails, no further authentication service will be tried.
onlyAuthService = 0

# Use passwords generated by this extension only.
forcePHPasswd = 1

# Update FE/BE user passwords to salted hash ones during authentication. (will not work when forcePHPasswd is
# activated)
updatePasswd = 1

In TYPO3 authentication services are managed by a priority number. Authentication services with a high priority number will be tried first. If authentication fails, services with a lower priority number will the be tried.

If “ onlyAuthService ”is enabled and authentication fails, no further authentication service will be tried.

If “ forcePHPasswd ”is enabled, only proper generated (newly created passwords will be used to authenticate an user. (no upgraded ones!)

If ” updatePasswd ”is enabled, FE/BE user passwords will be upgraded to proper salted password hashes during authentication. Obviously, this will not work, if “ forcePHPasswd ”is enabled.

Update existing records

After installing the extension and enabling usage of salted password hashes, the extension manager will allow to update existing FE/BE user passwords. This means that such passwords will converted to salted password hashes. The updated password strings will be prefixed with “C” or “M”, depending if they were plain-text or MD5 hashes before. You will only be able to authenticate with the updated passwords, if “ forcePHPasswd ”is disabled. To update existing records, please use UPDATE! function in the extension manager.

Configuration

TypoScript

Constants

This extension provides following TypoScript constants:

plugin.feadmin.fe_users {
# cat=plugin.feadmin.fe_users/file; type=file[html,htm,tmpl,txt]; label= Template File: HTML-template file
file.templateFile = EXT:t3sec_saltedpw/res/tmpl/fe_admin_fe_users.tmpl
}

Please check if it has been successfully applied!

Above TypoScript will override the template provided by extension “ feuser_admin ”. The new template is exactly that one of extension “ feuser_admin ”, but reduced by one single line which allowed an instant login by transmitting credentials via GET.

Setup

This extension provides following TypoScript setup:

# use salted password hashes
plugin.feadmin.fe_users.parseValues.password = trim,saltedHash
# set minimum password length; do not remove eval function atLeastOrEmpty
plugin.feadmin.fe_users.edit.evalValues.password = twice, atLeastOrEmpty[9]
# set minimum password length; do not remove eval function atLeastOrEmpty
plugin.feadmin.fe_users.create.evalValues.password = twice, atLeastOrEmpty[9]

Please check if it has been successfully applied!

Above TypoScript will make sure that plugin “ feuser_admin ”creates salted password hashes. Do not remove the parse function “ saltedHash ”or eval functions “ atLeastOrEmpty ”! You are encouraged to modify the minimum password length which is configured by X in “ atLeastOrEmpty[X] ”.

Extension Developers

If you would like to use salted password hashes for your extension (FE user registration, “forgot password” functionality, etc..), please use this extension to generate proper ones. Have a look at class res/lib/class.tx_t3secsaltedpw_phpass.php which provides an API for generating such salted password hashes.

((generated))

Example implementation

in case you are getting plain-text passwords:

$password = 'XXX'; // plain-text password
if (t3lib_extMgm::isLoaded('t3sec_saltedpw')) {
  require_once t3lib_extMgm::extPath('t3sec_saltedpw').'res/staticlib/class.tx_t3secsaltedpw_div.php';

  if (tx_t3secsaltedpw_div::isUsageEnabled()) {
    require_once t3lib_extMgm::extPath('t3sec_saltedpw').'res/lib/class.tx_t3secsaltedpw_phpass.php';
    $objPHPass = t3lib_div::makeInstance('tx_t3secsaltedpw_phpass');
    $password = $objPHPass->getHashedPassword($password);
  }
}
// $password is now a salted hashed one

in case you are getting md5 hashed passwords:

$password = 'XXX'; // md5 hashed password
if (t3lib_extMgm::isLoaded('t3sec_saltedpw')) {
  require_once t3lib_extMgm::extPath('t3sec_saltedpw').'res/staticlib/class.tx_t3secsaltedpw_div.php';

  if (tx_t3secsaltedpw_div::isUsageEnabled()) {
    require_once t3lib_extMgm::extPath('t3sec_saltedpw').'res/lib/class.tx_t3secsaltedpw_phpass.php';
    $objPHPass = t3lib_div::makeInstance('tx_t3secsaltedpw_phpass');
    $password = 'M' . $objPHPass->getHashedPassword($password); // note the “M” prefix
  }
}
// $password is now a salted hashed one

Known problems

No problems so far.

In case of bugs, please don't contact me directly. Instead, please use the Forge Issue Tracker !

To-Do list

  • Replace XCLASSes by HOOKs; currently user_feAdmin and tx_felogin_pi1(sysext felogin) are subclassed as they do not provide HOOKs for generating passwords/processing salted password hashes.Note: sysext felogin will generate salted password hashes when t3sec_saltedpw is installed and enabled (for TYPO3 >= 4.2.4)
  • There's a check for TYPO3_MODE in the eval function to work around a bug in the TYPO3 BE (md5() eval function is hardcoded for setting a BE user password). This check could be removed if the bug is fixed.

ChangeLog

Please check file ChangeLog for details!

Credits

First, I'd like to thank the guys of the Openwall Project and Drupal CMS for their work on such a great framework.

Besides that, thanks to Lars Houmark (TYPO3 Security Team), Dmitry Dulepov (TYPO3 Core Team), Michael Stucki (TYPO3 Core Team), Francois Suter (TYPO3 Core team), Wolfgang Zenker (punkt.de) and Sascha Kettler (AOE media) for their code contributions. Furthermore thanks to Henning Pingel (TYPO3 Security Team) for testing.

Licenses

This extension is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

The GNU General Public License can be found at ` http://www.gnu.org/copyleft/gpl.html <http://www.gnu.org/copyleft/gpl.html>`_ . A copy is found in the TYPO3 Sources at typo3/GPL.txt .

The modified Portable PHP password hashing framework, included in this extension, is retrieved from Drupal CMS. Drupal CMS is distributed under the terms of the GNU General Public License version 2.

The original Portable PHP password hashing framework is distributed under Public Domain.

The extension icon is retrieved from Mini Set of Mark James, which can be found at ` http://www.famfamfam.com/lab/icons/mini/ <http://www.famfamfam.com/lab/icons/mini/>`_ . This set is distributed under Creative Commons Attribution 2.5 License. The license can be found at http://creativecommons.org/licenses/by/2.5/ .

12