Integrare smart card in IPFire: pcsc-lite, CCID e OpenSC

Questo tutorial mostra come compilare e integrare pcsc-lite, driver CCID e OpenSC in IPFire 2.19, creare gli addon in formato pakfire e installarli su un sistema IPFire. Fornisce la sequenza di comandi, i problemi comuni (pkg-config, variabili d’ambiente, regole udev) e una checklist operativa per sviluppatori e amministratori.

Introduzione

Questo articolo prosegue il lavoro precedente sul firewall IPFire. Qui spieghiamo come aggiungere il supporto per token hardware (smart card) e i lettori CCID nel progetto IPFire. Le tre componenti compilate e impacchettate per IPFire 2.19 sono:

• pcsc-lite (demone PC/SC per smart card)
• CCID (driver open source per lettori smart card CCID)
• OpenSC (strumenti e librerie open source per smart card)

Definizioni rapide:

• PC/SC: API standard per l’accesso a smart card su sistemi Linux/Unix.
• CCID: specifica per lettori di smart card che usano USB.
• OpenSC: librerie e strumenti che implementano PKCS#11 e PKCS#15 per gestione e uso di smart card.

Per cosa si usano le smart card in un ambiente di rete:

• Autenticazione sicura per l’accesso web
• Login al workstation
• Crittografia e firma di file
• VPN (OpenVPN, L2TP)
• Crittografia email

Alcuni vendor supportati da OpenSC includono: ASEPCOS, FTCOSPK01C, OpenPGP Card, Cyberflex, CardOs, STARCOS.

Panoramica dell’ambiente di sviluppo

Per la preparazione dell’ambiente di sviluppo fare riferimento all’articolo precedente, dove è descritto come impostare l’LFS (Linux From Scratch) e la shell di test di IPFire. In sintesi, si lavora nella shell di test invocabile da:

./make shell

I sorgenti vengono posizionati in /usr/src/cache. In questo tutorial il pacchetto sorgente necessario è già nella cache.

Il sorgente di pcsc-lite visibile nella cache:

Compilazione in ambiente di test LFS

Prima di compilare pcsc-lite, installare la libreria di sviluppo libudev-dev nella shell di test se richiesto dal sistema di build:

apt-get install libudev-dev

Estrai il pacchetto e lancia lo script di configurazione:

tar -xf pcsc-lite-1.8.18.tar.bz2
./configure

Se il comando ./configure non riporta errori, procedere con make e make install:

./make
./make install

L’installazione di pcsc-lite mostra i percorsi importanti usati più avanti per compilare CCID:

Verificare che pcscd sia in esecuzione nella shell di test:

Compilare CCID: problemi comuni e soluzioni

Il pacchetto CCID fornisce i driver per vari lettori. Se lo script ./configure segnala che pcsc-lite non è trovato, impostare PCSC_CFLAGS per indicare l’include di PCSC:

./configure PCSC_CFLAGS=-I/usr/local/include/PCSC

Un altro errore frequente è la mancanza di libpcsclite.pc nel percorso di pkg-config. Esportare PKG_CONFIG_PATH e rilanciare configure:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
./configure PCSC_CFLAGS=-I/usr/local/include/PCSC

Quando configure trova le librerie PCSC, l’output mostra i file richiesti:

Compilare e installare CCID:

./make
./make install

Copiare le regole udev fornite dal pacchetto CCID nella directory di udev in IPFire, per permettere al sistema di riconoscere i lettori USB senza intervento manuale:

cp README/udev/92_pcscd_ccid.rules /etc/udev/rules.d/

Nel nostro esempio il file 92_pcscd_ccid.rules è stato copiato in /etc/udev/rules.d/.

Compilazione di OpenSC

Posizionarsi nella cache dove è presente il sorgente di OpenSC e lanciare lo script di configure per verificare dipendenze e feature:

L’output di configure può essere lungo: verificare la presenza di PKCS#11, PKCS#15, libpcsclite e degli header di tutte le dipendenze richieste.

Compilare e installare OpenSC nella shell di test:

./make
./make install

Verifica finale in ambiente di test:

A questo punto tutti gli strumenti necessari sono costruiti nell’LFS shell. La fase successiva è creare gli addon IPFire in formato pakfire.

Creazione degli addon per IPFire (pakfire)

La procedura dettagliata per creare addon in formato IPFire è stata mostrata nell’articolo precedente (sezione Building PSAD addon). Qui riassumiamo i punti principali e aggiungiamo suggerimenti pratici:

• Ogni pacchetto ha uno script di compilazione LFS (lfs script) nella directory lfs/
• Le modifiche agli addon vanno fatte anche nello script make.sh della tree di build

Creare gli script LFS per pcsc-lite-1.8.18, ccid-1.4.24 e opensc-0.16.0 e inserirli nella directory lfs di ipfire-2.x.

Esempi di LFS script per i tre addon:

Aggiornare make.sh per includere i nuovi pacchetti:

Per compilare gli addon usare i comandi dedicati:

ipfiremake pcsc-lite
ipfiremake ccid
ipfiremake opensc

Oppure, nel flusso di build generale, eseguire il build script principale (talvolta è necessario lanciarlo due volte durante la prima integrazione):

./make.sh build

Se il primo build segnala che mancano alcune rootfiles, cercare i file generati in log/ e copiarli in config/rootfiles/packages/ cambiando il nome per farlo combaciare con il nome LFS del pacchetto:

cp log/pcsc-lite-1.8.18 config/rootfiles/packages/pcsc-lite
cp log/ccid-1.4.24 config/rootfiles/packages/ccid
cp log/opensc-0.16.0 config/rootfiles/packages/opensc

Nota: i rootfiles possono contenere il carattere “+” che va rimosso prima di eseguire nuovamente la build. Rimuovere il “+” con sed:

sed -i 's/+//g' config/rootfiles/packages/pcsc-lite
sed -i 's/+//g' config/rootfiles/packages/ccid
sed -i 's/+//g' config/rootfiles/packages/opensc

Preparare gli script di installazione per pakfire: creare le directory src/paks/pcsc-lite, src/paks/ccid, src/paks/opensc e copiare i file template install.sh, uninstall.sh, update.sh da src/paks/default/ nelle nuove directory.

Eseguire di nuovo il build generale:

./make.sh build

Questa volta ignorare eventuali messaggi sui rootfiles mancanti, se sono stati già aggiornati nella cartella config. Al termine del processo troverai i pacchetti ipfire nella directory packages:

Esempi di nomi dei pacchetti creati: pcsc-lite-1.8.18-2.ipfire, ccid-1.4.24-2.ipfire, opensc-0.16.0-2.ipfire.

Installazione dei pacchetti pakfire sul sistema IPFire live

Copiare i pacchetti compilati nella macchina IPFire live, tipicamente in /opt/pakfire/tmp:

Estrarre i pacchetti sul sistema live:

tar -xvf pcsc-lite-1.8.18-2.ipfire
tar -xvf ccid-1.4.24-2.ipfire
tar -xvf opensc-0.16.0-2.ipfire

Eseguire gli script di installazione inclusi nei pacchetti:

./install.sh

Schermate di installazione riuscite:

Dopo questi passaggi il sistema IPFire è in grado di riconoscere e utilizzare smart card e lettori CCID tramite pcscd e i moduli di OpenSC.

Checklist rapida per la compilazione e il packaging

• Verificare che /usr/src/cache contenga i sorgenti pcsc-lite, ccid, opensc
• Eseguire ./make shell e lavorare nella shell di test LFS
• Installare dipendenze (libudev-dev, pkg-config) nella shell di test
• Compilare e installare pcsc-lite (./configure, make, make install)
• Esportare PKG_CONFIG_PATH se necessario
• Compilare CCID impostando PCSC_CFLAGS e correggendo PKG_CONFIG_PATH
• Copiare regole udev in /etc/udev/rules.d/
• Compilare OpenSC e verificare supporto PKCS#11/PKCS#15
• Preparare LFS script e aggiornare make.sh
• Copiare rootfiles da log/ in config/rootfiles/packages/ e rimuovere ‘+’
• Creare src/paks/ e aggiungere install.sh/uninstall.sh/update.sh
• Eseguire ./make.sh build fino alla creazione dei pacchetti
• Copiare i pacchetti in /opt/pakfire/tmp del sistema live e installare

Ruoli e responsabilità (role‑based checklist)

Sviluppatore LFS / Builder

• Preparare i sorgenti e gli LFS script
• Gestire le variabili d’ambiente PKG_CONFIG_PATH e PCSC_CFLAGS
• Verificare output di configure e correggere dipendenze mancanti

Maintainer del pacchetto IPFire

• Inserire rootfiles corretti in config/rootfiles/packages
• Fornire script install/uninstall/update in src/paks/
• Testare l’installazione sui sistemi di staging

Amministratore di sistema IPFire

• Copiare i pacchetti nella macchina live
• Eseguire l’installazione e verificare servizi (pcscd)
• Testare lettore smart card e flusso di autenticazione

Test di accettazione (criteri)

• pcscd si avvia all’avvio della macchina e risponde a pgrep o ps
• I lettori CCID vengono visti tramite pcsc_scan o pcscd log
• OpenSC rileva la smart card e permette operazioni PKCS#11 (es. pkcs11-tool)
• Gli script di installazione pakfire non lasciano file temporanei in /tmp
• Le regole udev sono presenti in /etc/udev/rules.d/ e consentono il riconoscimento senza root

Esempi di comandi di verifica

• Verificare pcscd:

ps aux | grep pcscd
pcsc_scan

• Verificare lettore e carta con OpenSC:

pkcs11-tool --list-slots
opensc-tool -l

Risoluzione dei problemi comuni

Problema: configure di CCID non trova pcsc-lite

• Controllare che pcsc-lite sia stato installato in /usr/local
• Esportare PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
• Lanciare ./configure PCSC_CFLAGS=-I/usr/local/include/PCSC

Problema: rootfiles mancanti durante il build

• Cercare i file in log/ dopo la prima compilazione
• Copiarli in config/rootfiles/packages/
• Rimuovere il carattere + con sed

Problema: lettore non riconosciuto al collegamento USB

• Verificare le regole udev in /etc/udev/rules.d/
• Ricaricare udev: udevadm control –reload e udevadm trigger
• Controllare dmesg per messaggi del kernel

Problema: permessi PKCS#11 o accesso alla smart card negato

• Controllare ownership e permessi dei nodi device in /dev
• Assicurarsi che le regole udev impostino mode e group corretti

Quando questa procedura può fallire (controesempi)

• Hardware proprietario non conforme allo standard CCID: alcuni lettori richiedono driver binari non presenti in CCID
• Smart card con filesystem o file system PKCS#15 non standard: OpenSC potrebbe non leggere dati proprietari
• Sistemi IPFire con dipendenze di librerie differenti: percorsi non standard di installazione possono richiedere aggiustamenti manuali delle variabili d’ambiente

Approcci alternativi

• Usare middleware proprietario del vendor quando CCID/OpenSC non supportano completamente il dispositivo
• Creare un container Linux separato che esponga i dispositivi smart card alla rete e usare IPFire solo come gateway, evitando di modificare la base di IPFire

Mini‑metodologia per l’integrazione (passi sintetici)

1. Verificare compatibilità hardware del lettore e della smart card
2. Preparare sorgenti nella cache LFS
3. Compilare pcsc-lite, CCID, OpenSC nella shell di test
4. Preparare gli LFS script e i rootfiles per pakfire
5. Costruire i pacchetti ipfire e testarli in staging
6. Distribuire su sistema live e validare il flusso di autenticazione

Sicurezza e privacy

• Trattare le smart card come dispositivi di autenticazione a privilegio elevato: proteggere gli script di installazione e i file rootfile
• Non loggare dati sensibili delle smart card (PIN, chiavi private) nei log
• Per scenari con dati personali, verificare che la gestione delle chiavi e delle identità sia conforme alle norme locali sulla protezione dei dati

Note di compatibilità e migrazione

• I percorsi di installazione possono variare tra release IPFire; verificare sempre /usr/local/include e /usr/local/lib
• Se si migra da una versione precedente, controllare eventuali conflitti con pacchetti pcsc-lite presenti

Diagramma decisionale per scegliere il percorso di integrazione

flowchart TD
  A[Hai un lettore CCID standard?] -->|Sì| B[Compila pcsc-lite e CCID]
  A -->|No| C[Verifica driver vendor]
  C -->|Driver binario disponibile| D[Usa driver vendor in un container o patcha kernel]
  C -->|No| E[Considera soluzioni alternative]
  B --> F[Compila OpenSC]
  F --> G[Test in staging]
  G -->|OK| H[Costruisci pacchetti pakfire]
  G -->|NO| I[Risolvi dipendenze/configurazione]

Suggerimenti pratici e trucchi

• Durante la fase di sviluppo usare la shell LFS per evitare di inquinare l’installazione live
• Tenere traccia delle versioni dei pacchetti (pcsc-lite/CCID/OpenSC) e della corrispondente compatibilità
• Verificare sempre i permessi impostati dalle regole udev

Conclusione

In questo tutorial abbiamo integrato il supporto per smart card e lettori CCID in IPFire 2.19 compilando pcsc-lite, CCID e OpenSC, creando i relativi addon pakfire e installandoli sul sistema live. Gli step fondamentali sono: preparare l’ambiente LFS, risolvere le dipendenze (PKG_CONFIG_PATH, PCSC_CFLAGS), creare e correggere i rootfiles, costruire i pacchetti e installarli. La procedura è utile per aggiungere autenticazione hardware-based e funzioni di sicurezza come VPN e cifratura file tramite smart card.

Important: testare sempre in un ambiente di staging prima di distribuire in produzione.

Summary

• Compilare pcsc-lite prima di CCID, esportando PKG_CONFIG_PATH se necessario
• Rimuovere il carattere + dai rootfiles e assicurarsi che i pacchetti abbiano gli script di installazione
• Verificare le regole udev e i permessi dei device per permettere l’accesso alle smart card