README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Crypto

Безопасные обёртки над проверенными криптопримитивами PHP для 8.1+: аутентифицированное шифрование (AES-256-GCM), хеширование паролей Argon2id, HMAC-подпись, криптостойкая генерация ключей/токенов и сравнение за константное время. Никакой самодельной криптографии.

Установка

composer require cloud-castle/crypto

Требуется PHP 8.1+ и расширение openssl.

Быстрый старт

<?php

use CloudCastle\Crypto\Encryptor;
use CloudCastle\Crypto\PasswordHasher;
use CloudCastle\Crypto\Hmac;
use CloudCastle\Crypto\Random;

// Аутентифицированное шифрование: подделка приводит к исключению.
$key       = Encryptor::generateKey();          // хранить в секрет-хранилище
$encryptor = new Encryptor($key);
$payload   = $encryptor->encrypt('номер карты');
$plaintext = $encryptor->decrypt($payload);

// Хеширование паролей (Argon2id, соль внутри хеша).
$hasher = new PasswordHasher();
$hash   = $hasher->hash($password);
$ok     = $hasher->verify($password, $hash);

// HMAC-подпись со сверкой за константное время.
$signature = Hmac::sign($payload, $secret);
$valid     = Hmac::verify($payload, $secret, $signature);

// Криптостойкие ключи, токены и коды.
$token = Random::token();                        // URL-безопасный токен сессии
$otp   = Random::int(100000, 999999);            // 6-значный код без смещения

Возможности

Аутентифицированное шифрование (AEAD) на AES-256-GCM: свежий IV на каждое сообщение, встроенный тег целостности, поддержка связанных данных (AAD).
Хеширование паролей Argon2id с настраиваемой стоимостью и needsRehash().
HMAC (по умолчанию SHA-256) с проверкой за константное время.
Криптостойкая генерация: ключи, URL-безопасные и hex-токены, случайные целые без смещения (только CSPRNG ОС).
Сравнение за константное время для секретов и подписей.
Безопасно по умолчанию: нельзя случайно выбрать небезопасный режим, секреты помечены #[SensitiveParameter], единственная зависимость — ext-openssl.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug. Свойство «обнаружение подделки» проверено реальным тестом порчи шифртекста.

1. Функциональность

Возможность	🏆 CloudCastle	defuse	halite	phpseclib	openssl¹	libsodium¹
Аутентифицированное шифрование (AEAD)	✅	✅	✅	✅	✅	✅
Связанные данные (AAD)	✅	❌	❌	✅	✅	❌
Хеширование паролей (Argon2id)	✅	❌	✅	❌	❌	✅
HMAC-подпись из коробки	✅	❌	✅	✅	✅	✅
Генерация ключей и токенов	✅	✅	✅	✅	❌	✅
Сравнение за константное время	✅	✅	✅	✅	❌	✅
Единый API (шифр + пароли + HMAC + random)	✅	❌	❌	❌	❌	❌
Всего	🏆 7	3	5	5	3	5

2. Безопасность

Свойство безопасности	🏆 CloudCastle	defuse	halite	phpseclib	openssl¹	libsodium¹
Обнаружение подделки (проверено тестом)	✅	✅	✅	✅	✅	✅
AEAD по умолчанию (нельзя выбрать небезопасный режим)	✅	✅	✅	❌	❌	✅
Свежий nonce/IV автоматически	✅	✅	✅	❌	❌	❌
Argon2id для паролей	✅	❌	✅	❌	❌	✅
Секреты помечены #[SensitiveParameter]	✅	❌	❌	❌	❌	❌
Нулевые внешние зависимости	✅	✅	❌	✅	✅	✅
Всего	🏆 6	4	4	2	2	4

3. Производительность

Шифрование + расшифрование 1 KiB, 20 000 раз (минимум из 4).

Решение	Время (мс)	Итог
libsodium¹	76,9	нативный примитив (пол, не библиотека)
openssl¹	83,4	нативный примитив (пол, не библиотека)
🏆 CloudCastle	98,9	быстрейшее среди библиотек
phpseclib	1 083	аналог
halite	6 969,1	аналог
defuse	8 871	аналог

4. Потребление памяти

Пик памяти на 20 000 операций (изолированный процесс).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	7 576	быстрейшее среди библиотек
openssl¹	7 576	нативный примитив (пол, не библиотека)
libsodium¹	7 576	нативный примитив (пол, не библиотека)
defuse	7 703	аналог
halite	7 710	аналог
phpseclib	8 634	аналог

¹ Нативные примитивы PHP показаны как «пол» производительности: это сырые вызовы без безопасного API, управления ключами и полноты решения — они не являются библиотеками-аналогами и не претендуют на победу.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/crypto
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия