OpenSSL#

Предупреждение

Попытка извлечь закрытый ключ приводит к аварийному завершению работы OpenSSL. Это нормально, поскольку закрытые ключи не могут быть извлечены из NetHSM. Вместо этого можно получить открытый ключ (см. пример ниже).

Двигатель#

Предупреждение

При использовании движка (libp11) версии 0.4.12 и старше наличие ключа EdDSA на NetHSM приводит к тому, что OpenSSL не находит ни одного ключа. В версии 0.4.12 и старше движок при запросе ключа перечисляет все ключи на NetHSM. При поиске ключа по метке или id рекомендуется использовать версию 0.4.13 или более новую, либо собирать libp11 из исходных текстов. Двоичный файл движка будет находиться в каталоге src/.libs/pkcs11.so.

Интерфейс движка OpenSSL - это старый способ реализации пользовательских бэкендов для OpenSSL, который устарел в OpenSSL 3. Это по-прежнему наиболее стабильный способ использования NetHSM с OpenSSL.

Вам необходимо настроить модуль PKCS#11, следуя этой инструкции.

Установите двигатель:

apt install libengine-pkcs11-openssl

Далее необходимо настроить OpenSSL на использование движка. Это делается путем добавления следующих строк в файл openssl.cnf:

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so
MODULE_PATH = /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so
init = 0

Примечание

Вы можете указать OpenSSL путь к конфигурационному файлу OpenSSL с помощью переменной окружения OPENSSL_CONF.

Предупреждение

Если основной конфигурационный файл OpenSSL будет изменен таким образом, чтобы содержать только эти строки, это может привести к поломке других программ, использующих OpenSSL. Поэтому, возможно, потребуется создать отдельный конфигурационный файл для движка.

Замените /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so на путь к установленному ранее модулю PKCS#11.

Замените /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so на путь к установленному вами движку OpenSSL. Путь зависит от дистрибутива. Число в engines-3 соответствует вашей версии OpenSSL. В Debian путь к движку OpenSSL 3 - /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so; в Fedora - /usr/lib64/engines-3/libpkcs11.so.

Теперь вы можете использовать ключи на NetHSM, используя URI PKCS#11, например:

engine:pkcs11:pkcs11:object=webserver;type=private

При этом будет использоваться ключ webserver.

Примечание

Для получения полного URI ключей можно воспользоваться командой p11tool из GnuTLS <https://gnutls.org/>:

p11tool --provider /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so --list-all

Пример команды#

Получение открытого ключа асимметричной пары ключей на NetHSM:

openssl pkey -engine pkcs11 -inform ENGINE -in "pkcs11:object=webserver;type=public" -pubout

Провайдер#

Интерфейс OpenSSL provider - это новый способ реализации пользовательских бэкендов для OpenSSL. Бэкенд pkcs11-provider пока находится на ранней стадии разработки.

Вам необходимо настроить модуль PKCS#11, следуя этой инструкции.

Установите провайдера. Для Fedora существует пакет с именем pkcs11-provider. Для других дистрибутивов Linux вам потребуется собрать его из исходных текстов.

Затем необходимо настроить OpenSSL на использование провайдера. Это делается путем добавления следующих строк в файл openssl.cnf:

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
pkcs11 = pkcs11_sect

[pkcs11_sect]
module = /home/sautax/git/pkcs11-provider/src/.libs/pkcs11.so
pkcs11-module-path = /usr/lib/libnethsm_pkcs11.so
activate = 1

Установите module на путь установленного провайдера, а pkcs11-module-path - на путь установленного модуля PKCS#11.

Если вы хотите установить NetHSM в качестве провайдера по умолчанию, вы можете добавить default = pkcs11 в раздел provider_sect.

Примечание

Вы можете указать OpenSSL путь к конфигурационному файлу OpenSSL с помощью переменной окружения OPENSSL_CONF.

Предупреждение

Если основной конфигурационный файл OpenSSL будет изменен таким образом, чтобы содержать только эти строки, это может привести к поломке других программ, использующих OpenSSL. Поэтому, возможно, потребуется создать отдельный конфигурационный файл для провайдера.

Затем можно использовать ключи на NetHSM с помощью URI PKCS#11, например:

openssl pkey -provider pkcs11 -in "pkcs11:object=rsakey" -pubout

Если в качестве провайдера по умолчанию установлен NetHSM, то аргумент -provider pkcs11 можно опустить.

Примечание

В настоящее время при ручном задании типа ключа в URI провайдер не сможет найти ключ. Вы можете опустить в URI часть ;type=private или ;type=public, чтобы все заработало.