Настройка автоматического распечатывания через PKCS11

Поддержка PKCS#11 позволяет использовать функциональность автораспечатывания с HSM. StarVault также поддерживает встроенные механизмы шифрования и расшифровки данных:

CKM_AES_GCM (0x1087) — симметричное шифрование
CKM_RSA_PKCS_OAEP (0x0009) — асимметричное шифрование

Добавлена поддержка механизмов:

GOSTR3410-12-DERIVE

Данный функционал недоступен в составе StarVault, поставляемого в составе Nova Container Platform.

Поддержка HSM PKCS#11 в StarVault активируется при добавлении блока seal "pkcs11" в файл конфигурации StarVault.

1. Пример конфигурации `pkcs11`

1.1. Предварительные условия

Для работы StarVault требуются следующие программные пакеты:

Библиотека интеграции HSM, совместимая с PKCS#11
Бинарный файл StarVault с поддержкой cgo для вашей архитектуры, включая соответствующие динамические библиотеки (например, glibc)

1.2. Настройка конфигурации

Данные настройки необходимо производить перед первой инициализацией StarVault.

В примере показана настройка печати HSM PKCS11 через файл конфигурации StarVault с указанием всех обязательных значений:

Пример конфигурации с механизмом RSA_PKCS_OAEP

seal "pkcs11" {
  lib         = "/usr/lib64/pkcs11/libsofthsm2.so" (1)
  slot        = "0x6e821619" (2)
  pin         = "1234" (3)
  token_label = "starvault" (4)
  key_label   = "starvault-key" (5)
  generate_key = "true"
  mechanism = "RSA_PKCS_OAEP" (6)
  rsa_oaep_hash = "sha1" (7)
}

lib (string, обязательный) - путь к файлу разделяемой библиотеки PKCS#11.

В зависимости от используемого HSM значение параметра lib может быть как бинарным файлом, так и динамической библиотекой. Его использование может требовать другие библиотеки в зависимости от системы, на которой запущен бинарный файл StarVault (например, в Linux могут потребоваться библиотеки для интерпретации Windows-файлов .dll).

slot (string, требуется слот или метка токена) - номер слота, указываемый в виде строки.

Слоты обычно отображаются в шестнадцатеричном формате в утилитах настройки ОС, но в данной конфигурации используется их десятичный эквивалент. Например, с помощью утилиты командной строки HSM pkcs11-tool слот, указанный как 0x2000000000000001 в шестнадцатеричном формате, равен 2305843009213693953 в десятичном. Эти значения могут отображаться короче или иначе в зависимости от используемого HSM.

3 pin (string, обязательный)- PIN-код для входа.

4 token_label (string, требуется слот или метка токена) - метка токена слота.

5 key_label (string, обязательный) - метка используемого ключа.

mechanism (string, по умолчанию наиболее подходящий) - механизм шифрования или дешифрования, указываемый по имени, либо десятичной или шестнадцатеричной (с префиксом 0x) строкой. Поддерживаемые механизмы:

CKM_AES_GCM (0x1087) - симметричное шифрование
CKM_RSA_PKCS_OAEP (0x0009) - асимметричное шифрование

7 rsa_oaep_hash (string, по умолчанию "sha256") - задает алгоритм хеширования для RSA с прокладкой OAEP. Допустимые значения: sha1, sha224, sha256, sha384, sha512. Доступен для механизма CKM_RSA_PKCS_OAEP.

Ниже приведен пример создания ключа в HSM. В данном случае качестве программного эмулятора HSM используется SoftHSM.

Инициализируйте HSM‑токен. Задайте метку токена StarVault и PIN‑коды администратора и пользователя:
```
softhsm2-util --init-token --slot 0  --label starvault --so-pin 0000 --pin 1234
```
Определите идентификатор слота (slot ID). Получите список доступных слотов и их идентификаторы:
```
pkcs11-tool --module /usr/lib64/pkcs11/libsofthsm2.so --list-slots
```
Пример вывода:
```
Available slots:
Slot 0 (0x2ec641d4): SoftHSM slot ID 0x2ec641d4
```
Зафиксируйте значение slot ID (в примере — 0x2ec641d4) для использования в следующих командах.

Сгенерируйте пары ключей RSA в HSM.

pkcs11-tool --module "/usr/lib64/softhsm/libsofthsm.so" --slot 0x6e821619 --pin 1234 --keypairgen --key-type rsa:4096 --label "starvault-key"

Проверьте созданные объекты.

pkcs11-tool --module /usr/lib64/pkcs11/libsofthsm2.so -l --pin 1234 --slot 0x6e821619 --list-objects | sed -n '/starvault-key/,+6p'

1.3. Настройка автораспечатывания через HSM КриптоПро

Поддерживается только ГОСТ-механизм: GOSTR3410_12_DERIVE.

1.3.1. Предварительные условия

Перед настройкой убедитесь, что выполнены следующие требования:

В инфраструктуре присутствует HSM КриптоПро
На сервере с установленным StarVault установлен клиент КриптоПро CSP 5.0 R3. Скачать клиент можно на официальном сайте КриптоПро CSP

1.3.2. Требования к контейнеру CryptoPro пользователя starvault

1.3.2.1. Пользовательское хранилище

Контейнер в хранилище starvault используется сервисом StarVault для выполнения операций seal/unseal. Должны быть выполнены следующие требования к контейнеру:

Контейнер должен быть скопирован в хранилище ключей пользователя starvault
Владелец: starvault:starvault
Права доступа: 700

Пример корректной структуры

ls -alh /var/opt/cprocsp/keys/starvault/
total 0
drwx------ 4 starvault starvault  42 Jun 15 21:00 .
drwxrwxrwt 5 root      root       51 May 21 20:11 ..
drwx------ 2 starvault starvault 114 Jun 15 21:00 8cadbe9a.000
drwx------ 2 starvault starvault   6 Jun 15 21:00 hsm_keys

1.3.2.2. Ключевая пара

В контейнере должны присутствовать приватный и публичный ключи со следующим атрибутом:

Usage: derive (обязательно)

1.3.2.3. Сертификат

Сертификат должен быть скопирован в пользовательское хранилище uMy
Владелец: пользователь starvault

Сертификат необходим для верификации пары ключей.

Пример корректного вывода pkcs11-tool

sudo -u starvault /bin/pkcs11-tool --module /opt/cprocsp/lib/amd64/libcppkcs11.so --slot 0 --login --pin XXXXXX --list-objects
Private Key Object; GOSTR3410-2012-256
  PARAMS OID: 06072a850302022400
  label:      8cadbe9a8-e0da-fdad-07df-b6526d1354d
  ID:         43383143423342443044394238363634
  Usage:      decrypt, sign, unwrap, derive
warning: PKCS11 function C_GetAttributeValue(ALWAYS_AUTHENTICATE) failed: rv = CKR_ATTRIBUTE_TYPE_INVALID (0x12)

  Access:     sensitive, always sensitive, extractable
Public Key Object; GOSTR3410-2012-256
  PARAMS OID: 06072a850302022400
  VALUE:      c81cb3bd0d9b8664ba17989b53b571e48f5630758d4b07622e391293ff5b9db5
              d3f5471ec73576c71bc1ff60acca81fa477777157a336326983eb5c5d2c67b52
  label:      8cadbe9a8-e0da-fdad-07df-b6526d1354d
  ID:         43383143423342443044394238363634
  Usage:      encrypt, verify, wrap, derive
  Access:     none
Certificate Object; type = X.509 cert
  label:      8cadbe9a8-e0da-fdad-07df-b6526d1354d
  subject:    DN: CN=1129.1129
  ID:         43383143423342443044394238363634
Object 3221225476, type 3461563219

1.3.3. Конфигурация StarVault

Создайте или отредактируйте файл /etc/starvault.d/starvault.hcl и добавьте в него настройку seal "pkcs11":

Пример конфигурации с механизмом GOSTR3410-DERIVE

seal "pkcs11" {
  lib         = "/opt/cprocsp/lib/amd64/libcppkcs11.so" (1)
  slot        = "0" (2)
  pin         = "11111111" (2)
  key_label   = "8cadbe9a8-e0da-fdad-07df-b6526d1354d" (3)
  mechanism   = "GOSTR3410_12_DERIVE" # или GOSTR3410_DERIVE

  cryptopro { (4)
    capi_pin     = "11111111"
    capi_lib_dir = "/opt/cprocsp/lib/amd64"
    container    = "\\\\.\\HDIMAGE\\8cadbe9a8-e0da-fdad-07df-b6526d1354d"
  }
}

1	Параметр `lib` — указывает на PKCS#11-библиотеку КриптоПро.
2	`slot` и `pin` — задают доступ к токену.
3	`key_label` — определяет целевой ключ, а `mechanism` задает используемый криптографический механизм.
4	`cryptopro` — блок является дополнительным объектом в конфигурации `pkcs11` и передает параметры, необходимые для взаимодействия StarVault с клиентскими библиотеками КриптоПро через CAPI-слой.

После внесения изменений перезапустите StarVault.

1.3.4. Пример настройки

Приведенные ниже команды являются примером настройки для дистрибутивов на базе RHEL. Для других дистрибутивов команды могут отличаться — как по путям установки, так и по способам управления контейнерами и сертификатами КриптоПро CSP.

Перед выполнением настройки обязательно ознакомьтесь с официальной документацией КриптоПро CSP для вашего дистрибутива.

Данная инструкция носит ознакомительный характер. Ответственность за корректность установки, настройки и эксплуатации КриптоПро CSP, а также за совместимость версий CSP с операционной системой лежит на администраторе системы.

1.3.4.1. Структура исходных файлов

В каталоге /home/ec2-user/csp находятся файлы, необходимые для подключения к HSM и работы клиента CSP:

ls -alh /home/ec2-user/csp
drwx------  5 ec2-user ec2-user 4.0K Jun 25 22:13 .
drwxr-xr-x. 3 root     root       22 May  5 18:52 ..
drwx------  3 ec2-user ec2-user   26 May 20 16:24 8cadbe9a.000   # контейнер
-rwxrwxr-x  1 ec2-user ec2-user  12K May 20 16:21 hsm_connect.sh # скрипт подключения к HSM
-rw-r--r--  1 ec2-user ec2-user  30M May 20 16:10 linux-amd64.tgz # клиент CSP 5.0 R3

1.3.4.2. Установка КриптоПро CSP

Для работы HSM-клиента требуется установить зависимости и компоненты КриптоПро CSP.

Установите необходимые системные пакеты:
```
sudo dnf install -y redhat-lsb-core tar wget opensc starvault
```
Распакуйте дистрибутив КриптоПро CSP и перейдите в каталог установки:
```
tar -xzf linux-amd64.tgz
cd linux-amd64
```
Запустите установку нужных компонентов CSP:
```
sudo ./install.sh kc2 cprocsp-stunnel lsb-cprocsp-pkcs11
```

1.3.4.3. Копирование контейнера в хранилища root и starvault

Скопируйте контейнер ключей в системное хранилище root и пользовательское хранилище starvault. Это позволит использовать контейнер от имени нужного пользователя при дальнейшей настройке.

Копирование в системное хранилище root

sudo cp -r /home/ec2-user/8cadbe9a.000 /var/opt/cprocsp/keys/root/
sudo chown -R root:root /var/opt/cprocsp/keys/root/8cadbe9a.000
sudo chmod -R 700 /var/opt/cprocsp/keys/root/8cadbe9a.000

Копирование в пользовательское хранилище starvault

sudo mkdir -p /var/opt/cprocsp/keys/starvault/
sudo cp -r /home/ec2-user/8cadbe9a.000 /var/opt/cprocsp/keys/starvault/
sudo chown -R starvault:starvault /var/opt/cprocsp/keys/starvault
sudo chmod -R 700 /var/opt/cprocsp/keys/starvault

1.3.4.4. Подключение к HSM

Перейдите в режим суперпользователя.
```
sudo -i
```
Откройте каталог с утилитой подключения к HSM:
```
cd /home/ec2-user/csp
```
Запустите скрипт подключения:
```
./hsm_connect.sh
```
При запуске скрипт запросит параметры подключения к HSM:
- количество подключений — 1
- адрес HSM — XX.XX.XX.XX (укажите фактический адрес устройства)
- ключ доступа — порядковый номер ключа из списка, выведенного скриптом
- пароль на контейнер — XXXXXX

1.3.4.5. Перенос сертификата в хранилище пользователя starvault

Проверьте, что сертификат присутствует в системном хранилище:
```
/opt/cprocsp/bin/amd64/certmgr -list
```
Убедитесь, что сертификат отсутствует в хранилище пользователя starvault:
```
sudo -u starvault /opt/cprocsp/bin/amd64/certmgr -list
```
Экспортируйте сертификат из хранилища хоста по DN:
```
/opt/cprocsp/bin/amd64/certmgr -export -cert -dn "CN=1129.1129" -dest /tmp/shared_cert.cer
```
Импортируйте сертификат в пользовательское хранилище uMy:
```
sudo -u starvault /opt/cprocsp/bin/amd64/certmgr -inst -store uMy -file /tmp/shared_cert.cer
```

1.3.5. Конфигурация StarVault

Добавьте в файл /etc/starvault.d/starvault.hcl блок seal "pkcs11":

seal "pkcs11" {
  lib         = "/opt/cprocsp/lib/amd64/libcppkcs11.so"
  slot        = "0"
  pin         = "XXXXXX"
  key_label   = "8cadbe9a8-e0da-fdad-07df-b6526d1354d"
  mechanism   = "GOSTR3410_12_DERIVE"

  cryptopro {
    capi_pin     = "YYYYYY"
    capi_lib_dir = "/opt/cprocsp/lib/amd64"
    container    = "\\\\.\\HDIMAGE\\8cadbe9a8-e0da-fdad-07df-b6526d1354d"
  }
}

После внесения изменений запустите StarVault:

systemctl start starvault

Выполните инициализацию StarVault по инструкции.

2. Ротация ключей

Для данной печати поддерживается ротация ключей с использованием разных меток ключей для отслеживания версий. Для ротации задайте значение ключа с новым именем в HSM и обновите конфигурацию StarVault, указав новое значение метки ключа. Перезапустите экземпляр StarVault, чтобы применить новую метку ключа — все новые операции шифрования будут использовать обновленную метку. Старые ключи не должны удаляться. Они используются для расшифровки старых данных.