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#
Download et arkiv med den seneste version fra releases-siden i arkivet. Brug det arkiv, der indeholder navnet på dit operativsystem i titlen.
Udpak filerne fra det downloadede arkiv med et arkiveringsprogram efter eget valg.
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.
Download et arkiv med den seneste version fra releases-siden i arkivet. Brug det arkiv med udgivelsen, der indeholder Source code i titlen.
Udpak filerne fra det downloadede arkiv med et arkiveringsprogram efter eget valg.
I mappen med den uddragne kildekode skal du udføre følgende kommando for at kompilere biblioteket.
./build.sh
./build.sh
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