PKCS#11 med pkcs11-tool#

Den här guiden beskriver användningen av PKCS#11-drivrutinen för NetHSM. I guiden används verktyg från OpenSC. Se deras dokumentation för att lära dig hur du använder dem i ditt operativsystem.

Viktigt

Den här drivrutinen är fortfarande en tidig Proof of Concept-implementation som endast implementerar de funktioner som är nödvändiga för att driva TLS-servrar.

Installation#

Installera förkompilerat bibliotek#

  1. Ladda ner ett arkiv med den senaste versionen från sidan releases i arkivet. Använd det arkiv som innehåller namnet på ditt operativsystem i titeln.

  2. Extrahera filerna från det nedladdade arkivet med ett valfritt arkiveringsprogram.

  3. Kopiera det utdragna biblioteket till respektive sökväg i ditt operativsystem. Sökvägen beror på din installation och konfiguration av OpenSC.

Kompilera från källkoden#

Viktigt

Den här drivrutinen kan endast kompileras med den officiella Go-kompilatorn. Använd inte GNU Go-kompilatorn (GCC-Go). Se deras webbplats ` <https://go.dev/doc/install>` __ för att lära dig hur du installerar den.

  1. Ladda ner ett arkiv med den senaste versionen från sidan releases i arkivet. Använd det arkiv som innehåller Source code i titeln.

  2. Extrahera filerna från det nedladdade arkivet med ett valfritt arkiveringsprogram.

  3. I katalogen med den utdragna källkoden utför du följande kommando för att kompilera biblioteket.

    ./build.sh

  4. Kopiera det utdragna biblioteket till respektive sökväg i ditt operativsystem. Sökvägen beror på din installation och konfiguration av OpenSC.

Konfiguration#

Konfigurationsfilen p11nethsm.conf krävs och används för att konfigurera anslutningen mellan PKCS#11-drivrutinen och NetHSM.

En exempelkonfigurationsfil ser ut på följande sätt.

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"

Ändra konfigurationsfilen p11nethsm.conf i enlighet med din miljö.

Konfigurationsfilen kan innehålla flera slots, i matrisen slots. Spåren representerar flera NetHSM-installationer. Fältet label för en slot måste innehålla ett unikt namn. Nycklarna url, user och password är obligatoriska. Av säkerhetsskäl rekommenderas att lösenordet skickas i en miljövariabel. För detta ändamål skickas env:NETHSM_PASS i nyckeln password, där NETHSM_PASS är namnet på den miljövariabel som innehåller lösenordet. Nyckeln certSHA256 måste ställas in om TLS-certifikatet inte är signerat av en certifikatutfärdare (CA) som finns i operativsystemets certifikatarkiv.

Konfigurationsfilen måste sparas antingen i följande sökvägar eller i den katalog där programmet körs.

  • $HOME/.nitrokey

  • /etc/nitrokey/`

Nyckelhantering#

Info#

Visa information om cryptoki-versionen och PKCS#11-drivrutinen.

$ 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 över spelautomater#

Information om de tillgängliga platserna. De listade facken beror på konfigurationen av facken i konfigurationsfilen p11nethsm.conf. Om du vill veta mer om konfigurationen av slots hänvisar vi till kapitel Konfiguration.

$ 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

Observera

Om din konfiguration har stöd för mer än en slot kan du behöva lägga till alternativet –slot <arg> i pkcs11-tool-kommandon för att använda rätt slot.

Generera nyckel#

Generera ett nyckelpar och lagra det på NetHSM.

Observera

PKCS#11-drivrutinen har för närvarande inte stöd för den här funktionen. Ett nyckelpar kan genereras med nitropy eller en REST API-förfrågan. Om du vill veta mer om hur man genererar en nyckel, se kapitel Generera nyckel.

Lista nycklar#

Visa information om nycklar och certifikat i Key Store på en 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

Läs nycklar#

Läs nycklar och certifikat från Key Store på en NetHSM. Det är inte möjligt att läsa privata nycklar från NetHSM.

Den offentliga nyckeln för ett nyckelpar kan läsas på följande sätt.

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

Certifikatet för ett nyckelpar kan läsas på följande sätt.

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

De returnerade certifikaten eller offentliga nycklarna är ASN.1-kodade. Uppgifterna kan avkodas med verktyget dumpasn1 eftersom de innehåller uppgifter i DER-format. DER-formatet kan konverteras till PEM-format med OpenSSL.

Skriv nycklar#

Skriv nycklar och certifikat till Key Store på en NetHSM.

Den privata nyckeln för ett nyckelpar kan skrivas på följande sätt.

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

Den offentliga nyckeln för ett nyckelpar kan skrivas på följande sätt.

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

Certifikatet för ett nyckelpar kan skrivas på följande sätt.

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

Viktiga verksamheter#

Kryptera#

NetHSM kan inte kryptera data med asymmetriska nycklar, men tillhandahåller den offentliga nyckeln som kan användas för kryptering. Se kapitel Show Key Details, eller hämta nyckeln enligt beskrivningen i kapitel Read Keys <pkcs11_with_pkcs11.html#read-keys>, för att lära dig mer om hur du hämtar den offentliga nyckeln. Exemplet utgår från den offentliga nyckeln i filen public.pem.

Data kan krypteras med OpenSSL på följande sätt.

$ 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

Avkryptera#

NetHSM kan dekryptera data för en privat nyckel som lagras i Key Store på NetHSM. I det här exemplet används det krypterade meddelandet från föregående kapitel Encrypt.

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

NetHSM rulez!

Skylt#

NetHSM kan signera data för en privat nyckel som lagras i Key Store på NetHSM. För signaturer med en RSA- och ECDSA-nyckel måste en digest beräknas först.

För att beräkna en digest krävs först data. Ett meddelande skapas på följande sätt.

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

Den skapade signaturen kan verifieras med OpenSSL på följande sätt.

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