Skip to content

Latest commit

 

History

History
116 lines (89 loc) · 4.57 KB

UPGRADING.md

File metadata and controls

116 lines (89 loc) · 4.57 KB
Raw

Upgrading Ion Auth.

Upgrading from a former revision of Ion Auth 3

  1. Download the latest Ion Auth 3 revision
  2. Overwrite "libraries/ion_auth.php" and "models/ion_auth_model.php" with the new versions.
  3. Overwrite "language/*" with the news versions.
  4. Check "config/ion_auth.php" for evolution.

Upgrading from Ion Auth 2

This is a bit more complex, depending on your configuration.

  1. Perform an upgrade as described above
  2. Check config/ion_auth.php, some options were modified (see list in relevant chapter below)
  3. Run the SQL migration file according to your environment:
  4. If you were not using the SHA1 hash method, you may also drop the salt column from the users table in your database
  5. If you were using the SHA1 hash method, please check the relevant chapter below
  6. Check your code for functions modification/removal (see list in relevant chapter below)

Options evolution from Ion Auth 2

The config file has changed:

  • For the Hash Method part:
    • hashMethod now only accepts bcrypt or the newer argon2 (PHP 7.2) (sha1 is no longer supported for security considerations, see note below)
    • default_rounds is modified to bcryptDefaultCost
    • random_rounds, min_rounds, max_rounds and salt_prefix are removed as they don't serve any purpose anymore
    • argon2DefaultParams is added for the Argon2 hash method
    • bcryptAdminCost and argon2AdminParams are added to tweak the hash parameters for users in the admin group
  • For the Authentication options part:
    • max_password_length is removed as it is not good practice to limit password's length
  • For the Cookie options part:
    • random_identity_cookie_name is removed as it doesn't serve any purpose anymore
  • The Forgot Password Complete Email Template part is completely removed because the feature doesn't exists anymore due to security issue.
    • emailForgotPassword_complete is removed
  • The Salt options part is completely removed due to the removing of the SHA1 hash method
    • salt_length and store_salt are removed

Functions evolution from Ion Auth 2

Only public functions are listed.

Functions modified

Ion_auth_model::hash_password_db($id, $password, $use_sha1_override = FALSE)
/* ... is updated to... */
Ion_auth_model::verify_password($password, $hash_password_db, $identity = NULL)
Ion_auth_model::clear_forgotten_password_code($code)
/* ... is updated to... */
Ion_auth_model::clear_forgotten_password_code($identity)
Ion_auth_model::hash_password($password, $salt = FALSE, $use_sha1_override = FALSE)
/* ... is updated to... */
Ion_auth_model::hash_password($password, $identity = NULL)
Ion_auth_model::remember_user($id)
/* ... is updated to... */
Ion_auth_model::remember_user($identity)

Public functions removed

Ion_auth_model::forgotten_password_complete($code, $salt = FALSE) // old feature no longer available due to security issue
Ion_auth_model::hash_code($password) // No longer needed
Ion_auth_model::is_time_locked_out($identity, $ip_address = NULL) // Was deprecated, use is_max_login_attempts_exceeded()
Ion_auth_model::salt() // No longer needed

Public functions added

Ion_auth_model::db()
Ion_auth_model::clear_remember_code($identity)
Ion_auth_model::get_user_by_forgotten_password_code($user_code)
Ion_auth_model::get_user_id_from_identity($identity = '')
Ion_auth_model::rehash_password_if_needed($hash, $identity, $password)

Migrating from SHA1

If you were using the sha1 hash method in Ion Auth 2, this method is no longer supported. The SHA1 is known to be insecure for password hashing, and should not be used.

However, fear not! The transition should actually be pretty smooth for you and your users. After upgrading to Ion Auth 3, any user logging in your application will be migrated to the new hashing method. This is completely transparent.

You can monitor it by looking in your database at the password field. Any field not starting with the dollar '$' sign is an old SHA1-based password.

After a while, you may want to invalidate any old user still having a SHA1-based hashed password.