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 stai utilizzando un altro sistema operativo o ambiente, ma tieni presente che potrebbero verificarsi le 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

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"

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 Cloud KMS Google Cloud. Il file YAML deve configurare almeno un token PKCS #11.

Se utilizzi OpenSSL con un altro processo che potrebbe andare in biforcazione (ad come Apache o Nginx), devi anche assicurarti che Il campo refresh_interval_secs non viene configurato o è 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 decrittografia 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. Punta KMS_PKCS11_CONFIG al tuo 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 di 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 Cloud KMS sono vincolate a usare un singolo digest. Ad esempio, una CryptoKeyVersion con l'algoritmo EC_SIGN_P256_SHA256 deve essere sempre utilizzato 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, in genere sono necessarie opzioni aggiuntive di OpenSSL: -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest

Crea una nuova firma

Se nel keyring configurato è presente una chiave denominata foo, usa 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 file binario senza formattazione.

Questo comando presuppone che tu stia utilizzando una chiave che accetta un digest SHA-256, quindi È stato utilizzato l'argomento -sha256. L'opzione -sha384 o -sha512 sarebbe appropriato per le chiavi Cloud HSM che usano questi tipi di digest.

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

Creare una nuova richiesta di firma del certificato

Puoi anche generare una richiesta di firma del certificato (CSR) per un Cloud HSM chiave di firma. 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 CryptoKey Cloud KMS con ASYMMETRIC_SIGN. Inoltre, assicurati di utilizzare i dati digest corretti e -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 CryptoKey Cloud KMS sono solo utilizzato per lo scopo ASYMMETRIC_SIGN. Inoltre, ricordati 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 tramite un'interfaccia PKCS #11. Lo fa interponendosi tra l'applicazione e la libreria PKCS #11 e registrando tutte le chiamate effettuate. Può essere utili per la risoluzione dei problemi.

Attenzione: non utilizzare PKCS #11 Spy con carichi di lavoro sensibili. Quando è configurato, PKCS #11 Spy è in grado di osservare tutte le interazioni con l'HSM.

Per utilizzare PKCS #11 Spy, devi aver installato 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 punti OpenSSL La libreria di spionaggio 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 questi ambienti , esegui questi comandi:

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