PKCS#11 pomocou nástroja pkcs11-tool#

Táto príručka opisuje používanie ovládača PKCS#11 pre NetHSM. Príručka využíva nástroje z OpenSC. Pozrite si ich dokumentáciu, aby ste sa dozvedeli, ako ich používať vo vašom operačnom systéme.

Dôležité

Tento ovládač je ešte stále ranou implementáciou Proof of Concept, ktorá implementuje len funkcie potrebné na prevádzku serverov TLS.

Inštalácia#

Inštalácia predkompilovanej knižnice#

  1. Archív s najnovšou verziou si stiahnite zo stránky releases úložiska. Použite archív s vydaním, ktorý v názve obsahuje názov vášho operačného systému.

  2. Rozbaľte súbory zo stiahnutého archívu pomocou archivačného programu podľa vlastného výberu.

  3. Skopírujte rozbalenú knižnicu do príslušnej cesty vo vašom operačnom systéme. Cesta závisí od vašej inštalácie a konfigurácie OpenSC.

Kompilácia zo zdrojového kódu#

Dôležité

Tento ovládač je možné skompilovať len pomocou oficiálneho kompilátora Go. Nepoužívajte kompilátor GNU Go (GCC-Go). Informácie o tom, ako ho nainštalovať, nájdete na ich webovej stránke ` <https://go.dev/doc/install>` __.

  1. Archív s najnovšou verziou si stiahnite zo stránky releases úložiska. Použite archív s vydaním, ktorý v názve obsahuje Zdrojový kód.

  2. Rozbaľte súbory zo stiahnutého archívu pomocou archivačného programu podľa vlastného výberu.

  3. V adresári s rozbaleným zdrojovým kódom vykonajte nasledujúci príkaz na kompiláciu knižnice.

    ./build.sh

  4. Skopírujte rozbalenú knižnicu do príslušnej cesty vo vašom operačnom systéme. Cesta závisí od vašej inštalácie a konfigurácie OpenSC.

Konfigurácia#

Konfiguračný súbor p11nethsm.conf sa vyžaduje a používa sa na konfiguráciu spojenia medzi ovládačom PKCS#11 a NetHSM.

Príklad konfiguračného súboru vyzerá takto.

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"

Upravte konfiguračný súbor p11nethsm.conf podľa svojho prostredia.

Konfiguračný súbor môže obsahovať viacero slotov v poli slots. Sloty predstavujú viacero nasadení NetHSM. Pole label slotu musí obsahovať jedinečný názov. Kľúče url, user a password sú povinné. Z bezpečnostných dôvodov sa odporúča odovzdať heslo v premennej prostredia. Na tento účel sa v kľúči password odovzdáva env:NETHSM_PASS, kde NETHSM_PASS je názov premennej prostredia obsahujúcej heslo. Kľúč certSHA256 je potrebné nastaviť, ak certifikát TLS nie je podpísaný certifikačnou autoritou (CA), ktorá sa nachádza v úložisku certifikátov operačného systému.

Konfiguračný súbor je potrebné uložiť buď do nasledujúcich ciest, alebo do adresára, v ktorom sa aplikácia spúšťa.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Riadenie kľúčov#

Informácie#

Zobrazenie informácií o verzii cryptoki a ovládača 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)

Zoznam slotov#

Informácie o dostupných slotoch. Uvedené sloty závisia od konfigurácie poľa slotov v konfiguračnom súbore p11nethsm.conf. Viac informácií o konfigurácii slotov nájdete v kapitole Konfigurácia.

$ 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

Poznámka

Ak vaša konfigurácia podporuje viac ako jeden slot, možno budete musieť v príkazoch pkcs11-tool pridať možnosť –slot <arg>, aby ste použili ten správny.

Generovanie kľúča#

Vygenerujte pár kľúčov a uložte ho do NetHSM.

Poznámka

Ovládač PKCS#11 v súčasnosti túto funkciu nepodporuje. Pár kľúčov možno vygenerovať pomocou nitropy alebo požiadavky REST API. Viac informácií o generovaní kľúča nájdete v kapitole Generovanie kľúča.

Zoznam kľúčov#

Zobrazenie informácií o kľúčoch a certifikátoch v úložisku kľúčov ** v zariadení 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

Prečítajte si kľúče#

Čítanie kľúčov a certifikátov z úložiska kľúčov ** v zariadení NetHSM. Z NetHSM nie je možné čítať súkromné kľúče.

Verejný kľúč dvojice kľúčov možno prečítať takto.

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

Certifikát páru kľúčov možno čítať takto.

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

Vrátené certifikáty alebo verejné kľúče sú kódované v ASN.1. Údaje možno dekódovať pomocou nástroja dumpasn1, pretože obsahujú údaje vo formáte DER. Formát DER možno pomocou OpenSSL previesť na formát PEM.

Napísať kľúče#

Zápis kľúčov a certifikátov do úložiska kľúčov ** v zariadení NetHSM.

Súkromný kľúč dvojice kľúčov možno zapísať takto.

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

Verejný kľúč dvojice kľúčov možno zapísať takto.

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

Certifikát páru kľúčov možno zapísať takto.

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

Kľúčové operácie#

Šifrovanie#

NetHSM nemôže šifrovať údaje asymetrickými kľúčmi, ale poskytuje verejný kľúč, ktorý možno použiť na šifrovanie. Viac informácií o tom, ako načítať verejný kľúč, nájdete v kapitole Show Key Details (Zobraziť podrobnosti o kľúči) alebo načítajte kľúč podľa popisu v kapitole Read Keys (Čítanie kľúčov) <pkcs11_with_pkcs11.html#read-keys>. Príklad predpokladá verejný kľúč v súbore public.pem.

Údaje možno šifrovať pomocou OpenSSL takto.

$ 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

Dešifrovanie#

Zariadenie NetHSM môže dešifrovať údaje pre súkromný kľúč uložený v úložisku kľúčov ** v zariadení NetHSM. V tomto príklade je použitá zašifrovaná správa z predchádzajúcej kapitoly Šifrovanie.

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

NetHSM rulez!

Podpísať#

NetHSM môže podpisovať údaje pre súkromný kľúč uložený v Úložisku kľúčov v NetHSM. Pre podpisy s kľúčom RSA a ECDSA sa musí najprv vypočítať digest.

Na výpočet digestu sú najprv potrebné údaje. Správa sa vytvorí takto.

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

Vytvorený podpis možno overiť pomocou OpenSSL takto.

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