Skip to content

Commit 9e9e18b

Browse files
amusarraamusarra
authored
Merge pull request #3 from amusarra/feature/doc-as-code
Aggiunta documentazione Doc-As-Code
2 parents 2e1609e + 1645e9e commit 9e9e18b

20 files changed

+1204
-1
lines changed

‎.github/workflows/publish_doc_to_gh_pages.yml

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: ci
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: write
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Configure Git Credentials
15+
run: |
16+
git config user.name github-actions[bot]
17+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
22+
- uses: actions/cache@v4
23+
with:
24+
key: mkdocs-material-${{ env.cache_id }}
25+
path: .cache
26+
restore-keys: |
27+
mkdocs-material-
28+
- run: pip install mkdocs-material
29+
- run: mkdocs gh-deploy --force

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -90,4 +90,5 @@ ENV/
9090
.ropeproject
9191

9292
# Idea
93-
.idea/
93+
.idea/
94+
/site/

‎CHANGELOG.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
### Changed
12+
### Removed
13+
### Deprecated
14+
### Security
15+
16+
## [1.0.1.dev0] - 2024-07-07
17+
18+
### Added
19+
- Added the `CHANGELOG.md` file
20+
- Added the documentation for the project
21+
- Added GitHub Actions for publishing the documentation to the GitHub Pages
22+
23+
## [1.0.0.dev0] - 2022-03-11
24+
- First release of the project

‎docs/guida/atr.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
La prima risposta di una Smart Card inserita in un lettore si chiama
2+
<a href="https://en.wikipedia.org/wiki/Answer_to_reset" target="_blank"
3+
rel="noopener"><strong>ATR</strong></a> (*Answer to reset*). Lo scopo
4+
dell'ATR è descrivere i parametri di comunicazione supportati, la natura
5+
e lo stato della carta. L'ottenimento di un ATR viene spesso utilizzato
6+
come prima indicazione che questa sia operativa, e il suo contenuto
7+
viene esaminato come prima prova che sia del tipo appropriato per un
8+
determinato utilizzo. <span style="text-decoration: underline;">Il
9+
lettore di Smart Card, il driver del lettore e il sistema operativo
10+
utilizzeranno questi parametri per stabilire una comunicazione con la
11+
scheda.</span>
12+
13+
L'ATR è descritto dallo standard
14+
<a href="https://it.wikipedia.org/wiki/ISO/IEC_7816" target="_blank"
15+
rel="noopener"><strong>ISO/IEC 7816-3</strong></a>. I primi byte
16+
dell'ATR descrivono i parametri elettrici, seguiti da byte che
17+
descrivono le interfacce di comunicazione disponibili e i rispettivi
18+
parametri. Questi byte di interfaccia sono quindi seguiti da byte
19+
storici che non sono standardizzati e sono utili per trasmettere
20+
informazioni proprietarie come il tipo di scheda, la versione del
21+
software integrato o lo stato della scheda. Infine questi byte storici
22+
sono eventualmente seguiti da un byte di checksum.
23+
24+
Potremmo riassumere che l'**ATR contiene "un sacco di dati" che ci
25+
dicono vita morte e miracoli della Smart Card**. Per esempio, scopriamo
26+
di più sull'ATR
27+
`3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 00 01 00 00 00 00 6A` 
28+
utilizzando il tool <a
29+
href="https://smartcard-atr.apdu.fr/parse?ATR=3B8F8001804F0CA000000306030001000000006A"
30+
target="_blank" rel="noopener">Smart card ATR parsing</a> sviluppato da
31+
<a href="https://ludovicrousseau.blogspot.com/" target="_blank"
32+
rel="noopener">Ludovic Rousseau</a>. La figura a seguire mostra le
33+
informazioni estratte alcune delle quali:
34+
35+
- tipo di Smart Card e in questo caso si tratta della MIFARE Classic 1K;
36+
- produttore della Smart Card e in questo caso NXP;
37+
- standard tecnologici;
38+
- protocolli di comunicazione e in questo caso T=0 (orientato al byte,
39+
che costituisce l'unità minima di informazione scambiata) e T=1
40+
(orientato al blocco di byte, grazie al quale la velocità di accesso è
41+
maggiore), protocollo solitamente utilizzato di default quando
42+
disponibile e supportato anche dal lettore.
43+
44+
[<img
45+
src="https://www.dontesta.it/wp-content/uploads/2022/03/mifare_classic_1k_atr_parsing-1024x1487.png"
46+
class="size-large wp-image-5529" width="1024" height="1487"
47+
alt="Figura 11 - Dettagli estratti sull&#39;ATR della Smart Card MIFARE Classic 1K" />](https://www.dontesta.it/wp-content/uploads/2022/03/mifare_classic_1k_atr_parsing.png)
48+
**Figura 11** - Dettagli estratti sull'ATR della Smart Card MIFARE Classic
49+
1K
50+
51+
Ludovic Rousseau ha fatto un ottimo lavoro tracciando dal 2002 un <a
52+
href="http://ludovic.rousseau.free.fr/softwares/pcsc-tools/smartcard_list.txt"
53+
target="_blank" rel="noopener">gran numero di ATR</a> costruendo un vero
54+
e proprio database. Così facendo è possibile identificare una Smart Card
55+
dato il suo ATR. All'interno della lista sono presenti anche le
56+
"nostrane Smart Card" come la **TS-CNS**
57+
(<a href="https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi"
58+
target="_blank" rel="noopener"><em>Tessera Sanitaria - Carta Nazionale
59+
Servizi</em></a>) e **CIE**
60+
(<a href="https://developers.italia.it/it/cie/" target="_blank"
61+
rel="noopener"><em>Carta d'Identità Elettronica</em></a>). È possibile
62+
utilizzare il comando `pcsc_scan` per ottenere informazioni di dettaglio
63+
sulla Smart Card, le stesse illustrate in figura 11. La figura 12 mostra
64+
l'output del comando menzionato da cui è possibile dedurre che la Smart
65+
Card analizzata è una CIE.
66+
67+
[<img
68+
src="https://www.dontesta.it/wp-content/uploads/2022/03/output_of_pcsc_scan_smart_card_cie-1024x656.png"
69+
class="size-large wp-image-5532" width="1024" height="656"
70+
alt="Figura 12 - Esempio di output del comando pcsc_scan che mostra le informazioni estratte dalla Smart Card, in questo caso CIE" />](https://www.dontesta.it/wp-content/uploads/2022/03/output_of_pcsc_scan_smart_card_cie.png)
71+
**Figura 12** - Esempio di output del comando pcsc_scan che mostra le
72+
informazioni estratte dalla Smart Card, in questo caso CIE

‎docs/guida/conclusioni.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
Ringrazio tutti voi per essere arrivati “incolumi” alla fine di questo
2+
lungo percorso sperando di non essere stato noioso e di essere riuscito
3+
nell’intento di rendere interessanti gli argomenti trattati oltre che a
4+
spingere la vostra curiosità in avanti.
5+
6+
Potrei lasciarvi un compito per casa: **come aprire la porta di casa
7+
utilizzando la propria CIE o TS-CNS**.
8+
9+
Mi sarebbe piaciuto approfondire maggiormente alcuni degli argomenti
10+
trattati, come per esempio il framework Pyscard e alcune sezioni del
11+
codice Python sviluppato. Nell’attesa di pubblicare altri articoli di
12+
approfondimento, vi chiedo di scrivere le vostre impressioni, esperienze
13+
o altro di cui vorreste qualche approfondimento utilizzando i commenti
14+
all’articolo oppure condividendo attraverso i classici canali social.
15+
16+
Sempre nell'ottica Open Source, il progetto
17+
<a href="https://github.com/amusarra/smartcard-contactless-raspberry-pi"
18+
target="_blank" rel="noopener">Smart Card Contactless Raspberry Pi</a>
19+
pubblicato sul mio repository GitHub, contiene all'interno della
20+
directory <a
21+
href="https://github.com/amusarra/smartcard-contactless-raspberry-pi/tree/master/docs"
22+
target="_blank" rel="noopener">docs</a> i seguenti elementi:
23+
24+
- il file diagrams.drawio contenente diagrammi e tabelle. File che
25+
potete aprire con <a href="https://app.diagrams.net/" target="_blank"
26+
rel="noopener">Draw.io</a>
27+
- il file SCH_Smart_Card_Contactless_Raspberry_Pi_2022-03-11.json dello
28+
schema elettrico che potete aprire con
29+
<a href="https://easyeda.com/" target="_blank"
30+
rel="noopener">EasyEDA</a>
31+
- i file UML \*.puml di <a href="https://plantuml.com/" target="_blank"
32+
rel="noopener">PlantUML</a> che contengono i sequence diagram

‎docs/guida/deploy_test_software_on_rpi.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
Ci siamo! È arrivato il momento d'installare il progetto software sul
2+
Raspberry Pi e verificare che tutto funzioni così per com'è stato
3+
ideato. Il deployment diagram della figura a seguire mostra tutti i
4+
componenti del nostro sistema di accesso.
5+
6+
[<img
7+
src="https://www.dontesta.it/wp-content/uploads/2022/03/system_deployment_on_raspberry-1024x891.png"
8+
class="size-large wp-image-5562" width="1024" height="891"
9+
alt="Figura 22 - Deployment diagram del sistema di accesso via Smart Card Contactless su Raspberry Pi" />](https://www.dontesta.it/wp-content/uploads/2022/03/system_deployment_on_raspberry.png)
10+
**Figura 22** - Deployment diagram del sistema di accesso via Smart Card
11+
Contactless su Raspberry Pi
12+
13+
Assumiamo a questo punto che tutti i requisiti software indicati in
14+
precedenza siano tutti soddisfatti (fare riferimento a 6. Requisiti
15+
Software). Per installare il progetto software sul Raspberry Pi occorre
16+
seguire i seguenti passi:
17+
18+
1. accedere in ssh alla Raspberry Pi;
19+
2. decidere una locazione dove installare il progetto software. Non ci
20+
sono restrizioni; nel mio caso ho preferito usare la home del mio
21+
account;
22+
3. eseguire il clone del repository del progetto;
23+
4. eseguire l'installazione delle dipendenze Python.
24+
25+
Per ambienti di sviluppo o test è possibile pensare di fare ricorso alla
26+
creazione di quella che viene definita nel mondo Python,
27+
<a href="https://docs.python.org/3/tutorial/venv.html" target="_blank"
28+
rel="noopener">Virtual Environments</a>.
29+
30+
31+
```bash
32+
# Accesso al Raspberry Pi via SSH
33+
ssh [email protected]
34+
35+
# Clone del repository GitHub del progetto
36+
git clone https://github.com/amusarra/smartcard-contactless-raspberry-pi.git
37+
38+
# Installazione delle dipendenze Python
39+
cd smartcard-contactless-raspberry-pi
40+
make
41+
```
42+
**Console 2** - Installazione del progetto software
43+
44+
Il comando `make` non fa altro che procedere con l'installazione delle
45+
dipendenze Python specificate sul file <a
46+
href="https://github.com/amusarra/smartcard-contactless-raspberry-pi/blob/master/requirements.txt"
47+
target="_blank" rel="noopener">requirements.txt</a> utilizzando
48+
<a href="https://pypi.org/project/pip/" target="_blank"
49+
rel="noopener">pip</a>. La figura 23 mostra il processo d'installazione
50+
delle dipendenze Python sul Raspberry Pi. Ultimata l'installazione, è
51+
possibile eseguire il test vero e proprio del software. Prima di
52+
eseguire il test occorre accertarsi che dal punto di vista hardware sia
53+
tutto regolare controllando tutti i collegamenti (vedi schema
54+
elettrico), compreso il collegamento del lettore di Smart Card via USB.
55+
56+
[<img
57+
src="https://www.dontesta.it/wp-content/uploads/2022/03/install_rpi_access_system_via_smart_card_1-1024x626.png"
58+
class="size-large wp-image-5568" width="1024" height="626"
59+
alt="Figura 23 - Installazione delle dipendenze Python tramite il comando make" />](https://www.dontesta.it/wp-content/uploads/2022/03/install_rpi_access_system_via_smart_card_1.png)
60+
**Figura 23** - Installazione delle dipendenze Python tramite il comando
61+
make
62+
63+
Ormai dovremmo sapere quali sono gli entry point da utilizzare, sia
64+
quello per il setup della Smart Card, sia quello che avvia il controllo
65+
degli accessi. Entrambi gli entry point, quindi gli script Python,
66+
devono essere avviati specificando una serie di parametri. Le due
67+
tabelle a seguire mostrano i parametri d'input dei due script:
68+
`setup_smart_card.py` e `access_via_smart_card.py`.
69+
70+
[<img
71+
src="https://www.dontesta.it/wp-content/uploads/2022/03/mind_map_script_setup_smart_card-1024x582.png"
72+
class="size-large wp-image-5572" width="1024" height="582"
73+
alt="Figura 24 - Tabella dei parametri d&#39;input per lo script Python setup_smart_card.py" />](https://www.dontesta.it/wp-content/uploads/2022/03/mind_map_script_setup_smart_card.png)
74+
**Figura 24** - Tabella dei parametri d'input per lo script Python
75+
setup_smart_card.py
76+
77+
[<img
78+
src="https://www.dontesta.it/wp-content/uploads/2022/03/mind_map_script_access_via_smart_card-1024x265.png"
79+
title="Figura 25 - Tabella dei parametri d&#39;input per lo script Python access_via_smart_card.py"
80+
class="wp-image-5573 size-large" width="1024" height="265"
81+
alt="Figura 25 - Tabella dei parametri d&#39;input per lo script Python access_via_smart_card.py" />](https://www.dontesta.it/wp-content/uploads/2022/03/mind_map_script_access_via_smart_card.png)
82+
**Figura 25** - Tabella dei parametri d'input per lo script Python
83+
access_via_smart_card.py
84+
85+
La figura 26 mostra un esempio di come si presenta l'help in linea dello
86+
script `setup_smart_card.py` attivato utilizzando l'opzione `--help` (o
87+
`-h`).
88+
89+
[<img
90+
src="https://www.dontesta.it/wp-content/uploads/2022/03/setup_smart_card.py_help_option-1024x618.png"
91+
class="size-large wp-image-5574" width="1024" height="618"
92+
alt="Figura 26 - Come si presenta l&#39;help in line dello script setup_smart_card.py" />](https://www.dontesta.it/wp-content/uploads/2022/03/setup_smart_card.py_help_option.png)
93+
**Figura 26** - Come si presenta l'help in linea dello script
94+
setup_smart_card.py
95+
96+
A questo punto siamo davvero pronti. Il primo step è la registrazione
97+
della Smart Card per il nuovo ospite Mario Rossi il cui documento
98+
d'identità ha il numero MU589876XD e al quale assegnamo la stanza numero
99+
due.
100+
101+
Prima di avviare la registrazione, prendiamo la Smart Card poggiandola
102+
sul lettore. Il comando da avviare per la registrazione è:
103+
`./setup_smart_card.py -a FFFFFFFFFFFF -i MU589876XD -s --firstname Mario --lastname Rossi -r 2`
104+
105+
Se tutto va per il verso giusto, l'output ottenuto in console dovrebbe
106+
essere quello mostrato dalla figura a seguire.
107+
108+
[<img
109+
src="https://www.dontesta.it/wp-content/uploads/2022/03/setup_smart_card_run_1-1024x511.png"
110+
class="size-large wp-image-5576" width="1024" height="511"
111+
alt="Figura 27 - Registrazione Smart Card MIFARE Classic 1K con i dati dell&#39;ospite " />](https://www.dontesta.it/wp-content/uploads/2022/03/setup_smart_card_run_1.png)
112+
**Figura 27** - Registrazione Smart Card MIFARE Classic 1K con i dati
113+
dell'ospite
114+
115+
Dopo la registrazione della Smart Card e la consegna all'ospite,
116+
quest'ultimo può usare la Smart Card per accedere alla propria stanza
117+
assegnata in fase di registrazione, che ricordo essere la numero due.
118+
119+
[<img
120+
src="https://www.dontesta.it/wp-content/uploads/2022/03/smart_card_registration_data_on_mongodb_1-1024x974.png"
121+
class="size-large wp-image-5577" width="1024" height="974"
122+
alt="Figura 28 - Documento registrato su MongoDB a fronte del processo di registrazione Smart Card" />](https://www.dontesta.it/wp-content/uploads/2022/03/smart_card_registration_data_on_mongodb_1.png)
123+
**Figura 28** - Documento registrato su MongoDB a fronte del processo di
124+
registrazione Smart Card
125+
126+
Avviamo adesso il programma del controllo degli accessi utilizzando il
127+
comando: `./access_via_smart_card.py -a FFFFFFFFFFFF`. Avviato il
128+
programma, questo resta in attesa di leggere la Smart Card. Poggiando la
129+
Smart Card registrata poc'anzi, l'ospite dovrebbe riuscire ad accedere
130+
alla sua stanza, così come mostra la figura a seguire.
131+
132+
[<img
133+
src="https://www.dontesta.it/wp-content/uploads/2022/03/smart_card_access_control_1-1024x570.png"
134+
class="size-large wp-image-5578" width="1024" height="570"
135+
alt="Figura 29 - Richiesta di accesso via Smart Card MIFARE Classic 1K" />](https://www.dontesta.it/wp-content/uploads/2022/03/smart_card_access_control_1.png)
136+
**Figura 29** - Richiesta di accesso via Smart Card MIFARE Classic 1K
137+
138+
L'output mostrato dalla figura 29 evidenzia anche un accesso non
139+
riuscito perché in questo caso la Smart Card presentata non è registrata
140+
sul sistema. Gli screencast a seguire mostrano i due entry point in
141+
azione: setup_smart_card.py e access_via_smart_card.py.
142+
143+
<a href="https://asciinema.org/a/475795" target="_blank"
144+
rel="noopener"><img src="https://asciinema.org/a/475795.svg"
145+
title="Screencast 1 - Processo di registrazione Smart Card in azione"
146+
width="1223" height="784"
147+
alt="Screencast 1 - Processo di registrazione Smart Card in azione" /></a>
148+
**Screencast 1** - Processo di registrazione Smart Card in azione
149+
150+
<a href="https://asciinema.org/a/475797" target="_blank"
151+
rel="noopener"><img src="https://asciinema.org/a/475797.svg"
152+
title="Screencast 2 - Processo di accesso alla stanza via Smart Card in azione"
153+
width="1223" height="784"
154+
alt="Screencast 2 - Processo di accesso alla stanza via Smart Card in azione" /></a>
155+
**Screencast 2** - Processo di accesso alla stanza via Smart Card in azione
156+
157+
Dopo i due screencast che mostrano il sistema di accesso in azione,
158+
possiamo affermare che il nostro lavoro di analisi, progettazione e
159+
implementazione sia arrivato al termine, raggiungendo anche l'obiettivo
160+
prefissato.

0 commit comments

Comments
 (0)