AsciiDoc files for eBook

CHANGELOG.md

@@ -13,6 +13,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 ### Security
 
+## [1.0.2.dev0] - 2024-07-04
+
+### Added
+- Added the AsciiDoc for eBook
+
 ## [1.0.1.dev1] - 2024-07-07
 
 ### Added

LICENSE.markdown

@@ -1,7 +1,7 @@
     MIT License
 
     Smart Card Contactless Raspberry Pi sample project
-    Copyright (c) 2022 Antonio Musarra (Antonio Musarra's Blog - https://www.dontesta.it)
+    Copyright (c) 2024 Antonio Musarra (Antonio Musarra's Blog - https://www.dontesta.it)
 
         Il permesso è così garantito, gratuito, a qualunque persona che ottenga
         una copia di questo software e i file associati di documentazione (il

docs/asciidoc/attributes/_attributes-common.adoc

@@ -0,0 +1,25 @@
+:author: Antonio Musarra
+:revnumber: 1.0.1
+:revdate: Luglio 11, 2024
+:email: antonio.musarra@gmail.com
+:description: 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 quelli che amo definire bonariaménte “pezzi di ferro”.
+
+:keywords: smartcard, raspberry, mifare, python
+:encoding: utf-8
+:lang: it
+:toc: left
+:hardbreaks-option:
+:sectnums:
+:sectnumlevels: 3
+:!figure-caption:
+:!chapter-signifier:
+:imagesdir: ../images
+:source-highlighter: rouge
+:sectanchors: true

docs/asciidoc/attributes/_attributes-pdf.adoc

@@ -0,0 +1,2 @@
+:doctype: book
+:icons: font

docs/asciidoc/chapters/00_informazioni_articolo.adoc

@@ -0,0 +1,38 @@
+[colophon]
+= Informazioni sulla Guida
+
+**Antonio Musarra,** Raspberry Pi e Smart Card Mifare Classic 1K - Guida pratica per realizzare un sistema di autenticazione con smart card contactless su Raspberry Pi
+
+Copertina e impaginazione di Antonio Musarra
+
+Prima edizione digitale Luglio 2024
+
+Serie: Elettronica&Informatica (#elettronica-informatica)
+
+[.text-left]
+Promosso da: Antonio Musarra's Blog (https://www.dontesta.it)
+
+Profilo LinkedIn https://www.linkedin.com/in/amusarra/
+
+[.text-left]
+Il progetto di esempio realizzato per quest'opera è disponibile sul repositoy GitHub all'indirizzo https://github.com/amusarra/smartcard-contactless-raspberry-pi
+
+[.text-left]
+Quest'opera è stata realizzata usando l'approccio doc-as-code e il testo è stato scritto in formato AsciiDoc.
+
+Nel caso di errori, segnalazioni o suggerimenti, si prega di aprire una issue o discussione sul repository GitHub.
+
+[.text-left]
+Progetto Smart Card Contactless Raspberry Pi
+
+[.text-left]
+. Apertura issue https://github.com/amusarra/smartcard-contactless-raspberry-pi/issues
+. Apertura discussione https://github.com/amusarra/smartcard-contactless-raspberry-pi/discussions
+
+Nell'ambito del social coding e del contributo alla comunità, è possibile contribuire al progetto con una pull request per migliorare questa guida e il progetto di esempio.
+
+[.text-left]
+**Note sul Copyright**
+Tutti i diritti d’autore e connessi sulla presente opera appartengono all’autore Antonio Musarra. Per volontà dell’autore quest’opera è rilasciata nei termini della licenza Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International il cui testo integrale è disponibile alla pagina web https://creativecommons.org/licenses/by-nc-sa/4.0/deed.it
+
+Tutti i marchi riportati appartengo ai legittimi proprietari; marchi di terzi, nomi di prodotti, nomi commerciali, nomi corporativi e società citati possono essere marchi di proprietà dei rispettivi titolari o marchi registrati d’altre società e sono stati utilizzati a puro scopo esplicativo e a beneficio del possessore, senza alcun fine di violazione dei diritti di copyright vigenti.

docs/asciidoc/chapters/01_introduzione.adoc

@@ -0,0 +1,12 @@
+<<<
+== Introduzione
+
+Le https://it.wikipedia.org/wiki/Smart_card[Smart Card] fanno parte ormai da tempo del nostro quotidiano: dalla https://it.wikipedia.org/wiki/Carta_SIM[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 quelli che amo definire bonariaménte **"pezzi di ferro"**.
+
+Quasi due anni fa ho scritto l'articolo https://www.dontesta.it/2020/07/17/raspberry-pi-esempio-applicazione-ts-cns-smartcard[Raspberry Pi – Un esempio di applicazione della TS-CNS], dove mostravo come poter creare un sistema di accesso utilizzando la propria TS-CNS; in questo articolo vedremo invece come mettere insieme: https://www.raspberrypi.org/[Raspberry Pi], modulo da quattro relè, lettore di Smart Card e https://en.wikipedia.org/wiki/MIFARE[MIFARE Classic 1K] contactless Smart Card per poi armonizzare il tutto, sviluppando 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 notevoli. 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.

docs/asciidoc/chapters/02_descrizione_scenario.adoc

@@ -0,0 +1,31 @@
+<<<
+== 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.
+
+image::hardware_diagram_smartcard_access_raspberry_pi_1.jpg[title="*Figura 1* - Schema hardware della soluzione di accesso (Smart Card icon da https://www.smartcardfocus.com/)"]
+
+La https://www.nxp.com/products/rfid-nfc/mifare-hf/mifare-classic:MC_41863[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 https://shop.bit4id.com/en/prodotto/minilector-cie/[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 https://it.wikipedia.org/wiki/General_Purpose_Input/Output[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 https://www.bpmn.org[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.
+
+image::guest_receiving_process.jpg[title="*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.
+
+image::room_access_process.jpg[title="Figura 3 - Processo di accesso alla stanza"]
+
+Credo che 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:
+
+1.  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;
+2.  la verifica che la chiave elettronica sia abilitata e associata all'ospite e alla stanza a cui consentire l'accesso.

docs/asciidoc/chapters/03_dettaglio_mifare.adoc

@@ -0,0 +1,24 @@
+<<<
+== Dettagli sulle carte MIFARE Classic 1K
+
+MIFARE è un marchio registrato di https://www.nxp.com/[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 https://it.wikipedia.org/wiki/ISO/IEC_14443[ISO/IEC 14443A] (caratteristiche fisiche, potenza e interfaccia del segnale radio, inizializzazione e anticollisione), poiché utilizzano un set di comandi proprietari invece del protocollo https://www.iso.org/standard/73599.html[ISO/IEC 14443-4] di alto livello e non sono conformi al formato frame https://www.iso.org/standard/73598.html[ISO/IEC 14443-3] e nelle comunicazioni crittografate usano un protocollo di sicurezza proprietario https://en.wikipedia.org/wiki/Crypto-1[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 https://it.wikipedia.org/wiki/Smart_card#Smart_card_a_sola_memoria[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 (https://it.wikipedia.org/wiki/EEPROM[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.
+
+image::mifare_classic_1k_memory_organization_MF1S50YYX_V1.png[title="*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.
+
+image::mifare_1K_memory_map-2.jpg[title="*Figura 5* - Memory Map della MIFARE Classic 1K completa di range d&#39;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.

docs/asciidoc/chapters/04_apdu.adoc

@@ -0,0 +1,36 @@
+<<<
+== 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 https://www.iso.org/obp/ui/#iso:std:iso-iec:7816:-4:ed-4:v1:en[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.
+
+image::structure_of_request_command_apdu-1-scaled.jpg[title="*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.
+
+image::apdu_command_for_request_uid.jpg[title="*Figura 7* - Comando per ottenere l&#39;UID della Smart Card MIFARE Classic 1K"]
+
+image::structure_of_response_command_apdu-1.jpg[title="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 (https://it.wikipedia.org/wiki/Bit_meno_significativo[LSB]) a sinistra e quello più significativo (https://it.wikipedia.org/wiki/Bit_pi%C3%B9_significativo[MSB]) a destra (quindi usa il sistema https://it.wikipedia.org/wiki/Ordine_dei_byte[little-endian]).
+
+image::apdu_response_of_the_command_uid-1.jpg[title="*Figura 9* - Risposta del comando APDU per ottenere l&#39;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.
+
+[NOTE]
+====
+**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.
+====
+
+image::response_apdu_command_uid_sw1_sw2-scaled.jpg[title="Figura 10 - Codici di risposta APDU comando UID"]
+
+<<<
+Per maggiori dettagli sui comandi ed eventuali estensioni, consiglio sempre di consultare il datasheet della https://www.nxp.com/docs/en/data-sheet/MF1S50YYX_V1.pdf[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.

docs/asciidoc/chapters/05_atr.adoc

@@ -0,0 +1,19 @@
+<<<
+== Cos’è l’Answer to reset o ATR
+
+La prima risposta di una Smart Card inserita in un lettore si chiama https://en.wikipedia.org/wiki/Answer_to_reset[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 https://it.wikipedia.org/wiki/ISO/IEC_7816[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 https://smartcard-atr.apdu.fr/parse?ATR=3B8F8001804F0CA000000306030001000000006A[Smart card ATR parsing] sviluppato da https://ludovicrousseau.blogspot.com[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.
+
+image::mifare_classic_1k_atr_parsing.png[title="*Figura 11* - Dettagli estratti sull&#39;ATR della Smart Card MIFARE Classic 1K"]
+
+Ludovic Rousseau ha fatto un ottimo lavoro tracciando dal 2002 un http://ludovic.rousseau.free.fr/softwares/pcsc-tools/smartcard_list.txt[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** (https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi[Tessera Sanitaria - Carta Nazionale Servizi]) e **CIE** (https://developers.italia.it/it/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.
+
+image::output_of_pcsc_scan_smart_card_cie.png[title="Figura 12 - Esempio di output del comando pcsc_scan che mostra le informazioni estratte dalla Smart Card, in questo caso CIE"]