Vedremo come sfruttare gli ambienti per una configurazione flessibile e come gestire più certificati client in modo centralizzato tramite un file di configurazione, una pratica essenziale quando si lavora con diversi servizi.

La documentazione ufficiale di Postman CLI non fornisce informazioni dettagliate su come configurare mTLS, ne quanto meno esempi pratici. Seguendo questa guida, ti assicuro che sarà un gioco da ragazzi!

Segui la guida fino in fondo!
Alla fine troverai un bonus: il link al repository GitHub che contiene l'intero progetto pronto all'uso, con tutte le configurazioni, gli script e le collection Postman illustrate in questo articolo.

Prerequisiti

Per seguire questa guida, assicuriamoci di avere:

• Postman CLI installato sull'ambiente di esecuzione. Versione minima consigliata: 1.18.0, poiché alcune funzionalità potrebbero non essere disponibili nelle versioni precedenti;
• un progetto con endpoint protetti da mTLS, come per esempio quarkus-mtls-auth;
• certificati client e CA (Certificate Authority) necessari per l'autenticazione mTLS.

Il login su Postman non è necessario per eseguire collection locali come in questo esempio, ma è richiesto nel caso in cui si voglia sincronizzare collection, ambienti o cronologia con il cloud di Postman.

Il progetto quarkus-mtls-auth offre un'implementazione di API REST protette dal meccanismo di sicurezza mTLS, che utilizzeremo per dimostrare la configurazione di Postman CLI. Quanto descritto in questa guida è applicabile a qualsiasi altro progetto e/o scenario simile.

Per quanto riguarda i certificati client e CA, esploreremo in seguito come generarli e configurarli correttamente in Postman CLI. La versione CLI, a differenza della versione Desktop, attualmente supporta solo certificati in formato PEM (Privacy Enhanced Mail).

Non ci sono restrizioni particolari riguardo il sistema operativo utilizzato, puoi seguire questa guida su Windows, macOS o Linux senza problemi. Per garantire la massima compatibilità, consiglio di utilizzare un terminale con supporto per i comandi Unix/Linux.

Per seguire in modo fluido questa guida, assicurati di avere familiarità con i concetti di base di mTLS e Postman e avere una certa dimestichezza con la linea di comando e il formato JSON.

Configurazione della struttura del progetto

Come primo passo, organizziamo un ambiente di lavoro che sia agevole e ben strutturato per Postman CLI. Inizieremo creando una cartella dedicata al nostro progetto e all'interno di essa, andremo a creare tutto il necessario per la configurazione.

# Creiamo la struttura delle cartelle
# La directory di lavoro (o root directory) sarà postman-mtls
mkdir postman-mtls

# Creiamo la cartella per i certificati client
mkdir -p postman-mtls/certificates/client

# Creiamo la cartella per i certificati CA
mkdir -p postman-mtls/certificates/ca

# Creiamo la cartella per la collection postman
mkdir postman-mtls/collections

# Creiamo la cartella per i file di configurazione (environments)
mkdir -p postman-mtls/config/environments

# Creiamo la cartella per i file di configurazione (certificates)
mkdir -p postman-mtls/config/certificates

Una volta eseguiti i comandi precedenti, la struttura delle cartelle dovrebbe apparire come segue.

postman-mtls/
├── certificates/
│   ├── client/
│   └── ca/
├── collections/
└── config/
    ├── environments/
    └── certificates/

Configurazione delle variabili d'ambiente di Postman

Usare le variabili d'ambiente in Postman è fondamentale per gestire configurazioni diverse senza modificare manualmente le richieste. Le variabili possono essere utilizzate per memorizzare valori come URL, token di accesso e certificati.

Per il nostro esempio, creeremo due ambienti: uno per lo sviluppo locale e un altro per l'ambiente di test. Vediamo quali sono le variabili che andremo a definire:

• base_url: l'URL di base del servizio. Questa variabile avrà un valore differente per ogni ambiente;
• api_connection_info_path: il path dell'API per le informazioni di connessione;
• api_connection_user_identity: il path dell'API per l'identità dell'utente;
• env_name: il nome dell'ambiente. È utile per identificare l'ambiente attivo durante l'esecuzione delle richieste e dei test.

La tabella a seguire riassume le variabili per ciascun ambiente.

Tabella 1 - Variabili per gli ambienti

Queste variabili possono essere definite e create dall'interfaccia di Postman o tramite file di configurazione JSON. Noi faremo a meno dell'interfaccia grafica e utilizzeremo file di configurazione JSON per definire i nostri ambienti.

Andremo a creare due file JSON, uno per l'ambiente di sviluppo locale e uno per l'ambiente di test. Questi file conterranno le variabili necessarie per ciascun ambiente. Chiameremo i file local.json e test.json che andranno posizionati nella cartella postman-mtls/config/environments.

# Creiamo i file di configurazione per gli ambienti
touch postman-mtls/config/environments/local.json
touch postman-mtls/config/environments/test.json

Il contenuto del file local.json sarà il seguente.

{
    "id": "quarkus-mtls-local-environment",
    "name": "Quarkus mTLS local environment",
    "values": [
        {
            "key": "env_name",
            "value": "local",
            "description": "Name of the environment",
            "type": "default",
            "enabled": true
        },
        {
            "key": "base_url",
            "value": "https://localhost:8443",
            "description": "Base URL for the local environment",
            "type": "default",
            "enabled": true
        },
        {
            "key": "api_connection_info_path",
            "value": "/api/v1/connection-info/info",
            "description": "Path for API connection info",
            "type": "default",
            "enabled": true
        },
        {
            "key": "api_connection_user_identity",
            "value": "/api/v1/connection-info/user-identity",
            "description": "Path for API user identity",
            "type": "default",
            "enabled": true
        }
    ]
}

Per l'ambiente di test il contenuto del file test.json sarà il seguente.

{
    "id": "quarkus-mtls-test-environment",
    "name": "Quarkus mTLS test environment",
    "values": [
        {
            "key": "env_name",
            "value": "test",
            "description": "Name of the environment",
            "type": "default",
            "enabled": true
        },
        {
            "key": "base_url",
            "value": "https://blog.quarkus.dontesta.it:8443",
            "description": "Base URL for the test environment",
            "type": "default",
            "enabled": true
        },
        {
            "key": "api_connection_info_path",
            "value": "/api/v1/connection-info/info",
            "description": "Path for API connection info",
            "type": "default",
            "enabled": true
        },
        {
            "key": "api_connection_user_identity",
            "value": "/api/v1/connection-info/user-identity",
            "description": "Path for API user identity",
            "type": "default",
            "enabled": true
        }
    ]
}

Importante: come base_url per l'ambiente di test abbiamo indicato l'FQDN blog.quarkus.dontesta.it, dobbiamo quindi assicurarci che questo sia risolvibile. In questo caso è più che sufficiente aggiungere una voce nel file /etc/hosts del nostro ambiente di sviluppo.

Una volta creati i file di configurazione per gli ambienti, possiamo procedere con la configurazione dei certificati client che saranno usati dalla CLI di Postman per eseguire le richieste HTTPS verso i servizi.

Configurazione dei certificati client in Postman CLI

La configurazione dei certificati client in Postman CLI è un passaggio cruciale per l'autenticazione mTLS. A differenza della versione Desktop di Postman, che consente di configurare i certificati tramite l'interfaccia grafica, la CLI richiede l'uso di file di configurazione JSON.

Per gestire più certificati client in modo centralizzato, creeremo un file di configurazione adatto allo scopo. Questo file conterrà le informazioni necessarie per ogni certificato, inclusi i percorsi dei file PEM per il certificato e la chiave privata, compresa la relativa passphrase.

Chiameremo questo file di configurazione client-certificates.json e lo posizioneremo nella cartella postman-mtls/config/certificates.

A seguire l'esempio di configurazione per i certificati client. In questo caso, abbiamo configurato due certificati, sia per l'ambiente locale che per l'ambiente di test. Questa configurazione è solo un esempio e può essere adattata in base alle esigenze specifiche.

[
  {
    "name": "local-certificate-1",
    "matches": ["https://localhost:8443/api/v1/connection-info/info"],
    "key": { "src": "certificates/client/client_with_device_id_and_roles_key.pem" },
    "cert": { "src": "certificates/client/client_with_device_id_and_roles_cert.pem" },
    "passphrase": "pZAXwq+l1BRlC+3X"
  },
  {
    "name": "local-certificate-2",
    "matches": ["https://localhost:8443/api/v1/connection-info/user-identity"],
    "key": { "src": "certificates/client/client_with_device_id_and_roles_1_key.pem" },
    "cert": { "src": "certificates/client/client_with_device_id_and_roles_1_cert.pem" },
    "passphrase": "z93Fl8nhQR8shWTq"
  },
  {
    "name": "test-certificate-1",
    "matches": ["https://blog.quarkus.dontesta.it:8443/api/v1/connection-info/user-identity"],
    "key": { "src": "certificates/client/client_new_device_id_key.pem" },
    "cert": { "src": "certificates/client/client_new_device_id_cert.pem" },
    "passphrase": "4l0nJ9nvreqleFnV"
  },
  {
    "name": "test-certificate-2",
    "matches": ["https://blog.quarkus.dontesta.it:8443/api/v1/connection-info/info"],
    "key": { "src": "certificates/client/client_with_device_id_and_roles_1_key.pem" },
    "cert": { "src": "certificates/client/client_with_device_id_and_roles_1_cert.pem" },
    "passphrase": "z93Fl8nhQR8shWTq"
  }
]

Poiché il progetto su cui eseguiremo i test è quarkus-mtls-auth, utilizzeremo certificati accettati dai servizi REST implementati in questo progetto. I certificati indicati sono stati generati appositamente per il testing tramite uno script specifico.

Per maggiori informazioni su come sono stati generati i certificati client, fare riferimento all'articolo Implementazione di TLS Mutual Authentication (mTLS) con Quarkus e in particolare al capitolo Step 10 - Generazione di un set di certificati client per eseguire dei test di accesso.

Come Postman CLI seleziona il certificato client

Quando si esegue una collection con Postman CLI e si specifica il file di configurazione dei certificati tramite l'opzione --ssl-client-cert-list, Postman seleziona automaticamente il certificato client da utilizzare per ogni richiesta HTTPS in base al campo matches presente nel file di configurazione.

Il campo matches è un array di URL o pattern che indicano a quali richieste il certificato deve essere associato. Durante l'esecuzione della collection, Postman confronta l'URL della richiesta con i valori definiti in matches per determinare quale certificato utilizzare.

• Se l'URL della richiesta corrisponde a uno dei valori definiti in matches, Postman utilizza il certificato associato a quella configurazione.
• Se nessun certificato corrisponde, la richiesta sarà inviata senza certificato client.

Questo meccanismo consente di gestire facilmente più certificati per diversi endpoint o ambienti, senza dover modificare manualmente la configurazione ad ogni esecuzione.

Esempio: se una richiesta viene inviata a https://localhost:8443/api/v1/connection-info/info, Postman CLI cercherà una configurazione con matches che includa esattamente quell'URL e userà il certificato specificato.

Per maggiori dettagli fare riferimento ad Add and manage CA and client certificates in Postman

Creazione della collection Postman

A questo punto possiamo creare la nostra collection Postman contenente le richieste necessarie per interagire con le API protette da mTLS, che in questo caso sono due: /api/v1/connection-info/infoe /api/v1/connection-info/user-identity. La prima API restituisce informazioni sulla connessione, mentre la seconda fornisce dettagli sull'identità dell'utente.

Procediamo ora con la creazione del file JSON della collection, che salveremo nella cartella postman-mtls/collections con il nome quarkus-mtls-collection.json. Di seguito è riportato il contenuto del file.

{
    "info": {
        "name": "Quarkus mTLS",
        "description": "Collection Postman per il test di servizi REST protetti da un meccanismo di sicurezza di tipo mTLS.",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "connection-info/info",
            "request": {
                "method": "GET",
                "header": [],
                "url": {
                    "raw": "{{base_url}}{{api_connection_info_path}}",
                    "host": [
                        "{{base_url}}{{api_connection_info_path}}"
                    ]
                },
                "description": "La risposta del servizio conterrà un set d'informazioni che riguardano la connessione instaurata."
            },
            "response": []
        },
        {
            "name": "connection-info/user-identity",
            "request": {
                "method": "GET",
                "header": [],
                "url": {
                    "raw": "{{base_url}}{{api_connection_user_identity}}",
                    "host": [
                        "{{base_url}}{{api_connection_user_identity}}"
                    ]
                },
                "description": "La risposta del servizio conterrà un set d'informazioni che riguardano l'indentità del client che ha richiesto l'accesso alla risorsa."
            },
            "response": []
        }
    ]
}

All'interno della collection abbiamo utilizzato le variabili definite nell'ambiente, come per esempio base_url, api_connection_info_path e api_connection_user_identity.

Vogliamo rendere la nostra collection ancora più "smart" per il testing automatizzato! Per farlo, aggiungeremo dei test alle richieste, così ogni ambiente avrà i suoi controlli dedicati. Immagina: ogni volta che lanci la collection, Postman CLI si trasforma in un vero e proprio "detective" delle API, pronto a scovare errori e confermare che tutto funzioni come previsto. La tabella qui sotto mostra quali test saranno eseguiti per ogni richiesta, a seconda dell'ambiente attivo. Pronti a scoprire chi supera l’esame?

Tabella 2 - Test automatizzati per ogni richiesta e ambiente

Perché i test sono diversi tra gli ambienti?

Un'attenta osservazione della Tabella 2 rivela che i test per la stessa API cambiano a seconda dell'ambiente. Qualcuno potrebbe giustamente obiettare: "I test non dovrebbero essere identici?"

L'obiezione è assolutamente valida, ma in questo contesto la differenza è intenzionale e strategica. Non stiamo solo verificando che l'API "funzioni", ma stiamo validando scenari di autorizzazione specifici legati ai diversi certificati client usati in ogni ambiente.

Come descritto nella configurazione dei certificati (Config. 3), ogni ambiente associa certificati client differenti alle API. Di conseguenza:

• Ambiente local: Per l'API connection-info/info, ci aspettiamo un 403 Forbidden. Questo è un test di sicurezza "negativo": verifichiamo che un client autenticato ma non autorizzato venga correttamente respinto.
• Ambiente test: Per la stessa API, ci aspettiamo un 200 OK. Questo è un test "positivo": verifichiamo che un client con un certificato diverso e autorizzato ottenga l'accesso.

In sintesi, sfruttiamo gli ambienti per simulare diversi profili di accesso e garantire che le regole di autorizzazione basate sui certificati siano implementate correttamente. Questo approccio va usato con le dovute considerazioni, ma in questo caso specifico è perfettamente giustificato.

Con riferimento alla tabella precedente, possiamo ora implementare i test all'interno della nostra collezione Postman. A seguire la nuova collection a cui daremo il nome quarkus-mtls-collection-with-test.json e posizioneremo sempre in postman-mtls/collections.

La sezione "event" di ogni richiesta conterrà gli script per l'esecuzione dei test. Gli script di test sono scritti in JavaScript e utilizzano l'API di test di Postman. Per maggiori approfondimenti fare riferimento alla documentazione ufficiale di Postman Write scripts to test API response data in Postman.

{
    "info": {
        "name": "Quarkus mTLS",
        "description": "Collection Postman per il test di servizi REST protetti da un meccanismo di sicurezza di tipo mTLS.",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "connection-info/info",
            "request": {
                "method": "GET",
                "header": [],
                "url": {
                    "raw": "{{base_url}}{{api_connection_info_path}}",
                    "host": [
                        "{{base_url}}{{api_connection_info_path}}"
                    ]
                },
                "description": "La risposta del servizio conterrà un set d'informazioni che riguardano la connessione instaurata."
            },
            "event": [
                {
                    "listen": "test",
                    "script": {
                        "type": "text/javascript",
                        "exec": [
                            "console.log('Environment attivo:', pm.environment.get('env_name'));",
                            "if (pm.environment.get('env_name') === 'local') {",
                            "    pm.test('Status code is 403', function () {",
                            "        pm.response.to.have.status(403);",
                            "    });",
                            "} else if (pm.environment.get('env_name') === 'test') {",
                            "    pm.test('Status code is 200', function () {",
                            "        pm.response.to.have.status(200);",
                            "    });",
                            "    pm.test('Content-Type is application/json', function () {",
                            "        pm.response.to.have.header('Content-Type', 'application/json;charset=UTF-8');",
                            "    });",
                            "    pm.test('certCommonName is rd.quarkus.dontesta.it', function () {",
                            "        var jsonData = pm.response.json();",
                            "        pm.expect(jsonData.server.certCommonName).to.eql('rd.quarkus.dontesta.it');",
                            "    });",
                            "}"
                        ]
                    }
                }
            ],
            "response": []
        },
        {
            "name": "connection-info/user-identity",
            "request": {
                "method": "GET",
                "header": [],
                "url": {
                    "raw": "{{base_url}}{{api_connection_user_identity}}",
                    "host": [
                        "{{base_url}}{{api_connection_user_identity}}"
                    ]
                },
                "description": "La risposta del servizio conterrà un set d'informazioni che riguardano l'indentità del client che ha richiesto l'accesso alla risorsa."
            },
            "event": [
                {
                    "listen": "test",
                    "script": {
                        "type": "text/javascript",
                        "exec": [
                            "console.log('Environment attivo:', pm.environment.get('env_name'));",
                            "if (pm.environment.get('env_name') === 'local') {",
                            "    pm.test('Status code is 200', function () {",
                            "        pm.response.to.have.status(200);",
                            "    });",
                            "    pm.test('Content-Type is application/json', function () {",
                            "        pm.response.to.have.header('Content-Type', 'application/json;charset=UTF-8');",
                            "    });",
                            "    pm.test('deviceId is valid', function () {",
                            "        var jsonData = pm.response.json();",
                            "        pm.expect(jsonData.attributes.deviceId).to.eql('MTc1NzAyNTE3OTk3MDAwODAwMCM1MjQwOGJkNC1hZjQzLTQwZjYtODgxZi00YWNjOTQ4OTM3MjEjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjMmVlNjA0Y2IyYzQ1Yjk0NDkwZDhmOWZiYTU4MTEwNjhkNDk1MmUwNjlkMzRmMzc0MjA5ODAzZmNjMjQ5ZWIxOA==');",
                            "    });",
                            "} else if (pm.environment.get('env_name') === 'test') {",
                            "    pm.test('Status code is 401', function () {",
                            "        pm.response.to.have.status(401);",
                            "    });",
                            "}"
                        ]
                    }
                }
            ],
            "response": []
        }
    ]
}

Ottimo lavoro! Ora che tutte le configurazioni sono pronte (ambienti, certificati e collection Postman sia con che senza test), siamo davvero a un passo dall'esecuzione pratica delle collection. Manca solo l’ultimo step: vedere tutto in azione!

Esecuzione della collection con Postman CLI

Arrivati a questo punto, la struttura del nostro progetto dovrebbe essere simile a quella indicata a seguire.

postman-mtls/
├── certificates
│   ├── ca
│   │   └── ca_cert.pem
│   └── client
│       ├── client_new_device_id_cert.pem
│       ├── client_new_device_id_key.pem
│       ├── client_new_device_id_key.pem.password
│       ├── client_with_device_id_and_roles_1_cert.pem
│       ├── client_with_device_id_and_roles_1_key.pem
│       ├── client_with_device_id_and_roles_1_key.pem.password
│       ├── client_with_device_id_and_roles_cert.pem
│       ├── client_with_device_id_and_roles_key.pem
│       └── client_with_device_id_and_roles_key.pem.password
├── collections
│   ├── quarkus-mtls-collection-with-test.json
│   └── quarkus-mtls-collection.json
└── config
    ├── certificates
    │   └── client-certificates.json
    └── environments
        ├── local.json
        └── test.json

Prima di eseguire le collection con Postman CLI, è importante assicurarsi che tutte le configurazioni siano corrette e che i certificati siano stati generati e posizionati nei percorsi appropriati.

Importante: prima di eseguire i test, assicurati che il progetto quarkus-mtls-auth sia avviato e che le API siano in ascolto sulla porta 8443 (come configurato negli ambienti local e test).
Puoi trovare le istruzioni dettagliate nella sezione Quickstart del repository, dove viene spiegato come avviare il servizio tramite Docker o Podman. Ecco un esempio pratico:

# Scarica l'immagine aggiornata da Docker Hub
podman pull amusarra/quarkus-mtls-auth:latest

# Avvia il container sulla porta 8443
podman run -p 8443:8443 amusarra/quarkus-mtls-auth:latest

Bash

Per eseguire le collection con Postman CLI, si utilizza il comando postman collection run specificando il percorso della collection, il file di ambiente tramite l'opzione --environment, il file di configurazione dei certificati tramite l'opzione --ssl-client-cert-list.

Nel nostro caso specifichiamo anche l'opzione --ssl-extra-ca-certs. Questa opzione permette di specificare un file PEM contenente i certificati delle CA che Postman CLI utilizzerà per verificare il certificato del server. Questo è particolarmente utile quando si lavora con server che utilizzano certificati autofirmati o emessi da una CA privata evitando il classico errore: unable to verify the first certificate.

Il file certificates/ca/ca_cert.pem deve contenere il certificato della CA utilizzata per firmare il certificato del server. Può essere anche un bundle di certificati CA.

Ecco il comando base per eseguire una collection con Postman CLI usando environment e certificati.

# Comando base per l'esecuzione della collection
# Sostituisci i segnaposto con i valori appropriati
postman collection run collections/.json \
    --environment config/environments/.json \
    --ssl-client-cert-list config/certificates/.json \
    --ssl-extra-ca-certs certificates/ca/.pem

A seguire una serie di comandi (completi) per eseguire le collection che abbiamo creato in precedenza e sui relativi ambienti: local e test.

# Esecuzione della collection senza test per l'ambiente local
postman collection run collections/quarkus-mtls-collection.json \
    --environment config/environments/local.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem

# Esecuzione della collection con test per l'ambiente local
postman collection run collections/quarkus-mtls-collection-with-test.json \
    --environment config/environments/local.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem

# Esecuzione della collection senza test per l'ambiente test
postman collection run collections/quarkus-mtls-collection.json \
    --environment config/environments/test.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem

# Esecuzione della collection con test per l'ambiente test
postman collection run collections/quarkus-mtls-collection-with-test.json \
    --environment config/environments/test.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem

La figura mostra l'output della Postman CLI durante l'esecuzione della collection con test sull'ambiente di test. Si evidenziano i risultati dei test automatici sulle richieste, lo stato delle asserzioni, il dettaglio delle risposte HTTP ricevute e le statistiche di esecuzione (numero di richieste, test eseguiti, tempo medio di risposta, dati ricevuti, ecc.). Questo tipo di output consente di verificare rapidamente il successo dei test e la correttezza della configurazione mTLS.

Nel caso in cui volessimo ottenere più informazioni in output come per esempio i dettagli delle richieste e delle risposte, possiamo utilizzare l'opzione --verbose.

La Figura 2 mostra un esempio di output ottenuto con l'opzione --verbose abilitata. In questo caso vengono visualizzati ulteriori dettagli sulle richieste HTTP, sulle risposte ricevute, sulle intestazioni, sui tempi di handshake TLS e sulle statistiche di trasferimento dati. Questo livello di dettaglio è utile per il troubleshooting e per analizzare il comportamento della comunicazione mTLS tra client e server.

Le due immagini seguenti mostrano il caso in cui i test automatizzati sull'endpoint /api/v1/connection-info/info falliscono.

La prima immagine evidenzia il riepilogo dell'esecuzione della collection. È mostrato il numero totale di richieste, test-script e asserzioni eseguite, con il dettaglio degli errori. In questo esempio, 3 asserzioni sono fallite:

• Il test sullo status code atteso (200) ha fallito perché la risposta è stata 403 Forbidden.
• Il test sulla presenza dell'header Content-Type con valore application/json non è stato superato.
• Il test sul valore dell'attributo certCommonName nel JSON di risposta non è stato eseguito correttamente a causa di input vuoto (nessun body JSON restituito).

La seconda immagine mostra il dettaglio della richiesta e della risposta. Si vede la richiesta GET verso l'endpoint /api/v1/connection-info/info sull'ambiente di test, che restituisce HTTP 403 Forbidden. Sono riportati i tempi di preparazione, handshake TLS, download e processing.

È anche mostrato l'output degli script di test, con il dettaglio delle asserzioni fallite (status code, content-type, valore certCommonName), confermando che la risposta non soddisfa i criteri attesi dai test automatizzati.

Queste schermate aiutano a diagnosticare rapidamente i motivi del fallimento dei test e a individuare eventuali problemi di configurazione, autorizzazione o formato della risposta dell'API.

Verifica tramite exit code

Quando si esegue una collection con Postman CLI, il comando restituisce un exit code che permette di verificare rapidamente se l'esecuzione è andata a buon fine:

• Exit code 0: tutti i test sono passati con successo.
• Exit code diverso da 0: almeno un test è fallito oppure si è verificato un errore durante l'esecuzione.

Questo comportamento consente di integrare facilmente Postman CLI in pipeline di Continuous Integration/Continuous Delivery (CI/CD) o script di automazione, gestendo il flusso in base al risultato dei test.

Esempio di verifica in bash:

postman collection run collections/quarkus-mtls-collection-with-test.json \
    --environment config/environments/test.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem

if [ $? -eq 0 ]; then
    echo "Tutti i test sono passati correttamente."
else
    echo "Alcuni test sono falliti o si è verificato un errore."
fi

Integrazione di Postman CLI in pipeline CI/CD

L'automazione dei test mTLS tramite Postman CLI può essere facilmente integrata in pipeline di CI/CD, come quelle basate su GitHub Actions, GitLab CI, Jenkins, Azure DevOps, ecc.

Esempio di utilizzo in GitHub Actions

Di seguito un esempio di step che esegue una collection Postman e verifica il risultato tramite l'exit code:

...
- name: Install Postman CLI
  run: |
    curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

- name: Run Postman Collection and Generate Report for local environment
  run: |
    postman collection run collections/quarkus-mtls-collection-with-test.json \
    --environment config/environments/local.json \
    --ssl-client-cert-list config/certificates/client-certificates.json \
    --ssl-extra-ca-certs certificates/ca/ca_cert.pem \
    --verbose \
    --reporters html,cli \
    --reporter-html-export postman_report_local.html
...

Se uno o più test falliscono, lo step viene marcato come failed e la pipeline si interrompe, garantendo che solo il codice che supera tutti i test venga distribuito.

Quando l'errore è il nostro migliore amico

Ecco il bello dell'automazione: quando la GitHub Action fallisce, come mostrato nell'immagine a seguire, non è solo una "X" rossa che ci fa storcere il naso. In realtà, quell'errore è stato fondamentale: ci ha subito segnalato che il certificato del servizio (REST API) era scaduto e che le richieste mTLS non potevano andare a buon fine. Meglio scoprirlo ora, in fase di test, che in produzione davanti agli utenti!

Insomma, il fallimento della pipeline è stato un vero alleato: ci ha permesso di intervenire tempestivamente, aggiornare i certificati e garantire la sicurezza e l'affidabilità del servizio. Ricorda: ogni errore ben evidenziato è un passo avanti verso un sistema più robusto!

Probabilmente senza questi test automatici non mi sarei mai accorto del certificato scaduto e avrei pubblicato la guida con un bel bug, lasciando il lettore a chiedersi perché non funzionasse nulla!
Ecco perché i test sono i veri supereroi delle guide tecniche: ti salvano la reputazione prima ancora che tu prema "pubblica"!

Vantaggi dell'integrazione

• Automazione completa: i test mTLS vengono eseguiti automaticamente ad ogni commit, merge o rilascio.
• Feedback immediato: eventuali errori di configurazione, autenticazione o regressioni vengono rilevati subito.
• Reportistica: è possibile esportare report HTML e allegarli agli artefatti della pipeline per una consultazione rapida.
• Sicurezza: si garantisce che le API protette da mTLS siano sempre testate e funzionanti prima della messa in produzione.

L'immagine seguente mostra l'esecuzione di Postman CLI in una GitHub Actions, con il riepilogo dei risultati e i report HTML generati come artefatti. Questa integrazione semplifica e automatizza la validazione delle API mTLS nei workflow DevOps.

Di seguito un esempio di report HTML generato da Postman CLI usando l'opzione --reporters html.

Questo report mostra in modo grafico e dettagliato lo stato delle richieste, i test eseguiti, le asserzioni superate e fallite, i tempi di risposta e tutte le informazioni utili per la validazione automatica delle API mTLS.

Conclusioni

In questa guida abbiamo visto come configurare e utilizzare Postman CLI per testare endpoint protetti da mTLS, sfruttando ambienti, variabili e certificati client multipli.

Abbiamo imparato a:

• Organizzare la struttura di progetto per Postman CLI.
• Definire ambienti e variabili per gestire facilmente configurazioni diverse.
• Configurare e selezionare certificati client in modo centralizzato tramite file JSON.
• Creare collection Postman con test automatizzati che variano in base all'ambiente.
• Eseguire le collection da CLI, verificare il risultato tramite exit code e generare report HTML.
• Integrare i test mTLS in pipeline CI/CD per garantire la qualità e la sicurezza delle API.

Questi strumenti e procedure ci permettono di automatizzare e rendere ripetibile la validazione di API protette da mTLS, migliorando la produttività e la robustezza dei processi di sviluppo e delivery.

Curiosità: Postman è sicuramente uno degli strumenti più diffusi per il testing delle API, ma il panorama offre anche valide alternative, alcune delle quali completamente offline e open source. Se sei curioso di scoprire nuovi strumenti, dai un'occhiata anche a Bruno, Hoppscotch e altri client API: potresti trovare la soluzione perfetta per le tue esigenze! Ti consiglio di leggere anche l'articolo "Bruno vs Postman: un client API offline" scritto da Serena Sensini e pubblicato su TheRedCode, per approfondire le differenze e scoprire nuove possibilità.

Premio per aver seguito la guida fino a qui!

Trovi l'intero progetto pronto all'uso su GitHub:
https://github.com/amusarra/postman-mtls

Nel repository troverai tutte le configurazioni, gli script, le collection Postman, i certificati di esempio, la GitHub Actions di esempio e molto altro. Puoi clonare il progetto, adattarlo alle tue esigenze e iniziare subito a testare API protette da mTLS con Postman CLI.

Risorse utili

Ecco una raccolta di risorse e riferimenti utili per approfondire i temi trattati nella guida:

Postman

• Documentazione ufficiale Postman CLI
• Installazione Postman CLI
• Gestione ambienti in Postman
• Gestione certificati in Postman
• Scrivere test in Postman
• Report con Postman CLI

GitHub

• Quickstart quarkus-mtls-auth
• Repository di esempio: postman-mtls
• GitHub Actions Documentation

Articoli e Guide

• Implementazione di TLS Mutual Authentication (mTLS) con Quarkus - pubblicato sul blog di Antonio Musarra
• Autenticazione mTLS con Quarkus - pubblicato sul podcast di Antonio Musarra
• Liferay 7.2: Esempio di Two-Way SSL/TLS Mutual Authentication Client - pubblicato sul blog di Antonio Musarra
• RabbitMQ 4.1 mTLS e AMQP 1.0: Guida essenziale per sviluppatori - pubblicato sul blog di Antonio Musarra

Wikipedia

• Mutual TLS (Wikipedia)
• Certificate Authority (Wikipedia)
• Privacy Enhanced Mail (PEM)

Altre Risorse

• Debug TLS/SSL con OpenSSL

Queste risorse ti aiuteranno ad approfondire la configurazione, l'automazione e il troubleshooting di mTLS e Postman CLI.

L'articolo Guida Avanzata: mTLS con Postman CLI, Ambienti e Certificati Multipli sembra essere il primo su Antonio Musarra's Blog.

Questo articolo ti guiderà passo dopo passo nella configurazione di RabbitMQ 4.1 con Mutual TLS (mTLS) per comunicazioni sicure bidirezionali e con il supporto al protocollo AMQP 1.0, il tutto gestito tramite Podman. Implementeremo un esempio pratico in Python utilizzando la libreria Qpid Proton.

Preferisci ascoltare? Questo articolo è accompagnato da un episodio podcast dedicato che approfondisce gli stessi argomenti. Ascoltalo qui: RabbitMQ 4.1 mTLS e AMQP 1.0 - Approfondimento Podcast

Con mTLS, sia il server RabbitMQ che i client (producer e consumer) si autenticano reciprocamente utilizzando certificati digitali. Questo rafforza ulteriormente la sicurezza rispetto al TLS standard, dove solo il client verifica il server. Utilizzeremo nomi di dominio completi (FQDN - Fully Qualified Domain Name) e Subject Alternative Names (SAN) per i certificati TLS server e certificati client dedicati, tutti firmati dalla stessa Certificate Authority (CA).

Per chi volesse seguire passo passo e avere a disposizione tutto il codice sorgente, gli script e il Makefile descritti in questa guida, il progetto completo è disponibile su GitHub: https://github.com/amusarra/rabbitmq-mtls-poc

Perché questa configurazione è importante?

Configurare mTLS fin dall'ambiente di sviluppo ti permette di:

1. Massima sicurezza: Autenticazione reciproca tra client e server.
2. Individuare problemi di sicurezza in anticipo: Non rimandare la sicurezza all'ultimo minuto.
3. Abituarsi alle configurazioni reali: Meno sorprese durante il deploy in produzione.
4. Testare end-to-end in modo realistico: Comprendere l'impatto di mTLS e delle configurazioni di rete.
5. Utilizzare protocolli moderni: AMQP 1.0 offre interoperabilità e funzionalità avanzate.

Prerequisiti

Prima di iniziare, assicurati di avere installato:

1. Make (versione >= 3.8): Per la gestione del progetto e l'automazione delle operazioni.
2. Podman (versione > 5.x): Per la gestione dei container.
3. OpenSSL (versione >= 3.3): Per la generazione dei certificati TLS.
4. Python 3 (versione >= 3.12): Per gli script di producer e consumer.
5. Librerie Python python-qpid-proton e python-dotenv che puoi installare con il comando pip install python-qpid-proton python-dotenv.
6. Possibilità di modificare il file /etc/hosts per la risoluzione del FQDN locale.

Nota: Il progetto collegato a questo articolo è stato realizzato e testato su un sistema macOS 15.4.1 24E263 arm64, ma dovrebbe funzionare anche su distribuzioni Linux. Se hai bisogno di aiuto per l'installazione di Podman o OpenSSL, puoi consultare la documentazione ufficiale o chiedere supporto.

Struttura del Progetto

Il progetto è organizzato per facilitare la gestione di certificati, configurazioni e script di esempio, in modo che tu possa rapidamente avviare un ambiente RabbitMQ sicuro e testare producer/consumer scritti in questo caso in Python.

Ecco una panoramica della struttura tipica del repository:

rabbitmq-mtls-poc/
├── certs/
├── rabbitmq_config/
│   └── rabbitmq.conf
└── scripts/
    ├── producer.py
    └── consumer.py

Descrizione delle principali cartelle e file:

• certs/: Contiene tutti i certificati e le chiavi generate per mTLS. Questa directory è creata automaticamente dal Makefile.
• rabbitmq_config/: Contiene il file di configurazione di RabbitMQ (rabbitmq.conf) con le impostazioni per mTLS.
• scripts/: Contiene gli script di esempio Python per il producer e il consumer, che utilizzano la libreria Qpid Proton per comunicare con RabbitMQ.
• Makefile: Un file di automazione che semplifica la generazione dei certificati e la gestione del container RabbitMQ.
• README.md: Documentazione del progetto, con istruzioni dettagliate su come configurare e utilizzare RabbitMQ con mTLS.

Configurazione di RabbitMQ per mTLS

Per abilitare la mutua autenticazione TLS (mTLS) in RabbitMQ, è necessario configurare il broker affinché accetti solo connessioni cifrate e richieda la presentazione di un certificato valido anche da parte dei client. Questo garantisce che solo i client autorizzati e dotati di certificato firmato dalla CA possano interagire con RabbitMQ.

Parametri chiave nel file di configurazione

Nel file rabbitmq.conf (che viene montato nel container RabbitMQ), assicurati di includere le seguenti direttive:

# Negazione del listener TCP standard
# RabbitMQ non accetterà connessioni non cifrate sulla porta 5672
# Questo è importante per forzare l'uso di TLS
listeners.tcp = none

# Abilita il listener TLS sulla porta 5671
listeners.ssl.default = 5671

# Percorsi dei certificati e della chiave privata del server
ssl_options.cacertfile = /etc/rabbitmq/certs/ca.pem
ssl_options.certfile   = /etc/rabbitmq/certs/server.pem
ssl_options.keyfile    = /etc/rabbitmq/certs/server.key

# Richiedi e verifica il certificato client
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = true

Questa configurazione obbliga RabbitMQ a:

• Accettare solo connessioni cifrate sulla porta 5671.
• Presentare il proprio certificato server ai client.
• Verificare che ogni client presenti un certificato valido e firmato dalla stessa CA.
• Rifiutare le connessioni da client privi di certificato o con certificato non valido.

Non è necessario modificare il file di configurazione di RabbitMQ per l'uso di AMQP 1.0, poiché questo protocollo è già supportato nativamente da RabbitMQ a partire dalla versione 4.0.

Cosa fa il Makefile e come usarlo

Il Makefile è un strumento molto potente che in questo progetto viene utilizzato per automatizzare la generazione dei certificati e la gestione del container RabbitMQ. Grazie a questo file, puoi facilmente creare un ambiente di sviluppo sicuro senza dover eseguire manualmente ogni singolo comando.

Il Makefile è pensato per essere idempotente e facilmente estendibile. Le principali operazioni automatizzate sono:

• Creazione della CA locale: genera la chiave privata e il certificato della Certificate Authority.
• Generazione delle chiavi e CSR per server e client: per ogni entità (server RabbitMQ, producer, consumer) vengono create chiavi private e richieste di firma.
• Firma dei certificati: la CA firma le CSR, producendo certificati validi per mTLS.
• Gestione dei Subject Alternative Names (SAN): i certificati server includono i SAN necessari per il corretto funzionamento con FQDN e localhost.
• Pulizia dell’ambiente: con make clean puoi eliminare tutti i certificati e le chiavi generate, riportando il progetto allo stato iniziale.
• Avvio e gestione del container RabbitMQ: il Makefile include anche comandi per avviare, fermare e configurare RabbitMQ in modo semplice e veloce.
• Configurazione di utenti e permessi: tramite comandi rabbitmqctl o API HTTP, il Makefile si occupa di configurare gli utenti, i permessi e i vhost necessari per il corretto funzionamento del broker.
• Configurazione della topologia: crea exchange, queue e binding necessari per il corretto funzionamento degli script di esempio.

Principali target del Makefile

Il Makefile del progetto è stato pensato per semplificare tutte le operazioni ricorrenti durante lo sviluppo e i test. Ecco una panoramica dei target più importanti:

• certs
  Genera tutti i certificati necessari per mTLS: CA, server RabbitMQ, producer e consumer.
  È il target da eseguire all’inizio per preparare l’ambiente di sicurezza.

• clean
  Rimuove tutti i certificati e le chiavi generate, riportando il progetto allo stato iniziale.
  Utile se vuoi rigenerare tutto da zero.

• rabbitmq-pod-start
  Avvia il container RabbitMQ con la configurazione mTLS, montando i certificati e il file di configurazione.
  Utilizza Podman (o Docker, se adattato).

• rabbitmq-pod-stop
  Ferma e rimuove il container RabbitMQ avviato in precedenza.

• rabbitmq-setup-permissions
  Configura utenti, permessi e vhost all’interno di RabbitMQ tramite comandi rabbitmqctl.
  Garantisce che i client possano autenticarsi e accedere alle risorse corrette.

• rabbitmq-setup-topology
  Crea exchange, queue e binding necessari per il corretto funzionamento degli script di esempio.

• rabbitmq-logs
  Mostra in tempo reale i log del container RabbitMQ, utile per il debug e il monitoraggio.

• all
  Esegue in sequenza i target fondamentali (certs, rabbitmq-pod-start, rabbitmq-setup-permissions, rabbitmq-setup-topology) per preparare l’intero ambiente con un solo comando.

Flusso di Setup con Makefile

Il Makefile orchestra la creazione dell'intero ambiente di sviluppo sicuro. Ecco una visione d'insieme del processo attivato, ad esempio, dal comando make all:

Per avere un'idea visiva dell'intero processo di setup orchestrato dal Makefile, puoi guardare questa breve demo.

Come scoprire tutti i target disponibili

Per vedere l’elenco completo dei target e una breve descrizione, puoi eseguire:

make help

Personalizzazione del Makefile

Se vuoi aggiungere nuovi certificati client o modificare i parametri dei certificati (ad esempio, cambiare l'FQDN o aggiungere nuovi SAN), puoi modificare le variabili all’inizio del Makefile. Tutte le operazioni sono trasparenti e facilmente adattabili alle tue esigenze.

Vantaggi dell’approccio automatizzato

• Ripetibilità: Ogni volta che esegui make certs, ottieni gli stessi risultati, riducendo il rischio di errori umani.
• Sicurezza: riduci il rischio di errori manuali nella generazione dei certificati.
• Velocità: Risparmi tempo prezioso, specialmente in ambienti di sviluppo e test.
• Facilità di integrazione: Puoi integrare il Makefile nel tuo processo CI/CD per generare automaticamente i certificati in ambienti di test e produzione.

Consulta il Makefile incluso nel repository per tutti i dettagli sulle regole e sulle variabili configurabili.

Gestione automatica dei certificati con il Makefile

Per semplificare e standardizzare la generazione dei certificati necessari per mTLS, il Makefile include il target certs che automatizza tutte le operazioni critiche: creazione della CA, generazione delle chiavi e delle richieste di firma (CSR), firma dei certificati server e client, e organizzazione dei file nelle cartelle corrette.

Per generare tutti i certificati necessari, ti basta eseguire:

make certs

L'output del comando sarà simile a questo:

Generating CA and Server certificates...
CA and Server certificates generated.
Generating Client certificates (Producer and Consumer)...
Producer client certificate generated: certs/order_sender_client.pem
Consumer client certificate generated: certs/delivery_receiver_client.pem
Client certificates generated.
All certificates generated in ./certs/

Questo comando creerà una directory certs con tutti i file necessari per la configurazione di RabbitMQ e dei client. A seguito della generazione, troverai:

• ca.pem: Certificato della CA.
• server.pem: Certificato del server RabbitMQ.
• server.key: Chiave privata del server RabbitMQ.
• order_sender_client.key: Chiave privata usata dallo script producer.py che rappresenta il producer.
• order_sender_client.pem: Certificato usato dallo script producer.py che rappresenta il producer.
• delivery_receiver_client.key: Chiave privata usata dallo script consumer.py che rappresenta il consumer.
• delivery_receiver_client.pem: Certificato usato dallo script consumer.py che rappresenta il consumer.

Nella lista precedente ho omesso volutamente il file *.csr, *.srl e *.ext, in quanto non sono necessari per l'esecuzione degli script di esempio. Questi file sono generati durante il processo di creazione dei certificati e possono essere utili per la diagnostica o per la verifica della corretta generazione dei certificati.

La configurazione dei Subject e dei Subject Alternative Names (SAN) sono state impostate in modo da garantire che i certificati siano validi per l'FQDN rabbitmq.labs.dontesta.it e per localhost, allo scopo di testare facilmente sia in locale che in ambienti di sviluppo. A seguire le variabili definite nel Makefile per la deefinizione dei Subject.

# Subject settings
CA_SUBJECT = "/C=IT/ST=Sicilia/L=Bronte/O=Dontesta/OU=DevOps/CN=Dontesta-CA"
SERVER_SUBJECT = "/C=IT/ST=Sicilia/L=Bronte/O=Dontesta/OU=RabbitMQServer/CN=${RABBITMQ_FQDN}"
PRODUCER_SUBJECT = "/C=IT/ST=Sicilia/L=Bronte/O=Dontesta/OU=Client/CN=order_sender_client"
CONSUMER_SUBJECT = "/C=IT/ST=Sicilia/L=Bronte/O=Dontesta/OU=Client/CN=delivery_receiver_client"

Nel caso in cui tu voglia generare i certificati per un altro FQDN e Subject, sarà sufficiente eseguire il comando make come segue:

make certs \
    RABBITMQ_FQDN="my.custom.broker.com" \
    CA_SUBJECT="/C=US/ST=California/L=MyCity/O=MyOrg/OU=DevOps/CN=MyOrg-Custom-CA" \
    SERVER_SUBJECT="/C=US/ST=California/L=MyCity/O=MyOrg/OU=RabbitMQServer/CN=my.custom.broker.com" \
    PRODUCER_SUBJECT="/C=US/ST=California/L=MyCity/O=MyOrg/OU=Client/CN=custom_producer.client" \
    CONSUMER_SUBJECT="/C=US/ST=California/L=MyCity/O=MyOrg/OU=Client/CN=custom_consumer.client"

Gestione di RabbitMQ tramite Makefile

Per rendere ancora più semplice la gestione dell’ambiente di sviluppo, il Makefile include anche un target dedicato all’avvio del container RabbitMQ già configurato per mTLS. In questo modo non dovrai ricordare o scrivere manualmente i comandi podman run o docker run.

Come avviare RabbitMQ

Dopo aver generato i certificati con make certs, puoi avviare RabbitMQ già pronto all’uso (con vhost, utenti, permessi e topologia) usando il comando:

make rabbitmq-pod-start rabbitmq-setup-permissions rabbitmq-setup-topology

Questo comando eseguirà il container RabbitMQ con le configurazioni corrette e monterà i certificati generati nella directory certs all'interno del container.

Nota: prima di eseguire lo start del container RabbitMQ, viene eseguito il target hosts-check, che verifica se il file /etc/hosts contiene la voce ${RABBITMQ_FQDN}. Se non è presente, il comando fallirà. Puoi aggiungere manualmente la riga al file /etc/hosts.

A seguire un esempio di output del comando:

Checking /etc/hosts for entry '127.0.0.1 rabbitmq.labs.dontesta.it'...
/etc/hosts is OK.
Starting RabbitMQ container (rabbitmq-dev-server) with image rabbitmq:4.1-management...
fc79be56d11261b0f193c1e8ca08756da6db005a580528da87e76906be77e25a
Container rabbitmq-dev-server created and started.
Waiting for RabbitMQ in container rabbitmq-dev-server to be ready...
RabbitMQ is ready.
Configuring RabbitMQ vhost, users, and permissions...
podman exec rabbitmq-dev-server rabbitmqctl add_vhost logistics_vhost || echo "Vhost logistics_vhost already exists."
Adding vhost "logistics_vhost" ...
Creating admin user: rabbit_admin
podman exec rabbitmq-dev-server rabbitmqctl add_user rabbit_admin 'SuperS3cureAdminP@ssw0rd!' || echo "User rabbit_admin already exists."
Adding user "rabbit_admin" ...
Done. Don't forget to grant the user permissions to some virtual hosts! See 'rabbitmqctl help set_permissions' to learn more.
podman exec rabbitmq-dev-server rabbitmqctl set_user_tags rabbit_admin administrator
Setting tags for user "rabbit_admin" to [administrator] ...
podman exec rabbitmq-dev-server rabbitmqctl set_permissions -p logistics_vhost rabbit_admin ".*" ".*" ".*"
Setting permissions for user "rabbit_admin" in vhost "logistics_vhost" ...
Creating application users...
podman exec rabbitmq-dev-server rabbitmqctl add_user order_sender 'OrderSenderP@ssw0rd' || echo "User order_sender already exists."
Adding user "order_sender" ...
Done. Don't forget to grant the user permissions to some virtual hosts! See 'rabbitmqctl help set_permissions' to learn more.
podman exec rabbitmq-dev-server rabbitmqctl add_user delivery_receiver 'DeliveryReceiverP@ssw0rd' || echo "User delivery_receiver already exists."
Adding user "delivery_receiver" ...
Done. Don't forget to grant the user permissions to some virtual hosts! See 'rabbitmqctl help set_permissions' to learn more.
Setting permissions for application users on vhost logistics_vhost...
podman exec rabbitmq-dev-server rabbitmqctl set_permissions -p logistics_vhost order_sender "" "^order_exchange$" ""
Setting permissions for user "order_sender" in vhost "logistics_vhost" ...
podman exec rabbitmq-dev-server rabbitmqctl set_permissions -p logistics_vhost delivery_receiver "" "" "^logistics_queue$"
Setting permissions for user "delivery_receiver" in vhost "logistics_vhost" ...
Vhost, users, and permissions configured.
Configuration topology RabbitMQ (exchange, queue, binding) with user rabbit_admin...
podman exec rabbitmq-dev-server rabbitmqadmin -u rabbit_admin -p 'SuperS3cureAdminP@ssw0rd!' -V logistics_vhost declare exchange name=order_exchange type=direct durable=true || echo "Exchange order_exchange already exists or error."
exchange declared
podman exec rabbitmq-dev-server rabbitmqadmin -u rabbit_admin -p 'SuperS3cureAdminP@ssw0rd!' -V logistics_vhost declare queue name=logistics_queue durable=true || echo "Queue logistics_queue already exists or error."
queue declared
podman exec rabbitmq-dev-server rabbitmqadmin -u rabbit_admin -p 'SuperS3cureAdminP@ssw0rd!' -V logistics_vhost declare binding source="order_exchange" destination_type="queue" destination="logistics_queue" routing_key="new_order_event" || echo "Binding already exists or error."
binding declared
Topology configured.

Se vuoi far tutto in un colpo solo, puoi eseguire il comando make all, che eseguirà in sequenza i target certs, rabbitmq-pod-start, rabbitmq-setup-permissions e rabbitmq-setup-topology.

Dall'output del comando di avvio puoi notare che il container RabbitMQ è stato avviato correttamente e che sono stati creati gli utenti, i permessi e la topologia necessaria per il corretto funzionamento degli script di esempio. Puoi anche notare che l'immagine RabbitMQ utilizzata è rabbitmq:4.1-management, che include l'interfaccia di gestione web e gli strumenti di monitoraggio e che il nome del container è rabbitmq-dev-server.

Il nome dell'immagine RabbitMQ è specificato nella variabile PODMAN_IMAGE_NAME del Makefile e il nome del container è specificato nella variabile CONTAINER_NAME. Puoi modificare questi valori se desideri utilizzare un'immagine diversa o un nome di container diverso.

Come vedere i log di RabbitMQ

Puoi visualizzare i log di RabbitMQ in tempo reale con:

make rabbitmq-logs

Questo comando ti permetterà di monitorare le attività del broker e diagnosticare eventuali problemi. A seguire un esempio di output:

2025-05-16 13:22:50.696329+00:00 [info] <0.931.0> accepting AMQP connection 192.168.127.1:59736 -> 10.88.0.39:5671
2025-05-16 13:22:50.716750+00:00 [debug] <0.931.0> User 'order_sender' authenticated successfully by backend rabbit_auth_backend_internal
2025-05-16 13:22:50.718257+00:00 [info] <0.931.0> Connection from AMQP 1.0 container '062a2bba-b46d-46ba-a63c-c8323456ac9c': user 'order_sender' authenticated using SASL mechanism PLAIN and granted access to vhost 'logistics_vhost'
2025-05-16 13:22:50.718347+00:00 [debug] <0.931.0> AMQP 1.0 connection.open frame: hostname = vhost:logistics_vhost, extracted vhost = logistics_vhost, idle-time-out = undefined
2025-05-16 13:22:50.722351+00:00 [debug] <0.931.0> AMQP 1.0 created session process <0.936.0> for channel number 0
2025-05-16 13:22:50.731249+00:00 [debug] <0.931.0> AMQP 1.0 closed session process <0.936.0> with channel number 0
2025-05-16 13:22:50.736862+00:00 [info] <0.931.0> closing AMQP connection (192.168.127.1:59736 -> 10.88.0.39:5671, duration: '40ms')

Vedendo questo log è possibile notare che il producer order_sender si è autenticato correttamente e ha aperto una connessione AMQP 1.0 con RabbitMQ. Puoi anche vedere i dettagli della connessione, come l'hostname e il vhost utilizzato.

Come fermare e riavviare RabbitMQ

Per fermare il container RabbitMQ, puoi eseguire:

make rabbitmq-pod-stop

Questo comando fermerà il container RabbitMQ in esecuzione mostrando un output simile a questo:

Stopping RabbitMQ container (rabbitmq-dev-server)...
rabbitmq-dev-server

Per riavviare il container RabbitMQ, puoi eseguire:

make rabbitmq-pod-start

Questo comando avvierà nuovamente il container RabbitMQ mostrando un output simile a questo:

Checking /etc/hosts for entry '127.0.0.1 rabbitmq.labs.dontesta.it'...
/etc/hosts is OK.
Starting RabbitMQ container (rabbitmq-dev-server) with image rabbitmq:4.1-management...
Container rabbitmq-dev-server exists but is not running. Removing it first...
24212a76d62a279e6d65922028aa12a9156e7f209b12ca81d17d6e9cf5473adc
Container rabbitmq-dev-server created and started.
Waiting for RabbitMQ in container rabbitmq-dev-server to be ready...
RabbitMQ is ready.

Esempio di Producer e Consumer in Python

Vediamo ora come si struttura un tipico producer e un consumer Python che comunicano con RabbitMQ tramite AMQP 1.0 e mTLS, evidenziando solo le parti fondamentali e il loro scopo.

Flusso di Comunicazione mTLS

Il diagramma seguente illustra il flusso di comunicazione sicuro tra il Producer, RabbitMQ e il Consumer, utilizzando mTLS e AMQP 1.0.

Producer: invio di ordini in modo sicuro

Caso d’uso:
Un microservizio producer deve inviare messaggi di nuovo ordine a RabbitMQ, garantendo che la comunicazione sia cifrata e autenticata tramite certificati; uno scenario comune in un’architettura a microservizi.

Punti chiave nello script:

• Configurazione SSL/mTLS:
  Il producer carica i percorsi dei certificati CA, client e chiave privata, e configura Proton per la verifica reciproca.
• Connessione protetta:
  La connessione viene stabilita usando l’URL amqps://, il vhost corretto e il parametro sni per l’SNI (Server Name Indication) TLS.
• Generazione ordini random:
  Prima di inviare, il producer genera un numero configurabile di ordini con dati casuali (ID, descrizione, quantità).
• Invio messaggi:
  Ogni ordine viene serializzato in JSON e inviato all’exchange configurato.
  La conferma di avvenuta ricezione da parte di RabbitMQ viene gestita tramite callback.

Consumer: ricezione sicura degli ordini

Caso d’uso:
Un microservizio consumer si collega a RabbitMQ per ricevere e processare i messaggi degli ordini, sempre in modo autenticato e cifrato; uno scenario comune in un’architettura a microservizi.

Punti chiave nello script:

• Configurazione SSL/mTLS:
  Anche il consumer carica i propri certificati e configura Proton per la verifica del server e la presentazione del certificato client.
• Connessione protetta:
  Si connette al broker usando le stesse impostazioni di sicurezza del producer.
• Ricezione e conferma:
  Riceve i messaggi dalla coda, li deserializza e li processa.
  Dopo l’elaborazione, invia una conferma esplicita (ACK) a RabbitMQ per ogni messaggio ricevuto.
• Gestione errori:
  In caso di errore di parsing o elaborazione, il messaggio può essere rilasciato o rifiutato, a seconda della logica implementata.

Nota:
Entrambi gli script fanno uso delle stesse best practice:

• Percorsi assoluti per i certificati per evitare problemi di path traversal.
• Uso di variabili d’ambiente per parametri sensibili.
• Separazione chiara tra configurazione di sicurezza e logica applicativa.

Questa architettura ti permette di testare end-to-end la sicurezza e la robustezza della tua soluzione RabbitMQ già in fase di sviluppo.

Punti di attenzione: AMQP 1.0, mTLS, Virtual Host e SNI con Proton

Quando si lavora con RabbitMQ, AMQP 1.0, mTLS e la libreria Proton, ci sono alcuni aspetti tecnici e trappole comuni che è importante conoscere per evitare errori difficili da diagnosticare.

1. AMQP 1.0, Virtual Host e Addressing

• Addressing:
  RabbitMQ utilizza un sistema di addressing basato su virtual host, exchange e queue. È importante comprendere come questi elementi interagiscono tra loro per garantire una corretta instradamento dei messaggi. In particolare l'addressing AMQP 1.0 è diverso da quello di AMQP 0-9-1, introducendo la versione 2 di cui qui https://www.rabbitmq.com/docs/amqp#address-v2 sono disponibili i dettagli.
• Formato del Virtual Host:
  RabbitMQ, quando utilizza AMQP 1.0, si aspetta che il virtual host venga specificato in un formato particolare (es. vhost:nome_vhost).
  Se il formato non è corretto, la connessione viene accettata ma il client potrebbe non avere accesso alle risorse desiderate o ricevere errori di autorizzazione perché si collegherà al vhost di default.
• Parametro virtual_host in Proton:
  Il parametro virtual_host passato alla funzione connect() di Proton deve corrispondere esattamente al nome del vhost configurato in RabbitMQ, e deve essere preceduto da vhost: (es. vhost:logistics_vhost).

2. mTLS: Certificati e Verifica

• Verifica reciproca:
  Con mTLS, sia il client che il server devono presentare certificati validi e firmati dalla stessa CA.
  Se anche solo uno dei due certificati non è valido o non è firmato dalla CA corretta, la connessione TLS fallisce.
• Percorsi assoluti:
  Usa sempre percorsi assoluti per i certificati nei tuoi script, per evitare errori dovuti alla directory di lavoro corrente. È anche una buona pratica per evitare problemi di path traversal.
• Subject Alternative Name (SAN):
  Il certificato server deve includere l'FQDN usato dal client (es. rabbitmq.labs.dontesta.it) nei SAN, altrimenti la verifica fallirà.

3. SNI (Server Name Indication) e Proton

• SNI e verifica del certificato:
  Proton, per default, può usare il valore di virtual_host anche come SNI nell’handshake TLS.
  Se il valore di SNI non corrisponde a un SAN valido nel certificato server, la verifica fallisce.
• Soluzione:
  Usa sempre il parametro sni nella chiamata a connect() di Proton per forzare l’SNI corretto (es. il FQDN del server RabbitMQ).
  Questo permette di separare la logica di autenticazione TLS da quella di routing AMQP.

4. Debug e risoluzione dei problemi

• Errori di handshake TLS:
  Spesso sono dovuti a mismatch tra SNI e SAN, o a CA non corretta.
• Errori di autorizzazione AMQP:
  Controlla sempre che il vhost sia corretto e che l’utente abbia i permessi necessari.
• Log di RabbitMQ:
  Consulta sempre i log del broker per capire se il problema è lato TLS, autenticazione, permessi o routing AMQP.

Quando usi Proton con RabbitMQ in mTLS e AMQP 1.0, presta particolare attenzione a come imposti virtual host e SNI, e assicurati che i certificati siano corretti e ben referenziati. Una configurazione attenta ti eviterà la maggior parte dei problemi tipici di interoperabilità e sicurezza.

Per aumentare il livello di trace e debug, puoi anche abilitare il logging dettagliato in RabbitMQ e nella libreria Proton. Questo ti aiuterà a diagnosticare eventuali problemi di connessione o di autenticazione.

In questo progetto di esempio, RabbitMQ è gia configurato con il livello di log debug, quindi puoi vedere in tempo reale cosa succede quando il producer e il consumer si connettono e inviano/ricevono messaggi.

Per quanto riguarda Proton, puoi abilitare un logging dettagliato eseguendo l'export della variabile d'ambiente PN_TRACE_FRM con il valore 1 prima di eseguire gli script Python. Questo ti permetterà di vedere i dettagli di trace sul protocol frame. Per maggiori informazioni sul logging di Proton, puoi consultare la guida sul loggin pubblicata su GitHub.

export PN_TRACE_FRM=1

In questo modo, potrai ottenere informazioni dettagliate su cosa sta accadendo durante la connessione e l'invio/ricezione dei messaggi. Questo è particolarmente utile per il debug e per comprendere meglio il funzionamento interno di Proton e RabbitMQ.

A seguire un esempio di output del trace:

[0x11af7a710]: SASL:FRAME:  -> SASL
[0x11af7a710]: SASL:FRAME:  <- SASL
[0x11af7a710]: AMQP:FRAME:0 <- @sasl-mechanisms(64) [sasl-server-mechanisms=@<symbol>[:PLAIN, :AMQPLAIN, :ANONYMOUS]]
[0x11af7a710]: AMQP:FRAME:0 -> @sasl-init(65) [mechanism=:PLAIN, initial-response=b"\x00order_sender\x00OrderSenderP@ssw0rd"]
[0x11af7a710]: AMQP:FRAME:0 <- @sasl-outcome(68) 
[0x11af7a710]: AMQP:FRAME:  -> AMQP
[0x11af7a710]: AMQP:FRAME:0 -> @open(16) [container-id="c71222a8-93a9-498c-afac-2956a7b18892", hostname="vhost:logistics_vhost", max-frame-size=0x8000, channel-max=0x7fff]
[0x11af7a710]: AMQP:FRAME:0 -> @begin(17) [next-outgoing-id=0x0, incoming-window=0x7fffffff, outgoing-window=0x7fffffff, handle-max=0x7fffffff]
[0x11af7a710]: AMQP:FRAME:0 -> @attach(18) [name="c71222a8-93a9-498c-afac-2956a7b18892-/exchanges/order_exchange/new_order_event", handle=0x0, role=false, snd-settle-mode=0x2, rcv-settle-mode=0x0, source=@source(40) [durable=0x0, timeout=0x0, dynamic=false], target=@target(41) [address="/exchanges/order_exchange/new_order_event", durable=0x0, timeout=0x0, dynamic=false], initial-delivery-count=0x0, max-message-size=0x0]
[0x11af7a710]: AMQP:FRAME:  <- AMQP
[0x11af7a710]: AMQP:FRAME:0 <- @open(16) [container-id="rabbit@rabbitmq", max-frame-size=0x20000, channel-max=0x3f, idle-time-out=0x7530, offered-capabilities=@<symbol>[:"LINK_PAIR_V1_0", :ANONYMOUS-RELAY], properties={:node="rabbit@rabbitmq", :"cluster_name"="rabbit@rabbitmq", :copyright="Copyright (c) 2007-2025 Broadcom Inc and/or its subsidiaries", :information="Licensed under the MPL 2.0. Website: https://rabbitmq.com", :platform="Erlang/OTP 27.3.4", :product="RabbitMQ", :version="4.1.0"}]
[0x11af7a710]: AMQP:FRAME:0 <- @begin(17) [remote-channel=0x0, next-outgoing-id=0xfffffffc, incoming-window=0x190, outgoing-window=0xffffffff, handle-max=0xff]
[0x11af7a710]: AMQP:FRAME:0 <- @attach(18) [name="c71222a8-93a9-498c-afac-2956a7b18892-/exchanges/order_exchange/new_order_event", handle=0x0, role=true, snd-settle-mode=0x2, rcv-settle-mode=0x0, source=@source(40) [durable=0x0, timeout=0x0, dynamic=false], target=@target(41) [address="/exchanges/order_exchange/new_order_event", durable=0x0, timeout=0x0, dynamic=false], max-message-size=0x1000000]
[0x11af7a710]: AMQP:FRAME:0 <- @flow(19) [next-incoming-id=0x0, incoming-window=0x190, next-outgoing-id=0xfffffffc, outgoing-window=0xffffffff, handle=0x0, delivery-count=0x0, link-credit=0xaa]
[0x11af7a710]: AMQP:FRAME:0 -> @transfer(20) [handle=0x0, delivery-id=0x0, delivery-tag=b"1", message-format=0x0] (147) \x00SpE\x00Ss\xc0\x19\x07@@@@@@\xa3\x10application/json\x00Sw\xa1l{\x22order_id\x22: \x22ORD_MTLS_3CF4CF72\x22, \x22item_id\x22: \x22ITEM_B_167\x22, \x22description\x22: \x22Brilliant Gadget\x22, \x22quantity\x22: 3}
[0x11af7a710]: AMQP:FRAME:0 <- @disposition(21) [role=true, first=0x0, last=0x4, settled=true, state=@accepted(36) []]
[0x11af7a710]: AMQP:FRAME:0 -> @close(24) []
[0x11af7a710]: AMQP:FRAME:0 <- @close(24) []
[0x11af7a710]:   IO:FRAME:  <- EOS
[0x11af7a710]:   IO:FRAME:  -> EOS

Nel caso fosse necessario, puoi sempre consultare la documentazione ufficiale di RabbitMQ e Qpid Proton per ulteriori dettagli e best practices.

Esecuzione di Producer e Consumer tramite Makefile

Il Makefile non solo automatizza la configurazione dell'ambiente, ma semplifica anche l'esecuzione degli script Python di producer e consumer. Questo è particolarmente utile per testare rapidamente le modifiche o per dimostrazioni.

Installazione delle dipendenze Python

Prima di poter eseguire il producer o il consumer, assicurati che:

1. L'ambiente RabbitMQ sia completamente configurato e in esecuzione. Puoi ottenere questo risultato con il comando make all. Questo comando si occuperà di generare i certificati, avviare il container RabbitMQ, e configurare vhost, utenti, permessi e la topologia necessaria (exchange, code, binding).
2. Le dipendenze Python per gli script siano installate. Il Makefile fornisce un target per generare il file requirements.txt usando il comando: make requirements. Una volta generato, puoi installare le dipendenze (preferibilmente in un ambiente virtuale Python) usando il comando: pip install -r requirements.txt

In questo modo, l'utente viene guidato a installare le dipendenze necessarie prima di tentare di eseguire gli script, prevenendo errori comuni.

Avviare il Producer

Per avviare lo script Python che funge da producer e invia messaggi a RabbitMQ, esegui:

make producer

Questo comando eseguirà lo script producer.py, che si connetterà a RabbitMQ utilizzando i certificati generati e inizierà a inviare messaggi di "nuovi ordini" all'exchange configurato (/exchanges/order_exchange/new_order_event).

A seguire un esempio di output del producer:

Running Producer Python script...
Producer: Generating 5 random orders...
Producer: Starting container to send 5 message(s)...
Producer: Starting, connecting to amqps://rabbitmq.labs.dontesta.it:5671/, target: /exchanges/order_exchange/new_order_event
Producer: SSL domain configured successfully.
Producer: Attempting mTLS connection to amqps://rabbitmq.labs.dontesta.it:5671/ with user order_sender on vhost vhost:logistics_vhost
Producer: mTLS connection initiated, vhost set to vhost:logistics_vhost
Producer: Sender created for target '/exchanges/order_exchange/new_order_event'
Producer: Message sent (1/5): {'order_id': 'ORD_MTLS_A3737866', 'item_id': 'ITEM_C_561', 'description': 'Cool Gizmo', 'quantity': 8}
Producer: Message sent (2/5): {'order_id': 'ORD_MTLS_FE742F82', 'item_id': 'ITEM_C_970', 'description': 'Cool Gizmo', 'quantity': 4}
Producer: Message sent (3/5): {'order_id': 'ORD_MTLS_07104306', 'item_id': 'ITEM_A_954', 'description': 'Amazing Widget', 'quantity': 4}
Producer: Message sent (4/5): {'order_id': 'ORD_MTLS_2BF2F2CC', 'item_id': 'ITEM_A_238', 'description': 'Amazing Widget', 'quantity': 4}
Producer: Message sent (5/5): {'order_id': 'ORD_MTLS_C22EAF68', 'item_id': 'ITEM_E_438', 'description': 'Elegant Contraption', 'quantity': 7}
Producer: Message accepted by broker. Confirmed: 1/5
Producer: Message accepted by broker. Confirmed: 2/5
Producer: Message accepted by broker. Confirmed: 3/5
Producer: Message accepted by broker. Confirmed: 4/5
Producer: Message accepted by broker. Confirmed: 5/5
Producer: All messages have been confirmed.
Producer: Container execution finished.

In questo esempio, il producer genera 5 ordini casuali e li invia a RabbitMQ. Ogni messaggio viene confermato dal broker, garantendo che sia stato ricevuto correttamente.

Avviare il Consumer

Per avviare lo script Python che funge da consumer e riceve messaggi da RabbitMQ, esegui:

make consumer

Questo comando eseguirà lo script consumer.py, che si connetterà a RabbitMQ utilizzando i certificati generati e inizierà a ricevere messaggi dalla coda configurata (/queues/logistics_queue).

A seguire un esempio di output del consumer:

Running Consumer Python script...
Consumer: Starting container to receive messages (Ctrl+C to interrupt)...
Consumer: Starting, connecting to amqps://rabbitmq.labs.dontesta.it:5671, source: /queues/logistics_queue
Consumer: SSL domain configured successfully.
Consumer: Attempting mTLS connection to amqps://rabbitmq.labs.dontesta.it:5671 with user delivery_receiver on vhost vhost:logistics_vhost
Consumer: mTLS connection initiated, vhost set to vhost:logistics_vhost
Consumer: Receiver created for source '/queues/logistics_queue'
--------------------
Consumer: New message received! (Total: 1)
Consumer: Content: {'order_id': 'ORD_MTLS_A3737866', 'item_id': 'ITEM_C_561', 'description': 'Cool Gizmo', 'quantity': 8}
Consumer: Order processed.
Consumer: Message confirmed (accepted).
--------------------
--------------------
Consumer: New message received! (Total: 2)
Consumer: Content: {'order_id': 'ORD_MTLS_FE742F82', 'item_id': 'ITEM_C_970', 'description': 'Cool Gizmo', 'quantity': 4}
Consumer: Order processed.
Consumer: Message confirmed (accepted).
--------------------
--------------------
Consumer: New message received! (Total: 3)
Consumer: Content: {'order_id': 'ORD_MTLS_07104306', 'item_id': 'ITEM_A_954', 'description': 'Amazing Widget', 'quantity': 4}
Consumer: Order processed.
Consumer: Message confirmed (accepted).
--------------------
--------------------
Consumer: New message received! (Total: 4)
Consumer: Content: {'order_id': 'ORD_MTLS_2BF2F2CC', 'item_id': 'ITEM_A_238', 'description': 'Amazing Widget', 'quantity': 4}
Consumer: Order processed.
Consumer: Message confirmed (accepted).
--------------------
--------------------
Consumer: New message received! (Total: 5)
Consumer: Content: {'order_id': 'ORD_MTLS_C22EAF68', 'item_id': 'ITEM_E_438', 'description': 'Elegant Contraption', 'quantity': 7}
Consumer: Order processed.
Consumer: Message confirmed (accepted).
--------------------
Consumer: Reception interrupted by user.
Consumer: Container execution finished.

In questo esempio, il consumer riceve i messaggi dalla coda e li elabora uno alla volta. Ogni messaggio viene confermato dopo l'elaborazione, garantendo che non venga perso. Il consumer continua a ricevere messaggi fino a quando non viene interrotto manualmente (Ctrl+C).

Conclusione

Abbiamo reso la configurazione di RabbitMQ 4.1 più sicura ed efficiente integrando mTLS, che abilita l’autenticazione reciproca tra client e server. Abbiamo mostrato come generare i certificati necessari, configurare RabbitMQ per la verifica dei client, e realizzare due script Python, producer e consumer, capaci di comunicare in modo sicuro tramite AMQP 1.0.

Inoltre, abbiamo evidenziato il valore del Makefile nell’automatizzare la generazione dei certificati e la gestione del container, semplificando il setup e riducendo il rischio di errori manuali.

Sono stati evidenziati alcuni punti critici da tenere a mente quando si lavora con RabbitMQ, AMQP 1.0 e mTLS, come la corretta configurazione dei virtual host, l'uso di SNI e la gestione dei certificati.

Questa configurazione non solo migliora la sicurezza della tua applicazione event-driven, ma ti prepara anche a scenari di produzione reali, dove la sicurezza e l'affidabilità sono fondamentali.

L'articolo RabbitMQ 4.1 mTLS e AMQP 1.0: Guida essenziale per sviluppatori sembra essere il primo su Antonio Musarra's Blog.

L'automazione del processo di build e distribuzione di immagini native rappresenta un elemento chiave nell'ottimizzazione del ciclo di sviluppo e rilascio di applicazioni. Questo articolo analizza come GitHub Actions possa essere sfruttato per orchestrare la build e la pubblicazione di immagini native di applicazioni Quarkus, utilizzando Quarkus CLI.

Il workflow descritto è implementato nel progetto quarkus-graphql-quickstart e si occupa di generare un'immagine nativa e distribuirla su un container registry. L'obiettivo principale è garantire efficienza, riproducibilità e scalabilità, minimizando l'intervento manuale nel processo di deployment.

Configurazione della GitHub Action

Il workflow è definito nel file docker_publish_native_quarkus_cli.yml. Di seguito, ne analizziamo le componenti principali, esplorando ogni aspetto in dettaglio.

Nella nostra GitHub Action, utilizziamo Quarkus CLI al posto di Maven per diversi motivi. Quarkus CLI offre un approccio più astratto rispetto a Maven, specialmente quando si lavora con diversi strumenti di build. Ecco alcuni motivi per preferire Quarkus CLI a Maven nelle pipeline:

• Astrazione dello strumento di build: Quarkus CLI permette di interagire con progetti sia Maven che Gradle allo stesso modo. Questo significa che i comandi rimangono consistenti indipendentemente dal sistema di build sottostante.
• Gestione semplificata delle estensioni: Quarkus CLI fornisce comandi intuitivi per trovare, aggiungere e rimuovere estensioni Quarkus, semplificando la gestione delle dipendenze del progetto.
• Coerenza: L'uso di Quarkus CLI garantisce una maggiore coerenza tra i diversi progetti, specialmente in ambienti dove sia Maven che Gradle sono utilizzati.

In sintesi, l'uso di Quarkus CLI può semplificare e uniformare le operazioni di build, rendendo le pipeline più manutenibili e meno dipendenti dallo strumento di build specifico del progetto.

Eventi Trigger

Gli eventi trigger determinano quando la pipeline viene eseguita automaticamente. In questo caso, la pipeline si attiva nei seguenti scenari:

on:
  push:
    branches:
      - develop
      - main
  release:
    types: [ published ]

• Push su develop e main: ogni volta che viene effettuato un push su queste branch, il workflow viene avviato per garantire che le ultime modifiche siano costruite e pubblicate immediatamente. Questo aiuta a mantenere aggiornate le immagini e a testare il codice più recente.
• Pubblicazione di una release: quando viene pubblicata una nuova release, la pipeline si avvia automaticamente per costruire e distribuire un'immagine nativa basata sul codice stabile della release. Questo garantisce che le versioni ufficiali dell'applicazione siano immediatamente disponibili per l'uso in produzione.

Configurazione dei Job

La configurazione dei job definisce l'ambiente e la strategia di esecuzione della pipeline. In questo caso, il workflow utilizza una matrice di esecuzione per garantire compatibilità su diverse piattaforme e architetture.

jobs:
  docker:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-24.04', 'ubuntu-24.04-arm' ]
        include:
          - os: ubuntu-24.04
            current_platform: 'amd64'
          - os: ubuntu-24.04-arm
            current_platform: 'arm64'

Ogni job viene eseguito su uno dei due ambienti definiti nella matrice: Ubuntu 24.04 per AMD64 e Ubuntu 24.04 per ARM64. La strategia della matrice permette di eseguire il workflow su entrambe le architetture contemporaneamente, assicurando che il codice sia compatibile sia con sistemi x86_64 che ARM.

 Nota: L'esecuzione su Linux ARM64 è attualmente in anteprima pubblica ed è soggetta a modifiche. L'uso di questa architettura consente di testare e ottimizzare le prestazioni dell'applicazione su dispositivi ARM, sempre più diffusi in ambito cloud e edge computing. Per maggiori informazioni fare riferimento alla documentazione About GitHub-hosted runners.

Questa strategia garantisce compatibilità con diverse architetture hardware, migliorando la portabilità dell'applicazione.

Passaggi della Pipeline

La pipeline è composta da una serie di step che permettono di automatizzare il processo di build e distribuzione dell’applicazione. Ogni step viene eseguito sequenzialmente per garantire che il codice venga recuperato, compilato, testato e infine pubblicato come immagine container.

1. Clonazione del Repository

Il primo step assicura che il codice sorgente più recente sia disponibile per la pipeline.

- uses: actions/checkout@v3
  with:
    fetch-depth: 0

Cosa fa il primo step?

• Clona l’intero repository, garantendo accesso alla cronologia completa dei commit.
• Il valore fetch-depth: 0 permette di recuperare tutti i commit, utile per calcoli di differenza tra versioni.

2. Configurazione di GraalVM

GraalVM è essenziale per la creazione di immagini native altamente ottimizzate, riducendo il tempo di avvio e il consumo di memoria dell'applicazione. Per approfondimenti sulla configurazione della GitHub Action graalvm/setup-graalvm@v1, consulta la documentazione ufficiale.

- name: Set up GraalVM
  uses: graalvm/setup-graalvm@v1
  with:
    java-version: '23.0.2'
    distribution: 'graalvm'
    github-token: ${{ secrets.TOKEN_GITHUB }}
    native-image-job-reports: 'true'

Cosa fa questo secondo step?

• Installa e configura GraalVM per l’ambiente di esecuzione.
• Imposta Java 23.0.2 e attiva la generazione di report per la build nativa.

3. Installazione di JBang e Quarkus CLI

Quarkus CLI consente di gestire e costruire applicazioni Quarkus in modo efficiente, semplificando la gestione delle dipendenze e delle configurazioni.

- name: Install JBang and Quarkus CLI
  run: |
    curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
    curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio
    echo "PATH=$PATH:/home/runner/.jbang/bin" >> $GITHUB_ENV

 Cosa fa questo terzo step?

• Installa JBang, un tool per la gestione di script Java.
• Installa e configura Quarkus CLI per eseguire build e gestire le dipendenze.

Per ulteriori dettagli sull’installazione della Quarkus CLI, consulta la documentazione ufficiale.

4. Autenticazione su Docker Hub

Prima di pubblicare l’immagine container, è necessario effettuare l’accesso a Docker Hub.

- name: Login to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_TOKEN }}

Cosa fa questo quarto step?

• Usa le credenziali salvate nei GitHub Secrets per effettuare il login a Docker Hub.
• Questo passaggio è fondamentale per poter pubblicare l’immagine nel repository remoto.

Per approfondimenti sulla gestione dei secrets in GitHub Actions, consulta la documentazione ufficiale.

5. Creazione dell’artefatto nativo

Questo step compila l’applicazione in un eseguibile nativo utilizzando Quarkus CLI.

- name: Build Native Artifact
  run: |
    quarkus build --native

Cosa fa questo quinto step?

• Compila il codice sorgente generando un eseguibile nativo altamente performante.
• Il codice risultante è ottimizzato per ridurre il consumo di memoria e migliorare il tempo di avvio.

6. Creazione e pubblicazione dell’immagine Docker

Infine, il codice compilato viene trasformato in un’immagine container e pubblicato su Docker Hub.

# Build the native image and push the Docker image
- name: Build Native Image and Push Docker Image
  run: |
    quarkus image build --native \
    -Dquarkus.native.additional-build-args=-march=native,-H:BuildOutputJSONFile=/tmp/native-image-build-output.json \
    -Dquarkus.native.container-build=false \
    -Dquarkus.container-image.push=true \
    -Dquarkus.container-image.registry=docker.io \
    -Dquarkus.container-image.username=${{ secrets.DOCKER_USERNAME }} \
    -Dquarkus.container-image.image=${{ secrets.DOCKER_USERNAME }}/${{ github.event.repository.name }}-native:${{ github.ref_name }}-${{ matrix.current_platform }} \
    -Dquarkus.container-image.additional-tags="latest-${{ matrix.current_platform }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.title\"="${{ github.event.repository.name }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.description\"="A native image built with Quarkus CLI" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.url\"="https://github.com/${{ github.repository }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.source\"="https://github.com/${{ github.repository }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.version\"="${{ github.ref_name }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.created\"="${{ steps.prep.outputs.created }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.revision\"="${{ github.sha }}" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.authors\"="Antonio Musarra <antonio.musarra@gmail.com>" \
    -Dquarkus.container-image.labels.\"org.opencontainers.image.licenses\"="MIT"

Cosa fa questo sesto step?

• Crea un’immagine container contenente l’eseguibile nativo.
• Applica tag specifici per identificare le versioni dell’immagine.
• Applica un set di label Open Containers (come description, url, source, etc.).
• Pubblica automaticamente l’immagine su Docker Hub.

Per ulteriori dettagli sulle specifiche Open Containers, consulta la documentazione ufficiale e in particolare la sezione Annotations sul repository GitHub.

Esecuzione della GitHub Action

La pipeline di GitHub Actions si avvia automaticamente in risposta a eventi specifici, garantendo un processo di build e deploy completamente automatizzato.

1. Quando si Attiva la Pipeline?

Il workflow viene eseguito nei seguenti scenari:

• Push su develop e main: ogni modifica su queste branch avvia automaticamente il workflow per garantire che il codice aggiornato venga compilato e pubblicato.
• Pubblicazione di una release: ogni volta che viene creata una nuova release, la pipeline si attiva per generare e distribuire un’immagine nativa della versione stabile.

2. Monitoraggio dell’Esecuzione

Una volta avviata, l’esecuzione della pipeline può essere monitorata direttamente dalla scheda Actions del repository GitHub. Qui è possibile:

• Osservare lo stato di avanzamento del workflow in tempo reale.
• Visualizzare i log dettagliati di ogni step per diagnosticare eventuali problemi.
• Identificare rapidamente errori grazie all’evidenziazione dei messaggi di errore e warning.

Le immagini a seguire evidenziano il processo automatizzato di build e deployment dell’immagine nativa del progetto su Docker Hub, mostrando, sia il workflow GitHub Actions completato con successo, sia il report dettagliato della compilazione GraalVM (grazie al parametro native-image-job-reports:true).

Puoi vedere i log completi di questo specifico workflow e job docker (ubuntu-24.04) di cui a seguire è mostrato l'esempio di ciò che vedresti.

Nel caso in cui avessi installato il GitHub CLI (gh), potresti usare per esempio, il comando gh run list -b main --workflow build_via_quarkus_cli.yml, per elencare le esecuzioni del workflow GitHub Actions build_via_quarkus_cli.yml sul branch main. 

Questo comando è utile per monitorare rapidamente lo stato delle build eseguite tramite Quarkus CLI senza dover accedere manualmente all’interfaccia web di GitHub Actions. A seguire un esempio di output.

Al termine del workflow, l’immagine container sarà quindi disponibile nel container registry configurato nel file di workflow, pronta per essere utilizzata in ambienti di sviluppo o produzione. A seguire sono mostrate le due immagini native, una per ARM64 e una per AMD64, contrassegnate dai rispettivi tag.

Conclusioni

Questa pipeline GitHub Actions automatizza l’intero ciclo di sviluppo, dalla compilazione al rilascio dell’immagine container. L’uso combinato di Quarkus CLI, GraalVM e Docker garantisce build efficienti, rapide e compatibili con diverse architetture.

Per approfondire:

• Documentazione ufficiale di Quarkus
• GitHub Actions
• Repository del progetto
• Metodo classico via Buildx: Pubblica su Docker Hub con le GitHub Actions - Canale YouTube EmmeCiLab - Informatica e Matematica
• Progetto Graalkus: Let Quarkus fly high with GraalVM: come creare l'immagine nativa per più piattaforme usando Buildx

Se hai domande o suggerimenti, lascia un commento qui sotto!

L'articolo GitHub Actions: Build e Push di Immagini Container con Quarkus CLI sembra essere il primo su Antonio Musarra's Blog.

In questo articolo vedremo:

1. Perché configurare Oracle Database in locale
2. Come creare la tua immagine container per Apple Silicon
3. Come condividere l’immagine container su un repository
4. Best practice per ottimizzare l’ambiente

Perche usare Oracle Database in locale

Oracle è uno dei database più utilizzati in ambito enterprise. Le ragioni per essere incluso in un ambiente di sviluppo locale sono molteplici e riporto a seguire quelle più comuni.

• Conformità ai requisiti aziendali: molte applicazioni sono progettate specificamente per Oracle, ed eseguire i test su altri database può portare a errori imprevisti.
• Testing di funzionalità avanzate: alcune caratteristiche, come i tablespace, le partizioni o PL/SQL, richiedono Oracle per essere testate correttamente.
• Miglioramento della velocità di sviluppo: avere un database locale elimina la latenza e la dipendenza da infrastrutture remote, garantendo una velocità di sviluppo e debug significativamente maggiore.

Come creare un'immagine container di Oracle 19c

Vedremo adesso come usare gli strumenti messi a disposizione dal progetto oracle/docker-images per creare facilmente un’immagine container di Oracle Database 19c anche su architetture ARM.

Prima di iniziare con la procedura di creazione, è necessario che siano soddisfatti i seguenti requisiti.

1. Mac con Apple Silicon (M1 o M2)
2. Docker Desktop installato (versione minima engine 17.09) o Podman Desktop (versione minima engine 1.6.0)
3. File binari di Oracle 19c scaricati dal sito ufficiale. Per il download è richiesto essere in posseso di un account Oracle e accettare i termini di licenza.
4. Storage minino 20-25 Gbyte. Spazio necessario per la build e installazione dell'edizione Enterprise di Oracle.
5. Git

Ho fatto riferimento alla serie M1 e M2 dei processori Apple Silicon, perché sono quelli per cui ho avuto modo di eseguire il processo di creazione dell'immagine container. I possesori più recenti, M3 e M4 non dovrebbero incontrare problemi.

Personalmente prediligo ormai da tempo l'uso di Podman, ragion per cui, l'immagine container sarà creata usando questo strumento. L'uso di Docker non comporta alcuna differenza in termini di sintassi dei comandi; qualora ne sia presente qualcuna, sarà opportunamente segnalata nel corso dell'articolo.

Procediamo per step con la costruzione dell'immagine container di Oracle 19c. Il primo passo è l'operazione di clone del repository oracle/docker-images.

# Step 1
#  1. Clonazione del repository https://github.com/oracle/docker-images.git
#  2. Cambio directory su docker-images/OracleDatabase/SingleInstance/dockerfiles 
git clone https://github.com/oracle/docker-images.git

cd docker-images/OracleDatabase/SingleInstance/dockerfiles

Il prossimo passo è il download del file LINUX.ARM64_1919000_db_home.zip dal sito di Oracle che deve poi essere copiato all'interno della directory 19.3.0.

# File LINUX.ARM64_1919000_db_home.zip scaricato dal sito di Oracle e copiato
# nella directory 19.3.0 
-rw-r--r--@ 1 amusarra  staff   2,2G 24 Dic 13:00 19.3.0/LINUX.ARM64_1919000_db_home.zip

A questo punto passiamo alla costruzione dell'immagine container usando lo script buildContainerImage.sh passando i parametri necessari affinché sia costruita la versione 19.3.0 edizione Enterprise.

Nel caso abbiate scelto di usare Podman, sono necessarie delle operazioni preliminari da eseguire prima di eseguire lo script di creazione dell'immagine container. Occorre fare l'esportazione di due variabili di ambiente: BUILDAH_FORMAT=docker e BUILDAH_ISOLATION=chroot. La prima variabile è richiesta per supportare HEALTHCHECK specificato nel Dockerfile. La seconda variabile è richiesta durante la build dell'immagine container in modalità rootless.

A seguire sono indicati i comandi che dobbiamo lanciare dalla nostra console per avviare il processo di creazione dell'immagine container di Oracle 19c edizione Enterprise (flag -e dello script buildContainerImage.sh).

Nota: Solo l'edizione Enterprise è supportata per le piattaforme ARM64 e di conseguenza Apple Silicon (serie M). Per maggiori informazioni sull'uso dello script, consultare il README del progetto oracle/docker-images.

# Esportazione di BUILDAH_FORMAT e BUILDAH_ISOLATION solo nel caso in cui
# abbiate scelto di usare Podman.
export BUILDAH_FORMAT=docker
export BUILDAH_ISOLATION=chroot

# Avvio del processo di creazione dell'immagine container di Oracle 19c Enterprise Edition
./buildContainerImage.sh -v 19.3.0 -e

Il processo di build impiegherà un po' di tempo, a seconda della velocità della propria connessione alla rete internet e dalle prestazioni del proprio Mac. Quando l'esecuzione dello script buildContainerImage.sh arriverà al termine, sul terminale dovreste vedere un output simile a quello mostrato a seguire.

[3/3] COMMIT oracle/database:19.3.0-ee
--> 337cf702a194
Successfully tagged localhost/oracle/database:19.3.0-ee
337cf702a194caab7145893915ea8616dc5dfa762a335a078cb4613db4acd766


  Oracle Database container image for 'ee' version 19.3.0 is ready to be extended:

    --> oracle/database:19.3.0-ee

  Build completed in 345 seconds.

Possiamo verificare la nuova immagine usando il comando podman image ls --filter "reference=localhost/oracle/database:19.3.0-ee" o docker image ls --filter "reference=localhost/oracle/database:19.3.0-ee", ottenendo un output simile a quello mostrato a seguire.

REPOSITORY                 TAG         IMAGE ID      CREATED         SIZE
localhost/oracle/database  19.3.0-ee   337cf702a194  12 minutes ago  5.6 GB

Test di avvio del container Oracle

A questo punto siamo nelle condizioni di poter eseguire un test dell'immagine appena creata avviando l'istanza di Oracle 19c usando il comando indicato a seguire.

# Creazione della directory per il volume
# dei dati Oracle
mkdir -p ~/.oracle/oradata

# Avvio dell'istanza Oracle 19c.
# Nel caso di docker basta sostituire podman con docker
podman run --name oracle19c \
  -p 1521 -p 5500:5500 \
	-e ORACLE_SID=MYDEVENV \
	-e ORACLE_PDB=MYDEVPDB1 \
	-e ORACLE_PWD=LwB_27i5Wi8=1 \
	-v ~/.oracle/oradata:/opt/oracle/oradata \
 	oracle/database:19.3.0-ee

# Per avviare il container in background usare l'opzione -d 
podman run -d --name oracle19c \
	-p 1521 -p 5500:5500 \
	-e ORACLE_SID=MYDEVENV \
	-e ORACLE_PDB=MYDEVPDB1 \
	-e ORACLE_PWD=LwB_27i5Wi8=1 \
	-v ~/.oracle/oradata:/opt/oracle/oradata \
 	oracle/database:19.3.0-ee

# Per visualizzare il log
podman logs -f oracle19c

Quando si crea l'istanza Oracle è opportuno impostare i parametri indicati sul comando podman run o docker run (vedi opzione -e) invece di lasciare i valori di default.

Senza specificare il volume (vedi opzione -v del comando podman run) per il database, i dati andrebbero persi ogni qualvolta il container fosse ricreato, situazione solitamente non voluta.

Consultare il README del progetto oracle/docker-images per verificare tutti i parametri disponibili per il database. Questi parametri sono molto utili al fine del tuning sulla base delle proprie esigenze.

Esiste la possibilità alquanto comoda, di poter eseguire script SQL alla fine della fase di inizializzazione del database. Qui Running scripts after setup and on startup è descritta la modalità d'uso, mentre in questo articolo How to setup Docker container Oracle Database 19c for Liferay Development Environment è possibile vedere un caso pratico.

Il primo avvio può durare da pochi minuti fino ad alcune decine di minuti, a seconda della configurazione. È importante consultare l'output del container per verificare quando il database è effettivamente pronto all'uso (messaggio: DATABASE IS READY TO USE!). I successivi avvii saranno decisamente più veloci.

Volendo potremmo anche monitorare lo status del container usando il comando podman ps -f "name=oracle19c" o docker ps -f "name=oracle19c" verificando il valore della colonna STATUS che dovrebbe essere valorizzata con Up <n> minutes (starting) quando ancora il container è in fase di avvio per poi assumere il valore Up <n> minutes (healthy) una volta che l'istanza Oracle sarà operativa.

Per fare una verifica veloce che tutto sia andato per il verso giusto, eseguiamo un test di connessione usando il comando podman exec -it oracle19c sqlplus system/LwB_27i5Wi8=1 per ottenere un output simile a quello indicato a seguire.

SQL*Plus: Release 19.0.0.0.0 - Production on Sat Jan 4 23:03:40 2025
Version 19.19.0.0.0

Copyright (c) 1982, 2023, Oracle.  All rights reserved.

Last Successful login time: Sat Jan 04 2025 22:56:53 +00:00

Connected to:
Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production
Version 19.19.0.0.0

SQL>

Ultima verifica da poter fare è la connessione alla console Enterprise Manager Database Express disponibile all'indirizzo https://localhost:5500/em accedendo con le credenziali da sysdba.

Dopo aver creato l'immagine container di Oracle 19c ed eseguito un test di avvio dell'istanza Oracle, possiamo passare alla pubblicazione su un repository per immagini container.

Come condividere l'immagine container su repository

Per condividere l’immagine con il team o accedervi da altre macchine, possiamo pubblicarla su un repository pubblico o privato. Esistono diversi repository, ma per lo scopo didattico dell'articolo, la scelta ricade su Docker Hub. Qualora non abbiate un account su Docker Hub, è necessario crearlo affinché sia possibile eseguire il push dell'immagine. La creazione dell'account è gratuita seguendo il link Create your account on Docker Hub.

I passi per poter pubblicare l'immagine su Docker Hub sono:

1. eseguire il login su Docker Hub;
2. eseguire il tag dell'immagine;
3. eseguire il push dell'immagine.

A seguire sono indicati i comandi che devono essere lanciati dalla propria console.

# Login su Docker Hub usando Podman
podman login docker.io

# Login su Docker Hub usando Docker
# Sostituisci <your-username> con il tuo nome utente Docker Hub.
docker login -u <your-username>

# Tag dell'immagine (sostituisci podman con docker nel caso usassi Docker)
# Sostituisci <your-dockerhub-username> con il tuo nome utente Docker Hub.
podman tag oracle/database:19.3.0-ee <your-dockerhub-username>/oracle19c:19.3.0

# Push dell'immagine su Docker Hub (sostituisci podman con docker nel caso usassi Docker)
# Sostituisci <your-dockerhub-username> con il tuo nome utente Docker Hub.
podman push <your-dockerhub-username>/oracle19c:19.3.0

Dopo aver eseguito il push dell'immagine di Oracle 19c, accedendo su Docker Hub dovreste vedere la nuova immagine e i dettagli, così come mostrato dalla figura a seguire. In questo caso è opportuno configurare questo specifico repository come privato (che nel piano gratuito è disponibile solo una unità).

Da questo momento in poi sarà possibile reperire l'immagine di Oracle 19c eseguendo il pull in questo modo: podman pull docker.io/amusarra/oracle19c:19.3.0 (o usando il comando docker al posto di podman).

Best practice per l’ottimizzazione

Una volta configurata l’immagine container di Oracle Database 19c, ci sono diverse strategie che possiamo adottare per ottimizzarne l’utilizzo e migliorare la produttività. Di seguito sono indicati una serie di suggerimenti per configurare al meglio l'ambiente di sviluppo.

1. Configurazione delle risorse: imposta limiti di CPU e RAM per evitare che il database monopolizzi le risorse.
2. Persistenza dei dati: utilizza volumi per salvare i dati, così da evitare perdite in caso di riavvio del container.
3. Gestione delle versioni: utilizza tag specifici per differenziare le versioni dell’immagine (es. 19.3.0-dev o 19.3.0-prod).

Conclusioni

Configurare e condividere un’immagine container di Oracle Database 19c per Apple Silicon è un’operazione semplice e pratica. Salvando l’immagine su uno dei repository disponibili (anche gratuitamente), puoi ridurre i tempi di configurazione, migliorare la collaborazione con il tuo team e garantire un ambiente di sviluppo coerente.

Risorse

Per approfondire i concetti trattati in questo articolo e ottimizzare ulteriormente l’utilizzo di Oracle Database su Docker, ecco alcune risorse online utili.

Documentazione Ufficiale

• Oracle Database 19c Documentation. La documentazione ufficiale di Oracle Database 19c offre informazioni dettagliate sulle funzionalità, configurazioni e parametri avanzati (https://docs.oracle.com/en/database/oracle/oracle-database/19/index.html).
• Docker. La guida ufficiale di Docker fornisce una panoramica completa sull’utilizzo di container, volumi, reti e best practice (https://docs.docker.com/).

Libri

• Oracle on Docker: Running Oracle Databases in Linux Containers di Sean Scott. Questo libro affronta i container dal punto di vista di amministratori di database, sviluppatori e amministratori di sistema. Spiega le differenze tra container e macchine virtuali e descrive perché i contenitori offrono maggiore velocità, flessibilità e portabilità, con requisiti di risorse inferiori. Imparerai come l'esecuzione di database Oracle in container integra l'infrastruttura di database esistente e accelera lo sviluppo e comprenderai i vantaggi che offrono per gli ambienti di test e convalida (https://amzn.to/4iXoJSt).
• Docker: Sviluppare e rilasciare software tramite container di Serena Sensini. I container Docker permettono di impacchettare e rilasciare un'applicazione corredata da tutti i suoi componenti funzionali e hanno cambiato la catena di fornitura del software sia nelle piccole che nelle grandi imprese, rivoluzionando il modo in cui società come Spotify, Netflix ed Expedia distribuiscono le loro soluzioni (https://amzn.to/40kjVz7). 

Progetti e Guide Online

• Repository Oracle Docker Images. Questo è il repository GitHub ufficiale di Oracle con istruzioni per la creazione di immagini container per Oracle Database (https://github.com/oracle/docker-images).
• Profiling e Ottimizzazione delle Applicazioni Dockerizzate. Ottimizzare le performance delle applicazioni containerizzate è essenziale per garantire che le risorse siano utilizzate in modo efficiente, che le applicazioni rispondano rapidamente e che l’infrastruttura possa scalare in modo adeguato (https://www.codegrind.it/documentazione/docker/profiling-ottimizzazione-performance). 
• Pillole di Docker di EmmeCiLab - Informatica e Matematica. Una raccolta di brevi video per conoscere i fondamenti di Docker (https://youtube.com/playlist?list=PLCbSCJEIR6CpDJw4MawjHlgbsP3IG376e)

L'articolo Come creare un’immagine container di Oracle 19c su Apple Silicon sembra essere il primo su Antonio Musarra's Blog.

PKCS#11 (Public-Key Cryptography Standards #11), noto anche come Cryptographic Token Interface Standard, è uno standard sviluppato da RSA Laboratories. Esso definisce un’API (Application Programming Interface) indipendente dalla piattaforma per l’accesso a dispositivi di sicurezza hardware come token crittografici, HSM (Hardware Security Modules) e, soprattutto, Smart Card.

L’obiettivo principale dello standard PKCS#11 è fornire un’interfaccia unificata che consenta alle applicazioni di accedere a chiavi crittografiche e altre operazioni crittografiche senza dover gestire direttamente i dettagli del dispositivo sottostante.

In questo articolo esploreremo i concetti chiave di PKCS#11 e come utilizzarlo per firmare e verificare la firma di un messaggio tramite una Smart Card che in questo caso sarà la "nostrana" TS-CNS (Tessera Sanitaria - Carta Nazionale Servizi).

PKCS#11 e le Smart Card

Le Smart Card sono dispositivi fisici che memorizzano in modo sicuro chiavi crittografiche e certificati. Sono utilizzate in una vasta gamma di applicazioni, come la firma digitale, l’autenticazione e la crittografia dei dati. Lo standard PKCS#11 permette alle applicazioni di interfacciarsi con queste Smart Card in maniera sicura e trasparente.

Vantaggi dell'uso delle Smart Card con PKCS#11

1. Sicurezza Hardware: le Smart Card sono dotate di un chip che esegue tutte le operazioni crittografiche, proteggendo le chiavi private dall’essere esposte al sistema host.
2. Portabilità: poiché le chiavi sono memorizzate fisicamente sulla Smart Card, possono essere trasportate in sicurezza e utilizzate su diversi sistemi semplicemente inserendo la carta nel lettore.
3. Indipendenza dalla piattaforma: grazie a PKCS#11, le applicazioni possono accedere alle funzionalità crittografiche della Smart Card senza dover implementare codice specifico per ogni dispositivo o sistema operativo.

Architettura e concetti chiave di PKCS#11

PKCS#11 è progettato per gestire una vasta gamma di dispositivi crittografici. Definisce una serie di oggetti e operazioni chiave che permettono alle applicazioni di interagire con i token crittografici come le Smart Card. Vediamo alcuni concetti chiave:

1. Slot e Token: uno slot rappresenta l’interfaccia fisica o logica con il dispositivo crittografico (ad esempio, un lettore di Smart Card). Un token è il dispositivo crittografico stesso (ad esempio, la Smart Card inserita nello slot).
2. Sessioni e Oggetti: le applicazioni aprono delle sessioni con il token per eseguire operazioni crittografiche. Gli oggetti memorizzati sul token possono essere chiavi crittografiche, certificati, o dati generici.
3. Meccanismi Crittografici: PKCS#11 supporta diversi meccanismi crittografici, inclusi RSA, ECC, AES, rendendolo flessibile per diverse applicazioni.
4. Chiavi e Certificati: le Smart Card utilizzano chiavi private per la firma digitale o l’autenticazione. Le chiavi pubbliche e i certificati associati possono essere archiviati sulla Smart Card e resi disponibili tramite PKCS#11.

Crittografia a chiave asimmetrica: il classico esempio di Alice e Bob

La crittografia a chiave asimmetrica è un metodo di crittografia che utilizza due chiavi differenti: una chiave pubblica e una chiave privata. Queste due chiavi sono matematicamente collegate tra loro, ma non è possibile risalire alla chiave privata conoscendo solo la chiave pubblica. Cerchiamo di capire in modo semplice come funziona.

• Chiave Pubblica: può essere condivisa pubblicamente con chiunque. Serve per cifrare i messaggi che solo il proprietario della corrispondente chiave privata può decifrare.
• Chiave Privata: deve essere mantenuta segreta. Viene usata per decifrare i messaggi cifrati con la chiave pubblica e per firmare digitalmente i dati.

Facciamo il classico esempio di Alice e Bob. Immaginiamo quindi, Alice e Bob, che vogliono comunicare in modo sicuro utilizzando la crittografia a chiave asimmetrica.

1. Scambio delle Chiavi:

   • Alice e Bob generano ciascuno una coppia di chiavi: una chiave pubblica e una chiave privata.
   • Alice invia la sua chiave pubblica a Bob.
   • Bob invia la sua chiave pubblica ad Alice.

2. Alice invia un messaggio cifrato a Bob:

   • Alice utilizza la chiave pubblica di Bob per cifrare un messaggio.
   • Solo Bob, con la sua chiave privata, può decifrare il messaggio.

3. Bob invia un messaggio firmato ad Alice:

   • Bob può firmare un messaggio con la sua chiave privata.
   • Alice può verificare l’autenticità del messaggio usando la chiave pubblica di Bob.

Figura 1 - Sequence Diagram di come Alice e Bob si scambiano un messaggio cifrato e firmato utilizzando le chiavi asimmetriche.

Ora, cerchiamo di capire una differenza importante, ovvero, quella esistente tra cifrare un messaggio e firmare un messaggio.

La cifratura e la firma digitale sono due concetti fondamentali della crittografia, ma servono a scopi diversi: la cifratura protegge la riservatezza di un messaggio, mentre la firma digitale garantisce autenticità e integrità.

Cifrare un Messaggio

Obiettivo: proteggere il contenuto del messaggio, mantenendolo segreto e accessibile solo al destinatario autorizzato.

Come funziona:

• Chiave pubblica del destinatario: usata per cifrare il messaggio.
• Chiave privata del destinatario: usata per decifrare il messaggio.

Usando l'approccio della cifratura asimmetrica:

Se Alice vuole inviare un messaggio segreto a Bob, Alice cifra il messaggio con la chiave pubblica di Bob. Solo Bob, con la sua chiave privata, potrà decifrare il messaggio e leggerne il contenuto.

Questo garantisce che nessun altro possa leggere il messaggio, mantenendo la riservatezza.

Esempio:

Immagina che Alice invii un'email a Bob con informazioni sensibili. Alice cifra il contenuto con la chiave pubblica di Bob. Anche se qualcun altro intercettasse l'email, non potrebbe decifrarla senza la chiave privata di Bob.

Firmare un Messaggio

Obiettivo: garantire che il messaggio provenga realmente dal mittente (autenticità) e che non sia stato alterato (integrità).

Come funziona:

• Chiave privata del mittente: usata per firmare digitalmente il messaggio.
• Chiave pubblica del mittente: usata dal destinatario per verificare la firma.

Usando l'approccio della firma asimmetrica:

Se Bob vuole inviare un messaggio firmato ad Alice, Bob firma il messaggio con la sua chiave privata. Alice può verificare la firma utilizzando la chiave pubblica di Bob. Se la verifica riesce, Alice sa che il messaggio è autentico (proviene da Bob) e non è stato alterato durante il trasporto (integrità).

Esempio:

Immagina che Bob invii un contratto digitale ad Alice e lo firmi digitalmente con la sua chiave privata. Alice può verificare la firma con la chiave pubblica di Bob per essere sicura che il documento sia stato inviato da Bob e non sia stato modificato.

La tabella a seguire mostra in modo schematico le differenze tra la cifratura e la firma digitale.

Per fare un riepilogo:

• cifrare serve a proteggere i dati, garantendo che solo il destinatario previsto possa leggere il messaggio.
• firmare serve a garantire autenticità e integrità, confermando che il messaggio proviene dal mittente e non è stato modificato.

In pratica, queste tecniche vengono spesso utilizzate insieme per fornire sicurezza completa: si può cifrare un messaggio per mantenerlo privato e firmarlo digitalmente per garantirne l'autenticità e l'integrità.

Il limite principale della crittografia asimmetrica risiede nelle prestazioni. La crittografia asimmetrica è più lenta rispetto a quella simmetrica, per cui spesso viene usata insieme alla crittografia simmetrica per cifrare dati più grandi.

Esempio pratico con PKCS#11 e Smart Card

Vediamo ora un esempio pratico di come utilizzare PKCS#11 per accedere a una Smart Card e eseguire operazioni di firma digitale.

Requisiti

Per portare a termine questo esempio, avremo bisogno degli elementi a seguire.

1. Una Smart Card compatibile con PKCS#11.
2. Un certificato digitale per la tua Smart Card.
3. Un PIN per accedere alla Smart Card.
4. Un lettore di Smart Card.
5. Un driver PKCS#11 per la tua Smart Card.
6. Un ambiente di sviluppo per il linguaggio di programmazione che desideri utilizzare.
7. Un'API PKCS#11 per il tuo linguaggio di programmazione.
8. Un'applicazione che utilizzi PKCS#11 per accedere alla Smart Card.
9. Un ambiente di test per eseguire l'applicazione.

In commercio esistono diverse Smart Card compatibili con PKCS#11 ma in questo esempio ho volutamente scelto di usare una Smart Card che credo abbiate tutti (o quasi): la TS-CNS (Tessera Sanitaria - Carta Nazionale Servizi).

Nota: prima di poter usare il nostro certificato digitale della TS-CNS, è necessario provvedere alla sua attivazione. Sul portale STS (Sistema Tessera Sanitaria) è possibile trovare tutte le informazioni necessarie per attivare la propria TS-CNS, più altre funzionalità, come per esempio la consultazione delle spese sanitarie. Ogni regione prevede modalità diverse per l'attivazione della TS-CNS, quindi è importante seguire le istruzioni specifiche per la propria regione. Nel caso della regione Lazio è possibile attivare la TS-CNS direttamente presso gli sportelli ASL di appartenenza. Per ulteriori informazioni, è possibile consultare il sito ufficiale della Regione Lazio nella sezione Come attivate la Carta Nazionale dei Servizi.

Per quanto riguarda il lettore di Smart Card, è possibile utilizzare un lettore USB o integrato nel computer. Personalmente ho utilizzato il lettore USB miniLector EVO prodotto da bit4id.

Per quanto riguarda il driver PKCS#11, è possibile utilizzare quello fornito dal produttore della Smart Card o utilizzare un driver open source come OpenSC. Per questo esempio ho utilizzato OpenSC, principalmente perché è open source e supporta una vasta gamma di Smart Card, tra cui la TS-CNS (basta eseguire il comando opensc-tool -c '?'per ottenere la lista dei driver tra cui è presente anche itacns - Italian CNS). Da non dimenticare che OpenSC è disponibile per diverse piattaforme, tra cui Linux, macOS e Windows.

Sul linguaggio di programmazione non c'è limite di scelta, in quanto PKCS#11 è supportato da diversi linguaggi di programmazione, tra cui C, C++, Java, Python, ecc. In questo esempio, la scelta ricade su Python, linguaggio molto popolare e facile da usare, soprattutto per chi è alle prime armi con la programmazione.

Le API PKCS#11 per Python sono disponibili tramite il modulo PyKCS11, che fornisce un'interfaccia per l'API PKCS#11. Per installare PyKCS11, è possibile utilizzare il gestore di pacchetti pip eseguendo il comando pip install PyKCS11.

Assodato che faremo uso di Python, PyKCS11 e OpenSC per portare a termine questo esempio, il mio ambiente di sviluppo e test è composto da: macOS, Python 3.12.6, PyKCS11 1.5.16 e OpenSC 0.25.1 [gcc Apple LLVM 15.0.0 (clang-1500.3.9.4)]. Ovviamente, per chi volesse replicare l'esempio su Windows o Linux, basta installare le versioni di Python, PyKCS11 e OpenSC compatibili con il proprio sistema operativo.

A questo punto che abbiamo soddisfatto tutti i requisiti, è giunto il momento di mettere le mani al codice andando a implementare un semplice programma che eseguirà un'operazione di firma digitale usando il nostro certificato presente all'interno della TS-CNS.

Implementazione dell'applicazione

Andremo a realizzare una semplice applicazione che implementa il flusso dove Bob firma un messaggio e Alice verifica la firma (vedi Figura 1). Il programma sarà diviso in due parti: una per la firma digitale (blocco che dovrebbe usare Bob) e una per la verifica della firma (blocco che dovrebbe usare Alice). In questo esempio, utilizzeremo la chiave privata della TS-CNS per firmare il messaggio e la chiave pubblica per verificare la firma.

Non entreremo nel dettaglio di come funziona l'API PKCS#11, ma ci concentreremo sull'utilizzo pratico per firmare e verificare la firma. Lascio a voi la curiosità di approfondire l'API PKCS#11 e come funziona consultando la documentazione ufficiale e la documentazione di PyKCS11.

Nota: Quelli che mostrerò a seguire sono gli snippet di codice per firmare e verificare la firma. Il codice completo è disponibile su GitHub.

Procediamo per step. Il primo passo è inizializzare l'API PKCS#11 e ottenere un handle per la Smart Card. Per far ciò, dobbiamo importare il modulo PyKCS11 e creare un oggetto PyKCS11.PyKCS11Lib con il percorso del driver PKCS#11 della nostra Smart Card.

import PyKCS11

# Percorso della libreria PKCS#11
pkcs11_lib_path = '/opt/homebrew/Cellar/opensc/0.25.1/lib/opensc-pkcs11.so'
if not os.path.exists(pkcs11_lib_path):
   raise PKCS11LibraryNotFound(
      f"Libreria PKCS#11 non trovata. Specifica il percorso manualmente. Percorso attuale: {pkcs11_lib_path}")

# Carica la libreria PKCS#11
pkcs11 = PyKCS11.PyKCS11Lib()
pkcs11.load(pkcs11_lib_path)

Source Code 1 - Inizializzazione dell'API PKCS#11 e caricamento della libreria PKCS#11

Il secondo passo è quello di ottenere lo slot e il token della Smart Card. Dopo aver ottenuto lo slot e il token, possiamo aprire una sessione con la Smart Card e autenticarci con il PIN.

    # Ottieni la lista degli slot con token presenti
    slots = pkcs11.getSlotList(tokenPresent=True)

    if len(slots) == 0:
        raise NoSmartCardInserted("Nessuna Smart Card inserita")

    # Usa il primo slot disponibile
    slot = slots[0]

    # Apri una sessione con la Smart Card
    session = pkcs11.openSession(slot)
    session.login(args.pin)

Source Code 2 - Ottenimento dello slot e del token della Smart Card e apertura di una sessione con la Smart Card

Il terzo passo consiste nel caricare la chiave privata per la firma e la chiave pubblica per la verifica della firma. Per fare ciò, dobbiamo ottenere gli oggetti chiave dalla Smart Card utilizzando il loro ID (vedi PyKCS11.CKO_PRIVATE_KEY, PyKCS11.CKO_CERTIFICATE e PyKCS11.CKA_VALUE).

In questo caso siamo certi del fatto che sulla TS-CNS abbiamo un solo certificato e una sola chiave privata, possiamo quindi assumere che in posizione [0] troveremo i nostri oggetti.

    # Trova la chiave privata sulla Smart Card
    private_key = session.findObjects([(PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY)])[0]

    # Trova il certificato pubblico sulla Smart Card
    public_cert = session.findObjects([(PyKCS11.CKA_CLASS, PyKCS11.CKO_CERTIFICATE)])[0]

    # Ottieni il certificato pubblico in formato DER
    public_cert_der = session.getAttributeValue(public_cert, [PyKCS11.CKA_VALUE], False)[0]
    public_cert_der = bytes(public_cert_der)

    # Carica il certificato pubblico
    cert = x509.load_der_x509_certificate(public_cert_der, backend=default_backend())

    # Ottieni la chiave pubblica dal certificato
    public_key = cert.public_key()

Source Code 3 - Caricamento della chiave privata e pubblica dalla Smart Card

Il quarto passo prevede la codifica del messaggio e la sua firma. Per firmare il messaggio, dobbiamo utilizzare la chiave privata e un algoritmo di firma come PyKCS11.CKM_SHA256_RSA_PKCS.

    # Codifica il messaggio da firmare
    data = args.message.encode()

    # Firma il messaggio usando la chiave privata
    mechanism = PyKCS11.Mechanism(PyKCS11.CKM_SHA256_RSA_PKCS, None)
    signature = session.sign(private_key, data, mechanism)
    signature = bytes(signature)

Source Code 4 - Codifica del messaggio e firma del messaggio

A questo punto abbiamo ottenuto la firma del messaggio (signature = bytes(signature)) che Bob vuole inviare ad Alice. Come ultimo passo, dobbiamo scrivere il blocco di codice che Alice dovrebbe usare per verificare che il messaggio sia stato firmato da Bob.

   # Verifica la firma usando la chiave pubblica
   try:
      public_key.verify(
         signature,
         data,
         padding.PKCS1v15(),
         hashes.SHA256()
      )
      print(f"{Fore.GREEN}✅ Firma verificata correttamente!")
   except Exception as e:
      print(f"{Fore.RED}❌ Verifica della firma fallita: {e}")
   
   # Logout dalla sessione
   session.logout()

Source Code 5 - Verifica della firma del messaggio

Wow! Abbiamo completato l'implementazione dell'applicazione che esegue un'operazione di firma digitale e verifica della firma utilizzando una Smart Card e l'API PKCS#11. Per fare un riepilogo e inserire nel contesto Bob e Alice, quello che dovrebbe accadere e quanto mostrato dal sequence diagram a seguire.

Figura 2 - Sequence Diagram di come Alice e Bob si scambiano un messaggio cifrato e firmato utilizzando le chiavi asimmetriche.

Conclusa la fase d'implementazione, passeremo alla fase di test.

Test dell'applicazione di firma digitale

L'applicazione finale è disponibile su GitHub e può essere eseguita da riga di comando. Per eseguire l'applicazione, è necessario specificare il PIN della Smart Card e il messaggio da firmare. Ecco un esempio di come eseguire l'applicazione:

# Installazione dei requirements
pip install -r requirements.txt

# Esegui l'applicazione per firmare un messaggio
./sign-via-ts-cns.py --pin 123456 --message "Prima firma di un messaggio tramite la mia TS-CNS"

Console 1 - Esempio di esecuzione dell'applicazione di firma digitale

In output l'applicazione mostrerà la firma generata (in formato esadecimale) e il risultato della verifica della firma. Se la firma è stata verificata correttamente, sarà visualizzato un messaggio di successo, altrimenti verrà visualizzato un messaggio di errore. A seguire un esempio di output dell'applicazione.

🔍 Dati da firmare: b'Prima firma di un messaggio tramite la mia TS-CNS'
✅ Firma generata (in esadecimale): b'99be876fb527dbd8e36e9d76f69357e6ef006c737e535b48ed45acd28ebb3b2a14cc7a08cc4902d92194b18b2cc8b61cc2a23747119b6c473fe4757e12ac66c6ce9488354a9fbbb95b003b643295e428b18383328192953c645afe0f9b00e9bf405981da4a52b40f288275023d8aa06e81f88a066888dc29e88a1b6280b5e7c2f26b1e8d5bc469839dcf07128b3e525ad88c9190b76811def76530131246e201a4428b74f65757957e67190ce284b0c8ee89f422b3cf960899467fd1bb66ded6a97999ccf3a2407b07f49af697590b0dac28585c5c3e8b0ca3b3aa1bc47eb1aab2d67a0b0fc1c8cf9bde51512acb9ebed80bf514f6cfe7e9900d2d3541df1f39'
✅ Firma verificata correttamente!

Console 2 - Esempio di output dell'applicazione di firma digitale

Quando l'applicazione termina con successo, questa genera tre file:

1. message_<uuid4>txt: il messaggio originale.
2. signature_<uuid4>.txt: la firma generata.
3. public_cert.pem: la chiave pubblica.

Questi file possono essere utilizzati per verificare la firma in un secondo momento o per inviare il messaggio firmato ad altri utenti, come per esempio Alice. Quindi, per fare fede a quanto indicato del sequence diagram di Figura 2, Alice dovrebbe usare questi tre file per verificare la firma del messaggio.

Qual è il modo più semplice per verificare la firma del messaggio? Semplice, usando OpenSSL. Ecco come fare.

# Verifica la firma del messaggio tramite openssl.
openssl dgst -sha256 -verify <(openssl x509 -in public_cert.pem -pubkey -noout) -signature signature_e032b4fe6213486eb9830fe0dacf9f3b.bin message_9789a64270b1443da672a5d1776d6664.txt

Console 3 - Verifica della firma del messaggio tramite OpenSSL

Il risultato atteso dovrebbe essere Verified OK. Se la firma è stata verificata correttamente, significa che l'applicazione ha funzionato correttamente e che la firma è stata generata e verificata con successo.

Nel caso in cui la verifica della firma fallisca, è possibile che ci siano stati errori durante la generazione della firma o magari per qualche motivo per esempio il messaggio originale è stato alterato. Facciamo una simulazione di alterazione del messaggio originale e vediamo cosa succede.

# Altera il messaggio originale
echo "Messaggio alterato" > message_9789a64270b1443da672a5d1776d6664.txt

# Verifica la firma del messaggio tramite openssl.
openssl dgst -sha256 -verify <(openssl x509 -in public_cert.pem -pubkey -noout) -signature signature_e032b4fe6213486eb9830fe0dacf9f3b.bin message_9789a64270b1443da672a5d1776d6664.txt

Console 4 - Verifica della firma del messaggio tramite OpenSSL con messaggio alterato

Il risultato atteso dovrebbe essere Verification Failure. Se la verifica della firma fallisce, significa che il messaggio è stato alterato dopo la firma e quindi la firma non è più valida.

Il programma completo consente di fare anche altro, per scoprirlo basta eseguire il comando ./sign-via-ts-cns.py --help per visualizzare l'help dell'applicazione e dovreste vedere qualcosa di simile a quanto mostrato a seguire.

usage: sign-via-ts-cns.py [-h] --pin PIN --message MESSAGE [--debug] [--signature-file SIGNATURE_FILE] [--message-file MESSAGE_FILE]
                          [--pkcs11-lib PKCS11_LIB]

Script per firmare un messaggio usando una Smart Card

options:
  -h, --help            show this help message and exit
  --pin PIN             PIN della Smart Card
  --message MESSAGE     Messaggio da firmare
  --debug               Abilita i messaggi di debug
  --signature-file SIGNATURE_FILE
                        File in cui salvare la firma
  --message-file MESSAGE_FILE
                        File in cui salvare il messaggio
  --pkcs11-lib PKCS11_LIB
                        Percorso della libreria PKCS#11

Console 5 - Help dell'applicazione di firma digitale

L'opzione che mi sento di consigliare è --debug che abilita in output ulteriori messaggi utili a capire meglio cosa stia succedendo durante l'esecuzione dell'applicazione. Inoltre, è possibile specificare il percorso della libreria PKCS#11 con l'opzione --pkcs11-lib e i file in cui salvare la firma e il messaggio con le opzioni --signature-file e --message-file.

A seguire il diagramma di sequenza che mostra come l'applicazione interagisce con la Smart Card attraverso la libreria PKCS#11 per firmare un messaggio e verificare la firma.

Figura 3 - Sequence Diagram di come l'applicazione interagisce con la Smart Card attraverso la libreria PKCS#11 per firmare un messaggio e verificare la firma

Utilizzo in applicazioni reali

Le Smart Card e lo standard PKCS#11 sono utilizzati in molti scenari di sicurezza crittografica.

1. Firma Digitale: le firme digitali eseguite tramite chiavi private su Smart Card sono molto comuni in applicazioni di governo elettronico (e-government) e nei sistemi finanziari.
2. Autenticazione Forte: molte aziende e istituzioni richiedono un’autenticazione a due fattori (2FA) basata su Smart Card per l’accesso ai sistemi critici.
3. Crittografia e Decrittazione: le Smart Card possono essere utilizzate per cifrare e decifrare documenti o dati sensibili direttamente all’interno del dispositivo, garantendo che le chiavi private non lascino mai la carta.
4. Infrastruttura PKI: le Smart Card sono comunemente utilizzate in un’infrastruttura a chiave pubblica (PKI) per la gestione sicura delle identità digitali.

Risorse e Approfondimenti

Il repository GitHub pkcs11-smart-card con il codice completo dell'applicazione è disponibile al seguente link.

Per ulteriori informazioni su PKCS#11 e PyKCS11, consiglio di consultare la documentazione ufficiale: PKCS#11 e PyKCS11.

Per ulteriori informazioni su OpenSC, consiglio di consultare la documentazione ufficiale: OpenSC.

Nel caso in cui si desideri approfondire la programmazione delle Smart Card, consiglio l'ottimo libro di Ugo Chirico Programmazione delle Smart Card.

Per altri temi che riguardano Smart Card e sicurezza informatica, propongo qualche articolo pubblicato sul mio blog personale:

1. Raspberry Pi e Smart Card Mifare Classic 1K: Realizzare un sistema di accesso
2. Implementazione di TLS Mutual Authentication (mTLS) con Quarkus
3. Raspberry Pi – Un esempio di applicazione della TS-CNS

Conclusioni

Lo standard PKCS#11 rappresenta uno strumento potente e flessibile per integrare dispositivi crittografici hardware, come le Smart Card, all’interno di applicazioni moderne. Grazie a questa API standardizzata, gli sviluppatori possono sfruttare le capacità crittografiche avanzate dei token hardware in modo semplice e sicuro, indipendentemente dalla piattaforma sottostante.

In questo articolo, abbiamo esplorato i concetti chiave di PKCS#11 e come utilizzarlo per firmare e verificare la firma di un messaggio tramite una Smart Card. Abbiamo anche visto come sia stato semplice implementare un’applicazione Python che sfrutta l’API PKCS#11 per interagire con una Smart Card, in questo caso la "nostrana" TS-CNS ed eseguire operazioni di firma digitale.

L'articolo Approfondimento sullo standard PKCS#11 e utilizzo con Smart Card sembra essere il primo su Antonio Musarra's Blog.

La sicurezza delle applicazioni web è sempre più critica, soprattutto in contesti in cui le comunicazioni devono essere protette da entrambe le parti coinvolte. In questo contesto, l’autenticazione reciproca TLS (mTLS) offre una soluzione solida, garantendo che sia il client sia il server siano autenticati prima di stabilire una connessione sicura. L'obiettivo di questo articolo è quello di guidarvi verso la strada dell'implementazione di mTLS in un’applicazione utilizzando Quarkus, un framework Java ottimizzato per il cloud.

Cos’è l’autenticazione reciproca TLS (mTLS)?

L’autenticazione reciproca TLS (o mutual TLS o mTLS) è un’estensione del protocollo TLS standard. Solitamente TLS viene utilizzato per proteggere le comunicazioni tra client e server, dove solo il server deve presentare un certificato valido per autenticarsi con il client. Con mTLS, anche il client deve presentare un certificato valido, garantendo così che entrambe le parti siano autentiche.

Questa autenticazione bidirezionale è particolarmente utile in applicazioni distribuite, microservizi o API, dove sia il client che il server devono fidarsi reciprocamente prima di scambiare dati sensibili.

Il sequence diagram a seguire mostra il processo di autenticazione reciproca TLS (mTLS) tra un client e un server. In particolare, il client invia il proprio certificato al server, che lo verifica prima di stabilire una connessione sicura. Se il certificato del client è valido, il server procede con l’autenticazione e la comunicazione può iniziare (come ultimo step).

Figura 1 - Sequence diagramm del processo di autenticazione reciproca TLS (mTLS)

È importate capire che la verifica dei certificati nel contesto mTLS è un processo cruciale per garantire la sicurezza della connessione, impedendo la comunicazione con entità non fidate o malintenzionate. Se una delle verifiche dovesse fallire (ad esempio, il certificato è scaduto o non valido), l’handshake sarà interrotto e la connessione non sarà stabilita.

Vediamo di approfondire quali sono i passaggi chiave per la verifica dei certificati in un contesto mTLS.

Verifica del certificato del server da parte del client

Quando il server invia il proprio certificato al client, quest’ultimo deve verificarlo attraverso i seguenti passaggi.

• Catena di certificazione (Certificate Chain): il client controlla che il certificato ricevuto dal server appartenga a una catena di certificati attendibili. Questo significa che il certificato del server deve essere firmato da un’autorità di certificazione (CA) che è inclusa nell’elenco delle CA fidate del client. La catena di certificazione viene verificata partendo dal certificato del server fino alla CA radice fidata.
• Firma del certificato: il client verifica la firma digitale sul certificato del server. La firma deve essere stata generata dalla CA utilizzando la sua chiave privata. Il client usa la chiave pubblica della CA, inclusa nel certificato della CA, per verificare la firma. Se la firma corrisponde, il certificato non è stato modificato e può essere considerato autentico.
• Validità temporale: il client verifica che il certificato non sia scaduto, controllando le date di validità (notBefore e notAfter) contenute nel certificato.
• Revoca del certificato: il client può verificare se il certificato del server è stato revocato. Questo avviene tramite il controllo delle CRL (Certificate Revocation List) o utilizzando il protocollo OCSP (Online Certificate Status Protocol) per interrogare in tempo reale lo stato del certificato.
• Hostname: Il client verifica che l’hostname del server corrisponda a quello presente nel certificato (nel campo Subject o nel campo Subject Alternative Name). Questo assicura che il certificato sia effettivamente emesso per il server con cui il client sta tentando di comunicare.

Verifica del certificato del client da parte del server

Quando il client invia il proprio certificato al server (se richiesto), il server deve verificarlo con i seguenti passaggi simili a quelli effettuati dal client.

• Catena di certificazione: il server verifica che il certificato del client appartenga a una catena di certificati attendibili, cioè che sia firmato da una CA che il server riconosce come fidata. Anche qui si controlla la catena fino alla CA radice.
• Firma del certificato: il server verifica la firma digitale sul certificato del client, utilizzando la chiave pubblica della CA che ha emesso il certificato per assicurarsi che la firma sia valida e che il certificato non sia stato alterato.
• Validità temporale: il server controlla che il certificato del client non sia scaduto, verificando le date di inizio e fine validità.
• Revoca del certificato: come nel caso del client, anche il server può effettuare un controllo per verificare se il certificato del client è stato revocato, usando una CRL o il protocollo OCSP.
• Identità del client: in alcuni casi, il server può verificare che il certificato del client corrisponda a un’entità specifica (ad esempio, un’azienda o un dispositivo) che ha diritto di accedere ai servizi del server. Questa verifica può essere basata sui campi presenti nel certificato, come il campo Subject.

Crittografia e integrità dei certificati

Durante l’handshake, la chiave pubblica contenuta nei certificati viene utilizzata per scambiare in modo sicuro il premaster secret, che sarà poi trasformato nella chiave di sessione. Grazie a questo, il client e il server possono essere certi dell’identità reciproca e stabilire una connessione sicura.

I cassetti digitali

Sì, i certificati utilizzati per l'autenticazione, sia lato client sia lato server, sono memorizzati in repository specifici che fungono da "cassetti digitali" in cui i certificati sono conservati e verificati durante l'handshake TLS/mTLS. Ecco una panoramica dei principali luoghi dove i certificati sono archiviati e controllati.

1. Truststore

Il truststore è una raccolta di certificati radice di autorità di certificazione (CA) fidate. Questo è il "cassetto" dove vengono conservati i certificati delle CA che il sistema considera attendibili.

• Lato Client: quando il client riceve il certificato del server, verifica che il certificato sia stato firmato da una delle CA presenti nel truststore. Se il certificato non può essere tracciato a una CA fidata (cioè, se non c'è una catena valida fino a una CA radice nel truststore), la connessione verrà rifiutata.

• Lato Server: analogamente, il server verifica il certificato del client confrontandolo con le CA presenti nel suo truststore.

Qualcuno si chiederà dove si trovi il truststore, questo dipende dal sistema operativo.

• Sistemi operativi: il truststore è integrato nel sistema operativo. Ad esempio, su:

  • Windows: i certificati fidati si trovano nel Certificato Root (CA) in "Gestione Certificati";
    • Linux: il truststore si trova solitamente in directory come /etc/ssl/certs/ o /usr/share/ca-certificates/. La posizione potrebbe differire a seconda della distribuzione Linux;
  • macOS: il truststore è gestito tramite il Keychain Access, che contiene i certificati radice fidati.

• Applicazioni: alcune applicazioni, come browser web o server, mantengono il proprio truststore separato. Ad esempio, i browser come Firefox usano un truststore indipendente da quello del sistema operativo.

2. Keystore

Il keystore è il luogo dove sono archiviati i certificati e le chiavi private associate a un'entità (come un server o un client). È simile a un portafoglio digitale che contiene le credenziali usate per identificarsi durante l'handshake.

• Lato Server: il server archivia il proprio certificato e la chiave privata nel keystore. Quando il client richiede il certificato del server, questo viene estratto dal keystore e inviato al client per la verifica.

• Lato Client: se la verifica del client è obbligatoria (come nel caso dell'mTLS), il client invia il proprio certificato estratto dal keystore quando il server lo richiede. Insieme al certificato, il client utilizza la chiave privata memorizzata nel keystore per firmare i messaggi di autenticazione durante l'handshake.

Qui la posizione del keystore dipende dal tipo di applicazione e dal sistema operativo.

• Java KeyStore (JKS): Java usa un formato keystore specifico chiamato JKS. Questo file può contenere certificati e chiavi private ed è ampiamente usato in ambienti Java, come server applicativi (es. Tomcat, Spring Boot).
• PKCS#12 (PFX o P12): è un formato standard per contenere certificati e chiavi private. Viene usato su diversi sistemi operativi e server. Ad esempio, i file .pfx o .p12 possono essere caricati in un server come Apache o NGINX.
• Keychain (macOS): Su macOS, i certificati e le chiavi private possono essere memorizzati nel Keychain.

Il formato JKS è ancora supportato ma sconsigliato l'uso in favore di PKCS#12, soprattutto per nuove implementazioni, poiché offre una migliore sicurezza e compatibilità.

3. Verifica tramite CRL o OCSP

Dopo aver estratto i certificati dai rispettivi "cassetti" (truststore o keystore), il client o il server possono verificare la validità del certificato, assicurandosi che non sia stato revocato.

• CRL (Certificate Revocation List): è un elenco pubblicato dalle CA che elenca i certificati revocati. Durante l'handshake, il client o il server possono consultare questa lista per verificare se il certificato è stato revocato.
• OCSP (Online Certificate Status Protocol): invece di scaricare un'intera lista, il sistema può interrogare un server OCSP per verificare in tempo reale se un certificato è stato revocato.

Volendo fare un riassunto, ecco un elenco dei principali componenti coinvolti nella gestione dei certificati e nella verifica durante l'handshake TLS/mTLS.

• Truststore: contiene i certificati delle CA radice fidate e viene usato per verificare i certificati ricevuti da client o server.
• Keystore: contiene il certificato dell'entità (client o server) e la relativa chiave privata. Viene usato per l'autenticazione.
• CRL/OCSP: utilizzati per controllare la revoca dei certificati.

In questo modo, i certificati sono archiviati e gestiti nei rispettivi "cassetti" (truststore/keystore), e vengono verificati tramite processi di validazione durante l'handshake TLS/mTLS per garantire la sicurezza e l'integrità della connessione.

Vi posso consigliare di esplorare il progetto su GitHub docker-apache-ssl-tls-mutual-authentication e il relativo articolo Docker Image Apache SSL/TLS Mutual Authentication on Azure Cloud per avere un'idea pratica di come implementare mTLS con Apache.

Perché gestire mTLS direttamente sull'applicazione?

Sono sicurissimo che qualcuno di voi potrebbe obiettare quanto segue: solitamente in ambienti di produzione, la sicurezza mTLS viene gestita da apparati ad hoc collocati davanti l’applicazione, quindi, quali sono i vantaggi nel configurare mTLS direttamente sull’applicazione?

È vero che in molti ambienti di produzione la sicurezza mTLS viene spesso gestita da dispositivi dedicati, come load balancer o gateway API, collocati davanti all’applicazione. Tuttavia, configurare mTLS direttamente sull’applicazione presenta alcuni vantaggi significativi, specialmente in certi scenari e architetture. Di seguito, esploreremo i motivi per cui questa scelta può essere valida.

Vantaggi di configurare mTLS direttamente sull’applicazione

A seguire vedremo brevemente quali siano i vantaggi principali nell'adozione di questa scelta.

1. Maggiore controllo e flessibilità

Configurare mTLS direttamente sull’applicazione consente di avere un controllo più granulare su come e quando l’autenticazione reciproca viene applicata. Ad esempio, puoi decidere:

• quali endpoint richiedono mTLS e quali no;
• diversificare la gestione dei certificati a livello di servizio o microservizio in base alle esigenze di sicurezza specifiche.

Questo tipo di configurazione può essere particolarmente utile in ambienti multi-tenant o con servizi sensibili, dove i requisiti di sicurezza possono variare da un microservizio all’altro.

2. Difesa in profondità

In sicurezza informatica, il principio di difesa in profondità (vedi sezione Importanti principi di protezione dell’ISA/IEC 62443) implica la stratificazione di più livelli di protezione. Anche se mTLS viene implementato a livello di gateway o di load balancer, aggiungere un ulteriore strato di sicurezza direttamente nell’applicazione riduce il rischio di compromissioni:

• se l’infrastruttura del gateway viene bypassata o compromessa, l’applicazione richiede comunque l’autenticazione reciproca per accedere.

In questo modo, anche se un attaccante riuscisse a superare un dispositivo di sicurezza a monte, troverebbe comunque un altro livello di protezione all’interno dell’applicazione.

3. Sicurezza end-to-end

Gestendo mTLS a livello dell’applicazione, puoi garantire una sicurezza end-to-end tra i client e i microservizi, senza dover delegare la fiducia a dispositivi intermedi. In ambienti distribuiti, soprattutto in scenari di microservizi, questo garantisce che le connessioni siano protette fino all’applicazione stessa, non solo fino al gateway.

• I certificati del client sono validati direttamente dall’applicazione, eliminando potenziali punti di vulnerabilità legati a configurazioni errate o attacchi intermedi che potrebbero verificarsi tra il gateway e l’applicazione.

4. Riduzione della complessità di infrastruttura

In alcune architetture moderne, come quelle serverless o microservizi in ambienti containerizzati, l’uso di dispositivi dedicati per la gestione della sicurezza può introdurre complessità e aumentare la latenza nelle comunicazioni. Implementare mTLS direttamente sui microservizi può ridurre la dipendenza da questi dispositivi e semplificare l’architettura complessiva:

• in ambienti dinamici, dove i microservizi si scalano rapidamente, l’uso di service mesh (ad esempio Istio) o configurazioni centralizzate a livello di applicazione può risultare più gestibile rispetto a delegare tutto ai dispositivi di front-end.

5. Ambienti multi-cloud o ibridi

In contesti multi-cloud o ibridi, in cui i servizi sono distribuiti su diversi provider o persino on-premise, configurare mTLS direttamente sulle applicazioni garantisce che la sicurezza sia gestita in modo uniforme, indipendentemente da dove siano eseguite. In questi casi, affidarsi completamente a dispositivi di front-end potrebbe non essere pratico o potrebbe richiedere una complessità aggiuntiva in termini di gestione dei certificati tra provider diversi.

6. Indipendenza dai dispositivi di rete

Affidarsi completamente ai dispositivi dedicati per la gestione di mTLS può comportare un legame tecnologico con una particolare infrastruttura o provider. Gestire la sicurezza mTLS direttamente sull’applicazione riduce la dipendenza da questi dispositivi, offrendo portabilità tra ambienti diversi (ad esempio, passare da un cloud provider all’altro senza dover riconfigurare l’infrastruttura di sicurezza a monte).

7. Testing e sviluppo più sicuri

Configurare mTLS direttamente nell’applicazione permette di simulare e testare scenari di sicurezza anche in ambienti di sviluppo o pre-produzione, senza dover riprodurre l’intera infrastruttura di produzione. In questo modo, i team di sviluppo possono:

• testare con maggiore precisione le configurazioni di sicurezza che verranno utilizzate in produzione;
• implementare flussi di DevSecOps più fluidi, dove la sicurezza viene verificata in ogni fase del ciclo di vita del software.

8. Personalizzazione della logica di autenticazione

In alcuni casi, potrebbe essere necessario personalizzare la logica di autenticazione in base alle esigenze specifiche dell’applicazione. Configurare mTLS direttamente nel codice o nelle configurazioni dell’applicazione permette di introdurre logiche personalizzate come:

• validazioni aggiuntive sui certificati;
• limitare l’accesso a specifici client in base a metadati contenuti nei certificati.

Quando usare dispositivi dedicati per la gestione di mTLS?

Nonostante i vantaggi della configurazione di mTLS direttamente nell’applicazione, ci sono contesti in cui l’uso di dispositivi dedicati rimane una scelta preferibile.

• Scalabilità centralizzata: in ambienti con molti servizi e microservizi, potrebbe essere più semplice e scalabile gestire mTLS a livello di gateway, piuttosto che applicare la stessa configurazione a decine o centinaia di microservizi.
• Performance e ottimizzazione: gli apparati specializzati (come load balancer hardware) possono essere ottimizzati per gestire rapidamente grandi quantità di connessioni TLS e mTLS, riducendo la latenza e scaricando l’onere crittografico dalle applicazioni.
• Amministrazione centralizzata: in organizzazioni di grandi dimensioni con team separati, delegare la gestione di mTLS a dispositivi dedicati può ridurre la complessità di gestione da parte degli sviluppatori, permettendo ai team di rete e sicurezza di concentrarsi esclusivamente su questi aspetti.

In conclusione

Configurare mTLS direttamente sull’applicazione in Quarkus offre una serie di vantaggi, tra cui maggiore controllo, flessibilità e sicurezza end-to-end. Questo approccio può essere particolarmente utile in ambienti distribuiti, multi-cloud, o in scenari dove la difesa in profondità è un requisito fondamentale.

Sebbene ci siano contesti in cui dispositivi dedicati a monte siano la scelta migliore per la gestione della sicurezza, integrare mTLS a livello di applicazione permette una gestione più granulare e può migliorare la sicurezza in architetture moderne come microservizi e container.

Quale scenario andremo a implementare

Utilizzando Quarkus andremo a implementare un classico scenario dove una risorsa (in questo caso REST) sia protetta attraverso il meccanismo mTLS. Il sequence diagram mostrato a seguire illustra proprio lo scenario, dove:

1. il Client inizia la connessione TLS con l’applicazione Quarkus;
2. Quarkus richiede il certificato del client come parte della procedura di autenticazione reciproca mTLS;
3. il Client invia il proprio certificato;
4. Quarkus verifica il certificato del client
   1. se il certificato è valido, Quarkus elabora la richiesta di accesso alla risorsa e restituisce i dati della risorsa;
   2. se il certificato non è valido, Quarkus restituisce un errore, negando l’accesso alla risorsa.

Sul sequence diagram sono stati omessi volutamente alcune delle fasi del processo TLS Handshake per dare risalato a quelle fasi che contribuisco al meccanismo di mutua autenticazione. Per il processo completo, fare riferimento al capitolo Cos’è l’autenticazione reciproca TLS (mTLS).

Figura 2 - Sequence diagramm della soluzione di mTLS da implementare tramite Quarkus

Per realizzare la soluzione mostrata nel diagramma precedente, avremo bisogno dei seguenti strumenti software.

• Java 21
• Maven (per la gestione del progetto)
• Quarks CLI (per l'installazione fare riferimento Building Quarkus apps with Quarkus Command Line Interface (CLI))
• Certificati TLS per il client e il server
• OpenSSL per gestire la generazione dei certificati

Nel corso dell'implementazione andremo a utilizzare diversi componenti di Quarkus che rientrano nel panorama dell'architettura di sicurezza di Quarkus e per cui invito a leggere le seguenti risorse.

1. Quarkus Security architecture
2. Quarkus Security overview
3. Built-in authentication mechanisms
4. Authorization of web endpoints
5. TLS registry reference

La figura 3 mostra l'architettura di sicurezza di Quarkus, dove ho volutamente evidenziare lo strato che riguarda il componente SecurityIdentityAugmentor perché nel corso dell'articolo vedremo a cosa serve questo componente e come implementare una personalizzazione utile per i nostri scopi.

Tra l'elenco delle risorse ho menzionato il TLS Registry che utilizzeremo per portare a termine con successo l'implementazione della soluzione.

Cos’è il TLS Registry di Quarkus? È un'estensione di Quarkus che centralizza la configurazione TLS per l'applicazione. Consente di definire la configurazione TLS in un unico luogo e di farvi riferimento da più punti nell'applicazione. Nel corso dell'articolo vedremo come ci verrà incontro.

Requisiti dell'applicazione Quarkus

Siamo certi del fatto che dobbiamo implementare la nostra applicazione per il supporto mTLS. In particolare andremo a implementare quanto descritto in maniera sintetica dalla tabella a seguire.

Generazione dei certificati

Per gestire correttamente la mutua autenticazione allo scopo di fare anche dei test sul nostro ambiente di sviluppo, abbiamo la necessità di disporre dei seguenti certificati X.509:

1. un certificato di Certificate Authority (CA);
2. un certificato server per il servizio HTTPS, quest'ultimo basato su Vert.x Core integrato all'interno di Quarkus;
3. un set di certificati client che devono avere specifiche caratteristiche per accedere ai servizi (vedi requisiti tre, quattro e sei).

Per il nostro ambiente di sviluppo siamo autonomi nella generazione dei certificati ma al momento vediamo quali sono le caratteriste dei certificati che dovremo generare e che sono mostrate nella tabella a seguire.

Nota: gli FQDN (Fully Qualified Domain Name) usati nei certificati sono puramente di esempio e andranno poi sostituiti con quelli reali.

Per soddisfare il requisito tre e quattro, il certificato client deve essere creato con le seguenti caratteristiche:

1. clientAuth in extendedKeyUsage: l’extendedKeyUsage con il valore clientAuth indica che il certificato può essere utilizzato per l’autenticazione del client in contesti mTLS o altre situazioni in cui un client deve dimostrare la propria identità a un server. L’**Object Identifier (OID)** associato a clientAuth è 1.3.6.1.5.5.7.3.2, ed è riconosciuto universalmente per identificare certificati che possono essere utilizzati per l’autenticazione dei client;
2. estensione personalizzate: per gestire i ruoli e attributi, i certificati client dovranno avere le seguenti estensioni personalizzate:
   1. 1.3.6.1.4.1.99999.1 = ASN1:UTF8String:Role=${ext_cert_role}
   2. 1.3.6.1.4.1.99999.2 = ASN1:UTF8String:DeviceId=${ext_cert_device_id}

Le due estensioni personalizzate che sono identificate con OID della classe privata 1.3.6.1.4.1 dove 99999 rappresenta un numero riservato per un’ipotetica organizzazione, sono usate rispettivamente per indicare ruoli e il deviceId. I placeholder ${ext_cert_role} e ${ext_cert_device_id} conterranno i rispettivi valori per Role e DeviceId.

L'estensione personalizzata avente OID 1.3.6.1.4.1.99999.1 deve contenere uno più ruoli attraverso una stringa che dovrà rispettare il pattern ^Role=([A-Za-z]+(?:,[A-Za-z]+)*+)$.

L'estensione personalizzata avente OID 1.3.6.1.4.1.99999.2 deve contenere l'identificativo di un ipotetico deviceId il cui valore deve essere calcolato secondo un regola ben definita e che vedremo successivamente.

In termini di configurazione OpenSSL, a seguire è mostrato un esempio di configurazione da usare per la generazione dei certificati client usando OpenSSL.

[ client_cert ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = critical, clientAuth
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer

# Estensioni personalizzate
1.3.6.1.4.1.99999.1 = ASN1:UTF8String:Role=${ext_cert_role}
1.3.6.1.4.1.99999.2 = ASN1:UTF8String:DeviceId=${ext_cert_device_id}

Configurazione 1 - Configurazione di OpenSSL per la generazione dei certificati client

L'extendedKeyUsage clientAuth ha il flag a critical perché la sua interpretazione da parte del server TLS è fondamentale; le estensioni personalizzate non sono segnate come critical, per cui il server TLS le ignorerà ma non i componenti di mapping (vedi requisiti tre e quattro).

A seguire è mostrato un estratto della chiave pubblica di un certificato client generato secondo le specifiche discusse in precendenza. La sezione X509v3 extensions mostra appunto le estensioni usate, sia quelle standard, sia quelle personalizzate.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            65:ef:ed:e0:55:06:f7:fa:23:75:ea:a5:df:c6:61:ab:75:8c:38:21
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA
        Validity
            Not Before: Sep 12 09:47:43 2024 GMT
            Not After : Sep 12 09:47:43 2025 GMT
        Subject: C=IT, ST=Italy, L=Rome, O=Bad Corporation, OU=Community & News, CN=24A5CCC7-EE36-4449-9025-54CED3011920
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus: ...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            X509v3 Key Usage:
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage: critical
                TLS Web Client Authentication
            X509v3 Subject Key Identifier:
                AF:06:90:23:56:1B:97:6A:E4:B3:63:4E:E3:F0:8A:24:6E:FE:A3:CD
            X509v3 Authority Key Identifier:
                28:CB:D3:55:FE:FA:AA:6D:34:D4:45:56:9D:A8:68:F1:E4:6D:20:A3
            1.3.6.1.4.1.99999.1:
                ..Role=User,CommunityManager
            1.3.6.1.4.1.99999.2:      ...DeviceId=MTcyNjEzNDQ2MzExMzA3NjAwMCM0MWJmNDAxNC1lNDFlLTQ5YWUtYTU4Mi02NTJiMGEzMzVlMTcjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjYTdkMmZmNDI0NjJiMGZjYWRhMzM1YjAwN2NhN2E4YTY5NzVkNjZlNmE3MDg3N2M1MzczM2VmYmYzODBkMWQ5Nw==
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:...

Configurazione 2 - Estratto della chiave pubblica di un certificato client generato secondo le specifiche.

Algoritmo per la generazione del DeviceId

La generazione del DeviceId dovrà avvenire nel modo seguente:

1. combina il timestamp corrente, un UUID (Universally Unique Identifier) generato e l’hostname del dispositivo per creare una stringa unica. Le singole informazioni devono essere separate dal carattere # (hash o diesis);
2. genera un HMAC (Hash-based Message Authentication Code) usando SHA-256 e una chiave segreta;
3. combina queste informazioni e codifica il risultato in Base64.

Il processo di verifica, è praticamente l'inverso:

1. decodifica un DeviceId codificato in Base64;
2. separa la stringa combinata e l’HMAC fornito;
3. rigenera l’HMAC basandosi sulla stringa originale.
4. confronta l’HMAC calcolato con quello fornito per verificare la validità dell’ID.

A seguire è mostrato il flow di quanto descritto in precedenza per generare e verificare il DeviceId.

Figura 4 - Flow per la generazione e verifica del DeviceId.

A seguire è mostrato lo pseudo codice per la generazione del DeviceId. Se fate attenzione, il DeviceId mostrato nell'esempio è quello visibile sulle info del certificato client di esempio mostrato in configurazione 2.

# Combined string
# Generate a unique string based on timestamp, UUID, and hostname
# timestamp=$(date +%s%N)                      # Get the current timestamp with nanoseconds
# uuid=$(uuidgen | tr '[:upper:]' '[:lower:]') # Generate a UUID and convert it to lowercase
# hostname=$(hostname)                         # Use the device's hostname for additional uniqueness
# combined_string="${timestamp}#${uuid}#${hostname}"
1726134463113076000#41bf4014-e41e-49ae-a582-652b0a335e17#amusarra-macbook-pro.local

# HMAC sha256 with secret key my_secret_key_for_generate_device_id
# Generate an HMAC SHA-256 based on the combined string and the secret key
# hmac=$(echo -n "$combined_string" | openssl dgst -sha256 -hmac "$DEVICE_ID_SECRET_KEY" | awk '{print $2}')
a7d2ff42462b0fcada335b007ca7a8a6975d66e6a70877c53733efbf380d1d97

# Combine the device ID with the HMAC
# device_id="${combined_string}#${hmac}"
1726134463113076000#41bf4014-e41e-49ae-a582-652b0a335e17#amusarra-macbook-pro.local#a7d2ff42462b0fcada335b007ca7a8a6975d66e6a70877c53733efbf380d1d97

# DeviceId in Base64
# Encode the result using Base64
# encoded_device_id=$(echo -n "$device_id" | base64)
MTcyNjEzNDQ2MzExMzA3NjAwMCM0MWJmNDAxNC1lNDFlLTQ5YWUtYTU4Mi02NTJiMGEzMzVlMTcjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjYTdkMmZmNDI0NjJiMGZjYWRhMzM1YjAwN2NhN2E4YTY5NzVkNjZlNmE3MDg3N2M1MzczM2VmYmYzODBkMWQ5Nw==

Source Code 1 - Pseudo codice che mostra la generazione del DeviceId

Volendo implementare uno script per la generazione e verifica del DeviceId, quello a seguire è il sequence diagram.

Struttura JSON di risposta dei servizi REST

A seguire lo schema del JSON di risposta per il servizio /api/v1/connection-info/user-identity e un esempio dell'istanza.

{
  "type": "object",
  "properties": {
    "principal": {
      "type": "string",
      "description": "A distinguished name (DN) representing the principal."
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of roles assigned to the principal."
    },
    "attributes": {
      "type": "object",
      "properties": {
        "deviceId": {
          "type": "string",
          "description": "An identifier for the device associated with the principal."
        }
      },
      "required": ["deviceId"],
      "description": "Additional attributes related to the principal."
    },
    "userCN": {
      "type": "string",
      "description": "The common name (CN) of the user."
    }
  },
  "required": ["principal", "roles", "attributes", "userCN"],
  "description": "Schema for representing a user principal with roles and attributes."
}

Source Code 2 - Schema del JSON di risposta per il servizio /api/v1/connection-info/user-identity

{
  "principal": "CN=24A5CCC7-EE36-4449-9025-54CED3011920,OU=Community & News,O=Bad Corporation,L=Rome,ST=Italy,C=IT",
  "roles": [
    "User",
    "CommunityManager"
  ],
  "attributes": {
    "deviceId": "MTcyNjEzNDQ2MzExMzA3NjAwMCM0MWJmNDAxNC1lNDFlLTQ5YWUtYTU4Mi02NTJiMGEzMzVlMTcjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjYTdkMmZmNDI0NjJiMGZjYWRhMzM1YjAwN2NhN2E4YTY5NzVkNjZlNmE3MDg3N2M1MzczM2VmYmYzODBkMWQ5Nw=="
  },
  "userCN": "24A5CCC7-EE36-4449-9025-54CED3011920"
}

Source Code 3 - Esempio di risposta JSON del servizio /api/v1/connection-info/user-identity

A seguire lo schema del JSON di risposta per il servizio /api/v1/connection-info/info e un esempio dell'istanza.

{
  "type": "object",
  "properties": {
    "httpRequestHeaders": {
      "type": "object",
      "properties": {
        "user-agent": {
          "type": "string",
          "description": "User agent string of the HTTP request."
        },
        "accept": {
          "type": "string",
          "description": "Accept header of the HTTP request."
        }
      },
      "required": ["user-agent", "accept"],
      "description": "Headers of the HTTP request."
    },
    "server": {
      "type": "object",
      "properties": {
        "notAfter": {
          "type": "string",
          "description": "Expiration date of the server's certificate."
        },
        "keyAlgorithm": {
          "type": "string",
          "description": "Algorithm used for the server's key."
        },
        "keySize": {
          "type": "integer",
          "description": "Size of the server's key in bits."
        },
        "certCommonName": {
          "type": "string",
          "description": "Common name of the server's certificate."
        },
        "certIssuer": {
          "type": "string",
          "description": "Issuer of the server's certificate."
        },
        "subjectAlternativeNames": {
          "type": "array",
          "items": {
            "type": "array",
            "items": [
              { "type": "integer" },
              { "type": "string" }
            ]
          },
          "description": "Subject alternative names in the server's certificate."
        },
        "certSubject": {
          "type": "string",
          "description": "Subject of the server's certificate."
        },
        "certSerialNumber": {
          "type": "string",
          "description": "Serial number of the server's certificate."
        },
        "certPEM": {
          "type": "string",
          "description": "PEM encoded server certificate."
        },
        "customExtensions": {
          "type": "object",
          "description": "Custom extensions for the server's certificate."
        },
        "notBefore": {
          "type": "string",
          "description": "Start date of validity for the server's certificate."
        }
      },
      "required": [
        "notAfter",
        "keyAlgorithm",
        "keySize",
        "certCommonName",
        "certIssuer",
        "subjectAlternativeNames",
        "certSubject",
        "certSerialNumber",
        "certPEM",
        "notBefore"
      ],
      "description": "Details about the server's certificate and key."
    },
    "protocol": {
      "type": "string",
      "description": "Protocol used for the connection (e.g., TLS version)."
    },
    "httpProtocol": {
      "type": "string",
      "description": "HTTP protocol version (e.g., HTTP/2)."
    },
    "clientPort": {
      "type": "integer",
      "description": "Port number used by the client."
    },
    "isSecure": {
      "type": "boolean",
      "description": "Indicates if the connection is secure."
    },
    "client": {
      "type": "object",
      "properties": {
        "notAfter": {
          "type": "string",
          "description": "Expiration date of the client's certificate."
        },
        "keyAlgorithm": {
          "type": "string",
          "description": "Algorithm used for the client's key."
        },
        "keySize": {
          "type": "integer",
          "description": "Size of the client's key in bits."
        },
        "certCommonName": {
          "type": "string",
          "description": "Common name of the client's certificate."
        },
        "certIssuer": {
          "type": "string",
          "description": "Issuer of the client's certificate."
        },
        "subjectAlternativeNames": {
          "type": "null",
          "description": "Subject alternative names in the client's certificate, if any."
        },
        "certSubject": {
          "type": "string",
          "description": "Subject of the client's certificate."
        },
        "certSerialNumber": {
          "type": "string",
          "description": "Serial number of the client's certificate."
        },
        "certPEM": {
          "type": "string",
          "description": "PEM encoded client certificate."
        },
        "customExtensions": {
          "type": "object",
          "properties": {
            "role": {
              "type": "string",
              "description": "Custom role information in the client's certificate."
            },
            "deviceId": {
              "type": "string",
              "description": "Custom device ID information in the client's certificate."
            }
          },
          "description": "Custom extensions for the client's certificate."
        },
        "notBefore": {
          "type": "string",
          "description": "Start date of validity for the client's certificate."
        }
      },
      "required": [
        "notAfter",
        "keyAlgorithm",
        "keySize",
        "certCommonName",
        "certIssuer",
        "certSubject",
        "certSerialNumber",
        "certPEM",
        "notBefore"
      ],
      "description": "Details about the client's certificate and key."
    },
    "userAgent": {
      "type": "string",
      "description": "User agent string used by the client."
    },
    "cipherSuite": {
      "type": "string",
      "description": "Cipher suite used for the connection."
    },
    "clientAddress": {
      "type": "string",
      "description": "Address and port of the client."
    }
  },
  "required": [
    "httpRequestHeaders",
    "server",
    "protocol",
    "httpProtocol",
    "clientPort",
    "isSecure",
    "client",
    "userAgent",
    "cipherSuite",
    "clientAddress"
  ],
  "description": "Schema representing a network connection including server and client details, protocols, and certificates."
}