Utilizzo di una chiave Cloud HSM con OpenSSL

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

Requisiti

Scarica una release della raccolta per iniziare. È disponibile una guida dell'utente per la consulenza.

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.

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"
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee /etc/profile

Configurazione della libreria PKCS #11

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

Se utilizzi OpenSSL con un altro processo che potrebbe comportare il fork (ad esempio, Apache o Nginx), devi anche 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 /etc/profile

Esecuzione dei comandi OpenSSL

Ora che il motore e la libreria sono configurati correttamente, puoi utilizzare il motore nei comandi OpenSSL.

Quando crei firme asimmetriche, tieni presente che le chiavi Cloud KMS sono vincolate per utilizzare 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.

Creare 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 utilizza un digest SHA-256, quindi è stato utilizzato l'argomento -sha256. Le opzioni -sha384 o -sha512 sarebbero appropriate per le chiavi Cloud HSM che utilizzano questi tipi di digest.

Per una chiave RSA-PSS, ricorda di utilizzare le opzioni -sigopt illustrate 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 Cloud HSM. Questo metodo è 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

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 del token SAML.

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