Введение

В данной инструкции описывается, как настроить модуль pam_pkcs11 для работы с библиотекой librtpkcs11ecp.so.

Стенд

Нам понадобится токен или смарт-карта семейства Рутокен ЭЦП, отформатированные через Утилита администрирования Рутокен (rtadmin).

Настройки для токена и смарт-карты идентичны.

Общий порядок действий

Шаг 1: Установка необходимых пакетов

Переходим в режим суперпользователя и обновляем список пакетов, затем устанавливаем необходимые компоненты для работы с Рутокен:

su -
apt-get update
apt-get install librtpkcs11ecp libp11 pam_pkcs11 opensc openssl

Проверка установки библиотеки Рутокен:

ls -la /usr/lib64/librtpkcs11ecp.so

Шаг 2: Проверка и создание пользователя

Проверяем существование пользователя user и создаём его при необходимости. Этот шаг критически важен, так как все последующие настройки (права доступа, сертификаты, аутентификация) будут применяться именно к этому пользователю:

id user 2>/dev/null || useradd -m user

Установите временный пароль для резервного входа:

echo "user:TempPass123" | chpasswd 2>/dev/null || true

Проверьте результат:

id user

Шаг 3: Проверка подключения токена

Проверяем, что токен Рутокен ЭЦП корректно определился системой и доступен для работы:

lsusb | grep -i "Aktiv\|Rutoken"

Проверяем доступность токена через библиотеку PKCS#11:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --list-slots

Шаг 4: Создание ключевой пары на токене

Генерируем на токене новую криптографическую пару ключей (приватный + публичный) с использованием алгоритма RSA длиной 2048 бит. Приватный ключ никогда не покидает токен — это обеспечивает безопасность аутентификации:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 12345678 --keypairgen --key-type rsa:2048 --id 45 --label "user"

Что делают параметры команды:

• --module /usr/lib64/librtpkcs11ecp.so — указывает путь к библиотеке Рутокен для работы с токеном
• --login — выполняет вход на токен (требуется для операций с ключами)
• --pin 12345678 — передаёт PIN-код пользователя для аутентификации на токене (используется стандартный заводской PIN)
• --keypairgen — команда генерации ключевой пары
• --key-type rsa:2048 — указывает тип ключа (RSA) и длину в битах (2048)
• --id 45 — задаёт уникальный идентификатор ключа (в шестнадцатеричном формате: 0x45)
• --label "user" — присваивает ключу понятную метку для идентификации

Смена PIN-кода (рекомендуется):

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 12345678 --change-pin --new-pin 123456789

Проверка успешной смены PIN:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 123456789 --list-slots

Шаг 5: Создание конфигурации OpenSSL

В OpenSSL 3.x изменилась архитектура движков. Для работы с PKCS#11 теперь обязательно требуется конфигурационный файл, даже при использовании переменной окружения OPENSSL_CONF. Этот файл настраивает взаимодействие OpenSSL с библиотекой Рутокен.

Проверяем существование движка PKCS#11 для OpenSSL 3.x:

ls -la /usr/lib64/openssl/engines-3/pkcs11.so

Создаём конфигурационный файл для работы с PKCS#11:

cat > /root/pkcs11.cnf << 'EOF'
openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib64/openssl/engines-3/pkcs11.so
MODULE_PATH = /usr/lib64/librtpkcs11ecp.so
PIN = 123456789
init = 1
EOF

Проверяем корректность конфигурации:

cat /root/pkcs11.cnf

Шаг 6: Создание самоподписанного сертификата

Создаём самоподписанный X.509 сертификат, который будет связан с приватным ключом на токене. Сертификат содержит идентифицирующую информацию о пользователе, включая поле CN (Common Name), которое должно совпадать с логином системы для корректной работы маппера opensc.

Проверяем наличие приватного ключа на токене:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 123456789 --list-objects --type privkey

Ожидаемый вывод должен содержать:

Private Key Object; RSA 2048 bits
  label:      user
  ID:         45

Создаём самоподписанный сертификат, связанный с приватным ключом на токене:

OPENSSL_CONF=/root/pkcs11.cnf openssl req -engine pkcs11 -x509 -new -key 45 -keyform engine -out client.pem -days 365 -subj "/C=RU/ST=Moscow/L=Moscow/O=Aktiv/OU=dev/CN=user/emailAddress=user@mail.com"

Проверяем корректность созданного сертификата:

openssl x509 -in client.pem -text -noout | grep "Subject:"

Шаг 7: Запись сертификата на токен

Записываем созданный самоподписанный сертификат на токен Рутокен ЭЦП, связывая его с ранее созданным приватным ключом через совпадающий идентификатор ID=45. Эта связка «приватный ключ + сертификат» на токене является основой для аутентификации через модуль pam_pkcs11:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 123456789 -y cert -w client.pem --id 45 --label "user"

Проверяем наличие сертификата и приватного ключа на токене:

pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 123456789 --list-objects

Ожидаемый вывод:

Private Key Object; RSA 2048 bits
  label:      user
  ID:         45
Certificate Object; type = X.509 cert
  label:      user
  ID:         45

Шаг 8: Настройка конфигурации pam_pkcs11

Создаём основной конфигурационный файл модуля pam_pkcs11, который управляет аутентификацией через токен:

cat > /etc/security/pam_pkcs11/pam_pkcs11.conf << 'EOF'
pam_pkcs11 {
  nullok = false;
  debug = false;
  use_first_pass = false;
  use_authtok = false;
  card_only = false;
  wait_for_card = true;
  use_pkcs11_module = rutokenecp;
 
  pkcs11_module rutokenecp {
    module = /usr/lib64/librtpkcs11ecp.so;
    slot_num = 0;
    support_thread = true;
    ca_dir = /etc/security/pam_pkcs11/cacerts;
    crl_dir = /etc/security/pam_pkcs11/crls;
    cert_policy = none;
  }
 
  use_mappers = opensc;
  mapper_search_path = /lib64/pam_pkcs11;
 
  mapper opensc {
    debug = false;
    module = /lib64/pam_pkcs11/opensc_mapper.so;
  }
}
EOF

Создаём директории для хранения сертификатов Удостоверяющего Центра (УЦ) и списков отозванных сертификатов (CRL).

Эти директории необходимы для будущего перехода на корпоративную инфраструктуру открытых ключей (PKI). Даже при текущей настройке cert_policy = none их создание обеспечивает готовность системы к использованию доверенных сертификатов:

mkdir -p /etc/security/pam_pkcs11/cacerts
mkdir -p /etc/security/pam_pkcs11/crls
chmod 0755 /etc/security/pam_pkcs11/cacerts
chmod 0755 /etc/security/pam_pkcs11/crls

Шаг 9: Настройка конфигурации PAM

Создаём конфигурационный файл для модуля аутентификации PAM (Pluggable Authentication Modules), который интегрирует аутентификацию через токен Рутокен с системой входа в ALT Linux. Конфигурация обеспечивает двухфакторную схему: основной вход по токену + резервный вход по паролю:

cat > /etc/pam.d/system-auth-pkcs11 << 'EOF'
#%PAM-1.0
# Аутентификация через Рутокен + резервный пароль

auth        sufficient    pam_pkcs11.so pkcs11_module=/usr/lib64/librtpkcs11ecp.so
auth        required      pam_unix.so try_first_pass nullok

account     required      pam_unix.so
account     sufficient    pam_localuser.so
account     sufficient    pam_succeed_if.so uid < 1000 quiet
account     required      pam_permit.so

password    required      pam_unix.so sha512 shadow try_first_pass use_authtok nullok

session     required      pam_unix.so
session     optional      pam_keyinit.so revoke
session     required      pam_limits.so
-session     optional      pam_systemd.so
session     [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session     required      pam_loginuid.so
EOF

⚠️ Обязательно создайте резервную копию оригинальной конфигурации (КРИТИЧЕСКИ ВАЖНО!):

cp /etc/pam.d/system-auth /etc/pam.d/system-auth.backup

Активируем новую конфигурацию через символическую ссылку:

rm -f /etc/pam.d/system-auth
ln -s /etc/pam.d/system-auth-pkcs11 /etc/pam.d/system-auth

Проверяем корректность активации конфигурации:

ls -la /etc/pam.d/system-auth
cat /etc/pam.d/system-auth | grep pkcs11

Шаг 10: Настройка прав доступа к токену

Убедитесь, что пользователь состоит в группе uucp, так же проверьте состав групп:

usermod -aG uucp user
groups user

Создайте правила udev с группой uucp:

cat > /etc/udev/rules.d/90-rutoken.rules << 'EOF'
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a89", ATTRS{idProduct}=="0030", MODE="0666", GROUP="uucp"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a89", MODE="0666", GROUP="uucp"
EOF

Перезагрузите правила:

udevadm control --reload-rules
udevadm trigger

Переподключите токен (вытащить и вставить обратно).

Проверка прав на устройство:

ls -la /dev/bus/usb/*/* 2>/dev/null | grep -i "0a89"

Ожидаемый вывод:

crw-rw-rw- 1 root uucp ... /dev/bus/usb/002/005

✅ Права crw-rw-rw- и группа uucp = доступ настроен правильно
❌ Права crw------- и группа root = правила udev не применились

Шаг 11: Настройка сертификата для пользователя

Копируем сертификат из файла client.pem в домашний каталог пользователя user в специальный каталог .eid. Маппер opensc использует этот файл для сопоставления сертификата на токене с учётной записью пользователя при аутентификации:

mkdir -p /home/user/.eid
cp client.pem /home/user/.eid/authorized_certificates
chown -R user:user /home/user/.eid
chmod 0755 /home/user/.eid
chmod 0644 /home/user/.eid/authorized_certificates

Проверяем корректность настройки сертификата:

cat /home/user/.eid/authorized_certificates

Шаг 12: Тестирование аутентификации

Выполняем проверку работоспособности настроенной системы аутентификации через токен Рутокен. Тестирование проводится в двух параллельных терминалах: в первом — мониторинг системных логов для диагностики, во втором — попытка входа под пользователем user с использованием PIN-кода токена.

В первом терминале (мониторинг логов):

journalctl -f | grep -i "pam\|pkcs11\|user"

Во втором терминале:

su - user

При запросе введите PIN-код токена: 123456789

Проверка успешного входа:

whoami
pwd

Финальная проверка

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

grep pkcs11 /etc/pam.d/system-auth
pkcs11-tool --module /usr/lib64/librtpkcs11ecp.so --login --pin 123456789 --list-objects
ls -la /home/user/.eid/
su - user
# Ввести PIN: 123456789

Теперь проверяем аутентификацию по токену (через смену УЗ):

✅ Если все проверки пройдены успешно — аутентификация через токен Рутокен настроена корректно и полностью работоспособна! 

Быстрая диагностика проблем

Если аутентификация не работает:

Включите отладку в /etc/security/pam_pkcs11/pam_pkcs11.conf:

debug = true;

Добавьте debug в строку pam_pkcs11 в /etc/pam.d/system-auth-pkcs11:

auth sufficient pam_pkcs11.so pkcs11_module=/usr/lib64/librtpkcs11ecp.so debug

Проверьте логи:

journalctl -f | grep -i "pam\|pkcs11"

Важные замечания

1. Не закрывайте текущую сессию root до полной проверки работоспособности.
2. Для диагностики временно включите отладку в /etc/security/pam_pkcs11/pam_pkcs11.conf: debug = true;
3. После настройки отключите отладку.
4. Убедитесь, что в сертификате поле CN совпадает с логином пользователя (CN=user).
5. PIN-код по умолчанию рекомендуется сменить на надёжный.

Откат изменений (если аутентификация не работает)

Если аутентификация через токен не работает и вы потеряли доступ:

В текущей сессии root выполните:

cp /etc/pam.d/system-auth.backup /etc/pam.d/system-auth

Перезагрузите систему или перезапустите службы:

systemctl restart systemd-logind

Войдите по паролю и устраните проблему.