DEV Community: Antonio Musarra

Approfondimento sullo standard PKCS#11 e utilizzo con Smart Card

Antonio Musarra — Sun, 22 Sep 2024 16:27:18 +0000

Introduzione a PKCS#11

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

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

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).
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.
Meccanismi Crittografici : PKCS#11 supporta diversi meccanismi crittografici, inclusi RSA, ECC, AES, e SHA, rendendolo flessibile per diverse applicazioni.
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.

Scambio delle Chiavi:
Alice invia un messaggio cifrato a Bob:
Bob invia un messaggio firmato ad Alice:

sequenceDiagram participant Alice participant Bob Alice->>Bob: Richiesta chiave pubblica Bob-->>Alice: Invia chiave pubblica Alice->>Alice: Cifra il messaggio con la chiave pubblica di Bob Alice->>Bob: Invia messaggio cifrato Bob->>Bob: Decifra il messaggio con la sua chiave privata Bob->>Alice: Richiesta chiave pubblica Alice-->>Bob: Invia chiave pubblica Bob->>Bob: Firma il messaggio con la chiave privata Bob->>Alice: Invia messaggio firmato Alice->>Alice: Verifica la firma con 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.

Aspetto	Cifratura	Firma Digitale
Scopo	Proteggere la riservatezza del messaggio	Garantire l'autenticità e l'integrità del messaggio
Chiave usata	Chiave pubblica del destinatario per cifrare	Chiave privata del mittente per firmare
Chiave per verificare	Chiave privata del destinatario per decifrare	Chiave pubblica del mittente per verificare
Risultato	Solo il destinatario può leggere il messaggio	Il destinatario può verificare la provenienza e l'integrità del messaggio

Tabella 1 - Differenza tra cifratura e 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.

Una Smart Card compatibile con PKCS#11.
Un certificato digitale per la tua Smart Card.
Un PIN per accedere alla Smart Card.
Un lettore di Smart Card.
Un driver PKCS#11 per la tua Smart Card.
Un ambiente di sviluppo per il linguaggio di programmazione che desideri utilizzare.
Un'API PKCS#11 per il tuo linguaggio di programmazione.
Un'applicazione che utilizzi PKCS#11 per accedere alla Smart Card.
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)

Python

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)

Python

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()

Python

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)

Python

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()

Python

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.

sequenceDiagram participant Bob participant SmartCard participant Alice Bob->>SmartCard: Inserisce la Smart Card Bob->>SmartCard: Inserisce il PIN SmartCard-->>Bob: Autenticazione riuscita Bob->>SmartCard: Firma il messaggio SmartCard-->>Bob: Restituisce la firma Bob->>Alice: Invia messaggio e firma Alice->>Bob: Chiede a Bob la chiave pubblica Bob-->>Alice: Restituisce la chiave pubblica Alice->>Alice: Verifica la firma con la chiave pubblica Alice-->>Alice: Firma verificata correttamente

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"

Bash

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!

Plaintext

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

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

message_<uuid4>txt: il messaggio originale.
signature_<uuid4>.txt: la firma generata.
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

Bash

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

Bash

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

Bash

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.

sequenceDiagram participant User participant Script participant PKCS11Lib participant SmartCard User ->> Script: Avvia lo script con i parametri Script ->> Script: Analizza i parametri di input Script ->> PKCS11Lib: Carica la libreria PKCS#11 Script ->> PKCS11Lib: Ottiene la lista degli slot con token presenti PKCS11Lib -->> Script: Lista degli slot Script ->> SmartCard: Apre una sessione con la Smart Card Script ->> SmartCard: Esegue il login con il PIN Script ->> SmartCard: Trova la chiave privata SmartCard -->> Script: Chiave privata Script ->> SmartCard: Trova il certificato pubblico SmartCard -->> Script: Certificato pubblico Script ->> SmartCard: Ottiene il certificato pubblico in formato DER SmartCard -->> Script: Certificato pubblico (DER) Script ->> Script: Carica il certificato pubblico Script ->> Script: Salva il certificato pubblico in formato PEM Script ->> Script: Ottiene la chiave pubblica dal certificato Script ->> Script: Codifica il messaggio da firmare Script ->> SmartCard: Firma il messaggio usando la chiave privata SmartCard -->> Script: Firma Script ->> Script: Salva la firma su file Script ->> Script: Salva il messaggio su file Script ->> Script: Verifica la firma usando la chiave pubblica Script ->> SmartCard: Esegue il logout dalla sessione Script ->> User: Termina l'esecuzione

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.

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.
Autenticazione Forte : molte aziende e istituzioni richiedono un’autenticazione a due fattori (2FA) basata su Smart Card per l’accesso ai sistemi critici.
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.
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:

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.

Implementazione di TLS Mutual Authentication (mTLS) con Quarkus

Antonio Musarra — Wed, 18 Sep 2024 23:21:53 +0000

Implementazione di TLS Mutual Authentication (mTLS) con Quarkus

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

sequenceDiagram autonumber participant Client participant Server Client->>Server: Client Hello (Supported ciphersuites, Random number) Server-->>Client: Server Hello (Chosen ciphersuite, Random number, Request client certificate) Server-->>Client: Certificate (Server's certificate) Client-->>Client: Verify Server Certificate Client->>Server: Client Certificate (Client's certificate) Server-->>Server: Verify Client Certificate Client->>Server: Client Key Exchange (Premaster secret encrypted with server public key) Client->>Server: Finished (Encrypted with session key) Server->>Client: Finished (Encrypted with session key) Client->>Server: Application Data Server->>Client: Application Data

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:
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:

il Client inizia la connessione TLS con l’applicazione Quarkus ;
Quarkus richiede il certificato del client come parte della procedura di autenticazione reciproca mTLS;
il Client invia il proprio certificato;
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).

sequenceDiagram participant Client participant QuarkusApp as Quarkus Application %% TLS Handshake Note over Client, QuarkusApp: TLS Handshake Starts Client->>QuarkusApp: Initiate TLS handshake QuarkusApp->>Client: Request Client Certificate Client->>QuarkusApp: Send Client Certificate Note over Client, QuarkusApp: TLS Handshake Complete QuarkusApp->>QuarkusApp: Verify Client Certificate via mTLS %% Resource Request alt Valid Client Certificate Client->>QuarkusApp: Request access to /resource QuarkusApp->>QuarkusApp: Process the request QuarkusApp->>Client: Return /resource data else Invalid Client Certificate QuarkusApp->>Client: Error: Invalid Client Certificate end

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.

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.

Figura 3 - Quarkus Security Architecture e flow del processo di autenticazione e autorizzazione (fonte Quarkus.io)

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.

ID	Requisito	Descrizione
1	Autenticazione mTLS	È richiesto che l'applicazione supporti mTLS come meccanismo di autenticazione utilizzando certificati in formato PEM e PKCS#12.
2	Private end-point REST	È richiesto la realizzazione di due end-point REST il cui accesso deve essere garantito solo ai client che si presentino con un certificato client avente determinate carratteristiche (vedi capitolo Generazione dei certificati).

Il primo end-point deve essere definito con la URI /v1/connection-info/info con metodo GET e produrre un JSON avente la struttura mostrata al capitolo Struttura JSON di risposta dei servizi REST. La risposta del servizio conterrà un set d'informazioni che riguardano la connessione instaurata.

Il secondo end-point deve essere definito con la URI /v1/connection-info/user-identity con metodo GET e produrre un JSON avente la struttura mostrata al capitolo Struttura JSON di risposta dei servizi REST. La risposta del servizio conterrà un set d'informazioni che riguardano l'indentità del client che ha richiesto l'accesso alla risorsa. |
| 3 | Mapping automatico dei ruoli | È richiesto che l'applicazione sia capace di mappare attributi specifici del certificato client sui ruoli gestisti da Quarkus (vedi Authorization of web endpoints). Per i dettagli sulla struttura del certificato client fare riferimento al capitolo Generazione dei certificati. |
| 4 | Mapping automatico degli attributi d'identità | È richiesto che l'applicazione sia capace di mappare attributi specifici del certificato client sugli Identity Attributes del client che ha richiesto l'accesso alla risorsa. Per i dettagli sulla struttura del certificato client fare riferimento al capitolo Generazione dei certificati. |
| 5 | Definizione delle policy di accesso ai servizi Rest | È richiesto che l'applicazione definisca una policy chiamata per esempio role-policy-cert che definisca i ruoli User e Administrator come abilitati per l'accesso alle due risorse REST descritte sul requisito numero 1. |
| 6_BONUS | Integrazione Trusted Service List (TSL) | È richiesto che l'applicazione sia integrata con il Trusted Service List (TSL) Italiano per l'acquisizione delle Certification Authority dei fornitori di servizi fiduciari qualificati e accreditati per il rilascio di certificati digitali. Questa è una predisposizione per consetire poi l'accesso all'applicazione in mTLS tramite per esempio CIE e CNS. |

Tabella 1 - Requisiti che l'applicazione Quarkus deve implementare.

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:

un certificato di Certificate Authority (CA);
un certificato server per il servizio HTTPS, quest'ultimo basato su Vert.x Core integrato all'interno di Quarkus;
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.

Tipo	CN	SAN	O	OU	L	ST	C	Valitità	Issuer
CA	Dontesta CA		Dontesta	IT Labs	Bronte	Catania	IT	5 anni	self
Server	rd.quarkus.dontesta.it	admin.quarkus.dontesta.it, blog.quarkus.dontesta.it, localhost	Dontesta	IT Labs	Bronte	Catania	IT	1 anno	Dontesta CA, Dontesta
Client	#client-id (può essere un qualunque tipo di identificatore)		#Organization	#OrganizationUnit	#Locality	#State	#Country	#Validity	#Issuer

Tabella 2 - Caratteristiche dei certificati da generare

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:

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;
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}

INI

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

Plaintext

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:

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);
genera un HMAC (Hash-based Message Authentication Code) usando SHA-256 e una chiave segreta;
combina queste informazioni e codifica il risultato in Base64.

Il processo di verifica, è praticamente l'inverso:

decodifica un DeviceId codificato in Base64;
separa la stringa combinata e l’HMAC fornito;
rigenera l’HMAC basandosi sulla stringa originale.
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.

graph TD A((Start)) --> B{Command?} B --> |Generate| C[Collect timestamp, UUID, and hostname] C --> D[Create combined string] D --> E[Generate HMAC SHA-256 with secret key] E --> F[Combine with HMAC and encode in Base64] F --> G[Return Base64 Device ID] B --> |Verify| H[Decode Base64 Device ID] H --> I[Extract combined string and provided HMAC] I --> J[Recalculate HMAC using secret key] J --> K{Compare HMACs} K --> |Match| L[Device ID verified] K --> |Mismatch| M[Verification failed] G --> N((End)) L --> N M --> N

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==

Bash

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.

Figura 5 - Sequence Diagram che mostra il funzionamento di un ipotetico script di generazione e verifica del DeviceId.

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."
}

JSON

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"
}

JSON

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."
}

JSON

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

{
  "httpRequestHeaders": {
    "user-agent": "curl/8.7.1",
    "accept": "*/*"
  },
  "server": {
    "notAfter": "Sun Sep 07 00:16:21 CEST 2025",
    "keyAlgorithm": "RSA",
    "keySize": 2048,
    "certCommonName": "rd.quarkus.dontesta.it",
    "certIssuer": "CN=Dontesta CA,OU=IT Labs,O=Dontesta,L=Bronte,ST=Catania,C=IT",
    "subjectAlternativeNames": [
      [
        2,
        "admin.quarkus.dontesta.it"
      ],
      [
        2,
        "blog.quarkus.dontesta.it"
      ],
      [
        2,
        "localhost"
      ]
    ],
    "certSubject": "CN=rd.quarkus.dontesta.it,OU=IT Labs,O=Dontesta,L=Bronte,ST=Catania,C=IT",
    "certSerialNumber": "581958667903693191343101950434363490497173665817",
    "certPEM": "<certPEM>",
    "customExtensions": {},
    "notBefore": "Sat Sep 07 00:16:21 CEST 2024"
  },
  "protocol": "TLSv1.3",
  "httpProtocol": "HTTP_2",
  "clientPort": 54845,
  "isSecure": true,
  "client": {
    "notAfter": "Fri Sep 12 11:47:43 CEST 2025",
    "keyAlgorithm": "RSA",
    "keySize": 2048,
    "certCommonName": "24A5CCC7-EE36-4449-9025-54CED3011920",
    "certIssuer": "CN=Dontesta CA,OU=IT Labs,O=Dontesta,L=Bronte,ST=Catania,C=IT",
    "subjectAlternativeNames": null,
    "certSubject": "CN=24A5CCC7-EE36-4449-9025-54CED3011920,OU=Community & News,O=Bad Corporation,L=Rome,ST=Italy,C=IT",
    "certSerialNumber": "581958667903693191343101950434363490497173665825",
    "certPEM": "<certPEM>",
    "customExtensions": {
      "role": "Role=User,CommunityManager",
      "deviceId": "DeviceId=MTcyNjEzNDQ2MzExMzA3NjAwMCM0MWJmNDAxNC1lNDFlLTQ5YWUtYTU4Mi02NTJiMGEzMzVlMTcjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjYTdkMmZmNDI0NjJiMGZjYWRhMzM1YjAwN2NhN2E4YTY5NzVkNjZlNmE3MDg3N2M1MzczM2VmYmYzODBkMWQ5Nw=="
    },
    "notBefore": "Thu Sep 12 11:47:43 CEST 2024"
  },
  "userAgent": "curl/8.7.1",
  "cipherSuite": "TLS_AES_256_GCM_SHA384",
  "clientAddress": "127.0.0.1:54845"
}

JSON

Source Code 5 - Esempio di risposta JSON del servizio /api/v1/connection-info/info

Requisiti software

Per sviluppare la nostra soluzione mTLS, abbiamo necessità di un set di strumenti software che potremmo dividere in due categorie.

Sviluppo
1. Java 21
2. Maven 3.9.x
3. Quarkus 3.14.x
4. Quarkus CLI (opzionale ma consigliato)
5. Git (opzionale ma consigliato)
Gestione certificati TLS (opzionali ma consigliato)
1. bash 5.2.x | zsh 5.x | GitBash 2.46
2. OpenSSL 3.x
3. Curl 8.x
4. Java KeyTool (in genere installato con la JDK)
5. Xidel è uno strumento da riga di comando e una libreria che consente di estrarre dati da documenti XML, HTML e JSON usando XPath, XQuery o CSS Selectors

La versione del framework di Quarkus deve essere dalla 3.14 in poi, questo perché alcune delle funzionalità, come per esempio il TSL Registry è stato introdotto dalla versione 3.14.0.

La Quarkus CLI è opzionale in quanto la maggior parte delle operazioni possono essere eseguite attraverso Maven e il plugin di Quarkus. Nel corso di questo articolo utilizzeremo però la Quarkus CLI.

Git è opzionale ma consigliato se volete seguire gli step di questo articolo e clonare il repository del progetto completo.

Per quanto riguarda i tool indicati per la gestione dei certificati TLS, non sono obbligatori ma ritengo utile l'installazione per provare con mano la gestione dei certificati TLS (client e server).

La gestione dei certificati TLS è in genere demandata a organi specifici all'interno di un'organizzazione ma noi sviluppatori dobbiamo essere "smart" ed essere capaci di gestire i certificati TLS per il nostro ambiente di sviluppo. Quarkus, in tal senso ha aggiunto dei tool Quarkus CLI commands and development CA (Certificate Authority) e Automatic certificate management with Let’s Encrypt per la gestione dei certificati TLS che però hanno qualche limite in termini di flessibilità, per questo motivo ho deciso di realizzare un tool ad hoc che vedremo poi nel corso di questo articolo.

Soddisfati i requisiti software, siamo nelle condizioni di poter iniziare a creare il nostro progetto software step by step e che rispetti i requisiti descritti al capitolo Requisiti dell'applicazione Quarkus.

Implementazione della soluzione

Adesso che abbiamo raccolto tutti i pezzi, possiamo finalmente mettere le mani al codice realizzando l'applicazione Quarkus e che soddisfi i requisiti descritti al capitolo Requisiti dell'applicazione Quarkus. Gli step da seguire per implemetare i requisiti dall'uno al cinque sono indicati a seguire. Per quanto riguarda il requisito bonus, lo affronteremo a parte.

Creazione dell'applicazione Quarkus tramite CLI specificando le estensioni necessarie.
Generazione del certificato di Certification Authority.
Generazione del certificato Server rilasciato dalla CA (creata alla step precedente).
Configurazione di Quarkus per l'attivazione di HTTPS.
Test della configurazione HTTPS/TLS.
Abilitazione del mTLS.
Implementazione dei componenti SecurityIdentityAugmentor per il mapping dei ruoli e attributi.
Implementazione dei servizi REST.
Configurazione delle policy di accesso ai servizi REST.
Generazione di un set di certificati client per eseguire dei test di accesso (positivi e negativi).
Test della configurazione mTLS.

Durante l'esecuzione degli step faremo riferimento al repository GitHub quarkus-mtls-auth-tutorial attraverso l'uso di tag per identificare gli step, per cui basta effettuare il clone in questo modo: git clone -b <nome-tag> https://github.com/amusarra/quarkus-mtls-auth-tutorial.git.

Tra il repository dedicato al tutorial e quello contenente il progetto completo della soluzione (disponibile sul repository GitHub Quarkus mTLS Auth), potreste notare delle differenze come per esempio la presenza degli unit-test ma i livello di funzionalità sono gli stessi.

Step 1 - Creazione dell'applicazione Quarkus via CLI

Il tag di riferimento per questo step è tutorial-step-1-create-project.

Le estensioni Quarkus di cui abbiamo bisogno sono:

io.quarkus:quarkus-vertx
io.quarkus:quarkus-arc
io.quarkus:quarkus-rest
io.quarkus:quarkus-rest-jackson
io.quarkus:quarkus-security
io.quarkus:quarkus-elytron-security-common

Procediamo con la creazione del progetto Quarkus tramite la CLI e le estensioni indicate. Per fare ciò, eseguire il comando a seguire (non necessario nel caso in cui abbiate eseguito il clone del repository GitHub quarkus-mtls-auth-tutorial con il tag di riferimento per questo step).

# Create initial Quarkus project via Quarkus CLI
quarkus create app it.dontesta.quarkus.tls.auth:tls-mutual-auth \
    --extension='quarkus-vertx' \
    --extension='quarkus-arc' \
    --extension='quarkus-rest' \
    --extension='quarkus-rest-jackson' \
    --extension='quarkus-security' \
    --extension='quarkus-elytron-security-common' \
    --no-code

Bash

Console 1 - Creazione del progetto Quarkus con le estensioni necessarie

Al termine dell'esecuzione del comando di creazione dell'applicazione Quarkus, dovremmo avere la directory tls-mutual-auth avente la struttura a mostrata a seguire.

tls-mutual-auth
├── README.md
├── mvnw
├── mvnw.cmd
├── pom.xml
└── src
    └── main
        ├── docker
        │   ├── Dockerfile.jvm
        │   ├── Dockerfile.legacy-jar
        │   ├── Dockerfile.native
        │   └── Dockerfile.native-micro
        ├── java
        └── resources
            └── application.properties

6 directories, 9 files

Bash

Console 2 - Struttura del progetto Quarkus creato tramite la CLI

Step 2 - Generazione del certificato di Certification Authority

Il tag di riferimento per questo step è tutorial-step-2-generate-ca.

Per generare il certificato della Certification Authority secondo quanto indicato in tabella 2, procederemo utilizzando lo script certs_manager.sh. Questo script è stato creato appositamente per questo tutorial e si trova all'interno del progetto Quarkus.

Per eseguire lo script sulla propria macchina di sviluppo, è necessario che i requisiti software per Gestione certificati TLS (vedi capitolo Requisiti software) siano soddisfatti.

Per generare il certificato della CA dobbiamo eseguire il comando a seguire dalla home del progetto. L'esecuzione del comando indicato (che si trova in src/main/shell/certs-manager/certs_manager.sh), creerà all'interno della directory src/main/resources/certs i seguenti file:

ca_private_key.pem: chiave privata del certificato in formato PEM (Privacy-Enhanced Mail);
ca_private_key.pem.password: file contenente la password della chiave private;
ca_cert.pem: chiave certificato in formato PEM;
ca_cert.p12: formato PKCS#12 del certificato.

# Generate the CA
./src/main/shell/certs-manager/certs_manager.sh generate-ca --working-dir src/main/resources/certs \
    --private-key-file ca_private_key.pem \
    --ca-certificate-file ca_cert.pem \
    --validity-days 1825 \
    --country IT \
    --state Catania \
    --locality "Bronte" \
    --organization Dontesta \
    --organizational-unit "IT Labs" \
    --common-name "Dontesta CA" \
    --output-p12-file ca_cert.p12

Bash

Console 3 - Generazione della CA

L'esecuzione del comando precedente, dovrebbe produrre un output simile a quello mostrato a seguire. Ricordate di prendere nota della password del file ca_cert.p12 che dovremo poi impostare sulla configurazione dell'applicazione Quarkus.

✅ OpenSSL version 3.3.2 is suitable.
🔑 Generating the private key...
..+.+...............+...........+...+++++++++++++++++++++++++++++++++++++++*..+.....+....+.........+.....+......+...+.+..+.......+..+...+.+...............+..+.........+.+..+.............+........+.+...+++++++++++++++++++++++++++++++++++++++*......+....+...+......+.+........................+...+...++++++
Private key password: 57t4Qb1IaGDSZSdv
📜 Generating the CA certificate...
✅ CA certificate generated successfully!
🔍 Verifying the Certificate Issuer...
✅ Certificate Issuer: issuer=C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA
🔍 Verifying the Certificate Serial...
✅ Certificate Serial (hex): serial=79FE005459C8FD77ABD0038B1383431380D97BD3
🔍 Verifying the Certificate Subject...
✅ Certificate Subject: subject=C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA
🔒 Generating the p12 file...
✅ p12 file generated successfully!
p12 file: src/main/resources/certs/ca_cert.p12
p12 password: bdo6zkObhUDsa3aL
All files generated in: src/main/resources/certs

Bash

Console 4 - Output del comando che ha generato il certificato della CA.

Step 3 - Generazione del certificato Server rilasciato dalla CA

Per generare il certificato server firmato dalla CA appena creata, utilizzeremo sempre lo stesso script cert-manager.sh ma con parametri diversi. Il comando da eseguire è indicato a seguire. L'esecuzione del comando indicato, creerà all'interno della directory src/main/resources/certs i seguenti file:

server_private_key.pem: chiave privata del certificato in formato PEM;
server_csr.pem: Certificate Signing Request (CSR) del certificato in formato PEM;
server_cert.pem: certificato del server in formato PEM;
server_cert.p12: formato PKCS#12 del certificato.

# Generate the Server certificate
./src/main/shell/certs-manager/certs_manager.sh generate-server --working-dir src/main/resources/certs \
    --private-key-file server_private_key.pem \
    --csr-file server_csr.pem \
    --server-cert-file server_cert.pem \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --validity-days 365 \
    --country IT \
    --state Italy \
    --locality "Bronte (CT)" \
    --organization Dontesta \
    --organizational-unit "IT Labs" \
    --common-name "rd.quarkus.dontesta.it" \
    --san-domains "DNS:admin.quarkus.dontesta.it,DNS:blog.quarkus.dontesta.it,DNS:localhost" \
    --output-p12-file server_cert.p12

Bash

Console 5 - Generazione del certificato server firmato dalla CA

L'esecuzione del comando precedente, dovrebbe produrre un output simile a quello mostrato a seguire. Ricordate di prendere nota della password del file server_cert.p12 che dovremo poi impostare sulla configurazione dell'applicazione Quarkus.

✅ OpenSSL version 3.3.2 is suitable.
🔑 Generating the private key...
....+++++++++++++++++++++++++++++++++++++++*.......+.....+.+.....+..........+..+.+..............+.......+........+..........+...+..+.+...........+...+.+......+...+............+...+........+..+..............++++++
Private key password: k/6lEQi/Abxm6lLu
📝 Creating OpenSSL config file for SAN...
✅ OpenSSL config file created for SAN.
📑 Generating the CSR...
🔏 Generating the server certificate...
Certificate request self-signature ok
subject=C=IT, ST=Italy, L=Bronte (CT), O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
🔍 Verifying the Certificate Issuer...
✅ Certificate Issuer: issuer=C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA
🔍 Verifying the Certificate Serial...
✅ Certificate Serial (hex): serial=41FB7FC18FABB3A846893339E25D3CAD399A92BE
🔍 Verifying the Certificate Subject...
✅ Certificate Subject: subject=C=IT, ST=Italy, L=Bronte (CT), O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
🔒 Generating the p12 file...
✅ p12 file generated successfully!
p12 file: src/main/resources/certs/server_cert.p12
p12 password: NWiOJRmJ26D8RTYD
All files generated in: src/main/resources/certs

Bash

Console 6 - Output del comando che ha generato il certificato del server firmato dalla CA.

Per maggiori informazioni sullo script certs_manager.sh, eseguire il comando ./src/main/shell/certs-manager/certs_manager.sh per ottenere la lista dei parametri che gestisce e la loro descrizione.

Step 4 - Configurazione di Quarkus per l'attivazione di HTTPS

Il tag di riferimento per questo step è tutorial-step-4-configure-https.

Adesso che abbiamo generato i certificati della CA e del server, possiamo procedere con la configurazione di Quarkus per l'attivazione di HTTPS. Per fare ciò, dobbiamo modificare il file src/main/resources/application.properties aggiungendo le proprietà necessarie affinché:

l'applicazione Quarkus utilizzi il certificato PKCS#12 del server;
l'applicazione Quarkus utilizzi il certificato PEM della CA per essere aggiunto al truststore;
l'applicazione Quarkus accetti solo richieste HTTPS;
l'applicazione Quarkus utilizzi solo il protocollo TLSv1.3;
l'applicazione Quarkus utilizzi la configurazione TLS denominata https.

#
# Section to configure the server to use HTTPS using the TLS registry,
# which was introduced in Quarkus 3.14 (https://quarkus.io/blog/quarkus-3-14-1-released/)
# For more information on the TLS registry, see https://quarkus.io/guides/tls-registry-reference
#

# Setting the key-store path. The key-store file is located in the `certs` directory
# inside the resources directory.
quarkus.tls.https.key-store.p12.path=certs/server_cert.p12

# Setting the key-store password.
# The password is stored in the `application.properties` file.
# In a development environment, the password may be changed when regenerating the key-store (e.g., using the `mvn clean` command).
# In a production environment, it is recommended to use a secure password storage mechanism.
quarkus.tls.https.key-store.p12.password=NWiOJRmJ26D8RTYD

# Setting the trust-store path.
# The trust-store file is located in the `certs` directory
# inside the resources directory.
quarkus.tls.https.trust-store.pem.certs=certs/ca_cert.pem

# Disabling insecure requests, only HTTPS requests are allowed.
quarkus.http.insecure-requests=disabled

# Setting the only supported TLS protocol to TLSv1.3.
quarkus.tls.https.protocols=TLSv1.3

# Setting the TLS configuration name to `https`.
quarkus.http.tls-configuration-name=https

Bash

Application Properties 1 - Configurazione di Quarkus per l'attivazione di HTTPS

In questa configurazione sono state utilizzate le proprietà che fanno parte del componente Quarkus TLS Registry e in particolare la caratteristica delle named configuration che nel nostro caso si chiama https , definita dalla proprietà quarkus.http.tls-configuration-name nel file application.properties. Questa possibilità è stata introdotta in Quarkus 3.14 e permette di configurare in modo centralizzato le configurazioni TLS per l'applicazione Quarkus. Per maggiori informazioni, vi rimando alla documentazione ufficiale.

Adesso che abbiamo configurato l'applicazione Quarkus per l'attivazione del protocollo HTTPS, potremo procedere con il test della configurazione HTTPS/TLS.

Step 5 - Test della configurazione HTTPS/TLS

Per testare la configurazione HTTPS/TLS, possiamo eseguire il comando quarkus:dev e verificare che l'applicazione Quarkus sia in esecuzione e che accetti solo richieste HTTPS.

Dall'output del comando quarkus:dev, dovremmo notare che l'applicazione Quarkus è in esecuzione e accetti solo richieste HTTPS sulla porta 8443. L'output del comando quarkus:dev dovrebbe essere simile a quello mostrato a seguire.

______  _______  _____  __________
 --/ __\/ / / / _ | / _ \/ //_/ / / /__ /
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\ ___\_\____ /_/ |_/_/|_/_/|_|\ ____/___ /
2024-09-12 18:32:13,818 INFO [io.quarkus] (Quarkus Main Thread) tls-mutual-auth 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.14.3) started in 1.390s. Listening on: https://localhost:8443

2024-09-12 18:32:13,821 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2024-09-12 18:32:13,823 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, rest, rest-jackson, security, smallrye-context-propagation, vertx]

Bash

Console 7 - Output del comando quarkus:dev che mostra l'applicazione Quarkus in esecuzione

Se l’applicazione Quarkus è in esecuzione e accetta solo richieste HTTPS, il comando curl dovrebbe restituire un messaggio di errore che indica il rifiuto della connessione. Questo comportamento è quello atteso, poiché l’applicazione è configurata per accettare esclusivamente richieste HTTPS.

# Verify that the application is running and only accepts HTTPS requests.
# The command should return an error message indicating that the connection was refused.
curl -k http://localhost:8080

Bash

Console 8 - Test della configurazione HTTPS/TLS

Verifichiamo ora che l’applicazione Quarkus accetti richieste HTTPS. A tal fine, possiamo utilizzare il comando curl per inviare una richiesta HTTPS. Il comando dovrebbe restituire una risposta dall’applicazione.

# Verify that the application is running and accepts HTTPS requests.
# The command should return a response from the application.
curl -k -v https://localhost:8443

Bash

Console 9 - Test della configurazione HTTPS/TLS

L'output del comando curl dovrebbe essere simile a quello mostrato a seguire.

* Host localhost:8443 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* Trying [::1]:8443...
* connect to ::1 port 8443 from ::1 port 56576 failed: Connection refused
* Trying 127.0.0.1:8443...
* Connected to localhost (127.0.0.1) port 8443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
* subject: C=IT; ST=Italy; L=Bronte (CT); O=Dontesta; OU=IT Labs; CN=rd.quarkus.dontesta.it
* start date: Sep 12 16:13:44 2024 GMT
* expire date: Sep 12 16:13:44 2025 GMT
* issuer: C=IT; ST=Catania; L=Bronte; O=Dontesta; OU=IT Labs; CN=Dontesta CA
* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://localhost:8443/
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: localhost:8443]
* [HTTP/2] [1] [:path: /]
* [HTTP/2] [1] [user-agent: curl/8.7.1]
* [HTTP/2] [1] [accept: */*]
> GET / HTTP/2
> Host: localhost:8443
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/2 302
< location: /q/dev-ui/welcome
< content-length: 0
<
* Connection #0 to host localhost left intact

Plaintext

Console 10 - Output del comando curl che ha testato la configurazione HTTPS/TLS

I più attenti avranno notato dall'output del comando precedente le seguenti informazioni:

la connessione TLS è stata stabilita con successo utilizzando il protocollo TLSv1.3;
grazie a ALPN, il server ha accettato il protocollo HTTP/2. Su Quarkus il protocollo HTTP/2 è abilitato di default;
il server ha risposto con il certificato del server creato in precedenza e firmato dalla CA sempre creata in precedenza.

Dobbiamo eseguire l’ultimo test, ovvero, verificare che l’applicazione Quarkus accetti solo connessioni HTTPS con protocollo TLSv1.3. Questa volta utilizzeremo il comando OpenSSL, come indicato di seguito.

# Verify that the application only accepts HTTPS requests with the TLSv1.3 protocol.
# The command should return an error message indicating that the connection was refused.
openssl s_client -connect localhost:8443 -servername rd.quarkus.dontesta.it -showcerts -tls1_2

Bash

Console 11 - Test della configurazione HTTPS/TLS

In questo caso il comando openssl dovrebbe restituire un messaggio di errore che indica che la connessione è stata rifiutata e in particolare tlsv1 alert protocol version:ssl/record/rec_layer_s3.c:907:SSL alert number 70. Questo è il comportamento atteso poiché l'applicazione Quarkus accetta solo richieste HTTPS con il protocollo TLSv1.3.

Step 6 - Abilitazione del mTLS

Il tag di riferimento per questo step è tutorial-step-6-enable-mtls.

Abbiamo configurato l'applicazione Quarkus per l'attivazione di HTTPS e verificato che l'applicazione accetti solo richieste HTTPS. Ora, potremo procedere con l'abilitazione del mTLS. Per fare ciò, occorre modificare il file src/main/resources/application.properties aggiungendo le proprietà necessarie affinché l'applicazione Quarkus sia configurata per il supporto di mTLS.

#
# Section to configure the server for mTLS authentication mechanism.
# For more information see Authentication mechanisms in Quarkus https://quarkus.io/guides/tls-registry-reference#mtls
# and configuring mTLS in Quarkus https://quarkus.io/guides/tls-registry-reference#configuring-mtls
#

# Enabling the mTLS authentication mechanism.
# The server requires clients to authenticate themselves using a client certificate.
# The value can be one of the following:
#- `NONE`: no client authentication is required.
#- `REQUEST`: authentication is requested but not required.
#- `REQUIRED`: authentication is required.
quarkus.http.ssl.client-auth=REQUIRED

Bash

Application Properties 2 - Abilitazione del mTLS

Per impostazione predefinita l'applicazione Quarkus è configurata per non richiedere l'autenticazione del client. Per abilitare l'autenticazione del client, dobbiamo impostare la proprietà quarkus.http.ssl.client-auth su REQUEST o REQUIRED. In questo caso, impostiamo la proprietà su REQUIRED alfine di richiedere l'autenticazione del client.

Una volta applicata la nuova configurazione, il primo risultato atteso è che l'applicazione Quarkus accetti solo richieste HTTPS con protocollo TLSv1.3 e richieda l'autenticazione del client. Per fare una verifica, è sufficiente eseguire il comando curl come indicato a seguire.

# Verify that the application only accepts HTTPS requests with the TLSv1.3 protocol and requires client authentication.
curl -k -v https://localhost:8443

Bash

Console 12 - Test della configurazione mTLS

L'output del comando curl dovrebbe essere simile a quello mostrato a seguire che indica che la connessione è stata rifiutata.

* Host localhost:8443 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* Trying [::1]:8443...
* connect to ::1 port 8443 from ::1 port 62500 failed: Connection refused
* Trying 127.0.0.1:8443...
* Connected to localhost (127.0.0.1) port 8443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Request CERT (13):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Certificate (11):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
* subject: C=IT; ST=Italy; L=Bronte (CT); O=Dontesta; OU=IT Labs; CN=rd.quarkus.dontesta.it
* start date: Sep 12 16:13:44 2024 GMT
* expire date: Sep 12 16:13:44 2025 GMT
* issuer: C=IT; ST=Catania; L=Bronte; O=Dontesta; OU=IT Labs; CN=Dontesta CA
* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://localhost:8443/
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: localhost:8443]
* [HTTP/2] [1] [:path: /]
* [HTTP/2] [1] [user-agent: curl/8.7.1]
* [HTTP/2] [1] [accept: */*]
> GET / HTTP/2
> Host: localhost:8443
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
* LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C412:SSL routines:ST_OK:sslv3 alert bad certificate, errno 0
* Failed receiving HTTP2 data: 56(Failure when receiving data from the peer)
* Connection #0 to host localhost left intact
curl: (56) LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C412:SSL routines:ST_OK:sslv3 alert bad certificate, errno 0

Plaintext

Console 13 - Output del comando curl che ha testato la configurazione mTLS

Dall'output del comando è possibile notare la richiesta del certificato client da parte del server ((304) (IN), TLS handshake, Request CERT (13)). Il server ha rifiutato la connessione poiché non è stato fornito un certificato client valido (in questo caso nessun certificato è stato inviato). Questo è il comportamento atteso poiché l'applicazione Quarkus richiede obbligatoriamente l'autenticazione del client.

A questo punto, abbiamo configurato l’applicazione Quarkus per l’attivazione di mTLS e verificato che accetti solo richieste HTTPS con protocollo TLSv1.3, richiedendo l’autenticazione del client. Adesso possiamo procedere con l'implementazione dei componenti SecurityIdentityAugmentor per il mapping dei ruoli e attributi.

Step 7 - Implementazione dei componenti SecurityIdentityAugmentor

Il tag di riferimento per questo step è tutorial-step-7-impl-security-identity-augmentor.

Al momento, l’applicazione Quarkus è configurata per supportare l’autenticazione via mTLS. Tuttavia, dobbiamo ancora soddisfare il resto dei requisiti, quindi procederemo con l’implementazione dei componenti SecurityIdentityAugmentor per il mapping di ruoli e attributi.

Ricordiamo che ruoli e attributi sono informazioni che dobbiamo estrarre dal certificato client per poterli utilizzare all'interno dell'applicazione Quarkus. L'OID che identifica i ruoli è 1.3.6.1.4.1.99999.1, mentre 1.3.6.1.4.1.99999.2 identifica l'attributo DeviceId.

I componenti SecurityIdentityAugmentor che implementeremo dovranno verificare che i valori degli OID siano presenti nel certificato del client e, in caso affermativo, estrarli e aggiungerli all’oggetto SecurityIdentity di Quarkus. Qualora i valori degli OID non rispettino le regole di validazione (vedi pattern per l’OID dei ruoli, capitolo Generazione dei certificati e capitolo Algoritmo per la generazione del DeviceId), il componente SecurityIdentityAugmentor dovrà rifiutare la richiesta di autenticazione.

Per raggiungere l'obiettivo andremo a implementare tre classi.

AttributesAugmentor : classe che implementa l'interfaccia io.quarkus.security.identity.SecurityIdentityAugmentor e sovrascrive il metodo augment per estrarre il valore dell'OID 1.3.6.1.4.1.99999.2 (DeviceId) e renderlo disponibile sull'oggetto io.quarkus.security.identity.SecurityIdentity.
RolesAugmentor : classe che implementa l'interfaccia io.quarkus.security.identity.SecurityIdentityAugmentor e sovrascrive il metodo augment per estrarre il valore dell'OID 1.3.6.1.4.1.99999.1 (ruoli) e renderlo disponibile sull'oggetto io.quarkus.security.identity.SecurityIdentity.
OidSecurityIdentityAugmentor : classe che implementa l'interfaccia io.quarkus.security.identity.SecurityIdentityAugmentor e sovrascrive il metodo augment per verificare che il valore dell'OID che identifica il DeviceId sia presente e valido secondo l'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId.

Le classi AttributesAugmentor, RolesAugmentor e OidSecurityIdentityAugmentor fanno parte del package it.dontesta.quarkus.tls.auth.ws.security.identity. A seguire i sequence diagram che illustrano il flusso di esecuzione delle classi implementate.

Il primo sequence diagram per AttributesAugmentor.augment() prevede i seguenti attori.

Client : il sistema o servizio che invoca la classe per l’operazione di autenticazione.
AttributesAugmentor : la classe principale che manipola il SecurityIdentity e ne arricchisce gli attributi con informazioni dal certificato.
CertificateCredential : un oggetto che contiene il certificato X.509 dal quale vengono estratti gli attributi.
SecurityIdentity : l’identità di sicurezza che viene aumentata con nuovi attributi.
QuarkusSecurityIdentity.Builder : il costruttore utilizzato per modificare e creare una nuova istanza di SecurityIdentity arricchita.
CertificateUtil : utility che decodifica il valore del certificato.
X509Certificate : il certificato dal quale viene estratto l’ID del dispositivo.

sequenceDiagram participant Client participant AttributesAugmentor participant SecurityIdentity participant CertificateCredential participant X509Certificate participant CertificateUtil participant QuarkusSecurityIdentityBuilder as QuarkusSecurityIdentity.Builder Client->>AttributesAugmentor: augment(identity, context) AttributesAugmentor->>SecurityIdentity: getCredential(CertificateCredential) SecurityIdentity-->>AttributesAugmentor: CertificateCredential AttributesAugmentor->>CertificateCredential: getCertificate() CertificateCredential-->>AttributesAugmentor: X509Certificate alt Certificate is null AttributesAugmentor-->>Client: SecurityIdentity (no augmentation) else Certificate is present AttributesAugmentor->>AttributesAugmentor: extractAttributesFromCertificate(X509Certificate) AttributesAugmentor->>X509Certificate: getExtensionValue(OID_DEVICE_ID) alt OID not found AttributesAugmentor-->>Client: SecurityIdentity (no augmentation) else OID found X509Certificate-->>AttributesAugmentor: byte[] AttributesAugmentor->>CertificateUtil: decodeExtensionValue(byte[]) CertificateUtil-->>AttributesAugmentor: deviceId alt deviceId is null AttributesAugmentor-->>Client: SecurityIdentity (no augmentation) else deviceId is valid AttributesAugmentor->>QuarkusSecurityIdentityBuilder: addAttribute("deviceId", deviceId) end end AttributesAugmentor->>QuarkusSecurityIdentityBuilder: build() QuarkusSecurityIdentityBuilder-->>AttributesAugmentor: SecurityIdentity AttributesAugmentor-->>Client: SecurityIdentity end opt Error during extraction AttributesAugmentor->>AttributesAugmentor: throw SecurityException AttributesAugmentor-->>Client: SecurityException end

Figura 6 - Sequence Diagram del flusso di esecuzione di AttributesAugmentor.augment().

Il secondo sequence diagram per RolesAugmentor.augment() prevede gli stessi attori del diagramma precedente con RolesAugmentor al posto di AttributesAugmentor che manipola il SecurityIdentity e ne arricchisce i ruoli con informazioni dal certificato.

sequenceDiagram participant Client participant RolesAugmentor participant SecurityIdentity participant CertificateCredential participant X509Certificate participant CertificateUtil participant QuarkusSecurityIdentityBuilder as QuarkusSecurityIdentity.Builder Client->>RolesAugmentor: augment(identity, context) RolesAugmentor->>SecurityIdentity: getCredential(CertificateCredential) SecurityIdentity-->>RolesAugmentor: CertificateCredential RolesAugmentor->>CertificateCredential: getCertificate() CertificateCredential-->>RolesAugmentor: X509Certificate alt Certificate is null RolesAugmentor-->>Client: SecurityIdentity (no augmentation) else Certificate is present RolesAugmentor->>RolesAugmentor: extractRolesFromCertificate(X509Certificate) RolesAugmentor->>X509Certificate: getExtensionValue(OID_ROLES) alt OID not found RolesAugmentor-->>Client: SecurityIdentity (no augmentation) else OID found X509Certificate-->>RolesAugmentor: byte[] RolesAugmentor->>CertificateUtil: decodeExtensionValue(byte[]) CertificateUtil-->>RolesAugmentor: decodedRoles alt decodedRoles is null RolesAugmentor-->>Client: SecurityIdentity (no augmentation) else decodedRoles matches pattern RolesAugmentor->>RolesAugmentor: Add roles to set RolesAugmentor->>QuarkusSecurityIdentityBuilder: addRoles(extracted roles) else decodedRoles does not match pattern RolesAugmentor->>RolesAugmentor: throw SecurityException RolesAugmentor-->>Client: SecurityException end end RolesAugmentor->>QuarkusSecurityIdentityBuilder: build() QuarkusSecurityIdentityBuilder-->>RolesAugmentor: SecurityIdentity RolesAugmentor-->>Client: SecurityIdentity end opt Error during extraction RolesAugmentor->>RolesAugmentor: throw SecurityException RolesAugmentor-->>Client: SecurityException end

Figura 7 - Sequence Diagrama del flusso di esecuzione di RolesAugmentor.augment().

Il terzo diagramma di sequenza relativo a OidSecurityIdentityAugmentor.augment() evidenzia che, in questo caso, il componente non agisce direttamente su SecurityIdentity, ma si limita a verificare che il valore dell’OID che identifica il DeviceId sia presente e valido secondo l’algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId.

sequenceDiagram participant Client participant OidSecurityIdentityAugmentor participant SecurityIdentity participant CertificateCredential participant X509Certificate participant CertificateUtil participant DeviceIdUtil Client->>OidSecurityIdentityAugmentor: augment(identity, context) OidSecurityIdentityAugmentor->>SecurityIdentity: getCredential(CertificateCredential) SecurityIdentity-->>OidSecurityIdentityAugmentor: CertificateCredential alt CertificateCredential is null OidSecurityIdentityAugmentor-->>Client: throw SecurityException("Client certificate not found") else CertificateCredential is present OidSecurityIdentityAugmentor->>CertificateCredential: getCertificate() CertificateCredential-->>OidSecurityIdentityAugmentor: X509Certificate OidSecurityIdentityAugmentor->>X509Certificate: getExtensionValue(AttributesAugmentor.OID_DEVICE_ID) alt OID is null OidSecurityIdentityAugmentor-->>Client: throw SecurityException("Invalid certificate OID missing for DeviceId") else OID is present X509Certificate-->>OidSecurityIdentityAugmentor: oidValueFromCert OidSecurityIdentityAugmentor->>CertificateUtil: decodeExtensionValue(oidValueFromCert) CertificateUtil-->>OidSecurityIdentityAugmentor: decoded OID value OidSecurityIdentityAugmentor->>OidSecurityIdentityAugmentor: remove OID prefix and trim value OidSecurityIdentityAugmentor->>DeviceIdUtil: verifyDeviceId(oidValue) alt DeviceId is not valid DeviceIdUtil-->>OidSecurityIdentityAugmentor: false OidSecurityIdentityAugmentor-->>Client: throw SecurityException("Invalid certificate OID value") else DeviceId is valid DeviceIdUtil-->>OidSecurityIdentityAugmentor: true OidSecurityIdentityAugmentor-->>Client: return identity end end end

Figura 8 - Sequence Diagram del flusso di esecuzione di OidSecurityIdentityAugmentor.augment().

Nel nostro caso, abbiamo registrato più di una SecurityIdentityAugmentor personalizzata nell’applicazione Quarkus. Queste saranno considerate paritetiche e invocate in ordine casuale. Tuttavia, è possibile imporre un ordine implementando il metodo SecurityIdentityAugmentor#priority. Gli Augmentor con priorità più alta saranno invocati per primi.

Nella classe OidSecurityIdentityAugmentor abbiamo implementato il metodo di priorità impostando un valore intero pari a dieci, per garantire che il controllo sull’OID del DeviceId sia eseguito prima degli altri. In caso di errore, sarà lanciata un’eccezione SecurityException e l’autenticazione fallirà (vedi sequence diagram di figura 8).

Nota : i SecurityIdentityAugmentor in Quarkus sono a livello globale, ma è possibile configurarli in modo condizionale o personalizzato in base a specifiche esigenze, anche se non esiste una configurazione diretta per attivarli basandosi esclusivamente sul nome di una configurazione TLS.

Step 8 - Implementazione dei servizi REST

Il tag di riferimento per questo step è tutorial-step-8-impl-rest-services.

L’impostazione dell’autenticazione mTLS è stata completata con successo. Ora possiamo procedere con la realizzazione dei servizi REST che utilizzeranno tale autenticazione. A tal fine, creeremo i servizi REST definiti nel secondo requisito, descritto nella tabella 1 del capitolo Requisiti dell’applicazione Quarkus.

I servizi REST che andremo a realizzare troveranno spazio all'interno del package it.dontesta.quarkus.tls.auth.ws.resources.endpoint.v1 e saranno implementati dalla classe ConnectionInfoResourceEndPoint.

La classe ConnectionInfoResourceEndPoint implementerà i seguenti metodi:

@GET /v1/connection-info/info: metodo che restituirà le informazioni di connessione del client;
@GET /v1/connection-info/user-identity: metodo che restituirà le informazioni circa l'identità del client che ha effettuato la richiesta.

Le risposte dei metodi saranno in formato JSON e conterranno le informazioni richieste e conformi agli schemi JSON definiti nel capitolo Struttura JSON di risposta dei servizi Rest.

Il sequence diagram mostra il flusso di esecuzione del metodo ConnectionInfoResourceEndPoint.getConnectionInfo(). Gli attori coinvolti nel diagramma sono:

Client : il sistema o servizio che invoca il metodo getConnectionInfo() sull'endpoint ConnectionInfoResourceEndPoint.
ConnectionInfoResourceEndPoint : la classe che gestisce la richiesta del client e costruisce l'oggetto connectionInfo.
RoutingContext : contesto di routing che fornisce informazioni sulla richiesta HTTP.
HttpServerRequest : rappresenta la richiesta HTTP ricevuta dal server.
SSLSession : rappresenta la sessione TLS/SSL, utilizzata per ottenere informazioni di sicurezza aggiuntive se la connessione è sicura.

Questi attori collaborano per ottenere e restituire le informazioni di connessione in risposta alla richiesta del client.

sequenceDiagram participant Client participant ConnectionInfoResourceEndPoint participant RoutingContext participant HttpServerRequest participant SSLSession Client->>ConnectionInfoResourceEndPoint: GET /v1/connection-info/info ConnectionInfoResourceEndPoint->>RoutingContext: @context RoutingContext RoutingContext-->>ConnectionInfoResourceEndPoint: routingContext ConnectionInfoResourceEndPoint->>HttpServerRequest: request() HttpServerRequest-->>ConnectionInfoResourceEndPoint: HttpServerRequest ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Create connectionInfo map ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Add basic connection details ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Add client address and port information alt request.isSSL() is true ConnectionInfoResourceEndPoint->>HttpServerRequest: sslSession() HttpServerRequest-->>ConnectionInfoResourceEndPoint: SSLSession alt sslSession is not null ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Add SSL-specific details ConnectionInfoResourceEndPoint->>SSLSession: getProtocol() SSLSession-->>ConnectionInfoResourceEndPoint: protocol ConnectionInfoResourceEndPoint->>SSLSession: getCipherSuite() SSLSession-->>ConnectionInfoResourceEndPoint: cipherSuite ConnectionInfoResourceEndPoint->>SSLSession: getLocalCertificates() SSLSession-->>ConnectionInfoResourceEndPoint: serverCerts ConnectionInfoResourceEndPoint->>SSLSession: getPeerCertificates() SSLSession-->>ConnectionInfoResourceEndPoint: clientCerts end end ConnectionInfoResourceEndPoint-->>Client: Response.ok(connectionInfo).build()

Figura 9 - Sequence Diagram del flusso di esecuzione di ConnectionInfoResourceEndPoint.info().

Il sequence diagram mostra il flusso di esecuzione del metodo ConnectionInfoResourceEndPoint.getUserIdentity(). Gli attori coinvolti nel diagramma sono:

Client : il sistema o servizio che invoca il metodo getUserIdentity() sull'endpoint ConnectionInfoResourceEndPoint.
ConnectionInfoResourceEndPoint : la classe che gestisce la richiesta del client e costruisce l'oggetto securityIdentityInfo.
SecurityIdentity : l'identità di sicurezza che contiene le informazioni dell'utente autenticato.
CertificateCredential : un oggetto che contiene il certificato X.509 dal quale vengono estratti gli attributi.
X509Certificate : il certificato dal quale vengono estratti gli attributi.

Questi attori collaborano per ottenere e restituire le informazioni di identità dell'utente in risposta alla richiesta del client.

sequenceDiagram participant Client participant ConnectionInfoResourceEndPoint participant SecurityIdentity participant CertificateCredential participant X509Certificate Client->>ConnectionInfoResourceEndPoint: GET /v1/connection-info/user-identity ConnectionInfoResourceEndPoint->>SecurityIdentity: @context SecurityIdentity SecurityIdentity-->>ConnectionInfoResourceEndPoint: securityIdentity ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Create securityIdentityInfo map ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Add principal, roles, and attributes ConnectionInfoResourceEndPoint->>SecurityIdentity: getCredential(CertificateCredential.class) SecurityIdentity-->>ConnectionInfoResourceEndPoint: CertificateCredential ConnectionInfoResourceEndPoint->>CertificateCredential: getCertificate() CertificateCredential-->>ConnectionInfoResourceEndPoint: X509Certificate ConnectionInfoResourceEndPoint->>X509Certificate: getCommonName() X509Certificate-->>ConnectionInfoResourceEndPoint: userCN ConnectionInfoResourceEndPoint->>ConnectionInfoResourceEndPoint: Add userCN to securityIdentityInfo ConnectionInfoResourceEndPoint-->>Client: Response.ok(securityIdentityInfo).build()

Figura 10 - Sequence Diagram del flusso di esecuzione di ConnectionInfoResourceEndPoint.getUserIdentity().

Step 9 - Configurazione delle policy di accesso ai servizi REST

Il tag di riferimento per questo step è tutorial-step-9-config-rest-services.

Ora che abbiamo implementato i servizi REST, possiamo procedere con la configurazione delle policy di accesso. A tal fine, creeremo le policy di accesso ai servizi REST definite nel terzo requisito e descritto nella tabella 1 del capitolo Requisiti dell’applicazione Quarkus.

Configurare le policy di accesso significa definire quali ruoli possono accedere ai servizi REST. Nel nostro caso, i ruoli sono due: Administartor e User. Questa configurazione può essere effettuata modificando il file application.properties aggiungendo le proprietà indicate di seguito.

Tramite la configurazione abbiamo definito:

un set di permessi certauthenticated che
1. si applicano alle risorse REST di tipo JAX-RS;
2. si applicano ai metodi GET e POST;
3. si applicano ai servizi REST /api/v1/connection-info/*;
4. utilizzano la policy role-policy-cert per il controllo degli accessi;
la policy role-policy-cert che
1. definisce i ruoli User e Administrator che possono accedere ai servizi REST.

#
# Section to configure the server for the role-based access control mechanism.
# For more information see Mapping certificate attributes to roles in Quarkus
# https://quarkus.io/guides/security-authentication-mechanisms#map-certificate-attributes-to-roles
# In this case using the `RolesAugmentor` class to map the certificate attributes to roles.
# The custom role as an extension in the client certificate is identified by the custom OID 1.3.6.1.4.1.99999.1
#

# Whether permission check should be applied on all matching paths, or paths specific for the Jakarta REST resources.
quarkus.http.auth.permission.certauthenticated.applies-to=jaxrs

# The methods that this permission set applies to.
quarkus.http.auth.permission.certauthenticated.methods=GET,POST

# The paths that this permission set applies to.
quarkus.http.auth.permission.certauthenticated.paths=/api/v1/connection-info/*

# The policy to use for the permission check.
quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert

# The roles allowed to access the resource.
quarkus.http.auth.policy.role-policy-cert.roles-allowed=User,Administrator

Bash

Application Properties 3 - Configurazione delle policy di accesso ai servizi REST

Adesso che abbiamo configurato le policy di accesso ai servizi REST, potremo procedere con il test dell’applicazione Quarkus con lo scopo di verificare che l’autenticazione mTLS funzioni correttamente e che le policy di accesso siano rispettate.

Step 10 - Generazione di un set di certificati client per eseguire dei test di accesso

Il tag di riferimento per questo step è tutorial-step-10-generate-client-certificates.

Prima di procedere con i test dei servizi REST, dobbiamo generare un set di certificati client. Questi certificati saranno utilizzati per testare l’autenticazione mTLS e le policy di accesso ai servizi REST.

Per generare i certificati client, possiamo utilizzare lo script certs-manager.sh, già impiegato per generare il certificato della CA e quello del server. Ricordiamo che lo script si trova nel percorso src/main/shell/certs-manager, mentre i certificati generati finora sono conservati nella directory src/main/resources/certs.

Andremo a generare un set di certificati client con le seguenti caratteristiche:

un certificato client senza estensioni personalizzate;
un certificato client con l'estensione personalizzata DeviceId e il valore 1234567890;
un certificato client con l'estensione personalizzata DeviceId con il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles e il valore 123User;
un certificato client con l'estensione personalizzata DeviceId con il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles e il valore ProjectManager;
un certificato client con l'estensione personalizzata DeviceId con il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles e il valore User,Administrator.

Ricordiamo che i certificati client generati saranno firmati dalla Certificate Authority (CA) che abbiamo creato in precedenza. Il certificato di CA è stato inoltre importato nel truststore dell'applicazione Quarkus per poter verificare la validità dei certificati client attraverso la proprietà quarkus.tls.https.trust-store.pem.certs valorizzata con il valore certs/ca_cert.pem.

Procediamo quindi con la generazione dei certificati client eseguendo lo script certs-manager.sh come indicato a seguire.

# Generate a client certificate without custom extensions
./src/main/shell/certs-manager/certs_manager.sh generate-client --working-dir src/main/resources/certs \
    --private-key-file client_without_custom_ext_key.pem \
    --csr-file client_without_custom_ext_csr.pem \
    --client-cert-file client_without_custom_ext_cert.pem \
    --validity-days 365 \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --country IT \
    --state Italy \
    --locality Rome \
    --organization "Mario Rossi Corporation" \
    --organizational-unit "Community & News" \
    --common-name "D54FF113-A0C4-4A67-A6DE-B8DEE24A5095" \
    --extensions-file src/main/shell/certs-manager/ssl_extensions_without_custom.cnf \
    --output-p12-file client_without_custom_ext_cert.p12

Bash

Console 13 - Generazione di un certificato client senza estensioni personalizzate

# Generate a client certificate with custom extension DeviceId and value 1234567890
./src/main/shell/certs-manager/certs_manager.sh generate-client --working-dir src/main/resources/certs \
    --private-key-file client_with_bad_device_id_key.pem \
    --csr-file client_with_bad_device_id_csr.pem \
    --client-cert-file client_with_bad_device_id_cert.pem \
    --validity-days 365 \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --country IT \
    --state Italy \
    --locality Rome \
    --organization "Antonella Bianchi Corporation" \
    --organizational-unit "Community & News" \
    --common-name "438D4FFD-0082-4189-8659-012692868913" \
    --extensions-file src/main/shell/certs-manager/ssl_extensions.cnf \
    --ext-cert-device-id 1234567890 \
    --output-p12-file client_with_bad_device_id_cert.p12

Bash

Console 14 - Generazione di un certificato client con estensione personalizzata DeviceId e valore 1234567890

# Generate a client certificate with custom extension DeviceId with the correct value generated by the algorithm described in the chapter "Algorithm for generating the DeviceId" and the custom extension Roles and the value 123User
./src/main/shell/certs-manager/certs_manager.sh generate-client --working-dir src/main/resources/certs \
    --private-key-file client_with_device_id_and_bad_roles_key.pem \
    --csr-file client_with_device_id_and_bad_roles_csr.pem \
    --client-cert-file client_with_device_id_and_bad_roles_cert.pem \
    --validity-days 365 \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --country IT \
    --state Italy \
    --locality Rome \
    --organization "Andrea Valdasso Corporation" \
    --organizational-unit "Community & News" \
    --common-name "B7422CD0-DDCC-435F-843C-11649C987256" \
    --extensions-file src/main/shell/certs-manager/ssl_extensions.cnf \
    --ext-cert-role 123User \
    --ext-cert-device-id "$(./src/main/shell/certs-manager/generate_device_id.sh generate true)" \
    --output-p12-file client_with_bad_device_id_and_bad_roles_cert.p12

Bash

Console 15 - Generazione di un certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore 123User

# Generate a client certificate with custom extension DeviceId with the correct value generated by the algorithm described in the chapter "Algorithm for generating the DeviceId" and the custom extension Roles and the value ProjectManager
./src/main/shell/certs-manager/certs_manager.sh generate-client --working-dir src/main/resources/certs \
    --private-key-file client_with_device_id_and_roles_key.pem \
    --csr-file client_with_device_id_and_roles_csr.pem \
    --client-cert-file client_with_device_id_and_roles_cert.pem \
    --validity-days 365 \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --country IT \
    --state Italy \
    --locality Rome \
    --organization "Marco Visco Corporation" \
    --organizational-unit "Community & News" \
    --common-name "3C266B12-8400-40DC-891B-CB52BB84CD86" \
    --extensions-file src/main/shell/certs-manager/ssl_extensions.cnf \
    --ext-cert-role ProjectManager \
    --ext-cert-device-id "$(./src/main/shell/certs-manager/generate_device_id.sh generate true)" \
    --output-p12-file client_with_device_id_and_roles_cert.p12

Bash

Console 16 - Generazione di un certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore ProjectManager

# Generate a client certificate with custom extension DeviceId with the correct value generated by the algorithm described in the chapter "Algorithm for generating the DeviceId" and the custom extension Roles and the value User,Administrator
./src/main/shell/certs-manager/certs_manager.sh generate-client --working-dir src/main/resources/certs \
    --private-key-file client_with_device_id_and_roles_1_key.pem \
    --csr-file client_with_device_id_and_roles_1_csr.pem \
    --client-cert-file client_with_device_id_and_roles_1_cert.pem \
    --validity-days 365 \
    --ca-cert-file ca_cert.pem \
    --ca-key-file ca_private_key.pem \
    --ca-key-password "$(cat src/main/resources/certs/ca_private_key.pem.password)" \
    --country IT \
    --state Italy \
    --locality Rome \
    --organization "Massimo Visco Corporation" \
    --organizational-unit "Community & News" \
    --common-name "7BF80D48-B92C-45EB-80F0-363D1CCA6E4C" \
    --extensions-file src/main/shell/certs-manager/ssl_extensions.cnf \
    --ext-cert-role User,Administrator \
    --ext-cert-device-id "$(./src/main/shell/certs-manager/generate_device_id.sh generate true)" \
    --output-p12-file client_with_device_id_and_roles_1_cert.p12

Bash

Console 17 - Generazione di un certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore User,Administrator

Come possiamo vedere dagli script sopra riportati, abbiamo generato cinque certificati client con le caratteristiche descritte in precedenza. I certificati client generati sono stati salvati all'interno della directory src/main/resources/certs e la tabella 3 mostra un riepilogo dei certificati client generati.

ID	Subject	Issuer	DeviceId	Roles	File p12	Password .p12	Password private key (PEM)
1	C=IT, ST=Italy, L=Rome, O=Mario Rossi Corporation, OU=Community & News, CN=D54FF113-A0C4-4A67-A6DE-B8DEE24A5095	Dontesta CA			client_without_custom_ext_cert.p12	5byk65SNHEIwfv3s	K3K8onVbmB2ACXdu
2	C=IT, ST=Italy, L=Rome, O=Antonella Bianchi Corporation, OU=Community & News, CN=438D4FFD-0082-4189-8659-012692868913	Dontesta CA	1234567890		client_with_bad_device_id_cert.p12	HQeQYfBkq2cf8AjL	DDSO642Dq2o+U1cF
3	C=IT, ST=Italy, L=Rome, O=Andrea Valdasso Corporation, OU=Community & News, CN=B7422CD0-DDCC-435F-843C-11649C987256	Dontesta CA		123User	client_with_device_id_and_bad_roles_cert.p12	7Rb1laR7WOdqcZk+	1JKARpPJ7wCnX4Ju
4	C=IT, ST=Italy, L=Rome, O=Marco Visco Corporation, OU=Community & News, CN=3C266B12-8400-40DC-891B-CB52BB84CD86	Dontesta CA		ProjectManager	client_with_device_id_and_roles_cert.p12	HA5b7g0Cy3bI/+1/	AeqFJRRA2wqnG0Nf
5	C=IT, ST=Italy, L=Rome, O=Massimo Visco Corporation, OU=Community & News, CN=7BF80D48-B92C-45EB-80F0-363D1CCA6E4C	Dontesta CA		User
Administrator	client_with_device_id_and_roles_1_cert.p12	uWTNwBluEXGszPYv	55MoxEiH1B/r5Muz

Tabella 3 - Certificati client generati per i test di accesso

Il valore del DeviceId è stato generato utilizzando lo script generate_device_id.sh e il valore è stato codificato in Base64. Il valore del DeviceId è stato inserito nel certificato client come estensione personalizzata DeviceId. A seguire un esempio dell'output dello script generate_device_id.sh.

# Generate a DeviceId
./src/main/shell/certs-manager/generate_device_id.sh generate true

# Output
MTcyNjM1NTMzNTQyMzYxNzAwMCMyYzBlMzY4ZS1lMDU5LTQ5OWQtYjFjNS0zNGU4MjdiYmE0MTIjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjNmNlZDI3YTI5ODUyMDJiNjhiOTA2YjQ3YTQzM2QyOGNkYTFmN2JkMjMxNzMzNTUxNmIzNmVlYTViMTc0MTdlOA==

Bash

Console 18 - Esempio di output dello script generate_device_id.sh per la generazione del DeviceId

Step 11 - Test della configurazione mTLS

Il tag di riferimento per questo step è tutorial-step-11-test-mtls-config.

Adesso che abbiamo generato i certificati client, possiamo procedere con il test dell'applicazione Quarkus per verificare che l'autenticazione mTLS funzioni correttamente e che le policy di accesso ai servizi REST siano rispettate.

Prima di proseguire con la serie di test, dobbiamo applicare una configurazione obbligatoria, ovvero, la secret key necessaria per la decodifica e verifica del DeviceId. La proprietà da aggiungere al file di configurazione application.properties è indicata a seguire.

# Setting the secret key for verifying the device ID extracted from the client certificate.
# The secret key is stored in the `application.properties` file. In a production environment,
# it is recommended to use a secure password storage mechanism.
client.cert.device.id.secret-key=my_secret_key_for_generate_device_id

Bash

Application Properties 4 - Configurazione della secret key per la verifica del DeviceId

La verifica del DeviceId è un passaggio obbligatorio per l’autenticazione mTLS. Il DeviceId è un identificativo univoco generato e inserito nel certificato client durante la sua creazione. Questo valore viene prodotto tramite un algoritmo specifico e successivamente decodificato e verificato dall’applicazione Quarkus per garantire l’autenticazione mTLS.

La verifica è implementata all'interno della classe DeviceIdUtil attraverso il metodo verifyDeviceId e l'algoritmo per la generazione del DeviceId è descritto nel capitolo Algoritmo per la generazione del DeviceId.

Durante la fase di test, potrebbe risultare utile avere il log di debug dei componenti di SecurityAugmentor per verificare che l'autenticazione mTLS funzioni correttamente. Per fare ciò, possiamo aggiungere le seguenti proprietà al file di configurazione application.properties.

# Logging configuration
quarkus.log.category."it.dontesta.quarkus.tls.auth.ws.security.identity.RolesAugmentor".level=DEBUG
quarkus.log.category."it.dontesta.quarkus.tls.auth.ws.security.identity.AttributesAugmentor".level=DEBUG
quarkus.log.category."it.dontesta.quarkus.tls.auth.ws.security.identity.OidSecurityIdentityAugmentor".level=DEBUG

Bash

Application Properties 5 - Configurazione del log di debug

Adesso possiamo procedere con il test dell'applicazione Quarkus. Per fare ciò, eseguiremo i seguenti passaggi:

avviare l'applicazione Quarkus;
eseguire i test di accesso ai servizi REST utilizzando i certificati client generati verificando che l'autenticazione mTLS funzioni correttamente, che le policy di accesso ai servizi REST siano rispettate e che le risposte dei servizi REST siano conformi agli schemi JSON definiti nel capitolo Struttura JSON di risposta dei servizi Rest.

Per avviare l'applicazione basta eseguire il comando quarkus:dev e se non ci sono errori, l'applicazione Quarkus sarà pronta per i test e dovremmo vedere un output simile a quello riportato di seguito.


          ,--------.,--. ,---. ,---.
,--,--,--.'--. .--'| | ' .-' ,-----. / O \ ,---. ,---.
| | | | | | `. `-. '-----' | .-. || .-. || .-. |
| | | | | | | '--..-' | | | | || '-' '| '-' '
`--`--`--' `--' `-----'`-----' `--' `--'| |-' | |-'
                                                     `--' `--'
Developed by: Antonio Musarra
Blog: https://www.dontesta.it
GitHub: https://github.com/amusarra
LinkedIn: https://www.linkedin.com/in/amusarra
Twitter: https://twitter.com/antonio_musarra

                                          Powered by Quarkus 3.14.3
2024-09-13 16:18:54,102 INFO [io.quarkus] (Quarkus Main Thread) tls-mutual-auth 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.14.3) started in 1.436s. Listening on: https://localhost:8443

2024-09-13 16:18:54,103 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2024-09-13 16:18:54,104 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, rest, rest-jackson, security, smallrye-context-propagation, vertx]

--
Tests paused
Press [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [:] for the terminal, [h] for more options>

Bash

Console 18 - Avvio dell'applicazione Quarkus

Avviata l'applicazione, possiamo preparare un set di richieste HTTP verso i due endpoint REST che abbiamo implementato. Per fare ciò, possiamo utilizzare un tool come curl o Postman. In questo esempio, utilizzeremo curl per inviare le richieste HTTP. In pipe (|) al comando curl è stato incluso l'utilizzo del tool jq che ci permette di ottenere un output più leggibile (in formato JSON) dei risultati delle richieste HTTP. Non è obbligatorio, ma è consigliabile installare il tool jq per poter leggere meglio l'output dei comandi.

Tenendo davanti a noi la tabella 2 con i certificati client generati (in formato PKCS#12), potremo procedere con i test di accesso ai servizi REST, verificando che l'output sia quello atteso. Ricordiamo che l'output dipenderà dal certificato client utilizzato per l'accesso ai servizi REST.

# Execute the request to the /api/v1/connection-info/info endpoint using the client certificate without custom extensions
curl -s \
    --cert src/main/resources/certs/client_without_custom_ext_cert.p12:5byk65SNHEIwfv3s \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/info | jq

# Output
{
  "statusCode": 401,
  "message": "Invalid certificate OID { 1.3.6.1.4.1.99999.2 } missing for DeviceId."
}

# Execute the request to the /api/v1/connection-info/user-identity endpoint using the client certificate without custom extensions
curl -s \
    --cert src/main/resources/certs/client_without_custom_ext_cert.p12:5byk65SNHEIwfv3s \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/user-identity | jq

# Output
{
  "statusCode": 401,
  "message": "Invalid certificate OID { 1.3.6.1.4.1.99999.2 } missing for DeviceId."
}

Bash

Console 19 - Esecuzione del test di accesso ai servizi REST con il certificato client senza estensioni personalizzate

L'output dei test di accesso ai servizi REST con il certificato client senza estensioni personalizzate mostra che l'autenticazione mTLS è fallita così come ci aspettavamo, in virtù del fatto che il certificato client non contiene l'estensione personalizzata DeviceId necessaria per l'autenticazione mTLS. In questo caso è intervenuta è la classe OidSecurityIdentityAugmentor che ha la priorità più alta rispetto alle altre e che ha lanciato l'eccezione SecurityException perché l'OID del DeviceId non è stato trovato.

Proseguiamo il test con il certificato client con l'estensione personalizzata DeviceId e il valore 1234567890.

# Execute the request to the /api/v1/connection-info/info endpoint using the client certificate with custom extension DeviceId and value 1234567890
curl -s \
    --cert src/main/resources/certs/client_with_bad_device_id_cert.p12:HQeQYfBkq2cf8AjL \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/info | jq

# Output
{
  "statusCode": 401,
  "message": "Invalid certificate OID value { 1234567890 } or OID { 1.3.6.1.4.1.99999.2 } missing for DeviceId."
}

# Execute the request to the /api/v1/connection-info/user-identity endpoint using the client certificate with custom extension DeviceId and value 1234567890
curl -s \
    --cert src/main/resources/certs/client_with_bad_device_id_cert.p12:HQeQYfBkq2cf8AjL \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/user-identity | jq

# Output
{
  "statusCode": 401,
  "message": "Invalid certificate OID value { 1234567890 } or OID { 1.3.6.1.4.1.99999.2 } missing for DeviceId."
}

Bash

Console 20 - Esecuzione del test di accesso ai servizi REST con il certificato client con estensione personalizzata DeviceId e valore 1234567890

Anche in questo caso l'esito del test è quello atteso, con la differenza che il messaggio di errore è leggermente diverso: l'OID del DeviceId è stato trovato ma il valore non è valido. In questo caso il blocco di codice che ha lanciato l'eccezione è quello che verifica il valore del DeviceId, cosi come mostrato a seguire (dalla classe OidSecurityIdentityAugmentor).

      if (!DeviceIdUtil.verifyDeviceId(oidValue)) {
        throw new SecurityException(
            "Invalid certificate OID value { %s } or OID { %s } missing for DeviceId.".formatted(
                oidValue, AttributesAugmentor.OID_DEVICE_ID));
      }

Java

Source Code 6 - Blocco di codice che verifica il valore del DeviceId

Continuiamo il test con il certificato client con l'estensione personalizzata DeviceId che ha il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles con il valore 123User.

# Execute the request to the /api/v1/connection-info/info endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value 123User
curl -s \
    --cert src/main/resources/certs/client_with_device_id_and_bad_roles_cert.p12:7Rb1laR7WOdqcZk+ \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/info | jq

# Output
{
  "statusCode": 401,
  "message": "Decoded roles do not match the expected pattern: Role=123User"
}

# Execute the request to the /api/v1/connection-info/user-identity endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value 123User
curl -s \
    --cert src/main/resources/certs/client_with_device_id_and_bad_roles_cert.p12:7Rb1laR7WOdqcZk+ \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/user-identity | jq

# Output
{
  "statusCode": 401,
  "message": "Decoded roles do not match the expected pattern: Role=123User"
}

Bash

Console 21 - Esecuzione del test di accesso ai servizi REST con il certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore 123User

Anche in questo caso l'esito del test è quello atteso, con la differenza che il messaggio di errore è leggermente diverso: Decoded roles do not match the expected pattern: Role=123User. In questo caso il blocco di codice che ha lanciato l'eccezione è quello che verifica il pattern dei ruoli, cosi come mostrato a seguire (dalla classe RolesAugmentor).

        if (decodedRoles != null) {
          log.debug("Decoded roles from certificate: %s".formatted(decodedRoles));

          // Verify that decodedRoles matches the expected pattern
          if (decodedRoles.matches("^Role=([A-Za-z]+(?:,[A-Za-z]+)*+)$")) {
            // Add the roles to the set
            roles.addAll(Arrays.stream(decodedRoles.split("=")[1].split(","))
                .map(String::trim)
                .collect(Collectors.toSet()));
          } else {
            log.warn("Decoded roles do not match the expected pattern: %s".formatted(decodedRoles));

            throw new SecurityException(
                "Decoded roles do not match the expected pattern: %s".formatted(decodedRoles));
          }
        }

Java

Source Code 7 - Blocco di codice che verifica il pattern dei ruoli

Sulla console di Quarkus dovremmo vedere un output simile a quello riportato di seguito.

2024-09-13 17:07:57,107 DEBUG [it.don.qua.tls.aut.ws.sec.ide.RolesAugmentor] (vert.x-eventloop-thread-0) Augmenting SecurityIdentity with roles extracted from certificate with OID: 1.3.6.1.4.1.99999.1
2024-09-13 17:07:57,109 DEBUG [it.don.qua.tls.aut.ws.sec.ide.RolesAugmentor] (vert.x-eventloop-thread-0) Decoded roles from certificate: Role=123User
2024-09-13 17:07:57,109 WARN [it.don.qua.tls.aut.ws.sec.ide.RolesAugmentor] (vert.x-eventloop-thread-0) Decoded roles do not match the expected pattern: Role=123User
2024-09-13 17:07:57,109 ERROR [it.don.qua.tls.aut.ws.sec.ide.RolesAugmentor] (vert.x-eventloop-thread-0) Occurred an error during roles extraction from certificate

Plaintext

Console 22 - Log di debug per la verifica del pattern dei ruoli

Andiamo avanti con il test utilizzando il certificato client con l'estensione personalizzata DeviceId che ha il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles con il valore ProjectManager.

# Execute the request to the /api/v1/connection-info/info endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value ProjectManager
curl -i \
    --cert src/main/resources/certs/client_with_device_id_and_roles_cert.p12:HA5b7g0Cy3bI/+1/ \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/info

# Output
HTTP/2 403
content-length: 0

# Execute the request to the /api/v1/connection-info/user-identity endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value ProjectManager
curl -i \
    --cert src/main/resources/certs/client_with_device_id_and_roles_cert.p12:HA5b7g0Cy3bI/+1/ \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/user-identity

# Output
HTTP/2 403
content-length: 0

Bash

Console 22 - Esecuzione del test di accesso ai servizi REST con il certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore ProjectManager

Anche in questo caso l'esito del test è quello atteso. L'accesso ai servizi REST è stato negato in quanto il ruolo ProjectManager non è presente tra i ruoli consentiti, infatti la policy di accesso che abbiamo definito sulla proprietà quarkus.http.auth.policy.role-policy-cert.roles-allowed prevede solo i ruoli User e Administrator.

Infine, proseguiamo il test con il certificato client che possiede l'estensione personalizzata DeviceId che ha il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles con il valore User,Administrator.

# Execute the request to the /api/v1/connection-info/info endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value User,Administrator
curl -s \
    --cert src/main/resources/certs/client_with_device_id_and_roles_1_cert.p12:uWTNwBluEXGszPYv \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/info | jq

# Output
{
  "httpRequestHeaders": {
    "user-agent": "curl/8.7.1",
    "accept": "*/*"
  },
  "server": {
    "notAfter": "Fri Sep 12 18:13:44 CEST 2025",
    "keyAlgorithm": "RSA",
    "keySize": 2048,
    "certCommonName": "rd.quarkus.dontesta.it",
    "certIssuer": "CN=Dontesta CA,OU=IT Labs,O=Dontesta,L=Bronte,ST=Catania,C=IT",
    "subjectAlternativeNames": [
      [
        2,
        "admin.quarkus.dontesta.it"
      ],
      [
        2,
        "blog.quarkus.dontesta.it"
      ],
      [
        2,
        "localhost"
      ]
    ],
    "certSubject": "CN=rd.quarkus.dontesta.it,OU=IT Labs,O=Dontesta,L=Bronte (CT),ST=Italy,C=IT",
    "certSerialNumber": "376693016274162034819659983838224914643739644606",
    "certPEM": "<removed>",
    "customExtensions": {},
    "notBefore": "Thu Sep 12 18:13:44 CEST 2024"
  },
  "protocol": "TLSv1.3",
  "httpProtocol": "HTTP_2",
  "clientPort": 64218,
  "isSecure": true,
  "client": {
    "notAfter": "Sat Sep 13 15:03:16 CEST 2025",
    "keyAlgorithm": "RSA",
    "keySize": 2048,
    "certCommonName": "7BF80D48-B92C-45EB-80F0-363D1CCA6E4C",
    "certIssuer": "CN=Dontesta CA,OU=IT Labs,O=Dontesta,L=Bronte,ST=Catania,C=IT",
    "subjectAlternativeNames": null,
    "certSubject": "CN=7BF80D48-B92C-45EB-80F0-363D1CCA6E4C,OU=Community & News,O=Massimo Visco Corporation,L=Rome,ST=Italy,C=IT",
    "certSerialNumber": "376693016274162034819659983838224914643739644614",
    "certPEM": "<removed>",
    "customExtensions": {
      "role": "Role=User,Administrator",
      "deviceId": "DeviceId=MTcyNjIzMjU5Njc5NTk2NjAwMCNmMjEwNTM2Ni02MTEyLTQyYTctOGI5OC00Njg3NmRkYWU0MmYjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjNWZlMGUxMTNkMGJjMDIzZTQ3YTY0OTAzM2Q1NmM2MmEwN2EzMDk0MzVkYzdiOWIyMjIxZjkxNDcwNDVkZTdjNg=="
    },
    "notBefore": "Fri Sep 13 15:03:16 CEST 2024"
  },
  "userAgent": "curl/8.7.1",
  "cipherSuite": "TLS_AES_256_GCM_SHA384",
  "clientAddress": "127.0.0.1:64218"
}

# Execute the request to the /api/v1/connection-info/user-identity endpoint using the client certificate with custom extension DeviceId with the correct value generated by the algorithm and the custom extension Roles and the value User,Administrator
curl -s \
    --cert src/main/resources/certs/client_with_device_id_and_roles_1_cert.p12:uWTNwBluEXGszPYv \
    --cert-type P12 \
    --cacert src/main/resources/certs/ca_cert.pem \
    https://localhost:8443/api/v1/connection-info/user-identity | jq

# Output
{
  "principal": "CN=7BF80D48-B92C-45EB-80F0-363D1CCA6E4C,OU=Community & News,O=Massimo Visco Corporation,L=Rome,ST=Italy,C=IT",
  "roles": [
    "User",
    "Administrator"
  ],
  "attributes": {
    "deviceId": "MTcyNjIzMjU5Njc5NTk2NjAwMCNmMjEwNTM2Ni02MTEyLTQyYTctOGI5OC00Njg3NmRkYWU0MmYjYW11c2FycmEtbWFjYm9vay1wcm8ubG9jYWwjNWZlMGUxMTNkMGJjMDIzZTQ3YTY0OTAzM2Q1NmM2MmEwN2EzMDk0MzVkYzdiOWIyMjIxZjkxNDcwNDVkZTdjNg=="
  },
  "userCN": "7BF80D48-B92C-45EB-80F0-363D1CCA6E4C"
}

Bash

Console 23 - Esecuzione del test di accesso ai servizi REST con il certificato client con estensione personalizzata DeviceId con il corretto valore ed estensione personalizzata Roles e valore User,Administrator

L'output dei test di accesso ai servizi REST con il certificato client con l'estensione personalizzata DeviceId con il corretto valore generato dall'algoritmo descritto nel capitolo Algoritmo per la generazione del DeviceId e l'estensione personalizzata Roles con il valore User,Administrator mostra che l'autenticazione mTLS è avvenuta con successo e che l'accesso ai servizi REST è stato consentito. Inoltre, l'output dei servizi REST è conforme agli schemi JSON definiti nel capitolo Struttura JSON di risposta dei servizi Rest.

Con questo ultimo test abbiamo completato la serie di verifiche dell’accesso ai servizi REST utilizzando i certificati client generati. Abbiamo confermato che l’autenticazione mTLS ha funzionato correttamente e che le policy di accesso ai servizi REST sono state applicate in modo adeguato.

Cos'è il Trusted Service List (TSL) e come integrarlo

Il TSL (Trusted Service List) è un documento elettronico standardizzato che contiene informazioni sui servizi fiduciari di uno Stato membro dell’Unione Europea o di un altro paese riconosciuto. I servizi fiduciari includono quelli che offrono servizi di firma digitale, autenticazione, sigilli elettronici, certificati SSL/TLS e altri meccanismi di sicurezza legati all’identità digitale.

La mindmap seguente suddivide il TSL nei seguenti rami principali.

Definizione : contiene la definizione del TSL e il documento elettronico standard che lo rappresenta.
Componenti Principali : elenca i principali componenti del TSL, come i fornitori di servizi fiduciari (TSP), i certificati digitali e i servizi fiduciari qualificati.
Normative : descrive le normative che regolano il TSL, come il regolamento eIDAS nell’UE e l’interoperabilità tra paesi.
Utilizzo : spiega come utilizzare il TSL per verificare i certificati, garantire la conformità normativa, firmare documenti digitali e proteggere i siti web con certificati SSL/TLS.
Aggiornamenti : discute la validità e l’aggiornamento periodico del TSL, nonché la revoca dei fornitori non conformi.

Figura 11 - Mindmap del Trusted Service List (TSL)

Gli Stati membri dell'Unione Europea e dello Spazio Economico Europeo pubblicano elenchi attendibili di fornitori di servizi fiduciari qualificati in conformità al Regolamento eIDAS. La Commissione Europea pubblica questi elenchi di fiducia in un formato elettronico standardizzato chiamato Trusted List (TL) che è possibile consultare sulla eIDAS Dashboard.

La soluzione dell'integrazione del TSL in Quarkus

Il tag di riferimento per questo step è tutorial-bonus-integrate-tsl.

Per integrare il TSL in un'applicazione Quarkus, potremmo utilizzare la libreria DSS : Digital Signature Service che fornisce un'implementazione Java per la gestione delle Trusted Lists (TL) più decine di altre cose all'interno dell'ecosistema DSS. La libreria DSS è stata sviluppata dalla Commissione Europea e fa parte dei Digital Building Blocks (DBB) per la creazione di servizi digitali sicuri e interoperabili. In questo esempio d'integrazione, faremo una nostra implementazione che richiede davvero poco sforzo e sfrutteremo in questo modo delle caratteristiche di Quarkus.

L'applicazione Quarkus, fino a questo momento è stata configurata per l'autenticazione mTLS e l'accesso ai servizi REST è stato limitato in base ai ruoli definiti e attributi presenti nel certificato client. L'integrazione del TSL potrebbe essere utile per verificare i certificati digitali dei fornitori di servizi fiduciari qualificati e garantire la conformità normativa.

Restando nel territorio Italiano e volendo fare un esempio pratico, potremmo utilizzare il TSL Italiano pubblicato dall'Agenzia per l'Italia Digitale (AgID) e integrarlo nell'applicazione Quarkus. L'AgID pubblica il TSL Italiano in un formato elettronico standardizzato che può essere consultato sulla eIDAS Dashboard.

Integrando il TSL Italiano sulla nostra applicazione Quarkus, potremo consentire l'accesso ai servizi REST per i possessori di certificati digitali rilasciati da fornitori di servizi fiduciari qualificati. Qual è il primo certificato digitale che quasi tutti i cittadini Italiani posseggono? La Carta d'Identità Elettronica (CIE) rilasciata dal Ministero dell'Interno e prodotta dal Poligrafico e Zecca dello Stato, è un esempio di certificato digitale che può essere verificato tramite il TSL Italiano.

Quali sono i macro passaggi per integrare il TSL Italiano nell'applicazione Quarkus?

Scaricare il file XML del TSL Italiano da eIDAS (https://eidas.agid.gov.it/TL/TSL-IT.xml).
Eseguire il parsing del file XML.
Estrarre i certificati X509 delle CA dei fornitori di servizi fiduciari qualificati.
Verificare i certificati digitali in ingresso.
Configurare il TLS in Quarkus con i certificati digitali validati.

Questi macro passaggi possono essere implementati all'interno di un Periodic Task di Quarkus che eseguirà gli step indicati in precedenza, così come mostrato nel diagramma di flusso a seguire.

flowchart TD UpdateTSL>Periodic Task \nGov Certificate Updater] --> SA subgraph SA [TSL Update Process] Start([Start]) --> A[Download the TSL-IT.xml] A --> B[Parse the XML file] B --> C[Extract certificates and TSP] C --> D{Valid certificates?} D -->|Yes| E[Validate incoming certificates] D -->|No| F[Generate invalid certificate error] E --> G[Configure TLS in Quarkus] F --> End G --> End([End]) end

Figura 12 - Diagramma di flusso per l'integrazione del TSL in Quarkus

Implementazione del parser XML del TSL e del task periodico di aggiornamento

Per quanto riguarda il parser XML del TSL, andremo a scrivere un componente che chiameremo GovCertificateParser che avrà le seguenti responsabilità:

eseguire il parser del file XML estraendo solo i certificati X509 che sono identificati dall'elemento ServiceTypeIdentifier con il valore http://uri.etsi.org/TrstSvc/Svctype/IdV;
verificare che i certificati X509 siano validi;
salvare i certificati X509 validi in formato PEM;
creare un bundle di certificati PEM che sarà poi utilizzato per configurare il TLS in Quarkus.

Per quanto riguarda il task periodico di aggiornamento, andremo a scrivere un componente che chiameremo GovCertificateUpdater che avrà le seguenti responsabilità:

eseguire il task periodico di aggiornamento del TSL con una frequenza che sia configurabile attraverso una proprietà applicativa sul file application.properties;
scaricare il file XML del TSL Italiano;
chiamare il componente GovCertificateParser che esegue il parsing del file XML e salva i certificati X509 all'interno di un bundle di certificati PEM;

Qui non riporterò il codice sorgente completo, che potete sempre visionare qui tutorial-bonus-integrate-tsl ma vi mostrerò il codice sorgente del componente GovCertificateUpdater che si occupa di scaricare il file XML del TSL Italiano e di chiamare il componente GovCertificateParser per eseguire il parsing del file XML e salvare i certificati X509 all'interno di un bundle di certificati PEM.

sequenceDiagram participant Scheduler participant GovCertificateUpdater participant HttpClient participant GovCertificateParser Scheduler->>GovCertificateUpdater: updateCertificates() activate GovCertificateUpdater GovCertificateUpdater->>HttpClient: download TSL-IT.xml activate HttpClient HttpClient-->>GovCertificateUpdater: TSL-IT.xml content deactivate HttpClient GovCertificateUpdater->>GovCertificateParser: parseAndSaveCerts(xmlContent) activate GovCertificateParser GovCertificateParser->>GovCertificateParser: cleanOutputPath() GovCertificateParser->>GovCertificateParser: apply(Node node) GovCertificateParser->>GovCertificateParser: saveCertificatesAsPem(inputDirectory, outputPath) deactivate GovCertificateParser deactivate GovCertificateUpdater

Figura 13 - Diagramma di sequenza per l'aggiornamento del TSL in Quarkus

Le configurazioni applicative introdotte per l'integrazione del TSL sono mostrate di seguito.

# Setting the URL of the Trust Service List (TSL) for the Italian government.
gov.trust.certs.url=https://eidas.agid.gov.it/TL/TSL-IT.xml

# Setting the path where the TSL certificates are stored.
gov.trust.certs.pem.bundle.output.path=/tmp/tsl-it

# Setting the name of the TSL certificates bundle file.
gov.trust.certs.pem.bundle.file.name=tsl-it_bundle.pem

# Setting the period for updating the TSL certificates
# The value can be expressed in milliseconds (ms), seconds (s), minutes (m), hours (h), or days (d).
# The configuration used by GovCertificateUpdater.
gov.trust.certs.tsl.update.period=2m

# Setting the initial delay for updating the TSL certificates
gov.trust.certs.tsl.update.initial.delay=60s

Bash

Application Properties 6 - Configurazioni applicative per l'integrazione del TSL

Oltre a introdurre queste nuove configurazioni applicative, affinché il TLS Registry di Quarkus sia in grado di caricare sul truststore i certificati estratti dal TSL Italiano, dobbiamo configurare il truststore di Quarkus con il bundle di certificati PEM e abilitare il meccanismo di refresh dei certificati. Per fare ciò, dobbiamo modificare la proprietà quarkus.tls.https.trust-store.pem.certs per aggiungere anche il bundle PEM delle CA del TSL e aggiungere la proprietà quarkus.tls.https.reload-period. A seguire le modifiche apportate al file application.properties.

# Setting the trust-store path.
# The trust-store file is located in the `certs` directory
# inside the resources directory.
quarkus.tls.https.trust-store.pem.certs=certs/ca_cert.pem,/tmp/tsl-it/tsl-it_bundle.pem

# Setting the reload period for the TLS configuration to 125 seconds.
quarkus.tls.https.reload-period=125s

Bash

Application Properties 7 - Configurazioni del TLS Registry per l'integrazione del TSL

L'attuale implementazione del TLS Registry di Quarkus, prevede che il caricamento iniziale dei certificati e successivo reload, possa avvenire solo attraverso filesystem, questo implica che il file tsl-it_bundle.pem (vedi configurazione) debba essere presente sul filesystem e valido; per esempio non può essere un file vuoto. Se queste condizioni non sono rispettate, il TLS Registry di Quarkus non sarà capace di caricare i certificati e il server non verrà avviato. Per maggiori informazioni consultare la documentazione ufficiale 6. Startup checks.

Come risolvere questo problema? Per gli ambienti superiori a sviluppo non è un problema perché in genere sono adottate soluzioni basate sulle kubernetes secrets o cert-manager (vedi 8. Using Kubernetes secrets or cert-manager) che inietteranno i certificati direttamente nel filesystem locale del pod, e questo garantirà che il bundle PEM sia presente e valido. Quanto mostrato in console è un esempio di quando l'applicazione Quarkus non riesce ad avviarsi a causa di un file PEM non valido.

2024-09-17 17:30:20,018 ERROR [io.qua.run.Application] (Quarkus Main Thread) Failed to start application: java.lang.RuntimeException: Failed to start quarkus
        at io.quarkus.runner.ApplicationImpl.doStart(Unknown Source)
        at io.quarkus.runtime.Application.start(Application.java:101)
        at io.quarkus.runtime.ApplicationLifecycleManager.run(ApplicationLifecycleManager.java:119)
        at io.quarkus.runtime.Quarkus.run(Quarkus.java:71)
        at io.quarkus.runtime.Quarkus.run(Quarkus.java:44)
        at io.quarkus.runtime.Quarkus.run(Quarkus.java:124)
        at io.quarkus.runner.GeneratedMain.main(Unknown Source)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:580)
        at io.quarkus.runner.bootstrap.StartupActionImpl$1.run(StartupActionImpl.java:116)
        at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: java.lang.IllegalStateException: Invalid PEM trusted certificates configuration for certificate 'https' - cannot read the PEM certificate files
        at io.quarkus.tls.runtime.keystores.PemKeyStores.verifyPEMTrustStoreStore(PemKeyStores.java:49)

Plaintext

Console 24 - Errore di avvio dell'applicazione Quarkus a causa di un file PEM non valido

Per riuscire a far partire l'applicazione Quarkus sul nostro ambiente di sviluppo, le strade sono due:

creare un file PEM (tsl-it_bundle.pem) con almeno un certificato valido all'interno della directory /tmp/tsl-it prima di avviare l'applicazione Quarkus;
creare il file tsl-it_bundle.pem contenente i certificati validi estratti dal TSL Italiano all'interno della directory /tmp/tsl-it prima di avviare l'applicazione Quarkus.

Indubbiamente la prima strada è la più semplice e veloce da percorrere, mentre la seconda richiede più di lavoro.

Seguendo la prima strada dovremmo attendere l'esecuzione del task finché porti a compimento l'aggiornamento del TSL per ottenere il bundle PEM con i certificati validi, per poi attendere il reload del TLS Registry di Quarkus (vedi quarkus.tls.https.reload-period). Il vantaggio della seconda strada è che all'avvio dell'applicazione Quarkus avremo già il bundle PEM con i certificati validi estratti dal TSL Italiano e il TLS sarà configurato correttamente.

In ogni caso, una volta che l'applicazione Quarkus sarà partita, il task periodico di aggiornamento del TSL si occuperà di aggiornare il file PEM con i certificati validi estratti dal TSL Italiano. Direi di seguire entrambe le strade e verificare così la differenza di comportamento.

La prima strada prevede di creare un file PEM con almeno un certificato di CA. Eseguendo dalla home del progetto lo script shell ./src/main/shell/certs-manager/download_tsl_it_certs.sh --fake, genereremo un file PEM con un certificato di CA fake. A seguire l'output dello script shell.

🚀 Starting certificate update process
🔐 Generating fake CA certificate
.+.....+.+...+...+..+++++++++++++++++++++++++++++++++++++++*.+.....................+..+..........+..+............+...............+...+...+....+......+..+......+++++++++++++++++++++++++++++++++++++++*...+....+...+...........+....+......+..+.............+..+...+....+.....+.+...............+....................+.+..................+..+....+.....+.........+.+..+.........+...+...+...+....+...........+....+......+.....+.........+.......+...+...+.........+......+.....+...+......+...+.+......+...+..+...+...............+.............+...+.....+.+...........+....+........+............+......+...+....+.................+...+.+......+...+...+........+....+...+..............+....+.....+.+...............+.....+....+..............+............+......+.......+......+...........+.........+............+....+.....+.+.....+...+......+......+...+.........+.+.....................+...+.....+.......+.....+.+..+.............+..+............+......+....+.........++++++
...+..+.+.........+........+.+.........+++++++++++++++++++++++++++++++++++++++*.........+.+..+...+......+.+...+++++++++++++++++++++++++++++++++++++++*...++++++
✅ Generated fake CA certificate at /tmp/tsl-it/fake_ca.pem
✅ Added fake CA certificate to PEM bundle

Bash

Console 25 - Esecuzione dello script shell per la generazione di un file PEM con un certificato di CA fake

Una volta ottenuto il file /tmp/tsl-it/fake_ca.pem lo rinominiamo in tsl-it_bundle.pem e avviamo l'applicazione Quarkus con il comando quarkus dev. L'applicazione Quarkus dovrebbe partire senza problemi, ed eseguendo il comando openssl s_client -connect localhost:8443 -showcerts, dovremmo vedere nella lista degli Acceptable client certificate CA names il certificato di CA fake (con subject C=US, ST=California, L=San Francisco, O=Fake Identity Corp, OU=IT Department, CN=Faked Identity Corp Root CA) che abbiamo generato, così come mostrato di seguito da un estratto dell'output del comando.

Connecting to 127.0.0.1
CONNECTED(00000005)
Can't use SSL_get_servername
depth=0 C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
verify error:num=21:unable to verify the first certificate
verify return:1
depth=0 C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
verify return:1

Server certificate
subject=C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
issuer=C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA

Certificate chain
 0 s:C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=rd.quarkus.dontesta.it
   i:C=IT, ST=Catania, L=Bronte, O=Dontesta, OU=IT Labs, CN=Dontesta CA
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Sep 6 22:16:21 2024 GMT; NotAfter: Sep 6 22:16:21 2025 GMT

Acceptable client certificate CA names
C=IT, O=Actalis S.p.A., OU=Servizi di Certificazione, CN=Regione Molise - CA Cittadini 2020
C=IT, O=Telecom Italia Trust Technologies S.r.l., OU=Servizi di certificazione, CN=TI Trust Technologies per il Ministero dell'Interno CA
C=IT, O=InfoCert S.p.A., OU=Servizi di Certificazione, CN=Regione Basilicata - CA Cittadini
C=IT, O=InfoCert S.p.A., OU=Trust Service Provider, organizationIdentifier=VATIT-07945211006, CN=InfoCert Certification Services CA 3
C=IT, O=Poste Italiane S.p.A., OU=Servizi di Certificazione, CN=Regione Siciliana - CA Cittadini
C=IT, O=Actalis S.p.A., OU=Servizi di Certificazione, CN=Regione Umbria - CA Cittadini
C=IT, O=InfoCert S.p.A., OU=Servizi di Certificazione, CN=Regione Marche - CA Cittadini
C=IT, L=Ponte San Pietro, O=ArubaPEC S.p.A., organizationIdentifier=VATIT-01879020517, OU=Trust Service Provider, CN=ArubaPEC EU Authentication Certificates CA G1

Plaintext

Console 27 - Output del comando openssl s_client -connect localhost:8443 -showcerts

Seguendo la prima strada del certificato di CA fake, abbiamo avuto modo di appurare come la nostra implementazione dell'integrazione del TSL e la configurazione del TLS Registry di Quarkus funzionino correttamente e come atteso. Ora possiamo passare alla seconda strada, ovvero, quella di creare il file tsl-it_bundle.pem con i certificati validi estratti dal TSL prima di avviare l'applicazione Quarkus.

Per generare quindi il file tsl-it_bundle.pem con i certificati validi estratti dal TSL, eseguiremo lo script shell ./src/main/shell/certs-manager/download_tsl_it_certs.sh che si occuperà di scaricare il file XML del TSL, estrarre i certificati validi e salvarli in formato PEM (bundle) all'interno della directory /tmp/tsl-it. Prima di eseguire lo script, dovreste accertare che l'applicazione Quarkus non sia attiva. A seguire un estratto di esecuzione dello script shell.

🚀 Starting certificate update process
✅ Downloaded XML content
💾 Saving XML content to file: /tmp/tsl-it.xml
✅ Saved XML content to /tmp/tsl-it.xml
🔍 Parsing and saving certificates
🧹 Cleaning output path: /tmp/tsl-it
✅ Cleaned output path: /tmp/tsl-it
****Retrieving: /tmp/tsl-it.xml****
 ****Processing: /tmp/tsl-it.xml****
💾 Saving certificate as PEM
Certificate will not expire
✅ Saved certificate to /tmp/tsl-it/b43852d091d7d0ecd4bd473286dc82e5ba1f24f9d82ac2b6d0fae39e5c38637f.pem
🔍 Certificate subject: subject=C=IT, O=INFOCERT SPA, OU=Ente Certificatore, serialNumber=07945211006, CN=InfoCert Servizi di Certificazione 2
💾 Saving certificate as PEM
Certificate will not expire
✅ Saved certificate to /tmp/tsl-it/1b944bedf3d946bb0f8b889b6fa5130a152668e1d73ea253c334d8ea392c773b.pem
🔍 Certificate subject: subject=C=IT, O=InfoCert S.p.A., OU=Servizi di Certificazione, CN=Provincia Autonoma di Bolzano - CA Cittadini
💾 Saving certificate as PEM
Certificate will not expire
Certificate will expire
❌ Certificate subject=C=IT, O=Postecom S.p.A., OU=Servizi di Certificazione, CN=Regione Marche - CA Cittadini is expired or not yet valid. Removing /tmp/tsl-it/b70ad3ec6f408fb3e3f42f22c0e0e654893204fa0401052e96932b5f192539d8.pem
🏁 Processed 138 certificates
🏁 Expired certificates: 31
📦 Creating PEM bundle
✅ Created PEM bundle at /tmp/tsl-it/tsl-it_bundle.pem
🏁 Certificate update process completed

Bash

Console 25 - Esecuzione dello script shell per l'aggiornamento del file tsl-it_bundle.pem

Ottimo! Abbiamo generato il file tsl-it_bundle.pem con i certificati validi estratti dal TSL. Ora possiamo avviare l'applicazione Quarkus con il comando quarkus dev e verificare che il TLS Registry di Quarkus sia stato ricaricato con i certificati validi estratti dal TSL. Eseguendo il comando openssl s_client -connect localhost:8443 -showcerts, dovreste vedere nella lista degli Acceptable client certificate CA names i certificati validi estratti dal TSL, così come atteso.

Adesso la nostra applicazione Quarkus è potenzialmente pronta per accettare client che si vogliano per esempio autenticare tramite CIE o CNS. Potenzialmente, perché l'attuale implementazione andrebbe estesa per garantire l'accesso ai servizi REST ma questo è un esercizio che lascio a voi.

Test di accesso con la TS-CNS

Adesso che abbiamo integrato il TSL nel nostro progetto Quarkus, dovremmo essere nelle condizioni di poter accedere alla Dev Console di Quarkus utilizzando per esempio la TS-CNS. Questo test ci permetterà di verificare che il TLS sia configurato correttamente e che il server sia in grado di autenticare il client.

Il comportamento atteso è che l'accesso alla Dev Console di Quarkus avvenga senza alcun problema dopo avere inserito il PIN della TS-CNS mentre l'accesso ai servizi REST dovrebbe fallire perché il certificato client della TS-CNS non rispetta i requisiti che abbiamo imposto per i certificati client (vedi tabella sui requisiti dei certificati client).

Per eseguire il test diamo per scontato che la macchina su cui eseguirete il test abbia installato e configurato correttamente un lettore di smart card compatibile con la vostra TS-CNS e che il browser utilizzato sia compatibile e configurato per l'uso della smart card.

Il test può essere eseguito in due modi, uno semplice e uno più avanzato.

dopo aver collegato il lettore di smart card e inserita la TS-CNS, puntando il browser sull'indirizzo https://localhost:8443/q/dev/, il comportamento atteso è che sia visualizzato il pop-up per l'inserimento del PIN, successivamente visulizzato il pop-up per la selezione e conferma del certificato client e infine la Dev Console di Quarkus;
utilizzando cURL avendo cura di istruire il comando curl a utilizzare il certificato client presente all'interno della TS-CNS. Per questo test vi rimando al video Autenticazione con la TS-CNS: come usarla in modalità batch.

A seguire le immagine del pop-up per l'inserimento del PIN della TS-CNS, del pop-up per la selezione del certificato client e della Dev Console di Quarkus.

Figura 14 - Pop-up per l'inserimento del PIN della TS-CNS

Figura 15 - Pop-up per la selezione del certificato client

Figura 16 - Dev Console di Quarkus

Ottimo! Abbiamo ottenuto il risultato atteso. Accedendo al servizio REST https://localhost:8443/api/v1/connection-info/user-identity dovremmo ottenere l'accesso negato al servizio in virtù del fatto che il certificato della TS-CNS non rispetta i requisiti imposti dalla nostra implementazione.

Figura 17 - Accesso negato al servizio REST

Come ho scritto in precedenza, l'estensione dell'implementazione per supportare i certificati digitali della TS-CNS o CIE è un esercizio che lascio a voi.

Risorse

Considerazioni finali

Wow! Abbiamo fatto un bel percorso.

L’implementazione di TLS Mutual Authentication (mTLS) utilizzando il framework Quarkus rappresenta un passo cruciale per garantire comunicazioni sicure e affidabili tra client e server. Il protocollo TLS, che cifra i dati trasmessi, viene potenziato con l’introduzione di mTLS, permettendo la doppia autenticazione tramite l’uso di certificati sia da parte del client che del server.

Un elemento fondamentale per la corretta gestione dei certificati e della fiducia tra le parti è la Trusted Service List (TSL), che fornisce un elenco di servizi e certificati fidati approvati da autorità di certificazione riconosciute. Nel contesto dell’implementazione di mTLS, l’uso di una TSL permette di garantire che solo i certificati verificati e conformi agli standard di sicurezza possano essere utilizzati, migliorando ulteriormente l’affidabilità del sistema.

Quarkus, con la sua capacità di integrarsi facilmente con mTLS e la gestione di certificati validati tramite TSL, fornisce una piattaforma sicura e scalabile per applicazioni cloud-native. Questo approccio consente di proteggere le comunicazioni, stabilire fiducia reciproca tra client e server e mantenere elevati livelli di sicurezza per le applicazioni distribuite.

In conclusione, l’integrazione di TLS, mTLS e TSL rappresenta una soluzione completa per chi desidera implementare elevati standard di sicurezza nelle proprie applicazioni. Con Quarkus, con una manciata di configurazioni e poche righe di codice, è possibile raggiungere questi obiettivi in maniera efficiente, bilanciando prestazioni e sicurezza.

L'articolo Implementazione di TLS Mutual Authentication (mTLS) con Quarkus sembra essere il primo su Antonio Musarra's Blog.

Cosa sono i modelli di licenza multipli nel software?

Antonio Musarra — Wed, 21 Aug 2024 07:15:48 +0000

Nel mondo del software, la scelta di una licenza rappresenta un passaggio cruciale nello sviluppo e nella distribuzione di un prodotto. Tuttavia, in alcuni casi, gli sviluppatori decidono di adottare un approccio più flessibile, optando per modelli di licenza multipli. Questa strategia permette al software di essere distribuito sotto diverse licenze, a seconda delle esigenze dell’utente o del contesto di utilizzo.

A settembre del 2023 ho deciso di archiviare il progetto liferay-portal-database-all-in-one-support e uno dei motivi principali che ha spinto questa mia azione riguardava proprio l’adozione dei modelli di licenza multipli da parte del progetto Liferay Portal.

In questo articolo esploreremo quali sono gli aspetti essenziali dei modelli di licenza multipli, il loro funzionamento, i vantaggi e gli svantaggi, nonché alcuni casi d’uso reali.

Cosa sono?

I modelli di licenza multipli si riferiscono alla pratica di rilasciare un software sotto più di una licenza. Questo significa che gli utenti o le aziende possono scegliere tra diverse licenze, ognuna delle quali offre diritti e restrizioni diversi. Le ragioni per adottare un approccio del genere sono molteplici e spesso includono la volontà di massimizzare la diffusione del software, soddisfare le esigenze di diversi mercati, o rispondere a differenti contesti normativi e commerciali.

Tipi di modelli di licenza multipli

Esistono diverse configurazioni per i modelli di licenza multipli.

Dual Licensing : Questa è la forma più comune di licenza multipla. In un modello di licenza duale, il software viene rilasciato sotto due licenze distinte, una delle quali è spesso una licenza open-source, come la GPL (General Public License), e l’altra è una licenza commerciale. Gli utenti possono scegliere di utilizzare il software secondo i termini della licenza open-source o di acquistare una licenza commerciale che offre vantaggi aggiuntivi, come l’assistenza tecnica o il diritto di creare software proprietario basato sul codice.
Licenza con Eccezione : Alcuni sviluppatori rilasciano il software sotto una licenza principale open-source, con delle eccezioni che permettono un utilizzo più ampio del codice. Ad esempio, un software potrebbe essere rilasciato sotto la GPL con un’eccezione che permette l’integrazione con software proprietari senza imporre la stessa licenza a quest’ultimo.
Licenza Tripla o Multipla : In questo modello, il software è rilasciato sotto tre o più licenze, offrendo una maggiore flessibilità. Ad esempio, un progetto potrebbe essere disponibile sotto la GPL, la LGPL (Lesser General Public License) e una licenza commerciale, permettendo agli utenti di scegliere quella che meglio si adatta alle loro necessità.

Vantaggi dei modelli di licenza multipli

I modelli di licenza multipli offrono una serie di vantaggi sia per gli sviluppatori che per gli utenti.

Flessibilità : Gli sviluppatori possono soddisfare le esigenze di diversi utenti o mercati, aumentando il potenziale di adozione del software.
Monetizzazione : La combinazione di licenze open-source e commerciali permette agli sviluppatori di attrarre una vasta base di utenti, pur mantenendo la possibilità di monetizzare attraverso licenze commerciali.
Adozione da Parte delle Aziende : Molte aziende preferiscono utilizzare software con licenze commerciali per motivi di supporto e conformità legale. Offrire un’opzione commerciale può facilitare l’adozione da parte di queste aziende.
Contributo alla Comunità : L’uso di una licenza open-source consente alla comunità di contribuire al progetto, migliorando il software e beneficiando al contempo di un feedback più ampio.

Svantaggi

Nonostante i numerosi vantaggi, i modelli di licenza multipli non sono privi di critiche.

Confusione : L’esistenza di più licenze può creare confusione tra gli utenti, specialmente se non sono esperti in materia legale.
Complessità Legale : Gestire più licenze può comportare una maggiore complessità legale, sia per gli sviluppatori che per gli utenti, che devono assicurarsi di rispettare i termini di tutte le licenze applicabili.
Rischio di Forking : In alcuni casi, i modelli di licenza multipli possono incentivare la creazione di fork del software, in particolare se una parte della comunità non è d’accordo con le condizioni delle licenze commerciali.

I punti sopra indicati evidenziano come i modelli di licenza multipli, pur offrendo flessibilità e opportunità, possano anche introdurre sfide significative nella gestione e nell’adozione del software.

Esempi di applicazione e note pratica

Alcuni dei più noti software che utilizzano modelli di licenza multipli includono:

• MySQL : Questo celebre sistema di gestione di database è stato rilasciato sotto la GPL, ma è disponibile anche con una licenza commerciale per coloro che desiderano incorporare il database in applicazioni proprietarie senza rilasciare il codice sorgente.

• Qt : La libreria Qt, utilizzata per lo sviluppo di interfacce grafiche, è disponibile sotto diverse licenze, inclusa una licenza GPL, LGPL, e una licenza commerciale.

• Mozilla Firefox : Anche se principalmente rilasciato sotto la MPL (Mozilla Public License), Firefox offre componenti disponibili sotto altre licenze, come la GPL e la LGPL, per favorire l’integrazione e l’utilizzo in vari contesti.

Prendendo in considerazione il progetto Liferay Portal, anch’esso fa uso dell’approccio dual-licensing di cui riporto un breve estratto dal file LICENSING.markdown.

This software is available to you under a dual-licensing approach, whereby you may choose under any of the following options:

- **FOSS [GNU Lesser General Public License v2.1 or later][lgpl-2.1-or-later]** – this means anyone may use it under either LGPL-2.1 or any later version of LGPL. Currently the only newer version is LGPL-3.0, but should the [FSF][fsf] in the future adopt a newer version, you will be able to choose that as well;
- **proprietary [EULA: Liferay Digital Experience Platform And Certain Applications (2002306_GL)][dxp_eula]**, available through _[Liferay Enterprise Services Agreement][esa]_ – this additional option is intended for Liferay's subscription customers. Should you wish to become a subscription customer, contact Liferay at <https://www.liferay.com/contact-sales>.

In addition, you should be aware that even if you opt to use the code under the LGPL-2.1 license (instead of LGPL-3.0), Liferay is a signatory of the [GPL Cooperation Commitment][gplcc]. Meaning that in case you, by chance, violated the LGPL-2.1, we would apply the much more friendly grace period and automatic license reinstatement from the GPL-3.0. For more info, see [our public commitment][gplcc_liferay] and this [blog post][gplcc_blog].

## SPDX and REUSE standards

The above licensing situation is expressed in [SPDX language][spdx_id] with the following unambiguous identifier, which you can find in every source code file that is released to you under these licenses:

`SPDX-License-Identifier: (LGPL-2.1-or-later OR LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06)`

You can find the texts of both licenses in the `LICENSES/` folder in the root of this repository/package, with the SPDX ID of each license as the files base name, specifically in:

- [LICENSES/LGPL-2.1-or-later.txt](LICENSES/LGPL-2.1-or-later.txt)
- [LICENSES/LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06.txt](LICENSES/LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06.txt)

This is in line with the [REUSE Software 3.0 specification][reuse] of community best practices regarding standardised declaring of copyright and licensing information for software projects.

Licensing.markdown

L’intestazione dei file sorgenti (indicata a seguire) riporta le due license mostrate nell’estratto precedente. Le licenze sono espresse in formato SPDX language come illustrato enll’esempio seguente per il file sorgente OracleDB.java.

/**
* SPDX-FileCopyrightText: (c) 2000 Liferay, Inc. https://liferay.com
* SPDX-License-Identifier: LGPL-2.1-or-later OR LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06
*/

OracleDB.java

Se notate, le due licenze sono indicate con la chiave “ OR ”, significa che il codice sorgente è rilasciato sotto una licenza duale, e chi utilizza il codice ha la possibilità di scegliere quale delle due licenze adottare. L’utente potrà quindi scegliere se rispettare i termini della licenza LGPL-2.1-or-later oppure quelli della licenza LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06. Ogni licenza ha le proprie condizioni e obblighi, quindi la scelta dell’utente può dipendere da quale licenza è più adatta al loro uso specifico.

Oltre alla chiave “OR”, esistono altre chiavi o combinazioni che possono essere utilizzate per indicare diverse modalità di licenza del codice sorgente, anche se sono meno comuni. Ecco una panoramica delle opzioni:

1. AND:

Significato : Se le licenze sono indicate con la chiave “AND” (esempio: “GPL-3.0 AND MIT”), significa che chi utilizza il codice deve rispettare entrambe le licenze contemporaneamente.
Implicazioni : Questo scenario richiede che l’utente soddisfi i requisiti di tutte le licenze applicabili. Questo può essere complicato, soprattutto se le licenze hanno condizioni che potrebbero essere difficili da conciliare.

Esempio :

GPL-3.0 AND MIT : L’utente deve rispettare i termini della GPL-3.0, che impone il rilascio del codice derivato sotto la stessa licenza, e anche i termini della licenza MIT, che potrebbe essere più permissiva. Di fatto, la GPL-3.0 è la licenza più restrittiva e quindi le sue condizioni prevalgono, ma bisogna comunque rispettare entrambe.

2. WITH:

Significato : La chiave “WITH” viene utilizzata in combinazione con clausole aggiuntive o eccezioni.
Implicazioni : Questa chiave indica che il codice è licenziato sotto una licenza principale, ma con alcune modifiche o eccezioni specifiche.

Esempio :

GPL-3.0 WITH Classpath Exception : Questa combinazione indica che il codice è rilasciato sotto la GPL-3.0, ma con un’eccezione specifica (la Classpath Exception) che consente un utilizzo più flessibile del codice in alcuni contesti, come il linking con software proprietario.

3. Dual/Multi-Licensing (senza chiavi specifiche):

Descrizione : Alcuni progetti possono essere rilasciati con più licenze, ma senza usare chiavi specifiche come “OR” o “AND”. In questi casi, le modalità di scelta o combinazione delle licenze vengono spiegate in dettaglio nella documentazione del progetto.
Implicazioni : La chiarezza delle condizioni di licenza dipende fortemente dalla documentazione fornita.

4. Composite Licensing:

Descrizione : In alcuni casi complessi, il codice potrebbe essere soggetto a una combinazione di licenze per diverse parti del progetto. Ad esempio, una parte del codice potrebbe essere rilasciata sotto una licenza e un’altra parte sotto un’altra.
Implicazioni : Gli utenti devono fare attenzione a rispettare le licenze specifiche applicabili a ciascuna parte del codice.

È essenziale per chi utilizza il codice comprendere queste combinazioni per garantire la conformità alle condizioni legali richieste.

Conclusioni

I modelli di licenza multipli rappresentano una strategia versatile che permette di combinare i vantaggi del software open-source con le opportunità commerciali. L’uso di chiavi come “OR”, “AND” e “WITH” permette di definire con precisione come devono essere applicate le licenze in un progetto di software.

L’adozione di modelli multipli, sebbene possano presentare alcune sfide, offrono un mezzo efficace per adattarsi a diversi mercati e contesti normativi. Per gli sviluppatori, la chiave del successo con questo modello risiede nella trasparenza e nella chiarezza nella comunicazione delle condizioni di licenza, assicurando che gli utenti comprendano appieno le opzioni a loro disposizione.

Risorse

Open Source Initiative (OSI) – opensource.org

L’OSI è l’organizzazione di riferimento per la certificazione delle licenze open-source. Il sito contiene risorse educative, articoli e documenti su varie licenze, comprese quelle multiple.

Free Software Foundation (FSF) – fsf.org

La FSF offre risorse approfondite sulle licenze software libere, inclusa la GPL, e sulle modalità di rilascio del software sotto licenze multiple.

Understanding Open Source and Free Software Licensing di Andrew M St Laurent (Autore)

Un testo essenziale per chiunque voglia capire le differenze tra le licenze open-source e free software. Include esempi pratici di licenze multiple e casi d’uso reali.

The Cathedral & the Bazaar – Musings on Linux & Open Source by an Accidental Revolutionary di Eric Raymond (Autore)

Anche se non specificamente focalizzato sulle licenze multiple, questo libro esplora la filosofia open-source e le implicazioni pratiche del rilascio di software con licenze aperte, toccando anche le dinamiche legate alla scelta delle licenze.

L'articolo Cosa sono i modelli di licenza multipli nel software? sembra essere il primo su Antonio Musarra's Blog.

Cos’è l’approccio Document as Code (doc-as-code)

Antonio Musarra — Mon, 24 Jun 2024 22:35:00 +0000

Negli ultimi anni, l’approccio Document as Code (Doc-as-Code) ha guadagnato popolarità tra i team di sviluppo software e le organizzazioni che si occupano di documentazione tecnica. Questa metodologia trasferisce i principi dello sviluppo software alla creazione e gestione della documentazione, portando con sé numerosi vantaggi in termini di efficienza, qualità e collaborazione. Ma cosa significa esattamente Document as Code?

Cercherò di spiegare questo approccio nel modo più chiaro e sintetico possibile per poi lasciarvi il bonus, ovvero, un progetto completo (out-of-the-box) di questo tipo di approccio.

1. Definizione e Principi Fondamentali

L’approccio Doc-as-Code prevede la gestione della documentazione tecnica nello stesso modo in cui si gestisce il codice sorgente. Ciò implica che i documenti siano scritti in formati testuali, abbiano una versione applicata tramite sistemi di controllo del codice sorgente come Git, e sottoposti a revisione e test automatizzati. I principi cardine di questo approccio sono indicati e descritti a seguire.

Tracciabilità e Versionamento : Utilizzando sistemi di controllo del codice sorgente, è possibile tracciare ogni modifica apportata alla documentazione. Questo consente di mantenere una cronologia completa delle versioni, facilitando il ritorno a una versione precedente in caso di necessità.
Collaborazione e Revisione : La documentazione può essere revisionata e migliorata attraverso pull request e code review , proprio come avviene per il codice sorgente. Questo processo incrementa la qualità e la precisione del contenuto.
Automazione : Strumenti di integrazione continua ( CI ) possono essere utilizzati per automatizzare la generazione, la validazione e la pubblicazione della documentazione. Questo riduce gli errori manuali e accelera il processo di aggiornamento.
Uniformità : Utilizzando linguaggi di markup (tra i più noti) come Markdown, AsciiDoc e reStructuredText, è possibile mantenere uno stile coerente e facilmente leggibile. Inoltre, i generatori di documentazione come Sphinx o MkDocs possono essere utilizzati per creare documenti HTML, PDF e altro ancora da sorgenti testuali.

2. Vantaggi dell’Approccio Doc-as-Code

Miglioramento della Qualità : La revisione paritaria e i test automatici assicurano che la documentazione sia accurata e aggiornata, riducendo il rischio di errori.
Efficienza : L’automazione delle operazioni di generazione e pubblicazione consente di risparmiare tempo prezioso, permettendo agli autori di concentrarsi sui contenuti piuttosto che sui dettagli tecnici.
Collaborazione : L’uso di strumenti comuni tra sviluppatori e scrittori tecnici facilita una collaborazione più stretta e una migliore integrazione tra codice e documentazione.
Flessibilità : La documentazione può essere aggiornata e distribuita rapidamente, adattandosi facilmente ai cambiamenti del software e alle esigenze degli utenti.
Manutenibilità : La struttura modularizzata e versionata dei documenti semplifica la gestione e l’aggiornamento continuo del materiale di documentazione.

3. Strumenti e Tecnologie

L’approccio Doc-as-Code si avvale di una serie di strumenti e tecnologie che facilitano la creazione, gestione e pubblicazione della documentazione.

Sistemi di Controllo del Codice Sorgente : Git è il più utilizzato, permettendo di versionare la documentazione e gestire le collaborazioni.
Linguaggi di Markup : Markdown, AsciiDoc e reStructuredText sono i più comuni, grazie alla loro semplicità e leggibilità.
Generatori di Documentazione : Strumenti come Sphinx, MkDocs, Jekyll e Hugo trasformano i file di markup in documenti formattati e navigabili.
CI/CD : Piattaforme come Jenkins, Travis CI e GitHub Actions possono automatizzare la generazione e la pubblicazione della documentazione.
Editor di Testo : Visual Studio Code, Intellj IDEA e altri editor moderni supportano estensioni che migliorano la scrittura e la formattazione della documentazione.

4. Il bonus: un progetto Doc-as-Code

Ogni promessa va onorata, per cui è arrivato il momento di presentarvi il bonus, un progetto doc-as-code completo.

L’articolo Deploy di un’applicazione Quarkus su OpenShift pubblicato su TheRedCode.it, è il primo di quattro articoli che spiegano parte del progetto Quarkus Event Bus Logging Filter JAX-RS e la documentazione di quest’ultimo è stata realizzata con l’approccio doc-as-code e in particolare:

questo Documentazione Quarkus Event Bus Logging Filter JAX-RS è il link al repository GitHub del progetto doc-as-code;
questo https://amusarra.github.io/eventbus-logging-filter-jaxrs-docs/ è il link alle GitHub Pages dov’è stata pubblicata la documentazione in formato HTML;
cliccando qui Quarkus Event – Come sfruttarlo al massimo, utilizzi e vantaggi otterrete la documentazione in formato PDF;
il linguaggio di markup utilizzato è AsciiDoc;
AsciiDoctor è il processore di testo che supporta la sintassi AsciiDoc e produce HTML5, DocBook, PDF e altri formati;
per ulteriori dettagli sul progetto, fare riferimento al README.

Con questo bonus spero che apprezziate ancora di più l’approccio doc-as-code e che in qualche modo possa servire come buon punto d’inizio per i vostri progetti doc-as-code.

Conclusioni

L’approccio Document as Code rappresenta un’evoluzione significativa nella gestione della documentazione tecnica. Adottando pratiche di sviluppo software per la creazione di documenti, le organizzazioni possono migliorare la qualità, l’efficienza e la collaborazione, offrendo agli utenti finali documentazione sempre aggiornata e accurata. In un mondo in cui il software è in continua evoluzione, avere una documentazione che può tenere il passo è essenziale per il successo di qualsiasi progetto.

L'articolo Cos’è l’approccio Document as Code (doc-as-code) sembra essere il primo su Antonio Musarra's Blog.

Come usare Java JMX in ambienti container

Antonio Musarra — Tue, 18 Jun 2024 22:05:43 +0000

Con l’adozione crescente delle architetture a microservizi e dei container per la distribuzione delle applicazioni, il monitoraggio delle prestazioni e la gestione dei servizi diventano aspetti critici. Java Management Extensions (JMX) è uno strumento potente che consente agli sviluppatori di monitorare e gestire le applicazioni Java. In ambienti containerizzati, come quelli orchestrati da Kubernetes, Docker, Podman o altro, l’utilizzo di JMX presenta alcune sfide e richiede configurazioni specifiche.

Questo articolo fornirà una guida dettagliata su come usare Java JMX in ambienti container e in particolare su Red Hat OpenShift. Vedremo come configurare JMX in un’applicazione Java basata su Quarkus e come connettersi a un server JMX utilizzando JDK Mission Control per monitorare le prestazioni, gestire le risorse, e cambiare il livello di log a runtime.

Per l’esempio pratico faremo riferimento all’applicazione di esempio Event Bus Logging Filter JAX-RS e come ambiente di deploy e runtime la Dev Sandbox di Red Hat OpenShift.

Qualcuno potrebbe domandarsi: JMX è ancora attuale?

Sì, Java Management Extensions (JMX) è ancora attuale e rilevante nel contesto dello sviluppo e della gestione delle applicazioni Java. Anche se alcune tecnologie evolvono e nuovi strumenti emergono, JMX continua a essere una componente fondamentale per diverse ragioni.

Standardizzazione e Compatibilità

JMX è una specifica standardizzata e parte integrante della piattaforma Java SE (Standard Edition). Questo garantisce la compatibilità con tutte le implementazioni di Java, rendendolo un’opzione affidabile per il monitoraggio e la gestione delle applicazioni.

Integrazione con Strumenti Moderni

Molti strumenti di monitoraggio e gestione delle applicazioni Java, come JConsole, VisualVM, e strumenti di terze parti come Prometheus e Grafana, offrono integrazioni native o plugin per lavorare con JMX. Questo permette di utilizzare JMX come base per la raccolta di metriche e la gestione delle risorse, integrandolo con soluzioni più moderne per la visualizzazione e l’analisi dei dati.

Utilizzo in Architetture Distribuite

Con l’aumento dell’adozione delle architetture a microservizi e dei container, JMX rimane utile per il monitoraggio delle applicazioni Java distribuite. Ad esempio, molti container orchestrator come Kubernetes possono essere configurati per raccogliere metriche esposte tramite JMX (Quarkus e Spring Boot lo consentono), facilitando il monitoraggio centralizzato delle applicazioni distribuite.

Flessibilità ed Estensibilità

JMX è altamente flessibile ed estendibile. Gli sviluppatori possono definire nuovi MBean per esporre metriche specifiche o per aggiungere funzionalità di gestione personalizzate. Questa estensibilità lo rende adattabile a molteplici scenari, sia per applicazioni legacy che moderne.

Anche se JMX rimane rilevante, è importante considerare che nuovi paradigmi di monitoraggio, come l’osservabilità completa (tracing, logging, e metriche combinate) con strumenti come OpenTelemetry, stanno guadagnando popolarità. Tuttavia, questi strumenti spesso possono essere configurati per raccogliere dati da sorgenti JMX, mostrando come JMX continui a integrarsi con le tecnologie emergenti.

Perché JMX nei Container?

L’utilizzo di JMX nei container permette di:

monitorare le prestazioni e lo stato delle applicazioni Java;
ottenere visibilità in tempo reale sulle risorse e sui thread dell’applicazione;
gestire dinamicamente le configurazioni senza necessità di riavviare l’applicazione.

Inoltre, JMX nei container può essere integrato con strumenti di monitoraggio e gestione delle applicazioni, come Prometheus, Grafana, JConsole o strumenti di APM (Application Performance Management), per raccogliere e visualizzare metriche, analizzare i dati, e rispondere in modo pro attivo ai problemi di prestazioni.

Configurazione di JMX in un’applicazione Java

Per abilitare JMX in un’applicazione Java, è necessario configurare il server JMX per esporre le metriche e MBean. Questo può essere fatto tramite le opzioni di avvio della JVM, specificando le proprietà di sistema per abilitare il server JMX e definire la porta di ascolto. Ad esempio, è possibile utilizzare le seguenti opzioni di avvio.



-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9091
-Dcom.sun.management.jmxremote.rmi.port=9091
-Djava.rmi.server.hostname=127.0.0.1
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.local.only=true

Configurazione 1 – Opzioni di avvio per abilitare JMX

Queste opzioni abilitano il server JMX sulla porta 9091, consentono la connessione da host remoti specificando l’indirizzo IP del server, disabilitano l’autenticazione e l’uso di SSL per semplificare la configurazione. È importante notare che queste opzioni sono solo un esempio e possono essere personalizzate in base alle esigenze specifiche dell’applicazione.

Se volessi abilitare JMX su di una applicazione Java basata su Quarkus e installata su Red Hat OpenShift, come dovrei fare?

Utilizzando gli strumenti messi a disposizione da Quarkus, tutto è molto semplice. Gli step sono i seguenti:

abilitare l’estensione OpenShift per Quarkus (tramite il comando quarkus add-extension io.quarkus:quarkus-openshift);
configurare la variabile d’ambiente JAVA_OPTS per il runtime di OpenShift per abilitare JMX;
configurare i port mapping per esporre la porta JMX e consentire la connessione da host remoti.

Per aggiungere la variabile d’ambiente JAVA_OPTS per abilitare JMX in Quarkus su OpenShift, è possibile utilizzare la seguente configurazione sul file application.properties. Sono le stesse opzioni di avvio che abbiamo visto in precedenza ma configurate come variabile d’ambiente.



quarkus.openshift.env.vars.java-opts=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.rmi.port=9091 -Djava.rmi.server.hostname=127.0.0.1 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=true

Configurazione 2 – Variabile d’ambiente JAVA_OPTS per abilitare JMX in Quarkus su OpenShift

Per soddisfare il terzo punto della precedente lista, occorre configurare il Deployment e Service (oggetti K8s) per esporre la porta JMX e consentire quindi la connessione da host remoti. Questo può essere fatto utilizzando le seguenti configurazioni (sempre sul file di configurazione application.properties).



# Define the ports that should be exposed by the container
# for the JMX monitoring
quarkus.openshift.ports.jmx.protocol=TCP
quarkus.openshift.ports.jmx.container-port=9091

Configurazione 3 – Configurazione dei port mapping per JMX in Quarkus su OpenShift

Le configurazioni mostrate in precedenza, faranno in modo che, in fase di build e deploy su OpenShift, siano creati i corretti oggetti K8s per esporre la porta JMX e consentire la connessione da host remoti; non ci dobbiamo preoccupare di creare manualmente i file di configurazione YAML per il Deployment e Service, di cui a seguire sono riportati gli estratti con le informazioni necessarie.



apiVersion: apps/v1
kind: Deployment
metadata:
spec:
  replicas: 2
  selector:
    matchLabels:
  template:
    spec:
      containers:
        - env:
            - name: JAVA_OPTS
              value: -Dcom.sun.management.jmxremote
                -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.rmi.port=9091
                -Djava.rmi.server.hostname=127.0.0.1 -Dcom.sun.management.jmxremote.authenticate=false
                -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=true
            - name: JAVA_APP_JAR
              value: /deployments/quarkus-run.jar
          image: eventbus-logging-filter-jaxrs:1.2.7-SNAPSHOT
          imagePullPolicy: Always
          name: eventbus-logging-filter-jaxrs
          ports:
            - containerPort: 9091
              name: jmx
              protocol: TCP

Configurazione 4 – Configurazione del Deployment per abilitare JMX in Quarkus su OpenShift

Nota: in realtà, la configurazione del Service per esporre la porta JMX non è strettamente necessaria, in quanto il Service viene creato automaticamente dal plugin OpenShift di Quarkus. Come vedremo in seguito, la connessione sarà instaurata direttamente con il pod che esegue l’applicazione Java.



apiVersion: v1
kind: Service
metadata:
  name: eventbus-logging-filter-jaxrs
spec:
  ports:
    - name: jmx
      port: 9091
      protocol: TCP
      targetPort: 9091
  selector:
    app.kubernetes.io/name: eventbus-logging-filter-jaxrs
    app.kubernetes.io/version: 1.2.7-SNAPSHOT
  type: ClusterIP

Configurazione 5 – Configurazione del Service per abilitare JMX in Quarkus su OpenShift

Nota: le configurazioni mostrate in precedenza sono generate automaticamente dal plugin OpenShift di Quarkus e disponibili all’interno del folder target/kubernetes.

A questo punto è possibile procedere con build e il deploy dell’applicazione su OpenShift. Una volta completato il deploy, sarà possibile connettersi al server JMX esposto dall’applicazione Java e monitorare le prestazioni, le risorse e i MBean.

Verifica del deploy e preparazione connessione a JMX

Per verificare che l’applicazione Java sia stata correttamente deployata su OpenShift e che il server JMX sia attivo, è possibile utilizzare il comando oc per ottenere informazioni sul pod.



# Get information about the pod
oc get pod

# Output
NAME READY STATUS RESTARTS AGE
activemq-artemis-675cf6d9-wpbrj 1/1 Running 0 3h26m
eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 1/1 Running 0 4m25s
eventbus-logging-filter-jaxrs-66586f8dc4-vx8sh 1/1 Running 0 4m36s
mongo-7d488b9474-vg8wq 1/1 Running 0 3h25m
postgresql-7fbdfbcd64-7b76h 1/1 Running 0 3h26m

Console 1 – Output del comando oc get pod

I pod (in questo caso due) dell’applicazione Java eventbus-logging-filter-jaxrs sono stati deployati correttamente e sono in stato Running. Adesso verifichiamo che la variabile di ambiente JAVA_OPTS sia stata correttamente configurata per abilitare JMX. Possiamo usare sempre il comando oc (in diverse forme) per ottenere informazioni sulle variabili d’ambiente del pod. A seguire sono mostrati due possibili modi.



# Get environment variables for the pod
# 1. Using the get pod command with the -o json flag to get the JSON output
# To execute this command, you need to have the jq utility installed
oc get pod eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 -o json | jq '.spec.containers[].env'

# 2. Using the exc command to get the environment variables
oc exec eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 -- env | grep JAVA_OPTS

Console 2 – Output dei comandi oc per ottenere le variabili d’ambiente del pod

A seguire l’output dei comandi oc per ottenere le variabili d’ambiente del pod e in particolare quella di nostro interesse JAVA_OPTS . Dall’output ottenuto, la variabile d’ambiente JAVA_OPTS è stata correttamente configurata e impostata per abilitare JMX.



# Output of the oc get pod eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 -o json | jq '.spec.containers[].env'
[
{
"name": "JAVA_OPTS",
"value": "-Xms100M -Xmx500M -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions -XX:MaxGCPauseMillis=200 -XX:InitiatingHeapOccupancyPercent=45 -XX:G1ReservePercent=10 -XX:ConcGCThreads=4 -XX:G1NewSizePercent=5 -XX:G1MaxNewSizePercent=60 -XX:ParallelGCThreads=4 -XX:+ExitOnOutOfMemoryError -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.rmi.port=9091 -Djava.rmi.server.hostname=127.0.0.1 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=true"
},
{
"name": "JAVA_APP_JAR",
"value": "/deployments/quarkus-run.jar"
}
]

# Output of the oc exec eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 -- env | grep JAVA_OPTS
JAVA_OPTS=-Xms100M -Xmx500M -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions -XX:MaxGCPauseMillis=200 -XX:InitiatingHeapOccupancyPercent=45 -XX:G1ReservePercent=10 -XX:ConcGCThreads=4 -XX:G1NewSizePercent=5 -XX:G1MaxNewSizePercent=60 -XX:ParallelGCThreads=4 -XX:+ExitOnOutOfMemoryError -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.rmi.port=9091 -Djava.rmi.server.hostname=127.0.0.1 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=true

Console 3 – Output dei comandi oc per ottenere le variabili d’ambiente del pod (dettaglio)

Affinchè dalla nostra macchina sia possibile eseguire la connessione JMX, è necessario creare un tunnel che reindirizza una porta del computer locale a una porta di un pod specifico; la porta di nostro interesse è la 9091. Questo tipo di operazione può essere fatta utilizzando il comando oc port-forward così come mostrato di seguito.



# Enable port forwarding for the JMX port
oc port-forward pod/eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4 9091:9091

# If the port forwarding is successful, you should see the following output
Forwarding from 127.0.0.1:9091 -> 9091
Forwarding from [::1]:9091 -> 9091

Console 4 – Comando oc port-forward per abilitare il forwarding della porta JMX

A questo punto, l’applicazione Java è pronta per essere monitorata tramite JMX. Per connettersi al server JMX, è possibile utilizzare strumenti come JConsole, VisualVM, o qualsiasi altro client JMX compatibile. Nel nostro caso utilizzeremo JDK Mission Control.

Connessione a JMX tramite JDK Mission Control

JDK Mission Control è uno strumento avanzato di monitoraggio e gestione delle applicazioni Java, incluso nella suite di strumenti Java Flight Recorder (JFR). Per connettersi a un server JMX, è possibile utilizzare JDK Mission Control e specificare l’indirizzo IP e la porta del server JMX.

Avviare JDK Mission Control utilizzando il comando jmc.
Dal menù File selezionare la voce Connect.
Selezionare la voce Create a new connection per aggiungere una nuova connessione JMX.
Specificare l’indirizzo IP e la porta del server JMX (es. localhost:9091).
Specificare un nome per la connessione (es. MyApp JMX Connection).
Fare clic su Test Connection per verificare che la connessione vada a buon fine con i parametri specificati. Se la connessione avverrà con successo, sarà visualizzato un messaggio di conferma.
Fare clic su Finish per terminare la configurazione della connessione.

La figura a seguire mostra la creazione di una nuova connessione JMX in JDK Mission Control e l’esito positivo del test di connessione.

Figura 1 – Creazione di una nuova connessione JMX in JDK Mission Control

Una volta definita la connessione JMX, è possibile visualizzare quali MBean sono esposti dall’applicazione Java, monitorare le prestazioni e le risorse, e gestire dinamicamente l’applicazione avviando la console JMX così come indicato dalla figura seguente.

Figura 2 – Avvio della console JMX in JDK Mission Control

Non appena connessi, dovreste vedere la dashboard di Mission Control con le metriche e i MBean esposti dall’applicazione Java. Da qui è possibile monitorare le prestazioni, analizzare i dati e gestire l’applicazione in tempo reale.

Figura 3 – Dashboard di JDK Mission Control con le metriche JMX

Accedendo alla sezione MBean Browser di JDK Mission Control, è possibile esplorare quali MBean sono esposti dall’applicazione Java e visualizzare le metriche e le operazioni disponibili per ciascun MBean. La figura seguente mostra per esempio le metriche che riguardano il connection pool e in particolare di Agroal.

Figura 4 – Browser MBean di JDK Mission Control

Come cambiare il livello di log a runtime

Quante volte vi è capitato di dover cambiare il livello di log di un’applicazione Java a runtime, senza dover riavviare l’applicazione stessa? Con JMX è possibile farlo in modo semplice e veloce.

Una delle caratteristiche più potenti di JMX è la possibilità di gestire dinamicamente le risorse e le configurazioni dell’applicazione Java senza necessità di riavviare l’applicazione.

Per farlo utilizzeremo JDK Mission Control e il MBean java.util.logging:type=Logging per cambiare il livello di log a runtime. Questo MBean consente di modificare il livello di log per i logger specifici dell’applicazione Java, consentendo di aumentare o diminuire il livello di dettaglio dei log senza dover riavviare l’applicazione.

Come primo step dobbiamo identificare il logger per cui desideriamo cambiare il livello di log. Questo può essere fatto esplorando i MBean esposti dall’applicazione Java e cercando il MBean java.util.logging:type=Logging (vedi figura a seguire).

Figura 5 – MBean java.util.logging:type=Logging in JDK Mission Control

Supponiamo di aver identificato il logger it.dontesta.eventbus.consumers.events.handlers.Dispatcher per cui vogliamo cambiare il livello di log a DEBUG. Prima di procedere con la modifica, verifichiamo il livello di log corrente (che dovrebbe essere INFO) per il logger utilizzando il metodo getLoggerLevel del MBean java.util.logging:type=Logging (vedi figura a seguire) e successivamente cambieremo il livello di log utilizzando il metodo setLoggerLevel.

Per accedere alle operazioni dello specifico MBean, fare clic sul nome del MBean e selezionare la voce Operations per visualizzare i metodi disponibili.

Figura 6 – Verifica del livello di log attuale per il logger it.dontesta.eventbus.consumers.events.handlers.Dispatcher

Dal risultato visibile dalla precedente figura, il livello di log attuale per il logger it.dontesta.eventbus.consumers.events.handlers.Dispatcher è INFO. Per cambiarlo a DEBUG, dobbiamo utilizzare il metodo setLoggerLevel del MBean java.util.logging:type=Logging specificando il nome del logger e il nuovo livello di log (vedi figura a seguire).

Figura 7 – Cambio del livello di log a DEBUG per il logger it.dontesta.eventbus.consumers.events.handlers.Dispatcher

Una volta cambiato il livello di log, l’applicazione Java inizierà a registrare i log con il nuovo livello di dettaglio senza necessità di riavviare l’applicazione. Questo permette di gestire dinamicamente i log dell’applicazione Java in tempo reale, adattandoli alle esigenze di monitoraggio e debug. A seguire un esempio di log registrato dall’applicazione Java con il nuovo livello di log DEBUG.



# Log output with DEBUG level
oc logs -f eventbus-logging-filter-jaxrs-66586f8dc4-5k7t4

# Output
2024-06-09 14:23:38,806 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Sending event message to target virtual address: nosql-trace
2024-06-09 14:23:38,807 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Sending event message to target virtual address: queue-trace
2024-06-09 14:23:38,807 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Received response from target virtual address: nosql-trace with result: Documents inserted successfully with Id BsonObjectId{value=6665baea279ab051ec5bce3d}
2024-06-09 14:23:38,808 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Received response from target virtual address: queue-trace with result: Message sent to AMQP queue successfully!
2024-06-09 14:23:38,808 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Received response from target virtual address: nosql-trace with result: Documents inserted successfully with Id BsonObjectId{value=6665baea279ab051ec5bce3e}
2024-06-09 14:23:38,808 DEBUG [it.don.eve.con.eve.han.Dispatcher] (vert.x-eventloop-thread-0) Received response from target virtual address: queue-trace with result: Message sent to AMQP queue successfully!

Console 5 – Output dei log con livello DEBUG

Conclusioni

In questo articolo abbiamo esplorato come utilizzare Java JMX in ambienti container, in particolare su Red Hat OpenShift. Abbiamo visto come configurare JMX in un’applicazione Java basata su Quarkus e come connettersi a un server JMX utilizzando JDK Mission Control per monitorare le prestazioni, gestire le risorse, e cambiare il livello di log a runtime.

Vorrei sottolineare il fatto che JMX può essere configurato in modo indipendente dal framework o dalla piattaforma utilizzata, e può essere utilizzato per monitorare e gestire qualsiasi applicazione Java.

La possibilità di utilizzare JMX risulta particolarmente utile quando per esempio siamo ancora in fase di sviluppo o in fase di test, (non abbiamo un strumento di APM completo) e dobbiamo monitorare le prestazioni e le risorse dell’applicazione Java, o quando dobbiamo cambiare il livello di log a runtime per debuggare un problema specifico.

Ho volutamente scelto di utilizzare Java Mission Control perché questo apre la strada all’uso di Java Flight Recorder (JFR) che è uno strumento molto potente per il monitoraggio delle prestazioni e l’analisi dei dati. Inoltre, Mission Control è uno strumento gratuito e open source, disponibile per tutti gli sviluppatori Java.

In tema di Java Flight Recorder, Red Hat sponsorizza il progetto Cryostat, che è un’alternativa open source a Mission Control, che consente di utilizzare Java Flight Recorder in ambienti containerizzati. Invito a leggere l’articolo Monitoring Quarkus JVM Mode With Cryostat per ulteriori dettagli.

L'articolo Come usare Java JMX in ambienti container sembra essere il primo su Antonio Musarra's Blog.

Raspberry Pi e Smart Card Mifare Classic 1K: Realizzare un sistema di accesso

Antonio Musarra — Fri, 11 Mar 2022 18:36:08 +0000

Le Smart Card fanno parte ormai da tempo del nostro quotidiano: dalla SIM (Subscriber Identity Module) del cellulare, alla carta di credito, come sistema di fidelizzazione, per accedere ai locali e come mezzo per fruire dei servizi della pubblica amministrazione.

Integrare sistemi di autenticazione basati su Smart Card nei propri sistemi e applicazioni, credo che possa essere un’attività molto interessante per chi programma e l’aspetto a mio avviso più coinvolgente è la vicinanza con i “pezzi di ferro”.

In questo articolo vedremo come mettere insieme Raspberry Pi, modulo da quattro relè, lettore di Smart Card e MIFARE Classic 1K contactless Smart Card per poi armonizzare il tutto con il software necessario allo scopo di realizzare un sistema di accesso.

Per lo sviluppo del progetto è necessario toccare un numero considerevole di argomenti e cercherò di trattare i principali con il giusto livello di profondità, in caso contrario l’articolo assumerebbe delle dimensioni considerevoli. Mi impegnerò a lasciare tutti i riferimenti utili per ogni vostro approfondimento.

A questo punto direi d’iniziare; mettetevi comodi e munitevi della giusta concentrazione perché la lettura di questo articolo sarà abbastanza impegnativa ma spero interessante.

1. Descrizione dello scenario

Credo d’intuire quale potrebbe essere il vostro pensiero in questo momento. Che tipo di Sistema di Accesso andremo a realizzare?

Vorrei implementare qualcosa che tutti almeno una volta abbiamo usato. Un comunissimo scenario di Sistema di Accesso lo abbiamo vissuto tutti accedendo alla nostra camera di albergo grazie alla Smart Card (o chiave elettronica) consegnata al momento dell’accoglienza. La figura a seguire mostra lo schema hardware della soluzione che andremo a realizzare.

Figura 1 – Schema hardware della soluzione di accesso (Smart Card Reader icon da https://www.smartcardfocus.com/)

La MIFARE Classic® 1K contactless si basa su NXP MF1 IC S50. Questa tipologia di carta è una buona scelta per applicazioni classiche come la biglietteria dei trasporti pubblici, servizi di fidelizzazione e può essere utilizzata anche per molte altre applicazioni come sistemi di apertura porte e simili.

Il lettore di Smart Card deve essere conforme a standard indicati nello schema di figura 1. Nel mio caso ho utilizzato il lettore CIE Bit4id miniLector collegato al Raspberry Pi tramite la porta USB. Il nome tecnico del lettore che ho utilizzato è: BIT4ID miniLector AIR NFC v3.

Al Raspberry Pi è collegato un modulo di quattro relè gestito tramite le porte GPIO. Nel nostro scenario, i relè rappresentano gli attuatori necessari per aprire le porte dell’hotel dove siamo ospiti.

Appurato che il nostro scenario è quello di un sistema di accesso per consentire agli ospiti di un hotel di accedere alle proprie stanze attraverso una Smart Card, vediamo quali sono i due processi che portano al raggiungimento di questo obiettivo.

La figura 2 illustra il processo semplificato (in notazione BPMN) di ciò che accade quando un ospite viene ricevuto dal personale dell’hotel. Dell’intero processo, solo il Service Task (indicato in rosso) sarà l’oggetto dell’implementazione del software.

Figura 2 – Processo semplificato di accoglienza dell’ospite in hotel.

Il processo di figura 3 mostra invece cosa succede quando l’ospite chiede di entrare nella sua camera tramite l’uso della chiave elettronica appoggiandola sul lettore. Dell’intero processo, solo i Service Task (indicati in rosso) saranno oggetto dell’implementazione del software.

Figura 3 – Processo di accesso alla stanza

Credo che per tutti i processi illustrati (in figura 2 e figura 3) in notazione BPMN siano abbastanza esplicativi da non richiedere ulteriori approfondimenti. I Service Task sono gli elementi che saranno oggetto di nostro interesse per l’implementazione del software che fin da questo momento possiamo dividere in due macro componenti le cui responsabilità devono essere:

il setup della Smart Card (o chiave elettronica) in fase di registrazione dell’ospite presso la struttura alberghiera. All’interno della Smart Card sarà memorizzato l’identificativo di un documento di riconoscimento dell’ospite, sul database del sistema di gestione dell’albergo saranno invece memorizzati i dati anagrafici insieme ad altri dati necessari per associare la chiave elettronica all’ospite e alla stanza a lui assegnata;
la verifica che la chiave elettronica sia abilitata e associata all’ospite e alla stanza a cui consentire l’accesso.

2. Qualche dettaglio sulla MIFARE Classic 1K

MIFARE è un marchio registrato di NXP Semiconductors. I prodotti MIFARE sono circuiti integrati ampiamente utilizzati per l’utilizzo in Smart Card senza contatto e molte altre applicazioni in tutto il mondo. La gamma MIFARE comprende circuiti integrati per la realizzazione di tessere contactless e lettori per la comunicazione con esse.

Il nome MIFARE racchiude diversi tipi di Smart Card senza contatto, quella utilizzata in questo scenario rientra nel tipo Classic. Si tratta di schede di memoria a logica cablata che solo parzialmente sono conformi allo standard ISO/IEC 14443A (caratteristiche fisiche, potenza e interfaccia del segnale radio, inizializzazione e anticollisione), poiché utilizzano un set di comandi proprietari invece del protocollo ISO/IEC 14443-4 di alto livello e non sono conformi al formato frame ISO/IEC 14443-3 nelle comunicazioni crittografate. Usano un protocollo di sicurezza proprietario NXP (CRYPTO1) per l’autenticazione e la crittografia che è stato rotto nel 2008.

Dopo l’ultima frase immagino che vi stiate domandando: perché scrivere allora un articolo su questa Smart Card? La risposta è abbastanza semplice. Questa è una delle Smart Card a sola memoria più diffuse e semplici da usare, e per il tipo di scenario qui presentato, la possibilità di scoprire “facilmente” la chiave di autenticazione è secondario, inoltre, questo è articolo prettamente didattico.

La MIFARE Classic 1K dispone di 1024 byte di memoria (EEPROM) suddivisa in 16 segmenti; ogni settore è protetto da due chiavi che vengono chiamate A e B. In tutti i tipi di carta, 16 byte a settore sono riservati alle chiavi e alle condizioni d’accesso e non possono essere utilizzati per i dati dell’utente; inoltre, i primi 16 byte contengono il numero di serie univoco e di sola lettura. In questo modo la memoria disponibile si riduce a 752 byte.

Data l’altissima diffusione di questa tipologia di Smart Card e le versioni “cinesi” esistenti, dubito che non ci siano numeri di serie duplicati, visto anche che i byte dedicati alla memorizzazione del numero di serie sono quattro.

Figura 4 – Struttura della memoria della Mifare Classic 1K (dal datasheet NXP MIFARE Classic EV1 1K https://www.nxp.com/docs/en/data-sheet/MF1S50YYX\_V1.pdf)

Prima di poter compiere operazioni di lettura o scrittura sui blocchi di memoria, è necessario eseguire prima un’autenticazione tramite la chiave del settore del blocco. In genere tutte le chiavi (A e B) sono impostate su valore FFFFFFFFFFFFh in fase di produzione del chip (e in ogni caso la documentazione fornita al momento dell’acquisto fornisce indicazioni sulle chiavi di accesso e su come eseguire la modifica).

La tabella mostrata in figura 5 rappresenta la mappa della memoria con in evidenza il range degli indirizzi per i Data Blocks e i _Trailer Block _per ogni settore. Questa mappa sarà utile nel momento in cui dovremo leggere e scrivere sui data blocks.

Figura 5 – Memory Map della MIFARE Classic 1K completa di range d’indirizzi dei blocchi

Dopo questa sorvolata sulle caratteristiche principali della MIFARE Classic 1K che sono di nostro interesse per il nostro obiettivo, possiamo andare avanti ed esplorare il modo su come comunicare con la carta per le operazioni di autenticazione, lettura e scrittura.

3. I misteriosi pacchetti APDU

La comunicazione delle informazioni tra la carta e il lettore è resa possibile grazie allo scambio di pacchetti detti APDU (Application Protocol Data Unit); essi rappresentano l’unità di comunicazione tra il lettore e la carta e la loro struttura è ben definita da ISO/IEC 7816-4 Organization, security and commands for interchange.

Esistono due tipi di APDU: quelli di comando e quelli di risposta. I primi richiedono un set di attributi attraverso cui il lettore è in grado di sapere quali operazioni compiere e quali dati inviare, i secondi contengono il risultato dell’operazione richiesta con in coda l’esito dell’operazione.

La tabella di figura 6 mostra la struttura dei comandi APDU che attraverso il lettore di Smart Card possiamo inviare alla carta MIFARE.

Figura 6 – Struttura dei comandi APDU

La tabella di figura 7 mostra un esempio di comando APDU per ottenere l’UID della MIFARE Classic 1K, la cui lunghezza è pari a 4 byte (vedi attributo Le). A fronte dei comandi inviati, riceviamo sempre una risposta che ha la struttura indicata dalla tabella di figura 8.

Figura 7 – Comando per ottenere l’UID della Smart Card MIFARE Classic 1K

Figura 8 – Struttura di risposta APDU

La tabella di figura 9 mostra la risposta ottenuta a fronte del comando APDU per richiedere l’UID (vedi figura 7) la cui lunghezza dell’UID è pari a 4 byte più 2 byte che segnalano l’esito del comando. L’UID è restituito con il byte meno significativo (LSB) a sinistra e quello più significativo (MSB) a destra (quindi usa il sistema little-endian).

Figura 9 – Risposta del comando APDU per ottenere l’UID della MIFARE Classic 1K

Confrontando i valori di SW1 e SW2 (Status Word) con quelli riportati dalla tabella mostrata in figura 10 è possibile evincere se l’esecuzione del comando è andato a buon fine.

Attenzione. I valori di SW1 e SW2 fanno riferimento al comando per ottenere l’UID della carta; questi valori potrebbero essere diversi per altre classi di comando, in particolare nei casi di errore.

Figura 10 – Codici di risposta APDU comando UID

Per maggiori dettagli sui comandi ed eventuali estensioni, consiglio sempre di consultare il datasheet della MIFARE Classic 1K. I comandi APDU di nostro interesse per implementare lo scenario descritto nella parte introduttiva dell’articolo, sono:

comando per ottenere l’UID della carta;
comando per leggere i dati da un determinato settore e blocco;
comando per scrivere dati su un determinato settore e blocco della carta.

4. Cos’è l’Answer to reset o ATR

La prima risposta di una Smart Card inserita in un lettore si chiama ATR (Answer to reset). Lo scopo dell’ATR è descrivere i parametri di comunicazione supportati, la natura e lo stato della carta. L’ottenimento di un ATR viene spesso utilizzato come prima indicazione che questa sia operativa, e il suo contenuto viene esaminato come prima prova che sia del tipo appropriato per un determinato utilizzo. Il lettore di Smart Card, il driver del lettore e il sistema operativo utilizzeranno questi parametri per stabilire una comunicazione con la scheda.

L’ATR è descritto dallo standard ISO/IEC 7816-3. I primi byte dell’ATR descrivono i parametri elettrici, seguiti da byte che descrivono le interfacce di comunicazione disponibili e i rispettivi parametri. Questi byte di interfaccia sono quindi seguiti da byte storici che non sono standardizzati e sono utili per trasmettere informazioni proprietarie come il tipo di scheda, la versione del software integrato o lo stato della scheda. Infine questi byte storici sono eventualmente seguiti da un byte di checksum.

Potremmo riassumere che l’ ATR contiene “un sacco di dati” che ci dicono vita morte e miracoli della Smart Card. Per esempio, scopriamo di più sull’ATR 3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 00 01 00 00 00 00 6A utilizzando il tool Smart card ATR parsing sviluppato da Ludovic Rousseau. La figura a seguire mostra le informazioni estratte alcune delle quali:

tipo di Smart Card e in questo caso si tratta della MIFARE Classic 1K;
produttore della Smart Card e in questo caso NXP;
standard tecnologici;
protocolli di comunicazione e in questo caso T=0 (orientato al byte, che costituisce l’unità minima di informazione scambiata) e T=1 (orientato al blocco di byte, grazie al quale la velocità di accesso è maggiore), protocollo solitamente utilizzato di default quando disponibile e supportato anche dal lettore.

Figura 11 – Dettagli estratti sull’ATR della Smart Card MIFARE Classic 1K

Ludovic Rousseau ha fatto un ottimo lavoro tracciando dal 2002 un gran numero di ATR costruendo un vero e proprio database. Così facendo è possibile identificare una Smart Card dato il suo ATR. All’interno della lista sono presenti anche le “nostrane Smart Card” come la TS-CNS (Tessera Sanitaria – Carta Nazionale Servizi) e CIE (Carta d’Identità Elettronica). È possibile utilizzare il comando pcsc_scan per ottenere informazioni di dettaglio sulla Smart Card, le stesse illustrate in figura 11. La figura 12 mostra l’output del comando menzionato da cui è possibile dedurre che la Smart Card analizzata è una CIE.

Figura 12 – Esempio di output del comando pcsc_scan che mostra le informazioni estratte dalla Smart Card, in questo caso CIE

5. Requisiti Hardware

Realizzare lo scenario descritto richiede il recupero di una serie di “pezzi di ferro”.

Per quanto riguarda il Raspberry Pi è possibile optare per la versione con 4GByte di RAM ma è importante installare come sistema operativo l’ultima versione di Raspberry Pi OS affinché sia supportato il lettore di Smart Card Bit4id miniLector CIE e questo grazie alla versione 1.4.34-1 della libreria libccid (check via apt info libccid).

Figura 13 – Dettaglio del driver libccid necessario per interoperabilità tra Sistema Operativo e lettore di Smart Card

Nel caso in cui abbiate già un lettore di Smart Card o vogliate acquistarne un diverso modello, consiglio di consultare la lista dei lettori di Smart Card supportati dal driver libccid.

6. Requisiti Software

Così come abbiamo bisogno dell’hardware, è necessario che siano soddisfatti una serie di requisiti software, quali:

Raspberry Pi OS (64bit)
Python 3.9.x (distribuito e installato di default con Raspberry Pi OS)
Docker 20.10.12
Development Tools (make, gcc) (install or update via sudo apt install build-essential)

Per questo genere di scenari non è assolutamente necessario provvedere all’installazione del sistema operativo in versione Desktop, consiglio pertanto di preparare e usare l’immagine di Raspberry Pi OS Lite (64bit). Per coloro che avessero bisogno di una guida su come installare questo sistema operativo, consiglio di seguire la guida ufficiale Installing the Operating System.

L’installazione di Docker potrebbe essere anche opzionale; personalmente preferisco installare il database in forma di container.

7. Schema elettrico della soluzione

Una volta ottenuto l’hardware (indicato in precedenza), possiamo procedere con il collegamento del modulo dei quattro relè all’interfaccia GPIO e alimentazione del Raspberry Pi con l’ausilio dei jumper femmina-femmina.

La figura 14 mostra lo schema elettrico di collegamento tra il modulo a quattro relè e il Raspberry Pi. Ricordo che il lettore di Smart Card è collegato via USB al Raspberry Pi. Utilizzando i jumper e seguendo lo schema, il risultato sarà assicurato. È preferibile eseguire l’operazione di collegamento lasciando il proprio Raspberry Pi spento e scollegato dalla fonte di alimentazione.

Figura 14 – Schema elettrico di collegamento tra il Raspberry Pi e il modulo da quattro relè

Per ogni dubbio sulla disposizione dei pin del connettore J8 del Raspberry, consultare l’output del comando pinout (vedi figura 15) prima di procedere con l’operazione di collegamento, oppure, puntate il vostro browser su pinout.xyz.

Figura 15 – Output del comando pinout, utile per verificare la piedinatura del GPIO e altre informazione sul layout hardware e componenti

8. Progettare il software

È arrivato il momento di saltare dall’hardware al software cercando di delineare ciò che dovremo implementare con l’obiettivo di soddisfare i requisiti espressi in forma di diagrammi BPMN (vedi figura 2 e figura 3). Ricordo che solo quanto espresso dai Service Task deve essere releazzato in forma di software.

Cerchiamo di identificare il cosa dovrà essere soddisfatto dal punto di vista funzionale per poi passare al come gli aspetti funzionali dovranno essere implementati. La tabella mostrata in figura 16 (trasposizione di una classica Mind Map), descrive gli aspetti funzionali che il software che andremo a realizzare deve implementare.

Figura 16 – Mind Map sugli aspetti funzionali che il software dovrà implementare

Il software deve prevedere due entry point, ed esattamente quelli indicati all’interno della tabella di figura 16, le cui responsabilità devo essere:

Setup Smart Card : entry point la cui principale responsabilità è quella di “formattare” la Smart Card (o chiave elettronica) con i dati personali dell’ospite e in questo caso il numero del documento d’identità, inoltre, creare l’associazione tra chiave elettronica, ospite e stanza a lui assegnata. Una volta eseguiti i task di questo entry point (vedi figura 16), la Smart Card potrà essere consegnata all’ospite.
Gestione Accesso Porte entry point la cui principale responsabilità è quella di garantire l’accesso (apertura della porta della stanza) solo a coloro che hanno in possesso una Smart Card valida, aggiornando i dati di accesso sul database. La Mind Map di figura 16 mostra i singoli task che devono essere eseguiti da questo specifico entry point.

Più volte è stato fatto riferimento all’esistenza di un database, bene, adesso cerchiamo di capire quali sono i dati da esso trattati e le responsabilità dei due entry point in merito al trattamento di questi dati. La tabella di figura 17 mostra la struttura dati del documento che descrive l’associazione ospite, Smart Card e stanza assegnata e traccia i dati degli eventi d’inizializzazione e accesso.

Figura 17 – Struttura dati che descrive l’associazione ospite, smart card e stanza assegnata e traccia i dati degli eventi d’inizializzazione e accesso

La tabella mostra un’informazione importante per ogni attributo del documento, ovvero, lo scope, quindi l’entry point, con evidenza del diritto di accesso: (r -read) lettura o (w – write) scrittura.

9. Implementare il software

Adesso che il cosa ** è chiaro, vediamo il **come , rispondendo alle domande a seguire:

Quale linguaggio usare per implementare lo scenario che abbiamo descritto all’inizio dell’articolo? Python
Esiste qualche libreria Python per la costruzione di applicazioni basate su Smart Card? Pyscard
Quale tipo di database usare per la memorizzazione dei dati? MongoDB (NoSQL database)
Esiste qualche libreria Python per operare con MongoDB? PyMongo
Esiste qualche libreria Python per interagire con l’interfaccia GPIO del Raspberry Pi? RPi.GPIO

Da questa lista le cose da fare sono parecchie e lo spazio per vederle tutte nel dettaglio in questo articolo non c’è. Direi quindi di focalizzare la nostra attenzione sui componenti da realizzare rimanendo ad alto livello, senza scendere nello specifico del codice.

Non vi allarmate! Il progetto è già stato sviluppato prima di scrivere questo articolo e disponibile sul mio repository GitHub Smart Card Contactless Raspberry Pi.

9.1 Cos’è Pyscard

Pyscard , Python Smart Card library, è un modulo Python che aggiunge il supporto per le Smart Card facilitando la costruzione di applicazioni che hanno la necessità di utilizzare la tecnologia delle Smart Card.

Pyscard supporta la piattaforma Microsoft Windows utilizzando i componenti Microsoft Smart Card Base, Linux e macOS utilizzando PCSC-lite. Il diagramma di figura 18 mostra l’architettura Pyscard (box in verde). Il modulo smartcard.scard è il wrapper di WinSCard API (smart card base components). Il modulo smartcard è un vero e proprio framework costruito su PC/SC API.

Figura 18 – Architettura di Pyscard

Pyscard sarà di aiuto per:

Eseguire la connessione al lettore di Smart Card e alla MIFARE Classic 1K
Filtrare le connessioni alle sole MIFARE Classic 1K tramite l’ATR
Inviare i comandi APDU
Ricevere le risposte ai comandi APDU
Intercettare gli eventi di aggiunta e rimozione Smart Card dal lettore

9.2 Struttura del progetto software

Adesso che abbiamo visto dalla superficie cos’è Pyscard e per cosa sarà utile, cerchiamo di disegnare la struttura del nostro progetto che implementerà lo scenario introdotto a inizio articolo.

Il diagramma (in notazione UML) di figura 19 mostra package, component e classi utilizzati per l’implementazione dello scenario che abbiamo descritto a inizio articolo. Gli elementi del diagramma del nostro progetto sono quelli evidenziati con il colore giallo ocra e in particolare:

Classi
- ManageRelay (manage_relay.py). Classe che gestisce attraverso l’interfaccia GPIO l’attivazione e disattivazione dei quattro relè, nonché l’inizializzazione della stessa interfaccia GPIO.
- SmartCardAccessCrud (smart_card_access_crud.py). Classe che gestisce le operazioni CRUD sul database NoSQL MongoDB.
- MifareClassicInterface (mifare_interface.py). Classe che gestisce la comunicazione con il lettore di Smart Card e di conseguenza d’interagire con la Smart Card connessa. Le operazioni gestite sono: autenticazione, lettura ATR, lettura UID, lettura dalla memoria della carta e scrittura sulla memoria della carta.
Component
- Setup Smart Card (setup_smart_card.py). Script Python che rapprensentata l’entry point responsabile del setup della Smart Card e memorizzazione dei dati anagrafici dell’ospite sul database MongoDB. Questo script deve ricevere in input i parametri necessari per eseguire il setup della Smart Card.
- Access via Smart Card (access_via_smart_card.py). Script Python che rappresenta l’entry point responsabile di governare l’apertura delle porte (attraverso l’attivazione dei relè) sulla base della validazione dei dati estratti dalla Smart Card. Questo script deve ricevere in input la chiave di autenticazione della Smart Card.

Figura 19 – Package/Component/Class diagram del progetto Smart Card Contactless Raspberry Pi

Il package smartcard (in verde) fa parte di Pyscard, e i componenti all’interno sono utilizzati per sfruttare il monitoraggio delle Smart Card. Utilizzando l’interfaccia CardObserver siamo in grado di poter sapere quando la Smart Card viene aggiunta (appoggiata sul lettore) o rimossa (dal raggio di azione del segnale RF).

Il sequence diagram di figura 20 descrive lo scenario del setup della Smart Card (vedi Figura 2 – Processo semplificato di accoglienza dell’ospite in hotel), mostrando le azioni principali e gli eventuali flussi alternativi. Sempre da questo diagramma possiamo vedere le relazioni che intercorrono, in termini di messaggi, tra i vari attori, quest’ultimi sono stati descritti in precedenza e mostrati nel diagramma di figura 19.

Le azioni decisamente più importanti sono quelle che riguardano l’invio dei comandi APDU, che riassumendo sono:

I link della precedente lista riportano direttamente sul metodo specifico della classe Mifare Classic Interface all’interno del quale è specificato il contenuto dell’APDU inviata.

Figura 20 – Diagramma di sequenza dell’entry point Setup Smart Card

Nella fase di setup della Smart Card, prima di inserire i dati anagrafici dell’ospite sul database, viene eseguita la query utilizzando il filtro {"smartCardId": f"{uid}", "documentId": f"{identification_number}"} , in modo che sia possibile verificare che non esista già un documento con l’associazione smartCardId e documentId (fare riferimento allo step 33 del sequence diagram di figura 20).

Il sequence diagram di figura 21 descrive lo scenario di Accesso alla stanza tramite Smart Card (vedi Figura 3 – Processo di accesso alla stanza), mostrando le azioni principali e gli eventuali flussi alternativi. Sempre da questo diagramma possiamo vedere le relazioni che intercorrono, in termini di messaggi, tra i vari attori, quest’ultimi sono stati descritti in precedenza e mostrati nel diagramma di figura 19.

In questo diagramma, tra gli attori in gioco abbiamo anche il componente Card Monitor di Pyscard, che abbiamo utilizzato per aggiungere la nostra interfaccia Mifare Classic Interface come observable, in questo modo il Card Monitor richiamerà il metodo update(self, observable, actions) nel momento in cui si verificheranno gli eventi di aggiunta o rimozione della Smart Card. Il metodo update implementa quando descritto in Figura 16 – Mind Map sugli aspetti funzionali che il software dovrà implementare, di cui le azioni sono evidenti sul sequence diagram a seguire.

Figura 21 – Diagramma di sequenza per l’entry point Access via Smart Card

I dati sono estratti dal database MongoDB utilizzando il filtro {"smartCardId": f"{uid}", "documentId":f{identification_number}", "smartCardEnabled": "true"}, nel caso non ci siano documenti che rispettino questo filtro, il sistema negerà l’accesso, alternativamente, sarà aggiornato il documento su MongDB e attivato il relè corrispondente al numero della stanza associato all’ospite (fare riferimento allo step 1.7 del sequence diagram di figura 21).

Molto bene! Una volta descritti i sequence diagram dei nostri due scenari, direi che potremmo passare all’azione, ovvero, eseguire il deploy dell’applicazione sul Raspberry Pi 4.

10. Deploy e test del software sul Raspberry Pi

Ci siamo! È arrivato il momento d’installare il progetto software sul Raspberry Pi e verificare che tutto funzioni così per com’è stato ideato. Il deployment diagram della figura a seguire mostra tutti i componenti del nostro sistema di accesso.

Figura 22 – Deployment diagram del sistema di accesso via Smart Card Contactless su Raspberry Pi

Assumiamo a questo punto che tutti i requisiti software indicati in precedenza siano tutti soddisfatti (fare riferimento a 6. Requisiti Software). Per installare il progetto software sul Raspberry Pi occorre seguire i seguenti passi:

accedere in ssh alla Raspberry Pi;
decidere una locazione dove installare il progetto software. Non ci sono restrizioni; nel mio caso ho preferito usare la home del mio account;
eseguire il clone del repository del progetto;
eseguire l’installazione delle dipendenze Python.


# Accesso al Raspberry Pi via SSH
$ ssh amusarra@192.168.238.169

# Clone del repository GitHub del progetto
$ git clone https://github.com/amusarra/smartcard-contactless-raspberry-pi.git

# Installazione delle dipendenze Python
$ cd smartcard-contactless-raspberry-pi
$ make

Il comando make non fa altro che procedere con l’installazione delle dipendenze Python specificate sul file requirements.txt utilizzando pip. La figura 23 mostra il processo d’installazione delle dipendenze Python sul Raspberry Pi. Ultimata l’installazione, è possibile eseguire il test vero e proprio del software. Prima di eseguire il test occorre accertarsi che dal punto di vista hardware sia tutto regolare controllando tutti i collegamenti (vedi schema elettrico), compreso il collegamento del lettore di Smart Card via USB.

Figura 23 – Installazione delle dipendenze Python tramite il comando make

Ormai dovremmo sapere quali sono gli entry point da utilizzare, sia quello per il setup della Smart Card, sia quello che avvia il controllo degli accessi. Entrambi gli entry point, quindi gli script Python, devono essere avviati specificando una serie di parametri. Le due tabelle a seguire mostrano i parametri d’input dei due script: setup_smart_card.py e access_via_smart_card.py.

Figura 24 – Tabella dei parametri d’input per lo script Python setup_smart_card.py

Figura 25 – Tabella dei parametri d’input per lo script Python access_via_smart_card.py

La figura 26 mostra un esempio di come si presenta l’help in linea dello script setup_smart_card.py attivato utilizzando l’opzione --help (o -h).

Figura 26 – Come si presenta l’help in linea dello script setup_smart_card.py

A questo punto siamo davvero pronti. Il primo step è la registrazione della Smart Card per il nuovo ospite Mario Rossi il cui documento d’identità ha il numero MU589876XD e al quale assegnamo la stanza numero due.

Prima di avviare la registrazione, prendiamo la Smart Card poggiandola sul lettore. Il comando da avviare per la registrazione è: ./setup_smart_card.py -a FFFFFFFFFFFF -i MU589876XD -s --firstname Mario --lastname Rossi -r 2

Se tutto va per il verso giusto, l’output ottenuto in console dovrebbe essere quello mostrato dalla figura a seguire.

Figura 27 – Registrazione Smart Card MIFARE Classic 1K con i dati dell’ospite

Dopo la registrazione della Smart Card e la consegna all’ospite, quest’ultimo può usare la Smart Card per accedere alla propria stanza assegnata in fase di registrazione, che ricordo essere la numero due.

Figura 28 – Documento registrato su MongoDB a fronte del processo di registrazione Smart Card

Avviamo adesso il programma del controllo degli accessi utilizzando il comando: ./access_via_smart_card.py -a FFFFFFFFFFFF. Avviato il programma, questo resta in attesa di leggere la Smart Card. Poggiando la Smart Card registrata poc’anzi, l’ospite dovrebbe riuscire ad accedere alla sua stanza, così come mostra la figura a seguire.

Figura 29 – Richiesta di accesso via Smart Card MIFARE Classic 1K

L’output mostrato dalla figura 29 evidenzia anche un accesso non riuscito perché in questo caso la Smart Card presentata non è registrata sul sistema. Gli screencast a seguire mostrano i due entry point in azione: setup_smart_card.py e access_via_smart_card.py.

Screencast 1 – Processo di registrazione Smart Card in azione

Screencast 2 – Processo di accesso alla stanza via Smart Card in azione

11. Conclusioni

Ringrazio tutti voi per essere arrivati “incolumi” alla fine di questo lungo articolo sperando di non essere stato noioso e di essere riuscito nell’intento di rendere interessanti gli argomenti trattati oltre che a spingere la vostra curiosità in avanti.

Potrei lasciarvi un compito per casa: come aprire la porta di casa utilizzando la propria CIE o TS-CNS.

Mi sarebbe piaciuto approfondire maggiormente alcuni degli argomenti trattati, come per esempio il framework Pyscard e alcune sezioni del codice Python sviluppato. Nell’attesa di pubblicare altri articoli di approfondimento, vi chiedo di scrivere le vostre impressioni, esperienze o altro di cui vorreste approfondire, utilizzando i commenti all’articolo oppure condividendo attraverso i classici canali social.

12. Risorse

Come di consueto lascio una serie di risorse che ritengo utili ai fini dell’approfondimento degli argomenti trattati nel corso di questo articolo.

Attuatori per maker – https://amzn.to/3slHmE9
Raspberry Pi. La guida completa – https://amzn.to/2RpYZWh
Docker: Sviluppare e rilasciare software tramite container – https://amzn.to/3tiyO1W di Serena Sensini
Valutiamo se continuare a usare Docker o passare a Podman – https://www.theredcode.it/podman/what-is-podman/
Pillole di Docker – https://www.youtube.com/watch?v=wAyUdtQF05w di Mauro Cicolella
Raspberry PI GPIO – Tutti i segreti del pinout – https://www.moreware.org/wp/blog/2021/04/09/raspberry-pi-gpio-tutti-i-segreti-del-pinout/
Smart cards – A short illustrated guide ( Feb. 2022) – https://www.thalesgroup.com/en/markets/digital-identity-and-security/technology/smart-cards-basics
Hacking Mifare Classic Cards – https://www.blackhat.com/docs/sp-14/materials/arsenal/sp-14-Almeida-Hacking-MIFARE-Classic-Cards-Slides.pdf
How to Crack Mifare Classic Cards – https://firefart.at/post/how-to-crack-mifare-classic-cards/
A Practical Attack on the MIFARE Classic – https://arxiv.org/pdf/0803.2285.pdf
ACR122U Application Programming Interface – https://www.acs.com.hk/download-manual/419/API-ACR122U-2.04.pdf

L'articolo Raspberry Pi e Smart Card Mifare Classic 1K: Realizzare un sistema di accesso sembra essere il primo su Antonio Musarra's Blog.

(English) How to use Oracle Database 19c Pre-Built Developer VM

Antonio Musarra — Sun, 09 Jan 2022 13:02:07 +0000

Ci spiace, ma questo articolo è disponibile soltanto in Inglese Americano. Per ragioni di convenienza del visitatore, il contenuto è mostrato sotto nella lingua alternativa. Puoi cliccare sul link per cambiare la lingua attiva.

How many times have we faced the arduous setup of an Oracle Database instance for our development environment and “spitting blood”?

I guess these times have been too many, here is a good reason to start using what Oracle makes available to us developers, that is, the Pre-Built Developer VMs for Oracle VM VirtualBox.

In the course of this article, we will see how to setup an Oracle Database 19c VM from the Database Virtual Box Appliance that Oracle provides.

1. Requirements

Before starting, it is necessary to verify that the following requirements are met.

Operating System that supports Virtual Box version 6.x
At least 2 GB of RAM
At least 15 GB of storage space
At least 2 GHz process
Administrator privileges

The reference Virtual Appliance is dated 20/06/2019 whose content is indicated below.

Oracle Linux 7
Oracle Database 19.3
Oracle SQL Developer 19.1
Oracle Application Express 19.1
Hands-On-Labs (accessible via the Toolbar Menu in Firefox)
- Oracle REST Data Services 19.1
- Oracle SQL Developer Data Modeler 19.1
- Oracle XML DB

Attention! This Virtual Appliance is for use in development/test environments only, it should not be used in a pre-production or production environment.

2. Virtual Appliance Setup

The setup procedure consists of some steps summarized below:

Download and install Oracle VM VirtualBox
Oracle DB Developer VM Download
Importing the Virtual Appliance on Oracle VM VirtualBox
Starting and testing the Virtual Appliance

2.1 Download and install Oracle VM VirtualBox

From the Oracle VM VirtualBox home page, you can download the binaries for your operating system. In my case, I proceeded to download the version for macOS.

The installation procedure is very simple and is not the subject of this article; in case of difficulty or further information, refer to the User Manual. The reference version for this article is 6.1.30. Figure 1 shows detailed information about the version installed on my MacBook Pro with macOS Monterey (version 12.1).

Figure 1 – Information on VirtualBox

2.2 Downloading Oracle DB Developer VM

From the Oracle DB Developer VM link you can access the DeveloperDaysVM2019-05-31_20.ova file which contains the Virtual Appliance. The OVA/OVF format is a standard for the packaging and distribution of Virtual Appliances.

Downloading the file requires the availability of an Oracle account (which you can create for free if necessary). The file size is over 7 GByte, so I recommend checking the file checksum at the end of the download. In Console 1, one of the ways for hash verification using the md5 and sha commands available on macOS, Unix / Linux and Windows 10 is identified.

MD5 (sum): 20b5a5bd91cfe9d4f5acf5128f06146e
SHA1: e0b9f8af8158664139b9ca970c3500752fc15fd2



# Verify the checksum MD5 and SHA1 on macOS
$ md5 DeveloperDaysVM2019-05-31_20.ova
$ shasum DeveloperDaysVM2019-05-31_20.ova

# Verify the checksum MD5 and SHA1 on Unix/Linux
$ md5sum DeveloperDaysVM2019-05-31_20.ova
$ sha1sum DeveloperDaysVM2019-05-31_20.ova

# Verify the checksum MD5 and SHA1 on Windows 10
> certutil -hashfile DeveloperDaysVM2019-05-31_20.ova MD5
> certutil -hashfile DeveloperDaysVM2019-05-31_20.ova SHA1

2.3 Importing the Virtual Appliance on Oracle VM VirtualBox

Once the ova file has been obtained, it is possible to proceed with importing it using the Import Appliance (or Import Virtual Application) function of Oracle VM VirtualBox which we can access from the File menu (see Figure 2).

Figure 2 – Access to the Import Appliance function (or Import Virtual Application)

After clicking on the menu item indicated above, you should see a dialog box like the one shown in Figure 3. The only information to specify is the location of the OVA file, after which it will be possible to continue by clicking on the Continue button.

Figure 3 – First Virtual Appliance import step: specify the location of the OVA file

After clicking on the Continue button, a subsequent dialog box will open showing the detailed information (such as CPU, RAM, age.) Of the Virtual Appliance (see Figure 4). It is possible to change some settings, but I recommend leaving those proposed; then continue by clicking on the Import button.

Figure 4 – Second step of Virtual Appliance import: summary of detailed information of the VA and start import

Figure 5 shows the progress of the import process. The duration of the import depends on the strength of your own and the availability of resources at the time of import. In my case, the import process took about 2 minutes.

Figure 5 – Virtual Appliance import process

Once the import process is finished, you should have a situation like the one shown in Figure 6, that is, a new Virtual Machine called Oracle DB Developer VM.

Figure 6 – Imported Oracle DB Developer VM virtual machine

Before you can start the virtual machine, you need to:

Check and/or create a new host network. This will allow access to the Oracle database services also from the host’s network, that is, from our PC
Add a new network adapter to the virtual machine and configure it to use the host’s network

For the first step, access the Host Network Manager window from the __File -> Host Network Manager menu, and you should see what is shown in Figure 7.

Figure 7 – Host network manager

In this case there is no host network interface present, we must therefore proceed with the creation, a step that can be done by clicking on the button that shows the Create label.

If one or more host network configurations are already present, it would be possible to use one of those available.

Figure 8 shows the new host network (vboxnet0) just created and the basic characteristics. After the creation of the network, we have to activate the DHCP Server option, leaving the default settings. This network will be the one that we will then specify on the configuration of the new network card of the virtual machine just imported.

*Important! * After setting the flag to enable the DHCP server, we need to close and reopen Oracle VM VirtualBox, this to make the DHCP server start correctly.

Figure 8 – New host network 192.168.56.1/24 with active DHCP

For the second step, a second network card must be added from the VM network settings by setting the type (“Connected to”) to host-only card, in this case specifying the name of the host network created in the previous step.

Figure 9 shows the configuration of the new network card configured to be connected to the host network (vboxnet0), while Figure 10 the summary of the VM settings after configuring the new network card.

Figure 9 – Configuration of the second network card connected to the host network

Figure 10 – Additional network card also visible on the VM summary

2.4 Starting and testing the Virtual Appliance

Once the step of importing and modifying the network settings has been completed, it is possible to proceed with starting the virtual machine through the start “green button”. Figure 11 shows the Grub boot menu highlighting the Oracle Linux operating system, which will be booted by default (without any action on our part).

Figure 11 – Starting the VM. Grub boot menu of the Oracle Linux operating system

After a few minutes, which can vary a lot depending on your hardware resources, you should find yourself in front of the GNOME desktop as shown in Figure 12 (even if the arrangement of the objects on the desktop may be different).

Figure 12 – GNOME desktop after starting the VM

Figure 12 highlights some important data that will be needed to connect to the Oracle database and machine via SSH. Below, I report these parameters.

Username/Password: oracle/oracle (also sudo user)
Oracle SID: orclcdb
Pluggable DB: orcl

At this point, we must verify that:

the Oracle database services in particular are in listen;
the connection to the database via SQL*Plus works correctly;
the VM is able to communicate with the public network (internet);
the new network card is seen correctly by the Oracle Linux operating system, and configure it via DHCP.

Console 2 shows the commands needed to obtain the above information.



# Verify that the SQLNet service is listening on standard TCP / IP port 1521
$ netstat -ltnp

# Verification of connection to the Oracle database via SQL*Plus with the user who has the SYSDBA role
$ sqlplus sys/oracle as sysdba

# Check connectivity to the public network (internet)
$ ping www.google.it

# Verify the configuration of the network card connected to the host network created earlier
$ ifconfig

# Configuration of the eth1 network card (see output of 
# ifconfig command) to get the IP address from the server 
# DHCP.
$ sudo dhclient eth1

Figures 13, 14 and 15 illustrate in the order indicated in Console 2 the output of the commands given directly on the machine. From Figure 13 it is possible to notice that the SQLNet service is correctly in LISTEN on TCP/IP port 1521 (all interfaces 0.0.0.0).

Figure 13 – Verify that Oracle’s SQLNet service is active on TCP/IP port 1521

From Figure 14 it is possible to notice how the connection to the Oracle database through SQL*Plus takes place in the correct way by showing the banner with the detailed information about the Oracle instance.

Figure 14 – Test connection to the SQLNet service via SQLPlus as a user with the role of SYSDBA

On the desktop (see Figure 12) there is a link to the SQL Developer tool that you could use as an interface to the Oracle database. The tool is already configured with a database connection as SYSDBA user. The version of SQL Developer installed on the VM is quite old, 19.1.

Figure 15 shows the correct configuration of the network card, which acquired the IP address 192.168.56.5 from the DHCP server.

To make the activation of the network card permanent via DHCP, it is possible to act on the Connect automatically flag and then to Apply on the configuration detail of the network card accessible through the Network Manager (see figures below).

Figure 15 – Verifying the correct configuration of the network card configured to use the host network

Figure 16 – Access to the configuration of the network cards

Figure 17 – List of network cards present on the system

Figure 18 – Permanent activation of the new eth1 network card connected to the host network

3. Connect to database from host machine

Once the setup of the Oracle Database VM is finished, we can interact with its services directly from our host machine, thanks to the fact that we are able to reach the SQLNet and SSH service.



# Connect to VM via SSH
# The specified IP address is the one obtained from the command
# ifconfig run on the VM. Address assigned by the server
# Host network DHCP. Remember that the default password
# of the oracle user is oracle
$ ssh oracle@192.168.56.5

To establish the connection to the database, you are obviously free to use any SQL client that supports Oracle. I prefer to stay around Oracle and for this I recommend installing and using SQL Developer whose latest version is 21.41.

Once SQL Developer is installed and started, we can add the database connection using the following parameters.

Username: sys
Password: oracle
Role: SYSDBA
Host Name: 192.168.56.5 (IP address of your VM which may be different from the one indicated here and in Figure 19)
Service Name: orcl

Figures 19 and 20 show the database connection setup and query execution.

Figure 19 – Setup of the connection from the Oracle database

Figure 20 – Example of executing a query on the Oracle database

At this point, we have our own Oracle development VM that we can use to host the databases of the projects we work on.

4. Useful resources

L'articolo (English) How to use Oracle Database 19c Pre-Built Developer VM sembra essere il primo su Antonio Musarra's Blog.

Come usare Oracle Database 19c Pre-Built Developer VM

Antonio Musarra — Wed, 29 Dec 2021 16:08:46 +0000

Quante volte ci siamo trovati ad affrontare l’arduo setup di una istanza Oracle Database per il nostro ambiente di sviluppo e “sputare decisamente sangue”?

Immagino che queste “volte” siano state anche troppe, ecco un buon motivo per iniziare a utilizzare quello che Oracle mette a disposizione a noi sviluppatori, ovvero, le Pre-Built Developer VMs per Oracle VM VirtualBox.

Nel corso di questo articolo vedremo come fare il setup di una VM Oracle Database 19c dal Database Virtual Box Appliance che Oracle fornisce.

1. Requisiti

Prima d’iniziare è necessario verificare che i seguenti requisiti siano soddisfatti.

Sistema Operativo che supporti la versione di Virtual Box 6.x
Almeno 2 GByte di RAM
Almeno 15 GByte di spazio per lo storage
Processo da almeno 2 GHz
Privilegi di amministratore

La Virtual Appliance di riferimento è del 20/06/2019 il cui contenuto è indicato a seguire.

Oracle Linux 7
Oracle Database 19.3
Oracle SQL Developer 19.1
Oracle Application Express 19.1
Hands-On-Labs (accessibile via the Toolbar Menu in Firefox)
- Oracle REST Data Services 19.1
- Oracle SQL Developer Data Modeler 19.1
- Oracle XML DB

Attenzione! Questa Virtual Appliance è da utilizzare solo in ambienti di sviluppo/test, non deve essere utilizzata in un ambiente di pre-produzione o produzione.

2. Setup della Virtual Appliance

La procedura di setup consta di alcuni passi riassunti a seguire:

Download e installazione di Oracle VM VirtualBox
Download di Oracle DB Developer VM
Importazione della Virtual Appliance su Oracle VM VirtualBox
Avvio e test della Virtual Appliance

2.1 Download e installazione di Oracle VM VirtualBox

Dalla home page di Oracle VM VirtualBox è possibile effettuare il download dei binari per il proprio sistema operativo. Nel mio caso ho provveduto a scaricare la versione per MacOS.

La procedura d’installazione è molto semplice e non è oggetto di questo articolo; in caso di difficoltà o approfondimenti, fare riferimento allo User Manual. La versione di riferimento per questo articolo è la 6.1.30. La Figura 1 mostra le informazioni di dettaglio circa la versione installata sul mio MacBook Pro con macOS Monterey (versione 12.1).

Figura 1 – Informazioni su VirtualBox

2.2 Download di Oracle DB Developer VM

Dal link Oracle DB Developer VM si accede al file DeveloperDaysVM2019-05-31_20.ova che contiene la Virtual Appliance. Il formato OVA/OVF è uno standard per il packaging e distribuzione delle Virtual Appliance.

Il download del file richiede la disponibilità di un account Oracle (che alla bisogna potete creare gratuitamente). La dimensione del file è di oltre 7 GByte, consiglio pertanto di verificare al termine del download il checksum del file. In Console 1 è indacato uno dei modi per la verifica dell’hash utilizzando i comandi md5 e sha disponibili su macOS, Unix/Linux e Windows 10.

MD5 (sum): 20b5a5bd91cfe9d4f5acf5128f06146e
SHA1: e0b9f8af8158664139b9ca970c3500752fc15fd2

# Verify the checksum MD5 and SHA1 on macOS
$ md5 DeveloperDaysVM2019-05-31_20.ova
$ shasum DeveloperDaysVM2019-05-31_20.ova

# Verify the checksum MD5 and SHA1 on Unix/Linux
$ md5sum DeveloperDaysVM2019-05-31_20.ova
$ sha1sum DeveloperDaysVM2019-05-31_20.ova

# Verify the checksum MD5 and SHA1 on Windows 10
> certutil -hashfile DeveloperDaysVM2019-05-31_20.ova MD5
> certutil -hashfile DeveloperDaysVM2019-05-31_20.ova SHA1

2.3 Importazione della Virtual Appliance su Oracle VM VirtualBox

Una volta ottenuto il file ova, è possibile procedere con l’importazione dello stesso tramite la funzionalità Import Appliance (o Importa Applicazione Virtuale) di Oracle VM VirtualBox a cui possiamo accedere dal menù File (vedi Figura 2).

Figura 2 – Accesso alla funziona di Import Appliance (o Importa Applicazione Virtuale)

Dopo aver cliccato sulla voce di menù indicata in precedenza, dovreste vedere una finestra di dialogo come quella mostrata in Figura 3. L’unica informazione da specificare è la posizione del file OVA, dopo di ché sarà possibile proseguire cliccando sul pulsante Continua.

Figura 3 – Primo step d’importazione Virtual Appliance: specificare la locazione del file OVA

Dopo il clic sul pulsante Continua sarà aperta una successiva finestra di dialogo che mostra le informazioni di dettaglio (come CPU, RAM, età.) della Virtual Appliance (vedi Figura 4). È possibile cambiare alcune impostazioni ma consiglio di lasciare quelle proposte; proseguiamo quindi cliccando sul pulsante Importa.

Figura 4 – Secondo step d’importazione Virtual Appliance: riepilogo informazioni di dettaglio della VA e start importazione

La Figura 5 mostra l’avanzamento del processo d’importazione. La durata dell’importazione dipende dalla potenza della propria e dalla disponibilità di risorse nel momento dell’importazione. Nel mio caso il processo d’importazione ha avuto una durata di circa 2 minuti.

Figura 5 – Processo d’importazione della Virtual Appliance

Una volta terminato il processo d’importazione, dovreste avere una situazione come quella mostrata in Figura 6, ovvero, una nuova Macchina Virtuale chiamata Oracle DB Developer VM.

Figura 6 – Macchina virtuale Oracle DB Developer VM importata

Prima di poter avviare la macchina virtuale è necessario:

Verificare e/o creare una nuova rete host. Questo consentirà l’accesso ai servizi del database Oracle anche dalla rete del host, ovvero, del nostro PC
Aggiungere una nuova scheda di rete alla macchina virtuale e configurarla per usare la rete dell’host

Per il primo step, accedere alla finestra del Gestore di rete dell’host dal menù File -> Gestore di rete dell’host e dovreste vedere quanto mostrato in Figura 7.

Figura 7 – Gestore di rete dell’host

In questo caso non risulta nessuna interfaccia di rete host presente, dobbiamo quindi procedere con la creazione, step ch’è possibile fare cliccando sul pulsante che riporta l’etichetta Crea.

Nel caso in cui fossero già presenti una o più configurazioni di rete host, sarebbe possibile sfruttarne una tra quelle disponibili.

La Figura 8 mostra la nuova rete host (vboxnet0) appena creata e le caratteristiche di base. Dopo la creazione della rete dobbiamo attivare l’opzione Server DHCP lasciando le impostazioni di default. Questa rete sarà quella che andremo poi a specificare sulla configurazione della nuova scheda di rete della macchina virtuale appena importata.

Importante! Dopo aver impostato il flag per attivare il server DHCP, dobbiamo chiudere e riaprire Oracle VM VirtualBox, questo per fa si che il server DHCP si avvi correttamente.

Figura 8 – Nuova rete host 192.168.56.1/24 con DHCP attivo

Per il secondo step, occorre aggiungere dalle impostazioni di rete della VM, una seconda scheda di rete impostando la tipologia (“Connessa a”) a scheda solo host, specificando in questo caso il nome della rete host creata nel precedente step.

La Figura 9 mostra la configurazione della nuova scheda di rete configurata per essere connessa alla rete dell’host (vboxnet0), mentre la Figura 10 il riepilogo delle impostazioni della VM dopo la configurazione della nuova scheda di rete.

Figura 9 – Configurazione delle seconda scheda di rete connessa alla rete dell’host

Figura 10 – Scheda di rete addizionale visibile anche sul riepilogo della VM

2.4 Avvio e test della Virtual Appliance

Completato lo step d’importazione e modifica delle impostazioni di rete, è possibile procedere con l’avvio della macchina virtuale attraverso il “pulsantone verde” di avvio. In Figura 11 è mostrato il boot menù di Grub con in evidenza il sistema operativo Oracle Linux che sarà avviato di default (senza alcuna azione da parte nostra).

Figura 11 – Avvio della VM. Grub menù di avvio del sistema operativo Oracle Linux

Dopo qualche minuto, tempo che può variare anche di molto in base alle proprie risorse hardware, dovreste trovarvi davanti il desktop di GNOME così come mostrato in Figura 12 (anche se la disposizione degli oggetti sul desktop potrebbe essere diversa).

Figura 12 – Desktop GNOME dopo l’avvio della VM

La Figura 12 evidenzia alcuni dati importanti che serviranno per connetterci al database Oracle e alla macchina tramite SSH. A seguire riporto questi parametri.

Username/Password: oracle/oracle (è anche sudo user)
Oracle SID: orclcdb
Pluggable DB: orcl

Arrivati a questo punto dobbiamo verificare che:

i servizi Oracle del database in particolare siano in listen;
la connessione al database via SQL*Plus funzioni correttamente;
la VM sia in grado di comunicare con la rete pubblica (internet);
la nuova scheda di rete sia vista correttamente dal sistema operativo Oracle Linux e provvedere alla configurazione via DHCP.

In Console 2 sono indicati i comandi necessari per ottenere le informazioni indicate in precedenza.

# Verifica che il servizio SQLNet sia in listen sulla porta standard TCP/IP 1521
$ netstat -ltnp

# Verifica di connessione al database Oracle via SQL*Plus con l'utente che ha il ruolo di SYSDBA
$ sqlplus sys/oracle as sysdba

# Verifica connettività verso la rete pubblica (internet)
$ ping www.google.it

# Verifica della configurazione della scheda di rete connessa alla rete host creata in precedenza
$ ifconfig

# Configurazione della scheda di rete eth1 (vedi output del 
# comando ifconfig) per acquisire l'indirizzo IP dal server 
# DHCP.
$ sudo dhclient eth1

Le Figure 13, 14 e 15 illustrano nell’ordine indicato in Console 2 l’output dei comandi impartiti direttamente sulla macchina. Dalla Figura 13 è possibile notare che il servizio SQLNet sia correttamente in LISTEN sulla porta TCP/IP 1521 (tutte le interfacce 0.0.0.0).

Figura 13 – Verifica che il servizio SQLNet di Oracle sia attivo sulla porta TCP/IP 1521

Dalla Figura 14 è possibile notare come la connessione al database Oracle attraverso SQL*Plus avviene nel modo corretto mostrando il banner con le informazioni di dettaglio circa l’istanza Oracle.

Figura 14 – Test di connessione al servizio SQLNet via SQLPlus come utente con il ruolo di SYSDBA

Sul desktop (vedi Figura 12) è disponibile il link al tool SQL Developer che potreste utilizzare come interfaccia verso il database Oracle. Il tool è già configurato con una connessione al database come utente SYSDBA. La versione di SQL Developer installata sulla VM è la 19.1 abbastanza vecchiotta.

Dalla Figura 15 è evidente la corretta configurazione della scheda di rete che ha acquisito dal server DHCP l’indirizzo IP 192.168.56.5.

Per rendere permanete l’attivazione della scheda di rete via DHCP, è possibile agire sul flag Connect automatically e poi su Apply sul dettaglio della configurazione della scheda di rete accessibile attraverso il Network Manager (vedi Figure a seguire).

Figura 15 – Verifica della corretta configurazione della scheda di rete configurata per usare la rete dell’host

Figura 16 – Accesso alla configurazione delle schede di rete

Figura 17 – Lista delle schede di rete presenti sul sistema

Figura 18 – Attivazione permanente della nuova scheda di rete eth1 connessa alla rete dell’host

3. Connessione al database dalla macchina host

Terminato il setup della VM di Oracle Database, possiamo interagire con i servizi di quest’ultima direttamente dalla nostra macchina host, grazie al fatto che siamo nelle condizioni di poter raggiungere il servizio SQLNet e SSH.

# Connessione alla VM via SSH
# L'indirizzo IP specificato è quello ricavato dal comando 
# ifconfig eseguito sulla VM. Indirizzo asseganto dal server
# DHCP della rete dell'host. Ricordo che la password di default
# dell'utente oracle è oracle
$ ssh oracle@192.168.56.5

Per instaurare la connessione al database siete ovviamente liberi di usare qualunque client SQL che supporti Oracle. Preferisco restare nell’intorno Oracle e per questo consiglio d’installare e usare SQL Developer la cui ultima versione è la 21.41.

Una volta installato e avviato SQL Developer, possiamo aggiungere la connessione al database utilizzando i seguenti parametri.

Nome Utente: sys
Password: oracle
Ruolo: SYSDBA
Nome Host: 192.168.56.5 (indirizzo IP della propria VM che potrebbe essere diverso quello indicato qui e in Figura 19)
Nome Servizio: orcl

Le Figure 19 e 20 mostrano il setup della connessione al database e l’esecuzione di una query.

Figura 19 – Setup della connesione dal database Oracle

Figura 20 – Esempio di esecuzione di una query sul database Oracle

A questo punto abbiamo una nostra VM di sviluppo Oracle che possiamo usare per ospitare i database dei progetti su cui lavoriamo.

4. Risorse utili

A seguire una lista di risorse utili a scopo di approfondimento:

L'articolo Come usare Oracle Database 19c Pre-Built Developer VM sembra essere il primo su Antonio Musarra's Blog.

Apple PowerBook G4: La rinascita grazie a OpenBSD

Antonio Musarra — Tue, 24 Aug 2021 20:11:18 +0000

Il mio primo Mac Portatile

Ogni volta che scendo giù a casa in Sicilia rispolvero cose del mio passato. Questa è stata la volta del mio primo portatile Apple, esattamente il PowerBook G4 basato sul processore RISC (Reduced Instruction Set Computer) a 32bit PowerPC G4. Ho usato questa macchina sette giorni su sette dal 2005 fino alla metà del 2010 senza nessuna interruzione. Qui sono disponibili tutte le specifiche tecniche Apple PowerBook G4 1.5 12″ (modello A1104).

Allo stato attuale questa incredibile macchina è ancora funzionante e con il sistema operativo Mac OS X 10.5.8 (Leopard), ultima versione disponibile per questa piattaforma hardware. Purtroppo non è possibile aggiornare il resto dei software come per esempio il semplice browser per navigare su internet. Con le versioni installate dei browser (Safari, Firefox e Chrome) è negata la navigazione a causa del fatto che i nuovi protocolli TLS (1.2 e 1.3), ormai adottati dalla stragrande maggioranza dei siti web non sono ovviamente supportati; al tempo non esistevano!

Le cose sono due, rimettere nuovamente il portatile in parcheggio o dargli una nuova possibilità di vita. Ho scelto la seconda opzione perchè non ho resistito alla richiesta di mio nipote di sei anni il quale mi ha domandato: zio, potrò usare questo piccolo computer?

Molto bene! In questo breve articolo vi mostrerò quello che ho fatto per dare nuova vita ad una macchina che per me è stata un ottimo strumento di lavoro e su cui mio nipote potrà iniziare a mettere le mani in pasta in questo fantastico mondo e magari iniziando proprio dalla linea di comando

1. La scelta del sistema operativo

Non è mia intenzione scrivere un papiro su questo aspetto, per questo motivo vi svelerò immediatamente quale sistema operativo ho scelto e le motivazioni principali. OpenBSD è il sistema operativo che ho selezionato per dare nuova vita al mio PowerBook G4.

OpenBSD è un sistema operativo libero, open-source, multipiattaforma, di tipo unix-like, derivato dalla Berkeley Software Distribution (4.4BSD). Il team di sviluppo di questo sistema operativo concentra gli sforzi per offrire: massima portabilità, standardizzazione, sicurezza pro-attiva e la crittografia integrata. I motivi principali della mia scelta sono:

grande esperienza di sistema operativo BSD. Sono arrivati alla 50° release, distribuita a maggio del 2021;
supporto per le piattaforme hardware PowerPC ( anche sulle nuove release di OpenBSD );
supporto (OOTB) per l’hardware del PowerBook G4 (schede di rete LAN, scheda di rete WiFi, touch pad, etc.);
grande disponibilità dei binari delle maggiori applicazioni anche per la piattaforma PowerPC;
documentazione testuale e efficace.

La versione specifica di OpenBSD è la 6.8 abbinata alla release song Hacker People.

Sono sicuro che alcuni di voi si domanderanno qual è stato il motivo per non scegliere l’ultima versione 6.9, semplice, perchè non sono disponibili in formato binario alcuni pacchetti del Desktop Environment XFCE.

2. Introduzione alla procedura d’installazione

Il programma di installazione di OpenBSD utilizza uno speciale kernel ramdisk (bsd.rd) che genera un ambiente live eseguito interamente in memoria. Contiene lo script di installazione e un piccolo numero di utilità necessarie per eseguire un’installazione completa. Queste utilità possono essere utili anche per il ripristino di emergenza.

Il kernel ramdisk può essere avviato da diverse sorgenti ma non tutte le piattaforme supportano queste opzioni di avvio.

CD/DVD
Chiavetta USB
Una partizione esistente
Tramite rete (PXE o altre opzioni di avvio di rete)
Floppy disk

Nel caso del PowerBook G4 le strade da preferire sono senza dubbio le prime due, nel mio caso specifico ho scelto la seconda, tramite una chiavetta USB. Ho scartato la prima opzione perchè sprovvisto di CD o DVD vergini su cui masterizzare l’immagine di OpenBSD.

3. Preparazione all’installazione

Prima di iniziare con il processo d’installazione vero e proprio, vale la pena considerare in anticipo alcuni aspetti che riporto a seguire, considerando il punto fermo dell’architettura.

Il nome da assegnare alla macchina, che nel mio caso sarà amusarra-pbook-g4.
Il metodo d’installazione che in questo caso è proprio Install (tra le altre possibili scelte Upgrade, Auto Install e Shell).
Il layout del disco desiderato. Nel mio caso ho scelto che su questa macchina sarà installato solo OpenBSD e utilizzerò quindi il layout del disco di default. Per ogni approfondimento sul tema, consiglio la lettura OpenBSD FAQ – Disk Setup.
Abilitare il Disk Encryption. Nel mio caso ho scelto di non abilitare questa funzionalità; per il tipo d’uso non è necessario e risparmio anche tempo di CPU prezioso. Per ogni approfondimento sull’argomento, consiglio la lettura OpenBSD Full Disk Encryption.
Setup della rete. Su questa macchina abbiamo a disposizione due schede di rete, quella LAN Ethernet (via caso) e quella WiFi. In questo caso, in fase d’installazione andrò ad impostare per la scheda di rete LAN il DHCP. Il setup della scheda WiFi può essere eseguito anche in un secondo momento.

4. Download OpenBSD e preparazione USB Disk

Consolidato il fatto che eseguiremo l’installazione da USB Disk, le operazioni che porteremo a termine nel corso di questo capitolo sono: download e verifica dell’immagine di OpenBSD, per finire con la creazione dell’USB Disk a partire dall’immagine scaricata in precedenza.

OpenBSD mette a disposizione diverse tipologie d’immagini, quella di nostro interesse si chiama installXX.iso (nel nostro caso install68.iso). Si tratta di un’immagine ISO 9660 che può essere utilizzata per creare un CD/DVD e USB Disk di installazione. Include i set di file, questo si traduce nel fatto che non sia necessaria la disponibilità di una connessione alla rete internet durante il processo d’installazione.

L’immagine può quindi essere scaricata dal seguente link https://cdn.openbsd.org/pub/OpenBSD/6.8/macppc/install68.iso. Una volta scaricata l’immagine accertiamoci che sulla stessa non ci siano alterazioni verificando il checksum SHA256. Esistono diverse possibilità per il controllo checksum, dipendenti in genere dal proprio sistema operativo. Nel caso di MacOS è possibile utilizzare il comando shasum -a 256 install68.iso o anche il comando openssl sha256 install68.iso. Il checksum atteso per il file install68.iso è da45cd5149e4d28ee20c3d06db9e1f3292760a77a176ad842bfb6a4a518df351. La lista degli hash SHA256 è reperibile al seguente link https://cdn.openbsd.org/pub/OpenBSD/6.8/macppc/SHA256.

Per il controllo del checksum su Windows è possibile utilizzare il comando CertUtil -hashfile install68.iso SHA256 mentre su Linux il comando sha256 install68.iso.

A questo punto non resta altro che trasferire l’immagine ISO install68.iso su una chiavetta USB. Le dimensioni minime per la chiavetta USB sono di 512MByte. Anche per l’esecuzione di quest’operazione esistono diversi metodi sulla base del proprio sistema operativo. Nel caso di sistemi operativi Unix-like (talvolta UN*X o *nix) è possibile utilizzare il comando dd. Per il comando dd potrebbero esserci leggere differenze tra i vari sistemi operativi, consiglio infatti, di far sempre riferimento alla documentazione specifica accessibile tramite il comando man dd.

Utilizzando il comando dd if=install68.iso of=/dev/disk2 bs=1m quello che otterremo è una chiavetta USB da cui saremo in grado di avviare l’installazione di OpenBSD versione 6.8. Il nome del device specificato sul parametro of, può essere diverso in base al proprio sistema, nel mio caso la chiavetta USB è mappata sul device /dev/disk2.

Nel caso il proprio sistema operativo sia Windows, allora potreste utilizzare l’utility Rufus, balenaEtcher o anche il comando dd nel caso abbiate GitBash (Burning an image on a USB flash drive from a Windows machine using Git Bash). La figura a seguire mostra l’output dell’esecuzione del comando dd per la creazione del disco USB dall’immagine per l’installazione di OpenBSD 6.8.

Figura 1 – Creazione del disco USB dell’immagine OpenBSD 6.8 per l’installazione

5. Boot in modalità Open Firmware

Per poter installare OpenBSD sul nostro Apple PowerBook G4, dobbiamo avviare quest’ultimo in modalità Open Firmware.

Open Firmware è una tecnologia hardware per sviluppare firmware indipendente dal sistema operativo (software caricato all’accensione del computer prima del sistema operativo) sviluppata da Sun Microsystems. È utilizzata nei computer Apple Macintosh dotati di processori PowerPC, nelle workstation SPARC e nei server della Sun Microsystems, nei computer PegasosPPCe in altri sistemi (fonte Wikipedia).

Prima di accendere la macchina ricordate d’inserire il disco USB su una delle due porte USB a disposizione e di connetterla alla vostra rete tramite cavo ethernet (non richiesto ma consigliato). Personalmente ho inserito il disco sulla prima porta, per cui il dispositivo sarà identificato con usb0.

Per accedere a Open Firmware, occorre premere la combinazione dei tasti, Command(⌘) + Option(⌥) + O + F, immediatamente all’avvio. Dopo qualche secondo dovreste vedere a schermo quando mostrato dalla figura a seguire.

Figura 2 – Avvio del PowerBook G4 in modalità Open Firmware

Open Firmware è accessibile utilizzando un’interfaccia di tipo shell basata sul Forth, un potente linguaggio ad alto livello, descritto nel documento IEEE 1275-1994 – IEEE Standard for Boot (Initialization Configuration) Firmware. Grazie a questa shell possiamo impartire tutti i comandi necessari per avviare l’installazione di OpenBSD.

Se volessimo verificare che il disco USB sia correttamente visto dal sistema, potremmo digitare il comando devalias, dall’output dovremmo essere in grado d’identificare com’è stato mappato il disco USB. Le figura a seguire mostra un esempio del comando.

Figura 3 – Uso del comando devalias per identificare la porta USB dove abbiamo collegato la chiavetta USB

La figura successiva mostra invece l’uso del comando dir usb0/disk@1:\ e dir usb0/disk@1: \6.8\macppc al fine di verificare che il contenuto sia quello desiderato.

Figura 4 – Utilizzo del comando dir per verificare il contenuto della chiavetta USB contenente l’immagine install68.iso

Il programma bootstrap di OpenBSD si chiama ofwboot , che avvierà poi il bsd.rd, il ramdisk Kernel. Dalla shell di OpenFirmware occorre eseguire il comando boot usb0/disk@1:,ofwboot /6.8/macppc/bsd.rd per iniziare l’installazione di OpenBSD.

Figura 5 – Boot OpenBSD Installer

Se tutto è andato per il verso giusto, si dovrebbe avviare il boot loader che a sua volta avvierà il ramdisk Kernel dal file bsd.rd. Al termine del caricamento del Kernel, potremo procedere con la fase d’installazione di OpenBSD.

6. Installazione di OpenBSD

A questo punto siamo davvero pronti per proseguire con l’installazione di OpenBSD. Gli step a seguire riguardano:

la scelta del tipo d’installazione, in questo caso optiamo per la voce (I)stall (vedi Figura 6);
la scelta dell’hostname da assegnare alla macchina, che nel mio caso imposterò a amusarra-pbook-g4 (vedi Figura 7);
la scelta della scheda di rete da configurare. Questo step è opzionale (digitando done quando richiesto), le schede possono essere configurate successivamente. Personalmente ho scelto di configurare in questa fase la scheda ethernet (gem0 il su nome) via DHCP (vedi Figura 8);
impostazione della password di root;
scegliere se far partire il servizio SSH di default (si per default), personalmente ho scelto di si;
scegliere se abilitare X Window System (si per default), personalmente ho scelto di si;
scegliere se abilitare il login grafico via xenodm (no per default), personalmente ho scelto no;
la creazione di un nuovo utente. Consiglio sempre di eseguire questo step, personalmente ho scelto di creare l’utente amusarra;
Scegliere se consentire la login all’utente root via SSH (no per default), personalmente ho scelto no, scelta fatta anche in termini di sicurezza;
scegliere il timezone. Nel mio caso Europe/Rome;
scegliere il disco dove installare OpenBSD. Nel mio caso specifico il disco di destinazione sarà wd0. Nella maggior parte dei sistemi BSD, i dispositivi di storage di massa di tipo IDE-like hanno il naming wd;
scegliere se utilizzare tutto il disco o parte di esso. In questo caso, dove abbiamo deciso di avere il solo OpenBSD come sistema operativo, la scelta è di utilizzare tutto il disco, quindi (W)hole disk;
scegliere o modificare il layout del file system. Come scritto in precedenza, a meno di particolari esigenze, consiglio di selezione il layout automatico (A)uto layout (vedi Figura 9);
scegliere la locazione per set di file che in questo caso risiedo all’interno della chiavetta USB che OpenBSD ha mappato sul dispositivo sd0. Alle domande rispondere in ordine: disk, no, sd0 (valore di default), 6.8/macppc (valore di default)
scegliere il set di pacchetti da installare. Personalmente ho scelto d’installare tutti i pacchetti. Dopo la selezione dei pacchetti sarà chiesto se eseguire la verifica di questi, step che si può evitare rispondendo yes alla domanda (vedi Figura 10).

Una volta che il processo d’installazione è terminato, dobbiamo riavviare la macchina nella modalità Open Firmware (e ormai sappiamo come si fa), per impostare OpenBSD in auto-boot (vedi Figura 11). È possibile fare ciò utilizzando i seguenti due comandi: setenv auto-boot? true e setenv boot-device hd:,ofwboot. L’ultimo comando reset-all salva le impostazioni sulla NVRAM (nonvolatile random-access memory). Quest’ultimo comando riavvierà la macchina che dovrebbe da adesso in poi partire con OpenBSD 6.8

La sequenza delle figure a seguire mostra gli step d’installazione più significativi descritti in precedenza.

Figura 6 – Step 1 => Selezione del tipo d’installazione

Figura 7 – Step 2 => Impostazione del nome host

Figura 8 – Step 3 => Configurazione Networking

Figura 9 Step 13 => Configurazione dei layout file system per l’installazione di OpenBSD

Figura 10 – Step 14-15 Installazione del set file di OpenBSD

Figura 11 – Impostazione del boot device di default per far avviare OpenBSD come impostazione predefinita

7. Il primo avvio di OpenBSD

Il primo avvio di OpenBSD appena installato, fa un pochino di cose, alcune delle quali: generazione delle chiavi RSA per il servizio SSH ma cosa ancora più importante, l’installazione dei firmware addizionali, in questo caso installerà il bwi-firmware, necessario per far funzionare la scheda di rete WiFi.

L’installazione dei firmware aggiuntivi è eseguita scaricando quest’ultimi dalla rete, è quindi necessario che la macchina sia connessa alla rete. In ogni caso è possibile installarli successivamente utilizzando il comando fw_update.

Figura 12 – Primo avvio di OpenBSD

Il nostro OpenBSD è praticamente pronto all’uso, consiglio comunque il setup della scheda WiFi per connettervi alla rete internet tramite il vostro Router WiFi. La procedura è veramente semplice e ben descritta all’interno della sezione Wireless Networking della documentazione di OpenBSD.

Gli step di configurazione prevedono i seguenti step:

verifica che la scheda di rete WiFi sia vista correttamente da OpenBSD. Per accertarsi di ciò, basta eseguire il comando if config bwi0 media. Il nome dispositivo assegnato dovrebbe essere quello indicato dal comando; in caso di problemi eseguire il comando ifconfig senza argomenti per verificare il nome esatto del dispositivo. La Figura 13 mostra l’output del comando;
creazione del file /etc/hostname.bwi0 il cui contenuto è mostrato in Figura 14;
riavvio della macchina o restart del servizio di network per applicare le modifiche. Per eseguire il restart del network, lanciare il comando sh /etc/netstart (vedi Figura 15). La Figura 16 mostra lo stato della scheda WiFi dopo la connessione avvenuta con successo al Router WiFi.

Figura 13 – Output del comando ifconfig sulla scheda WiFi con lo scopo di verificare che sia correttamente vista da OpenBSD

Figura 14 – Creazione del file /etc/hostname.bwi0 per la configurazione di connessione della schede WiFi al Router WiFi

Figura 15 – Restart della rete per applicare le modifiche alla configurazione delle scheda WiFi

Figura 16 – Esecuzione del comando ifconfig dopo l’applicazione della configurazione per la scheda WiFi

8. E adesso tocca a voi

In questo articolo ho voluto mostrare la mia personale esperienza nell’attività di far risuscitare il mio Apple PowerBook G4 da anni e anni di riposo installando OpenBSD. L’operazione in fin dei conti non è stata affatto complicata, forse lo potrà essere per coloro che non sono avvezzi a questo tipo di strumenti a “basso livello”; lo scopo dell’articolo è anche quello di rendere semplice l’installazione anche per i non avvezzi.

Se siete arrivati fino a questo punto della lettura, immagino che vi siate trovati nella stessa situazione o magari vorreste intraprendere quest’attività sulla vostra macchina. Vi lascio i commenti per descrivere la vostra esperienza o se avete domande in merito.

Un buon inizio di avventura con OpenBSD

Benvenuti in OpenBSD 6.8 su Apple PowerBook G4

L'articolo Apple PowerBook G4: La rinascita grazie a OpenBSD sembra essere il primo su Antonio Musarra's Blog.

Come ottenere una CIE funzionante su Fedora 34

Antonio Musarra — Mon, 09 Aug 2021 21:37:11 +0000

Finalmente il 26 luglio 2021 ho ottenuto la mia CIE (Carta d’Identità Elettronica) rilasciata dal Comune di Marino (RM). Appena arrivato a casa non ho perso un attimo e ho collegato il mio lettore miniLector CIE di Bit4id alla mia Workstation da Smart Worker iniziando a fare i primi test.

In questo articolo vedremo come eseguire il setup del software necessario al corretto funzionamento della CIE su sistema operativo Fedora 34.

Affinché sia possibile utilizzare la CIE, indipendentemente dal fatto che la usiate per accedere ai servizi della Pubblica Amministrazione, è necessario disporre di un lettore di Smart Card compatibile e del software d’interfaccia tra l’hardware e il sistema operativo. Nel mio caso dispongo dei seguenti “pezzi”:

lettore di Smart Card miniLector CIE di Bit4id;
sistema operativo Fedora 34.

Per quel che concerne il lettore di Smart Card, non sono richieste caratteristiche specifiche, è sufficiente che sia conforme allo standard internazionale PC/SC (Personal Computer/Smart Card) e alla norma ISO 7816-3, e che sia compatibile con i più comuni sistemi operativi come Windows, Mac OS e Linux/Unix. La caratteristica fondamentale da prendere in considerazione è il supporto per il protocollo standard CCID (Chip Card Interface Device). Il lettore in mio possesso è compatibile con lo standard CCID, non sarà quindi necessario installare i driver proprietari del lettore; i driver generici CCID sono in grado di far funzionare correttamente il lettore.

1. Verifica e installazione del software

La prima di verifica da eseguire consiste nell’accertarsi che il lettore di Smart Card sia correttamente visto dal sistema operativo. Fare questo tipo di controllo è abbastanza semplice, basta eseguire da terminale il comando lsusb. Dall’output del comando dovremmo essere in grado d’identificare il nostro lettore di Smart Card. La figura a seguire mostra l’esempio del mio lettore collegato alla mia workstation Fedora 34. Il nome “tecnico” del lettore Smart Card in uso è BIT4I miniLector AIR NFC v3.

Figura 1 – Controllo che il lettore Smart Card sia visibile a livello di Sistema Operativo

Se volessimo ottenere più informazioni riguardo il nostro lettore, potremmo usare il comando lsusb in questa forma: lsusb -v -s 3:6. Lo switch -s del comando, consente di specificare il dispositivo identificato tramite il bus e il device id, in questo caso rispettivamente 3 e 6. La figura a seguire mostra un estratto del comando precedente.

Figura 2 – Dettagli hardware sul lettore Smart Card connesso

Una volta sicuri del fatto che il nostro lettore sia visto correttamente dal sistema operativo, allora, sarà possibile procedere con l’installazione del software della CIE. Questo software o middleware, consente di utilizzare la Carta d’Identità Elettronica per l’accesso sicuro in rete ai servizi web erogati dalla Pubblica Amministrazione da un PC mediante lo schema d’identificazione Entra con CIE , i cui dettagli sono riportati sul sito del Ministero dell’Interno.

Il middleware CIE è una libreria software che implementa le interfacce crittografiche standard PKCS#11 e CSP. Esso consente agli applicativi integranti di utilizzare il certificato di autenticazione e la relativa chiave privata memorizzati sul chip della CIE astraendo dalle modalità di comunicazione di basso livello.

L’ultima versione del middleware è la 1.4.1 di cui è possibile scaricare il file RPM pronto per poter essere installato sulla nostra Fedora 34. L’installazione è davvero semplice, basta eseguire il comando: sudo rpm -i cie-middleware-1.4.1.rpm. La figura a seguire mostra i file che il comando precedente installa. Sono evidenziati in particolare il file che implementa le API dello standard PKCS#11 e il file dell’applicazione desktop. L’applicazione desktop consente di gestire la CIE in termini di PIN, PUK, associazioni CIE e funzionalità di Firma Elettronica Avanzata (FEA). La firma elettronica calcolata con la Carta d’Identità Elettronica è a tutti gli effetti una Firma Elettronica Avanzata, disciplinata all’interno del DPCM 22/02/2013, articolo 61.

Figura 3 – Lista dei file installati via RPM del middleware CIE

Una volta installato il middleware CIE, possiamo eseguire un semplice test di lettura della propria CIE utilizzando il comando che fa parte della suite PKCS#11. Appoggiate quindi la CIE sul lettore e lanciate questo comando: pkcs11-tool --module /usr/local/lib/libcie-pkcs11.so -I -L. Quello che il comando restituirà, saranno informazioni circa: il modulo PKCS#11, il lettore utilizzato e il token, che rappresenta la CIE vera e propria. La figura a seguire mostra l’output del comando che riguarda il mio lettore e CIE.

Figura 4 – Estrazione informazioni di dettaglio su lettore Smart Card e CIE via PCKS#11 tool

Arrivati a questo punto, manca davvero pochissimo per utilizzare la CIE come mezzo di accesso ai servizi della Pubblica Amministrazione. Il prossimo passo da seguire è quello che viene definito abbinamento e può essere portato a termine utilizzando l’applicazione CIE ID. Per l’esecuzione di questo passo di configurazione vi lascio alla lettura del capitolo 5. Primo utilizzo della CIE del manuale software CIE per Linux. Portato a termine il passo di abbinamento, il passo finale è la configurazione del browser per fare in modo che sia in grado di poter accedere alla CIE attraverso il lettore. Nel mio caso ho configurato Firefox e sul sito del Ministero dell’Interno è possibile trovare la guida completa su come configurare il lettore di Smart Card.

2. Come usare la CIE con il progetto CIE/CNS Apache Docker

“** L’utente normale”** utilizzerebbe la sua CIE per accedere ai servizi della Pubblica Amministrazione, gente come noi, oltre a questo vorrebbe sperimentare altro.

Tre anni or sono ho pubblicato come Developers Italia il progetto CIE/CNS Apache Docker. L’obiettivo di questo progetto è quello di fornire un template pronto all’uso che realizza un sistema di autenticazione tramite la Smart Card TS-CNS (o CNS) e la CIE (Carta d’Identità Elettronica) basato su Apache HTTP. Si tratta di un progetto docker per la creazione di un container che implementa un sistema di mutua autenticazione o autenticazione bilaterale SSL/TLS. Questo meccanismo di autenticazione richiede anche il certificato digitale da parte del client, certificato che in questo caso risiede all’interno della TS-CNS o della CIE. Questo progetto è nato ancor prima di quello che viene definito Entra con CIE e basato su SAML.

La particolarità del sistema implementato (attraverso questo container) è quella di consentire l’autenticazione tramite:

la TS-CNS (Tessera Sanitaria – Carta Nazionale Servizi), rilasciata dalla regione di appartenenza;
la CIE (Carta d’Identità Elettronica), rilasciata dal comune di residenza.

Il progetto è stato costruito in modo che consenta l’accesso a certificati che sono riconducibili esclusivamente a TS-CNS o CIE, inoltre esegue il controllo di revoca sfruttando il protocollo OCSP. Uno dei possibili utilizzi è come Reverse Proxy di autenticazione (classico scenario SSO); una volta avvenuta con successo l’autenticazione, le richieste posso essere passate all’applicazione di backend con l’informazione di quale sia l’identificativo dell’utente appena autenticato, che nel caso di TS-CNS e CIE è il codice fiscale. La figura a seguire mostra la pagina a cui si accede solo dopo essere stati autenticati, con evidenza i dati dell’utente presenti sulla CIE o TS-CNS (in questo caso CIE). Per maggiori informazioni consiglio la lettura del README di progetto.

Figura 5 – Accesso via CIE con visualizzazione delle informazioni di dettaglio

Sul mio canale YouTube potreste approfondire l’argomento seguendo il tutorial Cos’è il progetto CIE/CNS Apache Docker – Developers Italia dove affronto:

Introduzione al progetto
Overview su TS-CNS e CIE
Cos’è la Trust Service Status List
Struttura del Dockerfile
Struttura del progetto
Esecuzione dell’immagine Docker

3. Conclusioni

In questo breve articolo vi ho voluto fare partecipi della mia prima esperienza con la mia CIE su Fedora 34. Confesso che per fare i test dei vari progetti CIE dove sono stato coinvolto, ho usato la CIE di mio nipote

I campi di applicazione della CIE possono essere innumerevoli; sicuramente il primo a cui mi dedicherò appena possibile sarà quello della realizzazione di un sistema di accesso sfruttando un Raspberry Pi, analogo a quello realizzato usando la TS-CNS.

A seguire vi lascio una serie di risorse a scopo di appronfondimento.

Cos’è il progetto CIE/CNS Apache Docker (http://bit.ly/3aJ5Gbl)
CIE Carta d’Identità Elettronica (https://developers.italia.it/it/cie/)
Carta Nazionale dei Servizi (https://www.agid.gov.it/it/piattaform…)
Raspberry Pi – Un esempio di applicazione della TS-CNS (https://bit.ly/3hkJ8Aj)
Raspberry Pi: Come installare il miniLector CIE su Ubuntu Server 20.04 LTS
Pubblicare il servizio CIE/CNS Apache Docker su Azure Cloud (http://bit.ly/3aPoq8V)
Come accedere al portale VETINFO tramite TS-CNS e Mac OS (http://bit.ly/2VFMKq7)
Carta d’Identità Elettronica: come accedere ai servizi online con la CIE
CIEfacile

L'articolo Come ottenere una CIE funzionante su Fedora 34 sembra essere il primo su Antonio Musarra's Blog.

La mia workstation di sviluppo da Smart Worker

Antonio Musarra — Sun, 23 May 2021 21:16:12 +0000

Il mio primo portatile Macintosh (PowerBook G4)

Nella mia attività lavorativa sono stato affiancato e lo sono tuttora da macchine di casa Apple (portatili), partendo dal mio il primo PowerBook G4 ancora operativo e attualmente affidato a mio nipote di quasi sei anni.

A quasi un anno di attività lavorativa in modalità da Smart Worker, ho sentito la necessità di dotarmi di una vera e propria workstation. Cos’è esattamente una workstation?

Workstation (in italiano stazione di lavoro ) è un termine della lingua inglese utilizzato in informatica per indicare un tipo di computer monoutente, che si contraddistingue dall’essere destinato principalmente a un utilizzo produttivo (da cui il prefisso work = lavoro), e dall’avere alte prestazioni per poter assolvere compiti altamente professionali di vario genere (le prestazioni dei computer sono in continuo aumento quindi “alte prestazioni” è relativo al periodo di commercializzazione della workstation).

Sono utilizzate soprattutto nella forma di computer desktop, in ambiti di lavoro che necessitano di grandi potenze di calcolo come ad esempio il CAD, la ricerca scientifica, la produzione audio/video, le applicazioni di simulazione e calcolo ingegneristico. Esso è dunque sinonimo di un computer più potente rispetto ad un normale personal computer domestico o di ufficio. (Fonte Wikipedia https://it.wikipedia.org/wiki/Workstation)

Alla definizione standard aggiungerei che una workstation può definirsi tale se completa di uno o più monitor aventi caratteristiche che soddisfino le proprie esigenze lavorative.

In questo brevissimo articolo cercherò di esporre al meglio le scelte che ho seguito per costruire una workstation che rispondesse alla mie esigenze , senza assolutamente affermare che le scelte fatte da me siano il top. Questo articolo è in realtà la bella copia delle note che ho scritto durante la costruzione della mia workstation.

Quali sono le mie esigenze?

Il mio lavoro principale è la progettazione e realizzazione di soluzioni software. L’attività secondaria da Technical Blogger richiede che possa creare contenuti in diversi formati, tra cui, quello che impone la disponibilità di risorse non trascurabili è il video.

La selezione dell’hardware che andrà a costituire la propria workstation, deve essere eseguita sulla base delle proprie esigenze e nel mio caso queste corrispondono alle seguenti semplici domande.

Qual è il Sistema Operativo che si vuole installare? Questa scelta potrebbe “tagliare” parecchio hardware, semplicemente per il fatto che siamo costretti a scegliere hardware con disponibilità di driver (possibilmente certificati) per il sistema operativo scelto.
Quali sono i programmi di produttività e i tool di sviluppo maggiormente utilizzati? I programmi che usiamo hanno un peso notevole sulla scelta dell’hardware, è infatti importante conoscere le specifiche di dettaglio di ogni singolo programma.
*Una politica di backup locale è richiesta? * L’applicazione di una politica di backup locale richiede senza ombra di dubbio la scelta di storage dedicato a ospitare le copie di backup dei nostri dati.

E il budget?

Indipendentemente dai miei desideri, la scelta del budget è il primo limite che ho imposto prima di condurre le attività di ricerca per la mia workstation. Chiaro, ognuno di noi vorrebbe tra le mani una Ferrari anche se il più delle volte risulterebbe essere troppo per le proprie esigenze. Per la mia workstation ho deciso di stanziare un budget di 2500€ con il 5% di tolleranza.

Brandizzata o Custom?

Questo è il primo dilemma. Sono sicuro che anche voi abbiate dovuto affrontare questo primo quesito. Personalmente ho risolto la questione ponendo un’altra domanda, ovvero, quale dovrà essere la caratteristica principale della mia workstation? La maggior flessibilità possibile.

Ecco cosa intendo per flessibilità di una workstation:

agilità di configurazione;
hardware standard;
supporto ai più moderni standard hardware;
CPU aggiornabile;
RAM aggiornabile;
hardware compatibile con sistemi operativi Unix/Linux;
costo elastico.

Ho impiegato diverse settimane cercando soluzioni tra i produttori più conosciuti che potessero soddisfare i miei requisiti ma senza successo. Sicuramente il costo ha avuto il suo peso nella scelta ma soprattutto la flessibilità di cui ho scritto poc anzi. Alla fine ho deciso di prendere la strada della soluzione custom o come si suol dire, dell’assemblato.

La scelta dell’hardware

I componenti hardware della mia workstation

La scelta dell’hardware è stata guidata dalle domande che ho illustrato in precedenza. Il fatto di aver scelto Linux come sistema operativo, ha ristretto il range di hardware per via del supporto dei driver (anche certificati) per questo sistema operativo. Solitamente l’hardware che supporta nativamente Linux ha anche un costo maggiore. Per quanto possibile ho cercato di scegliere hardware recentissimo e con ampia possibilità di estensione. La tabella a seguire mostra i componenti hardware principali che ho scelto per la mia workstation e la motivazione che ha guidato la scelta.

| Componente | Modello | Motivazione |
| CPU | AMD Ryzen 9 3900X | Per il tipo di applicazioni che uso e che sviluppo, ho necessità di avere un processore che sia in grado di offrire una potenza computazionale abbastanza generosa a un costo contenuto. Per questo motivo ho scelto questa CPU AMD che offre ben 12 Core e ben 24 Thread. Più thread significa miglior multitasking e prestazioni migliorate con i software che sfruttano pesantemente i thread come gli editor e i transcoder video.

Questo processore supporta inoltre lo standard PCIe® Gen 4.0 di cui ne trarrà grande vantaggio lo storage e lo standard DDR4 per la memoria RAM fino a 3200MHz

|
| GPU | NVIDIA Quadro P2200 | La scelta della GPU è stata abbastanza semplice, guidata dal fatto che il mio scopo è prettamente circoscritto all’uso di programmi EDA (tipo KiCAD, Eagle PCB) di progettazione elettronica, DaVinci Resolve e OBS Studio per la creazione dei miei video tutorial e alcuni software che sfruttano CUDA. Caratteristica molto importante, questa scheda video dispone dei driver certificati per Linux e anche aggiornati. |
| Memoria RAM | DDR 4 3600MHz 64GB Intel XMP-ready e AMD Ryzen | Ho scelto questo taglio apparentemente grande perché utilizzo frequentemente applicazioni basate su container che richiedono una considerevole disponibilità di memoria RAM. La prima certificazione (Intel XMP-ready) attesta la possibilità di sfruttare appieno le potenzialità della CPU in relazione all’applicazione. La seconda, garantisce la piena funzionalità con processori AMD Ryzen. |
| Mother Board | Gigabyte X570 AORUS ULTRA | Questa è stata la scelta più sofferta tra tutti i componenti hardware, le motivazioni principali sono state:

Supporto dei processori AMD Ryzen 5000 Series / 3rd Gen Ryzen / 2nd Gen Ryzen / 3rd Gen Ryzen
Triple PCIe® Gen 4.0 M.2 with Thermal Guards
Intel® WiFi 6 802.11ax (con BT versione 5)
Dual Channel ECC/ Non-ECC Unbuffered DDR4 (5100), 4 DIMMs fino a 128GByte
Front & Rear USB 3.2 Gen2 Type-C Header & HDMI 2.0 support
PCIe 4.0 x16/x8/x4/x1 Slot

Queste caratteristiche consentono una grande flessibilità di estensione futura, dal processore alla memoria RAM. Inoltre i componenti hardware integrati sono compatibili con Linux e le ultime versioni del Kernel e in particolare la scheda WiFi + BT.

|
| Storage NVME | Samsung SSD 980 PRO 1TB | Questo disco SSD NVMe 4 credo che sia una scelta obbligata per avere uno storage con impressionanti prestazioni sia in termini di scrittura sia in termini di lettura. Questo è lo storage principale per SO + Applicazioni + Dati. |
| | Sabrent Rocket 4.0 500GB | Questo è il disco di “seconda scelta” dedicato a un’installazione di Microsoft Windows + test delle nuove versioni della distribuzione Linux che uso. |
| Storage HDD | ST4000VN008-2DR166 (SC60) 4TB x2 | Ho scelto questo storage di casa Segate e serie IronWolf perché indicato per le operazioni di backup. |
| | | |

Blocco Raffreddamento ad Aria, CPU, RAM e GPU

La scelta della distribuzione Linux

Fedora Workstation OS Info

Questa è stata la scelta certa fin dall’inizio della nascita dell’idea della workstation. Per la mia workstation di lavoro ho deciso di andare su una distribuzione stabile, al passo con i tempi e orientata a chi sviluppa. La distribuzione a cui faccio riferimento è Fedora, in particolare Fedora Workstation 34 con la nuova versione 40 di GNOME. Secondo il mio parere sono sette i punti di forza di questa distribuzione.

Ultima versione del Desktop Environment GNOME 40
Aggiornamenti veloci e affidabili
Pacchetti Flatpak e Snap
Una grande comunità
Essenziale
Già pronta per la tecnologia dei container
Supportato da RedHat

Lo schema di partizionamento

Schema di partizionamento storage

L’installazione di un qualunque Sistema Operativo dovrebbe essere eseguita secondo un schema ragionato, pensando al proprio modo di lavorare e senza trascurare il modo di rendere più semplici gli aggiornamenti futuri, in particolare di major release della distribuzione. Implementare un buono schema di partizionamento dello storage a disposizione è a mio avviso essenziale.

La tabella a seguire mostra lo schema di partizionamento cucito sulle mi necessità.

/dev/nvme0n1p6

|
Questa è la partizione dedicata a ospitare i setup/installer o archivi (zip, tar.gz, rpm, etc.) dei software installati sul sistema e fuori dai repository software standard di Fedora.
|
| |

/uwfs02

| xfs | 180GByte |

/dev/nvme0n1p7

Questa è la partizione dedicata a ospitare le macchine virtuali e container (Podman e Docker).

|
| |

/uwfs03

| xfs | 180GByte |

/dev/nvme0n1p8

Questa è la partizione dedicata a ospitare gli ambienti di lavoro suddivisi per progetto e i tool di lavoro specifici.

|
| |

/uwfs04

| xfs | 95GByte |

/dev/nvme0n1p9

Questa è la partizione dedicata a ospitare i sorgenti di progetti di terze parti e la cache di Gradle e Maven.

Ogni partizione indicata in tabella ha uno specifico scopo e rispecchia il mio modo personale di lavoro. Questo schema di partizionamento facilità inoltra l’aggiornamento di major release della distruzione, non intaccando in alcun modo le partizioni di lavoro. Quindi, fare una partizione unica non è mai una buona idea. Nel mio caso specifico, aggiornare da Fedora 33 a Fedora 34, con questo schema di partizionamento è stato una passeggiata di salute. Il nome del file system uwfs{n} sta per User Working File System.

Qualcuno di voi ha sicuramente notato che ho adottato il file system XFS%20e%20nella%202.6.) e non BTRFS, quest’ultimo di default da Fedora 33. La risposta è abbastanza semplice. Non ho ancora avuto modo di testare approfonditamente il BTRFS e ho quindi optato per il rodato XFS.

Il mio software principale di lavoro

A seguire la lista dei software installati sulla mia workstation e che uso giornalmente.

Office Automation
- Libre Office
Email/Calendar
- Mailspring
- GNOME Calendar (con CalDAV Remoto)
Backup
- Timeshift
Source Control

- Git

Meld
Network Tools
- Wireshark
- TCP Dump
- Nmap
VPN/Remote Desktop
- FortiClient
- PulseSecure
- OpenConnect
- Citrix Workspace
- Remmina
Shell/Terminal

- Tilix

ZSH 5.8

Estensione oh-my-zsh
Editor – IDE
- IntelliJ IDEA Enterprise
- Visual Studio Code
- PlatformIO

Sublime Text

Vim + Plugins

Typora
Linguaggi e Compilatori
- JDK 1.7
- JDK 1.8
- JDK 11
- JDK 16

Python 3.x
- GoLang
- GNU C/C++
Build
- Ant
- Maven
- Gradle
- Make
Tool Web Services
- SOAP UI
- Postman
- cURL
Database Client
- SQL Developer
- PostgreSQL Admin
Container
- Docker
- Podman
- MiniOpenShift
VM
- Virtual Box
- VMWare Workstation
Mappe Mentali
- XMind (true)
Video
- OBS Studio
- DavinciResolve Pro
Design/CAD
- Draw.io
- GIMP
- Inkscape

EASY EDA

KICAD
- Eagle PCB

Conclusioni

Il mio desktop

Ogni mestiere necessita degli strumenti adeguati affinché possa essere compiuto nel migliore dei modi e questi devono essere scelti con cura. Vi ho mostrato le motiviazioni che mi hanno portato alla costruzione della mia workstation da Smart Worker, le vostre quali sono?

Credo che la scelta di andare sulla soluzione dell’assemblato è senza dubbio quella che dà la maggior libertà di configurazione e di conseguenza permette di costruire una soluzione hardware adatta alle proprie esigenze.

L'articolo La mia workstation di sviluppo da Smart Worker sembra essere il primo su Antonio Musarra's Blog.

Raspberry Pi, ESP32, EMQ X and Node RED together

Antonio Musarra — Mon, 10 May 2021 09:04:14 +0000

This project refers to the article Un trittico vincente: ESP32, Raspberry Pi e EMQ X Edge published
on Antonio Musarra's Blog

This project contains the source code to be installed on the ESP32 devices that
are part of the IoT solution described by the article mentioned above.

It's easy to understand how things work with a simple diagram, and the one below
shows two devices (ESP32), a dashboard and a mobile phone. In this case and in
the context of the Publish/Subscribe pattern, these components take on the role
of both publisher and subscriber, and the broker is the message dispatcher.

The Dashboard and the Mobile Phone indicate to the broker that they want to
subscribe to all the messages that belong to the topic device01/temperature and
device02/temperature. This means that they will receive all the messages
published by the devices (device01 and device02) on their respective topics.
The Dashboard and the Mobile Phone publish "command" messages on the two topics
device01/command and device02/command, the respective devices are subscribed
to these two topics and will then receive the commands to activate or deactivate,
for example, relays or actuators.

Figure 1 - Animation showing the Publish/Subscribe architectural style in action

The common dialect used for communications between Gateway, Device and Dashboard
is the MQTT. The ESP32 communicates with the environmental sensor via the I2C bus,
while to pursue actions towards the relay module it uses four GPIO channels.

Figure 2 - Architecture of the IoT solution with evidence of hardware and software components

To implement this solution from the hardware point of view, we need to know how
to make the connections between the pieces of "iron" so that everything can work
correctly. The wiring diagram shows the connections concerning the device, then
the BME 280 sensor and the relay module to the ESP32 DOIT DEV KIT development
board (30-pin). The diagram also shows the connection of the Gateway with a
16 × 2 LCD display, inserted with the aim of showing the environmental data and
the status of the relays, information whose source is represented by each device.

Figure 3 - Electrical diagram of the hardware components that make up the IoT solution

The development board of the ESP32 is equipped with a Micro-USB port for powering
the module itself and uploading the firmware. This development board supports
automatic upload, so it will not be necessary to manually change the upload
and execution mode when it is necessary to upload the new software.

1. How to program the ESP32

ESP-IDF is Espressif's official IoT development framework for the ESP32 and ESP32-S series of SoCs. It provides a self-contained SDK for any generic application development on these platforms, using programming languages such as C and C ++. ESP-IDF currently powers millions of devices in the field and allows you to build a variety of networked products, ranging from simple light bulbs and toys to large appliances and industrial devices.

For this solution, however, I chose to adopt the Arduino framework based on Wiring , for three simple reasons: simple to use, extensive documentation and widely disseminated and known .

Will we then use the classic Arduino IDE programming environment? No, I propose something different.

I have always been of the idea that from the moment a software project is created, as far as possible, it is better not to link it to a specific IDE (Integrated Development Environment). I like the fact that the projects are independent from the IDE, I have to be able to build the project from the command line: git clone, build and install .

The something else is PlatformIO . It is a cross-platform, cross-architecture , multiple-framework : a tool for embedded systems engineers and software developers who write applications for embedded products.

Without going too deeply into the implementation details of PlatformIO, the work cycle of the project developed using PlatformIO is as follows:

The development boards involved are chosen by specifying them in the platformio.ini file (project configuration file).
Based on this list of boards, PlatformIO downloads the required toolchains and installs them automatically.
The development of the code begins and PlatformIO makes sure that it is compiled, prepared and loaded on all the cards of interest.
To write the code you can use your favorite editor or IDE, alternatively you can use PlatformIO for VSCode . The only requirement is the installation of PlatformIO Core (CLI) on your development machine. PlatformIO Core is written in Python and therefore works on Windows, macOS, Linux, FreeBSD and ARM- based credit-card sized computers ( Raspberry Pi , BeagleBone , CubieBoard , Samsung ARTIK , etc.).

The minimum version of PlatformIO Core to install is version 5.x. If you have already installed a version of PlatformIO, you can upgrade through the command pio upgrade.

Now that we have chosen PlatformIO as a software development support tool, we can move on to analyze the developed code.

2. Writing the software for the ESP32

The main responsibilities for the software to be created for the ESP32 are: the reading of environmental data and the subsequent publication on the topic esp32/telemetry_data through the Message Broker, as well as receiving the commands from the topic esp32/command and the subsequent execution of the same. The macro responsibilities are indicated below.

I2C setup for the GY-BME280 sensor
GPIO setup for relays
Setup of the connection to the WiFi network
Setup of the connection to the MQTT Message Broker
Reading of environmental data from the GY-BME280 sensor
Preparation of the message with the environmental data in JSON format
Preparation of the message with the relay status data in JSON format
Publication of environmental data via MQTT
Publication of the relay status via MQTT
Reading and execution of commands arriving on the topic esp32/command

The basic functions of the esp32_mqtt_publish_subscribe.cpp program are:

void setup_wifi() : the responsibility of this function is to establish the connection to the WiFi network. The connection parameters (SSID and username) can be set during the build phase; later we will see how. The WiFi network to which we must connect the devices must guarantee connectivity to the Message Broker;
void reconnect() : the responsibility of this function is to establish the connection to the Message Broker and manage any reconnections, for example in cases where the connection to the WiFi network fails. Immediately after the connection to the Message Broker, the topic is subscribed to esp32/command with QoS equal to one and the initialization of the relay status to off;
void update_relay_status(int relayId, const int status) : the responsibility of this function is to update the status of the relays by publishing messages on the related topics esp32/releay _ $ {id} _status;
int * get_relays_status() : the responsibility of this function is to return an array of four elements containing the status of the relays whose values can be: 0 for off and 1 for on;
void callback(char * topic, byte * message, unsigned int length) : this is the callback function called whenever a message is received on the topic for which you have an active subscription and in this case the topic for which there is a active subscription is esp32/command. The responsibility of this function is to acquire the messages arriving on the esp32/command topic, parse the received command and perform the corresponding action which can be: activate/deactivate the relay or publish the relay status.

By adopting the Arduino framework, we also carry the mandatory setup() and loop() functions . The setup() function is executed only once, at start-up, and the body of this function foresees:

initialization of the serial communication interface ;
initialization of the logging framework;
initialization and check of the I2C channel for the BME280 sensor;
initialization of the clientId variable used to identify the device as a client in the MQTT connection to the Message Broker;
initialization of the connection to the WiFi network;
pin mode initialization for relays (or actuators);
initialization of the state of the relays (via digitalWrite() bringing them all four to the deactivated state;
initialization of the NTP Client (with UTC timezone).

The loop() function is instead executed in "continuation" and the body of this function provides:

time client update via NTP;
control of the connection to the Message Broker and possible recession;
calling the loop() method on the MQTT client to allow processing of incoming messages and maintain connection to the server;
preparation of the message in JSON format that contains the environmental data coming from the BME280 sensor;
publication of environmental data on the topic esp32/telemety_data;
sending of the published JSON message on the serial line (for debugging purposes)

3. Compilation of the project

Building the project is quite simple and just the way I like it: git clone and build . Remember that before proceeding further, the required requirement is the installation of PlatformIO Core on your development machine.

Until now we have not made any reference to how to configure the access parameters to the WiFi network and the Message Broker. What must be done to configure the access parameters to the WiFi network and the Message Broker?

In these cases, I usually prefer to follow the path of build flags . These flags affect the pre-processor, compilation, assembly, and linking processes for C and C ++ code. All compiler and linker flags can be used. In this case we will use the build flag -D name = definition which affects the CPPDEFINES build variable . The contents of the definition are tokenized and processed as if they appeared during the third translation stage in a #define directive. For more information I invite you to read C preprocessor .

At the beginning of the esp32_mqtt_publish_subscribe.cpp source code there are the various ifdef… endif sections for reading all the build flags. The build flags defined on the project's platformio.ini file are shown below . Among the build flags, in addition to those concerning the access parameters to the WiFi network and the Message Broker, we also have a build parameter that sets the name of the device. Note that the values of these parameters come from their environment variables.

Before continuing with the compilation process, it is therefore necessary to set the environment variables indicated above. Since we have two devices on which to install the software, we are careful to modify the DEVICE_NAME environment variable . This environment variable can take the following values: esp32-zone-1 and esp32-zone-2. The device name information is reported on the JSON message that contains the environmental data.

Below are the commands necessary to complete the compilation of the project and thus generate the artifact ( firmware.bin ) which will subsequently be installed on the ESP32 device.

During the build process, PlatformIO also downloads the libraries on which the project depends and which are indicated in the lib_deps section of the platformio.ini file (see also Table 5).

The Compiling the ESP32 MQTT Publish/Subscribe project with PlatformIO screencast is shown below so that you can see exactly the execution of the steps indicated above.

4. Upload of the software on the ESP32 device

We have reached the final step for what concerns the ESP32 devices, that is, the upload of what can also be called the firmware of our devices. The upload operation is always assigned to PlatformIO using the simple command: pio run --target upload --environment esp32dev. The same operation can also be performed through the IDE.

In reality it is also possible to skip the project compilation process, the upload process, if necessary, will start the compilation of the code and then continue with the upload on the ESP32.

The Upload software to ESP32 Device via PlatformIO screencast is shown below so that you can see exactly the execution of the .pio/build/esp32dev/firmware.bin firmware upload phase on the ESP32 device.

On the image below it is possible to see the status of the LEDs after uploading the software to the devices and in particular of the blue LED. When the blue led is steady on, it means that:

the connection to the WiFi network was successful;
the ping to the Message Broker was successful;
the connection to the EMQ X Edge Message Broker went well;
the subscription to the topic esp32/command was successful.

Figure 4 - Indication of the operation of the ESP32 device through the blue LED on the development board

Ultimately this led ( attested on GPIO 2 ) gives us indications if everything is going the right way. In this case we are lucky, the led is on and we are therefore sure that the environmental data are published on the topic esp32/telemetry_data and that the device is ready to receive commands on the topic esp32/command. If we wanted to check the activity of the device, we could connect to the serial monitor always using PlatformIO, using the command: pio device monitor --environment esp32dev

The following image shows the output of the above command. As you can see, we get several information in the output. Information on the chip model, information on the WiFi network to which the device is connected, information on the Message Broker to which the device is connected and finally the JSON published on the topic esp32/telemetry_data.

Figure 5 - Attach of the serial monitor on one of the ESP32 devices in order to monitor the activities in progress

We have to repeat the same software compilation and upload operations also for the second device and once done we can define this phase concluded and go to carry out the first integration test.

5. The final result

The two images below show the different information that is displayed on the LCD display. The information refers in particular to environmental temperature and humidity data and the status of the relays. The LCD display also shows information on which device is the data source.

Figure 6 - LCD display showing environmental temperature and humidity data for each device

Figure 7 - LCD display showing the status of the relays for each device

Figure 8 - MQTT Dashboard Node-RED for the ESP32 Device 1