Utilizzo di una chiave Cloud HSM con OpenSSL

Questa guida fornisce istruzioni per configurare OpenSSL per l'utilizzo di 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

Scarica una release della raccolta per iniziare. 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

Impostazione della variabile di ambiente PKCS11_MODULE_PATH.

Per consentire a openssl di 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 questo 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 codice YAML deve configurare almeno un singolo token PKCS #11.

Se utilizzi OpenSSL con un altro processo che potrebbe causare il forking (ad esempio, Apache o Nginx), devi inoltre assicurarti che il campo refresh_interval_secs rimanga non impostato o sia impostato su 0.

Esempio di file di configurazione:

---
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 libreria.

Devi impostare le autorizzazioni per il file di configurazione in modo che sia accessibile solo dal proprietario del file. Posiziona il cursore KMS_PKCS11_CONFIG sul 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

Esecuzione dei comandi OpenSSL

Una volta configurati correttamente il motore e la libreria, puoi utilizzare il motore nei comandi OpenSSL.

Quando crei firme asimmetriche, tieni presente che le chiavi Cloud KMS sono vincolate all'utilizzo di un singolo digest. Ad esempio, una CryptoKeyVersion con l'algoritmo EC_SIGN_P256_SHA256 deve essere sempre 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 chiavi Cloud KMS con un algoritmo che inizia con RSA_PSS, OpenSSL richiede in genere opzioni aggiuntive:-sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest.

Crea una nuova firma

Supponendo che ci sia una chiave denominata foo nel keyring configurato, 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 è un programma binario non formattato.

Questo comando presuppone che tu stia utilizzando una chiave che accetta un digest SHA-256, quindi è 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.

Crea una nuova richiesta di firma del certificato

Puoi anche generare una richiesta di firma del certificato (CSR) per una chiave di firma di Cloud HSM. Ciò è utile se la tua autorità di certificazione richiede una richiesta di firma del certificato (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 CryptoKey Cloud KMS con lo scopo ASYMMETRIC_SIGN. Inoltre, assicurati di utilizzare l'algoritmo di digest 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 di 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 CryptoKey Cloud KMS vengono utilizzati solo per lo scopo ASYMMETRIC_SIGN. Inoltre, assicurati di utilizzare l'algoritmo digest corretto e le opzioni -sigopt per il tipo di chiave.

Risoluzione dei problemi con PKCS #11 Spy

PKCS #11 Spy è uno strumento open source che registra i contenuti delle interazioni su un'interfaccia PKCS #11. Ciò si trova tra l'applicazione e la libreria PKCS #11 e vengono registrate tutte le chiamate effettuate. Questo 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 avere installato il pacchetto opensc. Il pacchetto opensc contiene PKCS #11 Spy. Per assicurarti che opensc sia installato, esegui questo comando:

sudo apt-get install opensc

Quindi, imposta la variabile di ambiente PKCS11_MODULE_PATH in modo che punti OpenSSL alla libreria PKCS #11 Spy eseguendo questo comando:

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

Infine, indirizza PKCS #11 Spy alla libreria Cloud HSM PKCS #11 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"