PKCS#11 med pkcs11-tool#

Denne vejledning beskriver brugen af PKCS#11-driveren til NetHSM. Vejledningen anvender værktøjer fra OpenSC. Se venligst deres dokumentation for at lære, hvordan du bruger dem på dit operativsystem.

Vigtigt

Denne driver er stadig en tidlig Proof of Concept-implementering, som kun implementerer de funktioner, der er nødvendige for at drive TLS-servere.

Installation#

Installer et forkompileret bibliotek#

  1. Download et arkiv med den seneste version fra releases-siden i arkivet. Brug det arkiv, der indeholder navnet på dit operativsystem i titlen.

  2. Udpak filerne fra det downloadede arkiv med et arkiveringsprogram efter eget valg.

  3. Kopier det uddragne bibliotek til den respektive sti i dit operativsystem. Stien afhænger af din installation og konfiguration af OpenSC.

Kompilering fra kildekode#

Vigtigt

Denne driver kan kun kompileres med den officielle Go-kompiler. Du må ikke bruge GNU Go-kompileren (GCC-Go). Se venligst deres websted ` <https://go.dev/doc/install>` __ for at lære, hvordan du installerer den.

  1. Download et arkiv med den seneste version fra releases-siden i arkivet. Brug det arkiv med udgivelsen, der indeholder Source code i titlen.

  2. Udpak filerne fra det downloadede arkiv med et arkiveringsprogram efter eget valg.

  3. I mappen med den uddragne kildekode skal du udføre følgende kommando for at kompilere biblioteket.

    ./build.sh

  4. Kopier det uddragne bibliotek til den respektive sti i dit operativsystem. Stien afhænger af din installation og konfiguration af OpenSC.

Konfiguration#

Konfigurationsfilen p11nethsm.conf er påkrævet og bruges til at konfigurere forbindelsen mellem PKCS#11-driveren og NetHSM.

Et eksempel på en konfigurationsfil ser således ud.

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"

Ændre konfigurationsfilen p11nethsm.conf i overensstemmelse med dit miljø.

Konfigurationsfilen kan indeholde flere slots i arrayet slots. Slots repræsenterer flere NetHSM-implementeringer. Feltet label for et slot skal indeholde et entydigt navn. Nøglerne url, user og password er obligatoriske. Af sikkerhedshensyn anbefales det at angive adgangskoden i en miljøvariabel. I den forbindelse skal env:NETHSM_PASS overføres i password-nøglen, hvor NETHSM_PASS er navnet på den miljøvariabel, der indeholder adgangskoden. Nøglen certSHA256 skal indstilles, hvis TLS-certifikatet ikke er underskrevet af en certifikatudstedende myndighed (CA), der findes i operativsystemets certifikatlager.

Konfigurationsfilen skal gemmes enten i følgende stier eller i den mappe, som programmet udføres i.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Nøglehåndtering#

Info#

Viser oplysninger om cryptoki versionen og PKCS#11 driveren.

$ 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)

Liste slots#

Oplysninger om de tilgængelige slots. De anførte slots afhænger af konfigurationen af slots arrayet i konfigurationsfilen p11nethsm.conf. Hvis du vil vide mere om konfigurationen af slots, henvises til kapitel Configuration.

$ 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

Bemærk

Hvis din konfiguration understøtter mere end ét slot, skal du måske tilføje indstillingen –slot <arg> i pkcs11-tool-kommandoer for at bruge det rigtige slot.

Generere nøgler#

Generer et nøglepar, og gem det på NetHSM.

Bemærk

PKCS#11-driveren understøtter i øjeblikket ikke denne funktion. Et nøglepar kan genereres med nitropy eller en REST API-forespørgsel. Hvis du vil vide mere om, hvordan du genererer en nøgle, kan du læse mere i kapitel Generer nøgle.

Liste over nøgler#

Viser oplysninger om nøgler og certifikater 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 nøgler#

Læs nøgler og certifikater fra Key Store på en NetHSM. Det er ikke muligt at læse private nøgler fra NetHSM’en.

Den offentlige nøgle for et nøglepar kan læses på følgende måde.

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

Certifikatet for et nøglepar kan læses på følgende måde.

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

De returnerede certifikater eller offentlige nøgler er ASN.1-kodet. Dataene kan afkodes med værktøjet dumpasn1, da de indeholder data i DER-format. DER-formatet kan konverteres til PEM-format med OpenSSL.

Skriv taster#

Skriv nøgler og certifikater til Key Store på en NetHSM.

Den private nøgle for et nøglepar kan skrives på følgende måde.

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

Den offentlige nøgle for et nøglepar kan skrives på følgende måde.

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

Certifikatet for et nøglepar kan skrives på følgende måde.

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

Vigtigste operationer#

Krypter#

NetHSM kan ikke kryptere data med asymmetriske nøgler, men den leverer den offentlige nøgle, som kan bruges til kryptering. Se kapitel Show Key Details, eller hent nøglen som beskrevet i kapitel Read Keys <pkcs11_with_pkcs11.html#read-keys>, for at få mere at vide om, hvordan man henter den offentlige nøgle. I eksemplet antages den offentlige nøgle i filen public.pem.

Data kan krypteres med OpenSSL på følgende måde.

$ 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

Dekrypter#

NetHSM kan dekryptere data for en privat nøgle, der er gemt i Key Store på NetHSM. I dette eksempel anvendes den krypterede meddelelse fra det foregående kapitel Krypter.

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

NetHSM rulez!

Skilt#

NetHSM kan signere data for en privat nøgle, der er gemt i Key Store på NetHSM. For signaturer med en RSA- og ECDSA-nøgle skal der først beregnes en digest.

For at beregne et digest kræves dataene først. En meddelelse oprettes på følgende måde.

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

Den oprettede signatur kan verificeres med OpenSSL på følgende måde.

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