PKCS#11 met pkcs11-tool#

Deze gids beschrijft het gebruik van het PKCS#11-stuurprogramma voor de NetHSM. De gids gebruikt gereedschappen van OpenSC. Raadpleeg hun documentatie om te leren hoe ze te gebruiken op uw besturingssysteem.

Belangrijk

Dit stuurprogramma is nog een vroege Proof of Concept-implementatie die alleen de functies implementeert die nodig zijn voor de werking van TLS-servers.

Installatie#

Voorgecompileerde bibliotheek installeren#

  1. Download een archief met de laatste release van de releases pagina van de repository. Gebruik het release-archief met de naam van uw besturingssysteem in de titel.

  2. Pak de bestanden uit het gedownloade archief uit met een archiveringsprogramma naar keuze.

  3. Kopieer de uitgepakte library naar het respectievelijke pad in uw besturingssysteem. Het pad hangt af van uw installatie en configuratie van OpenSC.

Compileren vanuit de broncode#

Belangrijk

Dit stuurprogramma kan alleen worden gecompileerd met de officiële Go-compiler. Gebruik niet de GNU Go compiler (GCC-Go). Raadpleeg hun website om te leren hoe deze te installeren.

  1. Download een archief met de laatste release van de releases pagina van de repository. Gebruik het release-archief met Broncode in de titel.

  2. Pak de bestanden uit het gedownloade archief uit met een archiveringsprogramma naar keuze.

  3. In de map met de uitgepakte broncode voert u het volgende commando uit om de bibliotheek te compileren.

    ./build.sh

  4. Kopieer de uitgepakte library naar het respectievelijke pad in uw besturingssysteem. Het pad hangt af van uw installatie en configuratie van OpenSC.

Configuratie#

Het configuratiebestand p11nethsm.conf is vereist en wordt gebruikt om de verbinding tussen het PKCS#11-stuurprogramma en de NetHSM te configureren.

Een voorbeeld van een configuratiebestand ziet er als volgt uit.

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"

Pas het configuratiebestand p11nethsm.conf aan volgens uw omgeving.

Het configuratiebestand kan meerdere slots bevatten, in de slots array. De slots vertegenwoordigen meerdere NetHSM-installaties. Het label veld van een slot moet een unieke naam bevatten. De url, user, en password sleutels zijn verplicht. Om veiligheidsredenen is het aanbevolen om het wachtwoord door te geven in een omgevingsvariabele. Hiervoor wordt env:NETHSM_PASS doorgegeven in de password sleutel, waarbij NETHSM_PASS de naam is van de omgevingsvariabele die het wachtwoord bevat. De certSHA256 sleutel moet worden ingesteld als het TLS-certificaat niet is ondertekend door een Certificate Authority (CA) in de certificatenopslag van het besturingssysteem.

Het configuratiebestand moet worden opgeslagen in de volgende paden of in de map waarin de toepassing wordt uitgevoerd.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Sleutelbeheer#

Info#

Toon informatie over de cryptoki versie, en het PKCS#11 stuurprogramma.

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

Lijst Slots#

De informatie over de beschikbare slots. De vermelde slots zijn afhankelijk van de configuratie van de slots array in het configuratiebestand p11nethsm.conf. Meer informatie over de configuratie van slots vindt u in het hoofdstuk Configuratie.

$ 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

Notitie

Als uw configuratie meer dan één slot ondersteunt, moet u misschien de –slot <arg> optie toevoegen in pkcs11-tool commando’s om de juiste te gebruiken.

Genereer sleutels#

Genereer een sleutelpaar en sla het op in de NetHSM.

Notitie

Het PKCS#11-stuurprogramma ondersteunt deze functie momenteel niet. Een sleutelpaar kan worden gegenereerd met nitropy of een REST API-verzoek. Meer informatie over het genereren van een sleutel vindt u in het hoofdstuk Sleutel genereren.

Lijst Sleutels#

Informatie weergeven over de sleutels en certificaten in de Key Store op een 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

Sleutels lezen#

Lezen van sleutels en certificaten van de Key Store op een NetHSM. Het is niet mogelijk om privésleutels van de NetHSM te lezen.

De openbare sleutel van een sleutelpaar kan als volgt worden gelezen.

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

Het certificaat van een sleutelpaar kan als volgt worden gelezen.

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

De geretourneerde certificaten of openbare sleutels zijn ASN.1-gecodeerd. De gegevens kunnen worden gedecodeerd met de tool dumpasn1, aangezien ze gegevens in DER-formaat bevatten. Het DER-formaat kan worden omgezet in PEM-formaat met OpenSSL.

Schrijf toetsen#

Schrijf sleutels en certificaten naar de Key Store op een NetHSM.

De particuliere sleutel van een sleutelpaar kan als volgt worden geschreven.

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

De openbare sleutel van een sleutelpaar kan als volgt worden geschreven.

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

Het certificaat van een sleutelpaar kan als volgt worden geschreven.

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

Belangrijkste operaties#

Versleutel#

De NetHSM kan geen gegevens versleutelen met asymmetrische sleutels, maar levert de openbare sleutel die kan worden gebruikt voor versleuteling. Zie hoofdstuk Toon sleuteldetails, of haal de sleutel op zoals beschreven in hoofdstuk Lees sleutels <pkcs11_met_pkcs11.html#lees-sleutels>, om meer te leren over hoe de publieke sleutel op te halen. Het voorbeeld gaat uit van de publieke sleutel in het bestand public.pem.

Gegevens kunnen als volgt worden gecodeerd met OpenSSL.

$ 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

Ontcijfer#

De NetHSM kan gegevens decoderen voor een privésleutel die is opgeslagen in de Sleutelopslag op de NetHSM. Dit voorbeeld gebruikt het versleutelde bericht uit het vorige hoofdstuk Coderen.

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

NetHSM rulez!

Teken#

De NetHSM kan gegevens ondertekenen voor een private sleutel die is opgeslagen in de Key Store op de NetHSM. Voor handtekeningen met een RSA- en ECDSA-sleutel moet eerst een digest worden berekend.

Om een digest te berekenen zijn eerst de gegevens nodig. Een bericht wordt als volgt aangemaakt.

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

De aangemaakte handtekening kan als volgt worden geverifieerd met OpenSSL.

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