first commit

docs/security/crypto-gost.md

@@ -0,0 +1,50 @@
+# Криптографическая защита ПДн по ГОСТ (ФСБ №378)
+
+## Зачем
+
+Встроенный в Laravel шифратор использует **AES-256-GCM** — это надёжный
+международный алгоритм, но он **не является сертифицированным в России СКЗИ**.
+Для государственных ИСПДн и при выполнении требований приказа ФСБ России №378
+криптографическая защита ПДн должна выполняться сертифицированными СКЗИ,
+реализующими **ГОСТ Р 34.12-2015 («Кузнечик»/«Магма»)** и ГОСТ Р 34.13-2015.
+
+## Архитектура шаблона
+
+Шифрование изолировано за интерфейсом `App\Services\Crypto\PdnCipher`:
+
+- `LaravelAesCipher` — реализация по умолчанию (AES-256-GCM);
+- `GostCipher` — **заглушка** с точкой интеграции сертифицированного СКЗИ.
+
+Драйвер выбирается параметром `SECURITY_PDN_CIPHER_DRIVER` (`laravel` | `gost`)
+в `config/security.php`. Модели не зависят от конкретного алгоритма — они
+используют трейт `HasPdnEncryption`, который обращается к `PdnCipher`.
+
+## Как подключить КриптоПро CSP / VipNet
+
+1. Установите СКЗИ на сервер (КриптоПро CSP с действующей лицензией, или ПАК).
+2. Создайте ключевой контейнер и задайте параметры в `.env`:
+   ```dotenv
+   SECURITY_PDN_CIPHER_DRIVER=gost
+   SECURITY_GOST_BINARY=/opt/cprocsp/bin/amd64/csptest
+   SECURITY_GOST_CONTAINER="\\\\.\\HDIMAGE\\pdn-key"
+   ```
+3. Реализуйте методы `encrypt()` / `decrypt()` в `App\Services\Crypto\GostCipher`.
+   Возможные способы интеграции:
+   - вызов CLI КриптоПро (`csptest`, `cryptcp`) через `Symfony\Component\Process`;
+   - PHP-расширение с поддержкой ГОСТ (engine `gost` для OpenSSL, при наличии);
+   - gRPC/REST-шлюз к выделенному криптосервису (HSM/КриптоПро DSS).
+
+## Обязательные требования к реализации
+
+- Ключи СКЗИ хранятся в защищённом носителе/контейнере, **не** в `.env` и не в БД.
+- Разделение ключей: ключ ПДн ≠ `APP_KEY` ≠ `AUDIT_HMAC_KEY` ≠ `SECURITY_PSEUDONYM_KEY`.
+- Перешифрование при компрометации/смене ключа — предусмотрите миграционную
+  команду (artisan) для перешифровки полей.
+- Используйте `GostCipher::isAvailable()` в health-check перед включением драйвера.
+- Применение конкретного СКЗИ должно соответствовать его формуляру и классу КС.
+
+## Важное предупреждение
+
+Не оставляйте `SECURITY_PDN_CIPHER_DRIVER=gost` с нереализованным `GostCipher` —
+методы выбрасывают исключение, что прервёт работу с ПДн. Это сделано намеренно,
+чтобы исключить ложное ощущение сертифицированной защиты.