Utilizzo di una chiave Cloud HSM con OpenSSL

Questa guida fornisce istruzioni per configurare OpenSSL in modo da utilizzare una chiave Cloud HSM su Debian 11 (Bullseye). Queste istruzioni sono generalmente applicabili anche se utilizzi un altro sistema operativo o ambiente, ma tieni presente che potrebbero esserci lievi differenze.

Requisiti

Per iniziare, scarica una release della libreria. Per ulteriori dettagli sulla libreria PKCS #11, consulta la guida dell'utente.

Prima di iniziare, installa il pacchetto libengine-pkcs11-openssl.

sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl

Configurazione

Imposta la variabile di ambiente PKCS11_MODULE_PATH.

Affinché openssl possa utilizzare la nostra libreria PKCS #11, imposta la variabile di ambiente PKCS11_MODULE_PATH:

export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"

Per impostare definitivamente la variabile di ambiente, aggiungi export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" a /etc/profile eseguendo il seguente comando:

echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile

Configurazione della libreria PKCS #11

La libreria PKCS #11 richiede un file di configurazione YAML per individuare le risorse Cloud KMS. Il file YAML deve configurare almeno un token PKCS #11.

Se utilizzi OpenSSL con un altro processo che potrebbe finire per eseguire il fork (ad esempio Apache o Nginx), devi anche assicurarti che il campo refresh_interval_secs rimanga non impostato o sia impostato su 0.

File di configurazione di esempio:

---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"

Con questa configurazione, tutte le chiavi di firma e decriptazione asimmetriche in my-keyring saranno disponibili nella raccolta.

Devi impostare le autorizzazioni sul file di configurazione in modo che sia scrivibile solo dal proprietario del file. Fai in modo che KMS_PKCS11_CONFIG indichi il file di configurazione:

export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

Anche in questo caso, puoi rendere permanente questa impostazione aggiungendola a /etc/profile.

echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile

Eseguire i comandi OpenSSL

Con il motore e la libreria configurati correttamente, ora puoi utilizzare il motore nei comandi OpenSSL.

Quando crei firme asimmetriche, tieni presente che le chiavi Cloud KMS sono costrette a utilizzare un singolo digest. Ad esempio, una CryptoKeyVersion con l'algoritmo EC_SIGN_P256_SHA256 deve sempre essere utilizzata insieme a un digest SHA-256. Corrisponde al flag -sha256 in OpenSSL. Le chiavi che richiedono digest SHA-384 o SHA-512 devono essere utilizzate con i flag -sha384 o -sha512.

Nota: quando crei firme asimmetriche utilizzando le chiavi Cloud KMS con un algoritmo che inizia con RSA_PSS, in genere sono richieste opzioni aggiuntive da OpenSSL:-sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest.

Creare una nuova firma

Supponendo che nel tuo keyring configurato sia presente una chiave denominata foo, utilizza il seguente comando per creare una firma su bar.txt:

openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt

L'output di questo comando è in formato binario non formattato.

Questo comando presuppone che tu stia utilizzando una chiave che accetta un digest SHA-256, pertanto è stato utilizzato l'argomento -sha256. Le opzioni -sha384 o -sha512 sono appropriate per le chiavi Cloud HSM che utilizzano questi tipi di digest.

Per una chiave RSA-PSS, ricordati di utilizzare le opzioni -sigopt discusse in precedenza.

Creare una nuova richiesta di firma del certificato

Puoi anche generare una richiesta di firma del certificato (CSR) per una chiave di firma Cloud HSM. Questo è utile se la tua autorità di certificazione richiede una CSR per generare un nuovo certificato per la firma del codice o per proteggere le sessioni web TLS.

openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.csr

Nota: crea CSR solo per le chiavi di crittografia Cloud KMS con lo scopo ASYMMETRIC_SIGN. Inoltre, assicurati di utilizzare l'algoritmo di hashing corretto e le opzioni -sigopt per il tipo di chiave.

Genera un nuovo certificato autofirmato

Per lo sviluppo e i test locali, puoi utilizzare un certificato autofirmato per una chiave di firma Cloud HSM. I certificati autofirmati sono utili anche per la firma dei token SAML.

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.crt

Nota: i certificati autofirmati per le chiavi di crittografia Cloud KMS vengono utilizzati solo per lo scopo ASYMMETRIC_SIGN. Inoltre, assicurati di utilizzare l'algoritmo di digest e le opzioni -sigopt corretti per il tipo di chiave.

Risoluzione dei problemi relativi a PKCS #11 Spy

PKCS #11 Spy è uno strumento open source che registra i contenuti delle interazioni tramite un'interfaccia PKCS #11. Lo fa interponendosi tra l'applicazione e la libreria PKCS #11 e registrando tutte le chiamate effettuate. Ciò può essere utile per la risoluzione dei problemi.

Attenzione: non utilizzare PKCS #11 Spy con carichi di lavoro sensibili. Se configurato, PKCS #11 Spy può osservare tutte le interazioni con l'HSM.

Per utilizzare PKCS #11 Spy, devi installare il pacchetto opensc. Il opensc pacchetto contiene PKCS #11 Spy. Per assicurarti che opensc sia installato, esegui il seguente comando:

sudo apt-get install opensc

Quindi, imposta la variabile di ambiente PKCS11_MODULE_PATH in modo che indichi a OpenSSL la libreria Spy PKCS #11 eseguendo il seguente comando:

export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so

Infine, indica a PKCS #11 Spy la libreria PKCS #11 di Cloud HSM impostando le variabili di ambiente PKCS11SPY e PKCS11SPY_OUTPUT. Per impostare queste variabili di ambiente, esegui i comandi seguenti:

export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"