PKCS#11 z pkcs11-tool#

Ten przewodnik opisuje użycie sterownika PKCS#11 dla NetHSM. W przewodniku wykorzystano narzędzia z OpenSC. Zapoznaj się z ich dokumentacją, aby dowiedzieć się jak używać ich w swoim systemie operacyjnym.

Ważne

Ten sterownik to wciąż wczesna implementacja Proof of Concept, która implementuje tylko te funkcje, które są niezbędne do obsługi serwerów TLS.

Instalacja#

Zainstaluj prekompilowaną bibliotekę#

  1. Pobierz archiwum z najnowszym wydaniem ze strony releases repozytorium. Użyj archiwum wydania, które zawiera nazwę twojego systemu operacyjnego w tytule.

  2. Wypakuj pliki z pobranego archiwum za pomocą wybranego przez siebie programu archiwizującego.

  3. Skopiuj wyodrębnioną bibliotekę do odpowiedniej ścieżki w Twoim systemie operacyjnym. Ścieżka zależy od instalacji i konfiguracji OpenSC.

Kompilacja z kodu źródłowego#

Ważne

Ten sterownik może być kompilowany tylko za pomocą oficjalnego kompilatora Go. Nie należy używać kompilatora GNU Go (GCC-Go). Proszę odnieść się do ich strony ` <https://go.dev/doc/install>` __, aby dowiedzieć się jak go zainstalować.

  1. Pobierz archiwum z najnowszym wydaniem ze strony releases repozytorium. Użyj archiwum wydania, które zawiera Kod źródłowy w tytule.

  2. Wypakuj pliki z pobranego archiwum za pomocą wybranego przez siebie programu archiwizującego.

  3. W katalogu z rozpakowanym kodem źródłowym wykonaj następujące polecenie, aby skompilować bibliotekę.

    ./build.sh

  4. Skopiuj wyodrębnioną bibliotekę do odpowiedniej ścieżki w Twoim systemie operacyjnym. Ścieżka zależy od instalacji i konfiguracji OpenSC.

Konfiguracja#

Plik konfiguracyjny p11nethsm.conf jest wymagany i służy do konfiguracji połączenia pomiędzy sterownikiem PKCS#11 a NetHSM.

Przykładowy plik konfiguracyjny wygląda następująco.

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"

Zmodyfikuj plik konfiguracyjny p11nethsm.conf zgodnie ze swoim środowiskiem.

Plik konfiguracyjny może zawierać wiele slotów, wewnątrz tablicy slots. Sloty reprezentują wiele wdrożeń NetHSM. Pole label slotu musi zawierać unikalną nazwę. Klucze url, user i password są obowiązkowe. Ze względów bezpieczeństwa zaleca się przekazanie hasła w zmiennej środowiskowej. W tym celu env:NETHSM_PASS jest przekazywane w kluczu password, gdzie NETHSM_PASS jest nazwą zmiennej środowiskowej zawierającej hasło. Klucz certSHA256 musi być ustawiony, jeżeli certyfikat TLS nie jest podpisany przez Certificate Authority (CA) znajdujący się w magazynie certyfikatów systemu operacyjnego.

Plik konfiguracyjny musi być zapisany albo w poniższych ścieżkach albo w katalogu, w którym jest wykonywana aplikacja.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Zarządzanie kluczami#

Info#

Pokaż informacje o wersji cryptoki, oraz sterownika 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)

Lista slotów#

Informacja o dostępnych slotach. Wymienione sloty zależą od konfiguracji tablicy slotów w pliku konfiguracyjnym p11nethsm.conf. Aby dowiedzieć się więcej o konfiguracji slotów, zapoznaj się z rozdziałem Konfiguracja.

$ 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

Informacja

Jeśli twoja konfiguracja obsługuje więcej niż jedno gniazdo, być może będziesz musiał dodać opcję –slot <arg> w poleceniach pkcs11-tool, aby użyć właściwego.

Wygeneruj klucz#

Wygeneruj parę kluczy i zapisz ją w pamięci NetHSM.

Informacja

Sterownik PKCS#11 obecnie nie obsługuje tej funkcji. Para kluczy może być wygenerowana za pomocą nitropy lub żądania REST API. Aby dowiedzieć się więcej o tym, jak wygenerować klucz, zapoznaj się z rozdziałem Generate Key.

Lista kluczy#

Wyświetlanie informacji o kluczach i certyfikatach w sklepie Key Store w urządzeniu 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

Czytaj Klucze#

Odczyt kluczy i certyfikatów z magazynu kluczy Key Store w urządzeniu NetHSM. Nie ma możliwości odczytu kluczy prywatnych z urządzenia NetHSM.

Klucz publiczny pary kluczy można odczytać w następujący sposób.

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

Certyfikat pary kluczy można odczytać w następujący sposób.

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

Zwracane certyfikaty lub klucze publiczne są zakodowane w ASN.1. Dane te można zdekodować za pomocą narzędzia dumpasn1, ponieważ zawierają one dane w formacie DER. Format DER może zostać przekonwertowany do formatu PEM za pomocą OpenSSL.

Napisz klucze#

Zapisywanie kluczy i certyfikatów w sklepie z kluczami Key Store w urządzeniu NetHSM.

Klucz prywatny pary kluczy można zapisać w następujący sposób.

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

Klucz publiczny pary kluczy można zapisać w następujący sposób.

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

Certyfikat pary kluczy można zapisać w następujący sposób.

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

Kluczowe operacje#

Szyfruj#

NetHSM nie może szyfrować danych za pomocą kluczy asymetrycznych, ale udostępnia klucz publiczny, który może być użyty do szyfrowania. Więcej informacji na temat pobierania klucza publicznego można znaleźć w rozdziale Show Key Details, lub pobrać klucz zgodnie z opisem w rozdziale Read Keys <pkcs11_with_pkcs11.html#read-keys>. Przykład zakłada istnienie klucza publicznego w pliku public.pem.

Dane można zaszyfrować za pomocą OpenSSL w następujący sposób.

$ 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

Odszyfrować#

NetHSM może odszyfrować dane za pomocą klucza prywatnego przechowywanego w sklepie Key Store na dysku NetHSM. W tym przykładzie użyto zaszyfrowanej wiadomości z poprzedniego rozdziału Encrypt.

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

NetHSM rulez!

Podpisać#

NetHSM może podpisywać dane kluczem prywatnym przechowywanym w Key Store na NetHSM. W przypadku podpisu kluczem RSA i ECDSA należy najpierw obliczyć skrót.

Do obliczenia skrótu potrzebne są najpierw dane. Wiadomość tworzona jest w następujący sposób.

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

Utworzony podpis można zweryfikować za pomocą OpenSSL w następujący sposób.

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