Услуга шифрования

Услуга шифрования предоставляет двустороннее симметричное (с секретным ключом) шифрование данных. Сервис будет создавать и/или инициализировать обработчик шифрования, соответствующий вашим параметрам, как описано ниже.

Обработчики службы шифрования должны реализовывать простую модель EncrypterInterface. Использование соответствующего криптографического расширения PHP или сторонней библиотеки может потребовать установки дополнительного программного обеспечения на ваш сервер и/или может потребоваться явно включить его в вашем экземпляре PHP.

В настоящее время поддерживаются следующие расширения PHP:

• OpenSSL
• Sodium

Это не полное криптографическое решение. Если вам нужны дополнительные возможности, например, шифрование с открытым ключом, мы рекомендуем вам рассмотреть прямое использование OpenSSL или одного из других расширений криптографии. Еще одним вариантом является более комплексный пакет, такой как Halite (объектно-ориентированный пакет, построенный на libsodium).

• Использование библиотеки шифрования
  • Настройка библиотеки
  • Поведение по умолчанию
  • Установка вашего ключа шифрования
    • Кодирование ключей или результатов
    • Использование префиксов при хранении ключей
  • Заполнение
  • Примечания к обработчику шифрования
    • Примечания к OpenSSL
    • Примечания к Sodium
  • Длина сообщения
  • Использование службы шифрования напрямую
• Справочник по классам

Использование библиотеки шифрования

Как и все службы в CodeIgniter, она может быть загружена через Config\Services:

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

Предполагая, что вы установили начальный ключ (см. Настройка библиотеки), шифрование и дешифрование данных очень просто - передайте соответствующую строку методам encrypt() и/или decrypt():

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

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

И всё! Библиотека шифрования выполнит все необходимые действия для обеспечения криптографической безопасности всего процесса «из коробки». Вам не нужно об этом беспокоиться.

Настройка библиотеки

В приведенном выше примере используются настройки конфигурации, которые находятся в файле app/Config/Encryption.php.

Вы можете заменить настройки файла конфигурации, передав собственный объект конфигурации в вызов Services. Переменная $config должна быть экземпляром класса Config\Encryption.

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

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

Поведение по умолчанию

По умолчанию библиотека шифрования использует обработчик OpenSSL. Этот обработчик шифрует данные с использованием алгоритма AES-256-CTR, вашего настроенного ключа и аутентификации HMAC SHA512.

Установка вашего ключа шифрования

Ключ шифрования должен иметь длину, соответствующую используемому алгоритму шифрования. Для AES-256 это 256 бит или 32 байта (символа).

Ключ должен быть максимально случайным и не должен быть обычной строкой, результатом функции хеширования и т.д. Для создания подходящего ключа вы можете использовать метод createKey() библиотеки шифрования.

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

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

Ключ можно хранить в файле app/Config/Encryption.php, или вы можете разработать собственный механизм хранения и динамически передавать ключ при шифровании/дешифровании.

Чтобы сохранить ключ в файле app/Config/Encryption.php, откройте файл и установите:

public $key = 'YOUR KEY';

Кодирование ключей или результатов

Вы заметите, что метод createKey() выводит двоичные данные, которые сложно обрабатывать (например, копирование и вставка может повредить их), поэтому вы можете использовать bin2hex(), или base64_encode для работы с ключом более удобным способом. Например:

// Get a hex-encoded representation of the key:
$encoded = bin2hex(\CodeIgniter\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');

Вы можете найти ту же технику полезной для результатов шифрования:

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

Использование префиксов при хранении ключей

Вы можете воспользоваться двумя специальными префиксами при хранении ключей шифрования: hex2bin: и base64:. Когда эти префиксы сразу предшествуют значению вашего ключа, Encryption будет разумно анализировать ключ и все равно передавать библиотеке двоичную строку.

// In Encryption, you may use
public $key = 'hex2bin:<your-hex-encoded-key>'

// or
public $key = 'base64:<your-base64-encoded-key>'

Аналогичным образом, вы можете использовать эти префиксы в файле .env!

// For hex2bin
encryption.key = hex2bin:<your-hex-encoded-key>

// or
encryption.key = base64:<your-base64-encoded-key>

Заполнение

Иногда длина сообщения может многое рассказать о его природе. Если сообщение — это «да», «нет» и «возможно», шифрование сообщения не поможет: знание длины достаточно, чтобы узнать, что это за сообщение.

Заполнение — это техника, позволяющая избежать этого, делая длину кратной заданной длине блока.

Заполнение реализовано в SodiumHandler с использованием собственных функций libsodium sodium_pad и sodium_unpad. Это требует использования длины заполнения (в байтах), добавляемой к сообщению-открытому тексту перед шифрованием и удаляемой после дешифрования. Заполнение настраивается через свойство $blockSize класса Config\Encryption. Это значение должно быть больше нуля.

Примечания к обработчику шифрования

Примечания к OpenSSL

Расширение OpenSSL давно входит в стандартный набор PHP.

Обработчик OpenSSL CodeIgniter использует шифр AES-256-CTR.

Ключ, указанный в вашей конфигурации, используется для вывода двух других ключей: один для шифрования и один для аутентификации. Это достигается с помощью техники, известной как функция вывода ключа на основе HMAC (HMAC-based Key Derivation Function (HKDF)).

Примечания к Sodium

Расширение Sodium по умолчанию включено в PHP начиная с версии PHP 7.2.0.

Sodium использует алгоритмы XSalsa20 для шифрования, Poly1305 для MAC и XS25519 для обмена ключами при отправке секретных сообщений в сценарии «от конца до конца». Для шифрования и/или аутентификации строки с использованием общего ключа, такого как симметричное шифрование, Sodium использует алгоритм XSalsa20 для шифрования и HMAC-SHA512 для аутентификации.

Длина сообщения

Зашифрованная строка обычно длиннее исходной строки открытого текста (в зависимости от шифра).

Это зависит от самого алгоритма шифра, вектора инициализации (IV), предваряющего зашифрованный текст, и сообщения аутентификации HMAC, также предваряющего его. Кроме того, зашифрованное сообщение также кодируется в Base64, чтобы его можно было безопасно хранить и передавать независимо от используемой кодировки символов.

Учитывайте эту информацию при выборе механизма хранения данных. Например, куки могут хранить только 4 Кб информации.

Использование службы шифрования напрямую

Вместо (или дополнительно к) использованию Services, как описано в Использовании библиотеки шифрования, вы можете создать «шифратор» напрямую или изменить настройки существующего экземпляра.

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

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

Помните, что $config должен быть экземпляром класса Config\Encryption.

Справочник по классам

CodeIgniter\Encryption\Encryption

static createKey([$length = 32])

Параметры:	$length (int) – Длина результата
Возвращает:	Псевдослучайный криптографический ключ заданной длины или false при ошибке
Тип возвращаемого значения:	string

Создаёт криптографический ключ, получая случайные данные из источников операционной системы (например /dev/urandom).

initialize([Encryption $config = null])

Параметры:	$config (Config\Encryption) – Параметры конфигурации
Возвращает:	Экземпляр CodeIgniter\Encryption\EncrypterInterface
Тип возвращаемого значения:	CodeIgniter\Encryption\EncrypterInterface
Исключения:	CodeIgniter\Encryption\Exceptions\EncryptionException

Инициализирует (настраивает) библиотеку для использования различных настроек.

Пример:

$encrypter = $encryption->initialize(['cipher' => '3des']);

Подробную информацию см. в разделе Настройка библиотеки.

CodeIgniter\Encryption\EncrypterInterface

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

Параметры:	$data (string) – Данные для шифрования $params (array|string|null) – Параметры конфигурации (ключ)
Возвращает:	Зашифрованные данные
Тип возвращаемого значения:	string
Исключения:	CodeIgniter\Encryption\Exceptions\EncryptionException

Шифрует входные данные и возвращает зашифрованный текст.

Если вы передаёте параметры во втором аргументе, элемент key будет использован в качестве начального ключа для этой операции, если $params является массивом; или начальный ключ может быть передан в виде строки.

Если вы используете SodiumHandler и хотите передать другой blockSize во время выполнения, передайте ключ blockSize в массив $params.

Примеры:

$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])

Параметры:	$data (string) – Данные для дешифрования $params (array|string|null) – Параметры конфигурации (ключ)
Возвращает:	Дешифрованные данные
Тип возвращаемого значения:	string
Исключения:	CodeIgniter\Encryption\Exceptions\EncryptionException

Дешифрует входные данные и возвращает их в виде открытого текста.

Если вы передаёте параметры во втором аргументе, элемент key будет использован в качестве начального ключа для этой операции, если $params является массивом; или начальный ключ может быть передан в виде строки.

Если вы используете SodiumHandler и хотите передать другой blockSize во время выполнения, передайте ключ blockSize в массив $params.

Примеры:

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]);