Encriptar y verificar contraseñas en PHP con Argon2id
PHP trae todo lo necesario para guardar contraseñas sin librerías externas: password_hash() para crear el hash, password_verify() para comprobarlo y password_needs_rehash() para saber cuándo hay que regenerarlo. No hace falta una clase propia ni nada por encima.
Aunque se suele decir «encriptar», en realidad es un hash: no se puede descifrar. Para comprobar una contraseña no se recupera la original, se vuelve a calcular y se compara.
Qué hace cada parte
password_hash()genera un salt aleatorio distinto por contraseña y lo guarda dentro del propio hash. No tienes que añadir ninguno tú.PASSWORD_ARGON2IDes el algoritmo recomendado hoy (PHP 7.3 o superior). Es la variante que combina las protecciones de Argon2i y Argon2d.memory_cost,time_costythreadsmarcan lo costoso que es calcular cada hash. Cuanto más costoso, más difícil es atacar las contraseñas por fuerza bruta.password_verify()lee el algoritmo, el salt y los parámetros del propio hash, así que no necesita las opciones.password_needs_rehash()avisa cuando un hash guardado se creó con otro algoritmo u otros parámetros.
Antes de empezar: ¿tu PHP tiene Argon2?
Según el manual de PHP, Argon2id solo está disponible si PHP se ha compilado con soporte de Argon2. Desde PHP 7.4 también puede venir de la extensión sodium. Si no lo tiene, la constante PASSWORD_ARGON2ID no existe y el código falla. Compruébalo una vez en el servidor:
php -r "var_dump(defined('PASSWORD_ARGON2ID'));"
Si devuelve false, usa PASSWORD_DEFAULT (bcrypt) hasta que puedas activarlo.
Guardar y comprobar
<?php
// Parámetros de Argon2id, en un solo sitio.
// memory_cost en KiB (65536 = 64 MiB), time_cost en pasadas, threads en hilos.
const OPCIONES_PASS = ['memory_cost' => 65536, 'time_cost' => 4, 'threads' => 1];
$password = $_POST['password'] ?? '';
// Al dar de alta al usuario o cambiar la contraseña: guardar este hash
$hash = password_hash($password, PASSWORD_ARGON2ID, OPCIONES_PASS);
// Al iniciar sesión: $hash_guardado es el que se leyó de la base de datos
$hash_guardado = $hash;
if (password_verify($password, $hash_guardado)) {
// Contraseña correcta. Si los parámetros han cambiado, se regenera el hash.
if (password_needs_rehash($hash_guardado, PASSWORD_ARGON2ID, OPCIONES_PASS)) {
$nuevo_hash = password_hash($password, PASSWORD_ARGON2ID, OPCIONES_PASS);
// guardar $nuevo_hash en la base de datos
}
echo "contraseña correcta\n";
} else {
echo "contraseña incorrecta\n";
}
Algunas notas:
- Rechaza antes una contraseña vacía. El ejemplo no lo hace para no alargarlo, y
password_hash('')es un hash válido que luego se comprueba sin problema. - Guarda el hash en una columna de 255 caracteres (
VARCHAR(255)). Es lo que recomienda el manual de PHP, porque el tamaño puede crecer si cambian el algoritmo o los parámetros. - Deja
threadsen 1. Según el manual, la implementación de Argon2 de sodium no admite más de un hilo. - En PHP 8.5, 65536 y 4 son los valores por defecto de
memory_costytime_cost. Se ponen explícitos para que no cambien sin que te enteres y para quepassword_needs_rehash()compare siempre con lo mismo.
Ajustar los costes a tu servidor
Los valores del ejemplo son un punto de partida razonable. Mide cuánto tarda un hash en tu servidor:
<?php
$inicio = microtime(true);
password_hash('test', PASSWORD_ARGON2ID, ['memory_cost' => 65536, 'time_cost' => 4, 'threads' => 1]);
echo round((microtime(true) - $inicio) * 1000) . " ms\n";
Si tarda poco, sube time_cost. Si tarda tanto que el inicio de sesión se nota lento, bájalo. Cuando los cambies, password_needs_rehash() irá actualizando los hashes de cada usuario la próxima vez que inicie sesión.
Qué no hacer
- No añadas un «salt» fijo en el código. Ya lo hace
password_hash, la opciónsaltestá obsoleta desde PHP 7.0 y un salt fijo no aporta seguridad. - No uses
md5()nisha1()para contraseñas. - Si quieres una capa extra (pepper), guárdala fuera del código y de la base de datos, por ejemplo en una variable de entorno. Nunca en el propio código.
Si usabas la clase de la versión anterior
La versión anterior de esta entrada proponía una clase EncrypterPop que aplicaba hash_hmac('sha512', ...) con una clave fija antes de password_hash y usaba Argon2i. Los hashes que guardaste con ella no se pueden comprobar con password_verify() directamente: si sustituyes el código sin más, ninguna contraseña existente funcionará.
Esta clase mantiene los mismos nombres de método y migra cada usuario a Argon2id la próxima vez que inicia sesión:
<?php
class EncrypterPop {
private const OPTIONS = ['memory_cost' => 65536, 'time_cost' => 4, 'threads' => 1];
// El valor que tenías en $slt en la versión anterior, copiado tal cual.
// Solo se usa para comprobar hashes antiguos.
private const CLAVE_ANTIGUA = 'el valor de tu $slt';
public static function encryptPass(string $pass): string {
return password_hash($pass, PASSWORD_ARGON2ID, self::OPTIONS);
}
public static function checkPass(string $pass, string $hash): bool {
if (password_verify($pass, $hash)) {
return true;
}
// Hash de la versión anterior: HMAC-SHA512 con clave fija y después Argon2i
return password_verify(hash_hmac('sha512', $pass, self::CLAVE_ANTIGUA), $hash);
}
public static function needsRehash(string $hash): bool {
return password_needs_rehash($hash, PASSWORD_ARGON2ID, self::OPTIONS);
}
}
Y tras cada inicio de sesión correcto, regenerar el hash si hace falta:
if (EncrypterPop::checkPass($password, $hash_guardado)) {
if (EncrypterPop::needsRehash($hash_guardado)) {
$nuevo_hash = EncrypterPop::encryptPass($password);
// guardar $nuevo_hash en la base de datos
}
}
Un hash antiguo empieza por $argon2i$ y uno nuevo por $argon2id$, así que puedes contar en la base de datos cuántos usuarios quedan por migrar. Cuando no quede ninguno, quita la segunda comprobación y la constante CLAVE_ANTIGUA.
Actualizado el 2026-10-27: en la versión anterior la clase aplicaba un HMAC con clave fija antes del hash y usaba Argon2i con parámetros muy bajos. Se ha simplificado, corregido y se ha añadido la migración.
Fuentes
- Manual de PHP: password_hash, constantes de contraseñas, password_needs_rehash.
Deja una respuesta