Servicio de cifrado

Importante

DO NOT use this or any other encryption library for almacenamiento de contraseña! Las contraseñas deben tener hash en su lugar, y usted debería hacerlo a través de la extensión Password Hashing de PHP.

El Servicio de cifrado proporciona cifrado de datos simétrico (clave secreta) bidireccional. El servicio creará una instancia y/o inicializará un controlador de cifrado para adaptarlo a sus parámetros como se explica a continuación.

Los controladores del servicio de cifrado deben implementar la sencilla EncrypterInterface de Higgs. Es posible que sea necesario utilizar una extensión criptográfica PHP adecuada o una biblioteca de terceros. software adicional que se instalará en su servidor y/o podría necesitar ser explícitamente habilitado en su instancia de PHP.

Actualmente se admiten las siguientes extensiones de PHP:

OpenSSL<https://www.php.net/openssl> _
Sodio<https://www.php.net/manual/en/book.sodium> _

Esta no es una solución criptográfica completa. Si necesita más capacidades, por ejemplo, cifrado de clave pública, le sugerimos que considere el uso directo de OpenSSL o una de las otras Extensiones de criptografía<https://www.php.net/manual/en/refs.crypto.php> _. Un paquete más completo como Halite<https://github.com/paragonie/halite> _ (un paquete OO construido sobre libsodium) es otra posibilidad.

Nota

Support for the MCrypt extension has been dropped, as that has ha quedado obsoleto a partir de PHP 7.2.

Usando la biblioteca de cifrado 

Como todos los servicios en Higgs, se puede cargar a través de Config\Services:

<?php

$encrypter = \Config\Services::encrypter();

Suponiendo que haya configurado su clave de inicio (ver configuración), cifrar y descifrar datos es simple: pase la cadena apropiada a encrypt() y/o métodos decrypt():

<?php

$plainText  = 'This is a plain-text message!';
$ciphertext = $encrypter->encrypt($plainText);

// Outputs: This is a plain-text message!
echo $encrypter->decrypt($ciphertext);

¡Y eso es! La biblioteca de cifrado hará todo lo necesario. para que todo el proceso sea criptográficamente seguro desde el primer momento. No necesitas preocuparte por eso.

Configurando la biblioteca 

El ejemplo anterior utiliza los ajustes de configuración que se encuentran en app/Config/Encryption.php.

Puede reemplazar la configuración del archivo de configuración pasando una configuración objeto propio a la llamada Servicios. La variable $config debe ser una instancia de la clase Config\Encryption.

<?php

$config         = new \Config\Encryption();
$config->key    = 'aBigsecret_ofAtleast32Characters';
$config->driver = 'OpenSSL';

$encrypter = \Config\Services::encrypter($config);

Configuración para mantener la compatibilidad con H3 

Nuevo en la versión 7.0.0.

Desde v7.3.0, puede descifrar datos cifrados con el cifrado de H3. Si necesita descifrar dichos datos, utilice la siguiente configuración para mantener la compatibilidad.

<?php

use Config\Encryption;
use Config\Services;

$config         = new Encryption();
$config->driver = 'OpenSSL';

// Your H3's 'encryption_key'
$config->key = hex2bin('64c70b0b8d45b80b9eba60b8b3c8a34d0193223d20fea46f8644b848bf7ce67f');
// Your H3's 'cipher' and 'mode'
$config->cipher = 'AES-128-CBC';

$config->rawData        = false;
$config->encryptKeyInfo = 'encryption';
$config->authKeyInfo    = 'authentication';

$encrypter = Services::encrypter($config, false);

Algoritmos de autenticación HMAC compatibles 

Para la autenticación de mensajes HMAC, la biblioteca de cifrado admite uso de la familia de algoritmos SHA-2: =========== ==================== ==================== ========= Algoritmo Longitud bruta (bytes) Longitud codificada en hexadecimal (bytes) =========== ==================== ==================== ========= SHA512 64 128 SHA384 48 96 SHA256 32 64 SHA224 28 56 =========== ==================== ==================== =========

La razón para no incluir otros algoritmos populares, como MD5 o SHA1 es que ya no se consideran lo suficientemente seguros y como tal, no queremos fomentar su uso. Si es absolutamente necesario utilizarlos, es fácil hacerlo a través de PHP. nativo hash_hmac()<http://php.net/manual/en/function.hash-hmac.php> _ función.

Por supuesto, en el futuro se añadirán algoritmos más potentes a medida que aparecen y se vuelven ampliamente disponibles.

Comportamiento por defecto 

De forma predeterminada, la biblioteca de cifrado utiliza el controlador OpenSSL. Ese controlador cifra usando el algoritmo AES-256-CTR, su clave configurada y la autenticación SHA512 HMAC.

Configuración de su clave de cifrado 

Su clave de cifrado debe ser tan larga como lo permita el algoritmo de cifrado en uso. Para AES-256, tiene una longitud de 256 bits o 32 bytes (caracteres).

La clave debe ser lo más aleatoria posible y no debe ser una cadena de texto normal. ni la salida de una función hash, etc. Para crear una clave adecuada, puede utilizar el método createKey() de la biblioteca Encryption.

<?php

// $key will be assigned a 32-byte (256-bit) random key
$key = \Higgs\Encryption\Encryption::createKey();

// for the SodiumHandler, you can use either:
$key = sodium_crypto_secretbox_keygen();
$key = \Higgs\Encryption\Encryption::createKey(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);

La clave se puede almacenar en app/Config/Encryption.php, o puede diseñar un mecanismo de almacenamiento propio y pasar la clave dinámicamente al cifrar/descifrar.

Para guardar su clave en su app/Config/Encryption.php, abra el archivo y establecer:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Encryption extends BaseConfig
{
    public $key = 'YOUR KEY';

    // ...
}

Claves de codificación o resultados 

Notarás que el método createKey() genera datos binarios, que es difícil de manejar (es decir, copiar y pegar puede dañarlo), por lo que puede usar bin2hex() o base64_encode para trabajar con la clave en una manera más amigable. Por ejemplo:

<?php

// Get a hex-encoded representation of the key:
$encoded = bin2hex(\Higgs\Encryption\Encryption::createKey(32));

// Put the same value with hex2bin(),
// so that it is still passed as binary to the library:
$key = hex2bin('your-hex-encoded-key');

Es posible que la misma técnica le resulte útil para los resultados. de cifrado:

<?php

// Encrypt some text & make the results text
$encoded = base64_encode($encrypter->encrypt($plaintext));

Uso de prefijos al almacenar claves 

Puede aprovechar dos prefijos especiales para almacenar su claves de cifrado: hex2bin: y base64:. Cuando estos prefijos precede inmediatamente al valor de su clave, Encryption analizar inteligentemente la clave y aún así pasar una cadena binaria a la biblioteca.

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Encryption extends BaseConfig
{
    // In Encryption, you may use
    public $key = 'hex2bin:<your-hex-encoded-key>';
    // or
    public $key = 'base64:<your-base64-encoded-key>';
    // ...
}

De manera similar, ¡también puedes usar estos prefijos en tu archivo .env!

// Para hex2bin
cifrado.clave = hex2bin:<your-hex-encoded-key>

// o
cifrado.clave = base64:<your-base64-encoded-key>

Relleno 

A veces, la longitud de un mensaje puede proporcionar mucha información sobre su naturaleza. Si un mensaje es de «sí», «no» y «tal vez», cifrar el mensaje no ayuda: saber la longitud es suficiente para saber cuál es el mensaje.

El relleno es una técnica para mitigar esto, haciendo que la longitud sea un múltiplo de un tamaño de bloque determinado.

El relleno se implementa en SodiumHandler usando sodium_pad y sodium_unpad nativos de libsodium. funciones. Esto requiere el uso de una longitud de relleno (en bytes) que se agrega al texto sin formato. mensaje antes del cifrado y eliminado después del descifrado. El relleno es configurable a través del Propiedad $blockSize de Config\Encryption. Este valor debe ser mayor que cero.

Importante

You are advised not to devise your own padding implementation. You must always use la implementación más segura de una biblioteca. Además, las contraseñas no deben rellenarse. Uso de No se recomienda el relleno para ocultar la longitud de una contraseña. Un cliente dispuesto a enviar en su lugar, una contraseña de un servidor debería tener un hash (incluso con una sola iteración de la función hash). Esto garantiza que la longitud de los datos transmitidos sea constante y que el servidor no obtenga fácilmente una copia de la contraseña.

Notas del controlador de cifrado 

Notas de OpenSSL 

El `OpenSSL<https://www.php.net/openssl> La extensión `_ ha sido una parte estándar de PHP durante mucho tiempo.

El controlador OpenSSL de Higgs utiliza el cifrado AES-256-CTR.

La clave que proporciona su configuración se utiliza para derivar otras dos claves, una para cifrado y otro para autenticación. Esto se consigue mediante una técnica conocida como una función de derivación de claves basada en HMAC<https://en.wikipedia.org/wiki/HKDF>` _ (HKDF).

Notas de sodio 

El sodio<https://www.php.net/manual/en/book.sodium> _ la extensión está incluida de forma predeterminada en PHP como de PHP 7.2.0.

Sodium utiliza los algoritmos XSalsa20 para cifrar, Poly1305 para MAC y XS25519 para el intercambio de claves en enviar mensajes secretos en un escenario de extremo a extremo. Para cifrar y/o autenticar una cadena usando una clave compartida, como el cifrado simétrico, Sodium utiliza el algoritmo XSalsa20 para cifrar y HMAC-SHA512 para la autenticación.

Nota

Higgs’s SodiumHandler uses sodium_memzero in every encryption or decryption sesión. Después de cada sesión, el mensaje (ya sea en texto plano o cifrado) y la clave de inicio son eliminado de los amortiguadores. Es posible que tengas que volver a proporcionar la clave antes de iniciar una nueva sesión.

Longitud del mensaje 

Una cadena cifrada suele ser más larga que la cadena de texto sin formato original (según el cifrado).

Esto está influenciado por el propio algoritmo de cifrado, el vector de inicialización (IV) antepuesto al texto cifrado y el mensaje de autenticación HMAC que también se antepone. Además, el mensaje cifrado también está codificado en Base64 para que sea seguro. para almacenamiento y transmisión independientemente del juego de caracteres en uso.

Tenga en cuenta esta información al seleccionar su mecanismo de almacenamiento de datos. Las cookies, por ejemplo, sólo pueden contener 4K de información.

Usar el servicio de cifrado directamente 

En lugar de (o además de) usar Servicios como se describe en Usando la biblioteca de cifrado, puede crear un «Encriptador» directamente o cambiar la configuración de una instancia existente.

<?php

// create an Encryption instance
$encryption = new \Higgs\Encryption\Encryption();

// reconfigure an instance with different settings
$encrypter = $encryption->initialize($config);

Recuerde que $config debe ser una instancia de la clase Config\Encryption.

Referencia de clase 

class Higgs\Encryption\Encryption

static createKey([$length = 32])

Parámetros:

$longitud (int) – Longitud de salida

Devuelve:

una clave criptográfica pseudoaleatoria con la longitud especificada, o «falsa» en caso de error

Tipo del valor devuelto:

cadena

Crea una clave criptográfica obteniendo datos aleatorios de las fuentes del sistema operativo (es decir /dev/urandom).

initialize([Encryption $config = null])

Parámetros:

$config (Config\Encryption) – Parámetros de configuración

Devuelve:

instancia Higgs\Encryption\EncrypterInterface

Tipo del valor devuelto:

Higgs\Encryption\EncrypterInterface

Lanza:

Higgs\Encryption\Exceptions\EncryptionException

Inicializa (configura) la biblioteca para usar diferentes configuraciones.

Ejemplo:

<?php

$encrypter = $encryption->initialize(['cipher' => 'AES-256-CTR']);

Consulte la sección configuración para obtener información detallada.

Higgs\Encryption\EncrypterInterface

encrypt($data[, $params = null])

Parámetros:

$data (string) – datos para cifrar
$params (array|string|null) – Parámetros de configuración (clave)

Devuelve:

datos cifrados

Tipo del valor devuelto:

cadena

Lanza:

Higgs\Encryption\Exceptions\EncryptionException

Cifra los datos de entrada y devuelve su texto cifrado.

Si pasa parámetros como segundo argumento, el elemento key se utilizará como clave inicial para esta operación si $params es una matriz; o la clave inicial se puede pasar como una cadena.

Si está utilizando SodiumHandler y desea pasar un blockSize diferente en tiempo de ejecución, pase la clave blockSize en la matriz $params.

Ejemplos:

<?php

$ciphertext = $encrypter->encrypt('My secret message');
$ciphertext = $encrypter->encrypt('My secret message', ['key' => 'New secret key']);
$ciphertext = $encrypter->encrypt('My secret message', ['key' => 'New secret key', 'blockSize' => 32]);
$ciphertext = $encrypter->encrypt('My secret message', 'New secret key');
$ciphertext = $encrypter->encrypt('My secret message', ['blockSize' => 32]);

decrypt($data[, $params = null])

Parámetros:

$data (string) – datos para descifrar
$params (array|string|null) – Parámetros de configuración (clave)

Devuelve:

datos descifrados

Tipo del valor devuelto:

cadena

Lanza:

Higgs\Encryption\Exceptions\EncryptionException

Descifra los datos de entrada y los devuelve en texto sin formato.

Si pasa parámetros como segundo argumento, el elemento key se utilizará como clave inicial para esta operación si $params es una matriz; o la clave inicial se puede pasar como una cadena.

Si está utilizando SodiumHandler y desea pasar un blockSize diferente en tiempo de ejecución, pase la clave blockSize en la matriz $params.

Ejemplos:

<?php

echo $encrypter->decrypt($ciphertext);
echo $encrypter->decrypt($ciphertext, ['key' => 'New secret key']);
echo $encrypter->decrypt($ciphertext, ['key' => 'New secret key', 'blockSize' => 32]);
echo $encrypter->decrypt($ciphertext, 'New secret key');
echo $encrypter->decrypt($ciphertext, ['blockSize' => 32]);