PKCS#11 pomocí nástroje pkcs11-tool#

Tato příručka popisuje použití ovladače PKCS#11 pro NetHSM. Příručka využívá nástroje z OpenSC. Informace o jejich použití ve vašem operačním systému naleznete v jejich dokumentaci.

Důležité

Tento ovladač je zatím ranou zkušební verzí, která implementuje pouze funkce nezbytné pro provoz serverů TLS.

Instalace#

Instalace předkompilované knihovny#

  1. Stáhněte si archiv s nejnovější verzí ze stránky releases úložiště. Použijte archiv s vydáním, který v názvu obsahuje název vašeho operačního systému.

  2. Rozbalte soubory ze staženého archivu pomocí zvoleného archivačního programu.

  3. Zkopírujte rozbalenou knihovnu do příslušné cesty ve vašem operačním systému. Cesta závisí na vaší instalaci a konfiguraci OpenSC.

Kompilace ze zdrojového kódu#

Důležité

Tento ovladač lze zkompilovat pouze pomocí oficiálního kompilátoru Go. Nepoužívejte kompilátor GNU Go (GCC-Go). Informace o tom, jak jej nainstalovat, naleznete na jejich webových stránkách ` <https://go.dev/doc/install>` __.

  1. Stáhněte si archiv s nejnovější verzí ze stránky releases úložiště. Použijte archiv s verzí, která obsahuje v názvu Zdrojový kód.

  2. Rozbalte soubory ze staženého archivu pomocí zvoleného archivačního programu.

  3. V adresáři s rozbaleným zdrojovým kódem spusťte následující příkaz pro kompilaci knihovny.

    ./build.sh

  4. Zkopírujte rozbalenou knihovnu do příslušné cesty ve vašem operačním systému. Cesta závisí na vaší instalaci a konfiguraci OpenSC.

Konfigurace#

Konfigurační soubor p11nethsm.conf je vyžadován a slouží ke konfiguraci spojení mezi ovladačem PKCS#11 a NetHSM.

Příklad konfiguračního souboru vypadá 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í soubor p11nethsm.conf podle svého prostředí.

Konfigurační soubor může obsahovat více slotů v poli slots. Sloty představují více nasazení NetHSM. Pole label slotu musí obsahovat jedinečný název. Klíče url, user a password jsou povinné. Z bezpečnostních důvodů se doporučuje předávat heslo v proměnné prostředí. Za tímto účelem se v klíči password předává env:NETHSM_PASS, kde NETHSM_PASS je název proměnné prostředí obsahující heslo. Klíč certSHA256 je třeba nastavit, pokud certifikát TLS není podepsán certifikační autoritou (CA) obsaženou v úložišti certifikátů operačního systému.

Konfigurační soubor musí být uložen buď v následujících cestách, nebo v adresáři, ve kterém je aplikace spuštěna.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Správa klíčů#

Informace#

Zobrazí informace o verzi nástroje cryptoki a ovladače 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)

Seznam slotů#

Informace o dostupných slotech. Uvedené sloty závisí na konfiguraci pole slotů v konfiguračním souboru p11nethsm.conf. Více informací o konfiguraci slotů naleznete v kapitole Konfigurace.

$ 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

Pokud vaše konfigurace podporuje více než jeden slot, možná budete muset v příkazech pkcs11-tool přidat volbu –slot <arg>, abyste použili ten správný.

Generování klíčů#

Vygenerujte pár klíčů a uložte jej do zařízení NetHSM.

Poznámka

Ovladač PKCS#11 tuto funkci v současné době nepodporuje. Pár klíčů lze vygenerovat pomocí nitropy nebo požadavku REST API. Více informací o generování klíče naleznete v kapitole Generování klíče.

Seznam klíčů#

Zobrazení informací o klíčích a certifikátech v úložišti klíčů ** v zařízení 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

Přečtěte si klíče#

Čtení klíčů a certifikátů z úložiště klíčů ** v zařízení NetHSM. Soukromé klíče není možné z NetHSM číst.

Veřejný klíč páru klíčů lze přečíst následujícím způsobem.

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

Certifikát páru klíčů lze přečíst takto.

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

Vrácené certifikáty nebo veřejné klíče jsou kódovány v ASN.1. Data lze dekódovat pomocí nástroje dumpasn1, protože obsahují data ve formátu DER. Formát DER lze pomocí OpenSSL převést na formát PEM.

Klíče pro zápis#

Zápis klíčů a certifikátů do úložiště klíčů ** v zařízení NetHSM.

Soukromý klíč páru klíčů lze zapsat takto.

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

Veřejný klíč páru klíčů lze zapsat takto.

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

Certifikát páru klíčů lze zapsat takto.

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

Klíčové operace#

Šifrování#

NetHSM nemůže šifrovat data asymetrickými klíči, ale poskytuje veřejný klíč, který lze použít k šifrování. Více informací o tom, jak získat veřejný klíč, naleznete v kapitole Show Key Details, nebo si klíč načtěte podle popisu v kapitole Read Keys <pkcs11_with_pkcs11.html#read-keys>. Příklad předpokládá veřejný klíč v souboru public.pem.

Data lze šifrovat pomocí protokolu OpenSSL následujícím způsobem.

$ 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šifrování#

Zařízení NetHSM může dešifrovat data pro soukromý klíč uložený v úložišti klíčů ** v zařízení NetHSM. Tento příklad používá zašifrovanou zprávu z předchozí kapitoly Šifrování.

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

NetHSM rulez!

Podepsat#

Zařízení NetHSM může podepisovat data pro soukromý klíč uložený v úložišti Key Store v zařízení NetHSM. Pro podpisy s klíčem RSA a ECDSA musí být nejprve vypočten digest.

Pro výpočet digestu je nejprve nutné získat data. Zpráva se vytvoří takto.

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

Vytvořený podpis lze ověřit pomocí OpenSSL následujícím způsobem.

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