PKCS#11 с помощью pkcs11-tool#

Это руководство описывает использование драйвера PKCS#11 для NetHSM. В руководстве используются инструменты из OpenSC. Пожалуйста, обратитесь к их документации, чтобы узнать, как использовать их в вашей операционной системе.

Важно

Этот драйвер все еще является ранней реализацией Proof of Concept, которая реализует только функции, необходимые для работы TLS-серверов.

Установка#

Установите предварительно скомпилированную библиотеку#

  1. Загрузите архив с последним выпуском со страницы releases репозитория. Используйте архив с релизом, в заголовке которого содержится название вашей операционной системы.

  2. Извлеките файлы из загруженного архива с помощью выбранной вами программы архивации.

  3. Скопируйте извлеченную библиотеку в соответствующий путь в вашей операционной системе. Путь зависит от установки и конфигурации OpenSC.

Компиляция из исходного кода#

Важно

Этот драйвер может быть скомпилирован только с помощью официального компилятора Go. Не используйте компилятор GNU Go (GCC-Go). Пожалуйста, обратитесь к их сайту ` <https://go.dev/doc/install>` __, чтобы узнать, как его установить.

  1. Скачайте архив с последним релизом со страницы releases репозитория. Используйте архив с релизом, в названии которого содержится Source code.

  2. Извлеките файлы из загруженного архива с помощью выбранной вами программы архивации.

  3. В директории с извлеченным исходным кодом выполните следующую команду для компиляции библиотеки.

    ./build.sh

  4. Скопируйте извлеченную библиотеку в соответствующий путь в вашей операционной системе. Путь зависит от установки и конфигурации OpenSC.

Конфигурация#

Конфигурационный файл p11nethsm.conf необходим и используется для настройки соединения между драйвером PKCS#11 и NetHSM.

Пример конфигурационного файла выглядит следующим образом.

YAML 1.1
---
p11nethsm:
  logfile: /tmp/p11nethsm.log
  maxsessioncount: 5
  debug: true
  slots:
  - label: NetHSM1
    description: NetHSM Zone A
    url: "https://nethsmdemo.nitrokey.com/api/v1"
    # certSHA256:
    #   - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
    user: "operator"
    password: "env:NETHSM_PASS"

Измените конфигурационный файл p11nethsm.conf в соответствии с вашим окружением.

Конфигурационный файл может включать несколько слотов в массиве slots. Слоты представляют несколько развертываний NetHSM. Поле label слота должно содержать уникальное имя. Ключи url, user и password являются обязательными. В целях безопасности рекомендуется передавать пароль в переменной окружения. Для этого в ключе password передается env:NETHSM_PASS, где NETHSM_PASS - имя переменной окружения, содержащей пароль. Ключ certSHA256 необходимо установить, если сертификат TLS не подписан центром сертификации (ЦС), содержащимся в хранилище сертификатов операционной системы.

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

  • $HOME/.nitrokey

  • /etc/nitrokey/

Управление ключами#

Информация#

Показать информацию о версии cryptoki и драйвере PKCS#11.

$ pkcs11-tool --module p11nethsm.so --show-info

Cryptoki version 2.40
Manufacturer     Nitrokey GmbH
Library          NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)

Список слотов#

Информация о доступных слотах. Перечисленные слоты зависят от конфигурации массива слотов в конфигурационном файле p11nethsm.conf. Чтобы узнать больше о конфигурации слотов, обратитесь к главе Конфигурация.

$ pkcs11-tool --module p11nethsm.so --list-slots

Available slots:
Slot 0 (0x0): NetHSM Zone A
  token label        : NetHSM1
  token manufacturer : Nitrokey GmbH
  token model        : NetHSM
  token flags        : rng, token initialized, PIN initialized, readonly
  hardware version   : 0.1
  firmware version   : 0.1
  serial num         : 0
  pin min/max        : 3/256

Примечание

Если ваша конфигурация поддерживает более одного слота, возможно, вам придется добавить опцию –slot <arg> в команды pkcs11-tool, чтобы использовать нужный слот.

Генерировать ключи#

Сгенерируйте пару ключей и сохраните ее на NetHSM.

Примечание

В настоящее время драйвер PKCS#11 не поддерживает эту функцию. Пара ключей может быть сгенерирована с помощью nitropy или запроса REST API. Чтобы узнать больше о том, как сгенерировать ключ, обратитесь к главе Generate Key.

Ключи списка#

Показать информацию о ключах и сертификатах в хранилище ключей ** на NetHSM.

$ pkcs11-tool --module p11nethsm.so --list-objects

Using slot 0 with a present token (0x0)
Private Key Object; RSA
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      none
  Access:     none

Читать ключи#

Считывание ключей и сертификатов из хранилища ключей ** на NetHSM. Невозможно считывать закрытые ключи с NetHSM.

Открытый ключ пары ключей может быть прочитан следующим образом.

$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key

Сертификат пары ключей можно прочитать следующим образом.

$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key

Возвращаемые сертификаты или открытые ключи имеют кодировку ASN.1. Данные могут быть декодированы с помощью инструмента dumpasn1, поскольку они содержат данные в формате DER. Формат DER может быть преобразован в формат PEM с помощью OpenSSL.

Ключи для записи#

Запись ключей и сертификатов в хранилище ключей ** на NetHSM.

Закрытый ключ пары ключей можно записать следующим образом.

$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey

Открытый ключ пары ключей можно записать следующим образом.

$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey

Сертификат пары ключей можно записать следующим образом.

$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey

Основные операции#

Зашифровать#

NetHSM не может шифровать данные с помощью асимметричных ключей, но он предоставляет открытый ключ, который может быть использован для шифрования. Обратитесь к главе Show Key Details, или получите ключ, как описано в главе Read Keys <pkcs11_with_pkcs11.html#read-keys>, чтобы узнать больше о том, как получить открытый ключ. В примере предполагается, что открытый ключ находится в файле public.pem.

Данные могут быть зашифрованы с помощью OpenSSL следующим образом.

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
   -inkey public.pem \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha512 \
   -pkeyopt rsa_mgf1_md:sha512 \
   -out encrypted.data

Расшифровать#

NetHSM может расшифровывать данные для закрытого ключа, хранящегося в Key Store на NetHSM. В данном примере используется зашифрованное сообщение из предыдущей главы Encrypt.

$ pkcs11-tool --module p11nethsm.so --decrypt \
   --mechanism RSA-PKCS-OAEP \
   --input-file encrypted.data \
   --label myFirstKey \
   --hash-algorithm SHA512

NetHSM rulez!

Подпишитесь#

NetHSM может подписывать данные закрытым ключом, хранящимся в Key Store на NetHSM. Для подписей с ключом RSA и ECDSA сначала необходимо вычислить дайджест.

Для вычисления дайджеста сначала необходимо получить данные. Сообщение создается следующим образом.

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
   --sign \
   --mechanism SHA512-RSA-PKCS-PSS \
   --output-file sig.data \
   --label myFirstKey

Созданная подпись может быть проверена с помощью OpenSSL следующим образом.

$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
   -verify public.pem \
   -sha512 \
   -sigopt rsa_padding_mode:pss \
   -sigopt rsa_pss_saltlen:-1 \
   -signature sig.data