PKCS#11 con pkcs11-tool#

Questa guida descrive l’uso del driver PKCS#11 per NetHSM. La guida utilizza gli strumenti di OpenSC. Per sapere come utilizzarli sul proprio sistema operativo, consultare la relativa documentazione.

Importante

Questo driver è ancora una prima implementazione Proof of Concept che implementa solo le funzioni necessarie per il funzionamento dei server TLS.

Installazione#

Installare la libreria precompilata#

Scaricare un archivio con l’ultima release dalla pagina releases del repository. Utilizzate l’archivio di release che contiene il nome del vostro sistema operativo nel titolo.
Estrarre i file dall’archivio scaricato con un programma di archiviazione di propria scelta.
Copiare la libreria estratta nel rispettivo percorso del sistema operativo. Il percorso dipende dall’installazione e dalla configurazione di OpenSC.

Compilazione da codice sorgente#

Importante

Questo driver può essere compilato solo con il compilatore Go ufficiale. Non utilizzare il compilatore GNU Go (GCC-Go). Consultare il sito ` <https://go.dev/doc/install>` __ per sapere come installarlo.

Scaricare un archivio con l’ultima release dalla pagina releases del repository. Utilizzare l’archivio dei rilasci che contiene Codice sorgente nel titolo.
Estrarre i file dall’archivio scaricato con un programma di archiviazione di propria scelta.
Nella directory con il codice sorgente estratto, eseguire il seguente comando per compilare la libreria.
./build.sh
./build.sh
Copiare la libreria estratta nel rispettivo percorso del sistema operativo. Il percorso dipende dall’installazione e dalla configurazione di OpenSC.

Configurazione#

Il file di configurazione p11nethsm.conf è necessario e serve a configurare la connessione tra il driver PKCS#11 e NetHSM.

Un esempio di file di configurazione è il seguente.

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"

Modificare il file di configurazione p11nethsm.conf in base al proprio ambiente.

Il file di configurazione può includere più slot, all’interno dell’array slots. Gli slot rappresentano distribuzioni multiple di NetHSM. Il campo label di uno slot deve contenere un nome unico. Le chiavi url, user e password sono obbligatorie. Per motivi di sicurezza, si consiglia di passare la password in una variabile d’ambiente. A tale scopo, nella chiave password si passa env:NETHSM_PASS, dove NETHSM_PASS è il nome della variabile d’ambiente contenente la password. La chiave certSHA256 deve essere impostata se il certificato TLS non è firmato da un’autorità di certificazione (CA) contenuta nell’archivio dei certificati del sistema operativo.

Il file di configurazione deve essere salvato nei seguenti percorsi o nella directory di esecuzione dell’applicazione.

$HOME/.nitrokey
/etc/nitrokey/

Gestione delle chiavi#

Info#

Mostra informazioni sulla versione di cryptoki e sul driver 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)

Elenco slot#

Informazioni sugli slot disponibili. Gli slot elencati dipendono dalla configurazione dell’array di slot nel file di configurazione p11nethsm.conf. Per ulteriori informazioni sulla configurazione degli slot, consultare il capitolo `Configurazione <pkcs11_with_pkcs11-tool.html#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

Nota

Se la vostra configurazione supporta più di uno slot, forse dovrete aggiungere l’opzione -slot <arg> nei comandi di pkcs11-tool per usare quello giusto.

Generare le chiavi#

Generare una coppia di chiavi e memorizzarla sul NetHSM.

Nota

Il driver PKCS#11 attualmente non supporta questa funzione. Una coppia di chiavi può essere generata con nitropia o con una richiesta API REST. Per saperne di più su come generare una chiave, consultare il capitolo Generate Key.

Chiavi dell’elenco#

Mostra informazioni sulle chiavi e sui certificati presenti nel Key Store ** su un 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

Leggi le chiavi#

Leggere chiavi e certificati dal Key Store ** su un NetHSM. Non è possibile leggere le chiavi private dal NetHSM.

La chiave pubblica di una coppia di chiavi può essere letta come segue.

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

Il certificato di una coppia di chiavi può essere letto come segue.

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

I certificati o le chiavi pubbliche restituite sono codificate ASN.1. I dati possono essere decodificati con lo strumento dumpasn1, poiché contengono dati in formato DER. Il formato DER può essere convertito in formato PEM con OpenSSL.

Tasti di scrittura#

Scrivere chiavi e certificati nel Key Store ** su un NetHSM.

La chiave privata di una coppia di chiavi può essere scritta come segue.

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

La chiave pubblica di una coppia di chiavi può essere scritta come segue.

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

Il certificato di una coppia di chiavi può essere scritto come segue.

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

Operazioni chiave#

Crittografare#

NetHSM non può criptare i dati con chiavi asimmetriche, ma fornisce la chiave pubblica che può essere utilizzata per la crittografia. Per saperne di più su come recuperare la chiave pubblica, consultare il capitolo Show Key Details, oppure recuperare la chiave come descritto nel capitolo Read Keys <pkcs11_with_pkcs11.html#read-keys>. L’esempio assume la chiave pubblica nel file public.pem.

I dati possono essere crittografati con OpenSSL come segue.

$ 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

Decriptare#

Il NetHSM può decifrare i dati per una chiave privata memorizzata nel Key Store del NetHSM. Questo esempio utilizza il messaggio crittografato del capitolo precedente Crittografia.

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

NetHSM rulez!

Segno#

Il NetHSM può firmare i dati per una chiave privata memorizzata nel Key Store del NetHSM. Per le firme con chiave RSA ed ECDSA, è necessario calcolare prima un digest.

Per calcolare un digest sono necessari innanzitutto i dati. Un messaggio viene creato come segue.

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

La firma creata può essere verificata con OpenSSL come segue.

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