Merge pull request #1 from Untori/bluetooth

Bluetooth

.drone.yml

@@ -27,6 +27,11 @@ steps:
     event:
     - tag
 
+trigger:
+  branch:
+  - master
+  - develop
+
 volumes:
 - name: config
   host:

documentazione.md

@@ -1,4 +1,4 @@
-# Protocollo TCN
+# Protocollo TCN {#sec:tcn-protocol}
 
 
 
@@ -27,15 +27,89 @@
 
 # Applicazione
 
+L'applicazione permette di tracciare i contatti degli utenti attraverso l'impiego del Bluetooth Low Energy (BLE).
+In particolare lo smartphone di ogni utente si comporta sia da trasmittente di beacon bluetooth che da ricevente.
+In questo modo quando due utenti entrano nel raggio di azione del bluetooth il contatto verrà memorizzato sui rispettivi dispositivi.
 
+L'applicazione prevede differenti modalità di funzionamento, ognuna delle quali garantisce un diverso livello di privacy.
+Nella modalità di funzionamento ***A*** ogni qual volta si verifica un contatto l'applicazione si occupa di notificare immediatamente l'evento al server in modo tale che esso possa essere aggiunto al database remoto.
+Questa modalità è quella meno *privacy friendly* in quanto la comunicazione avviene in *real-time* e all'interno del messaggio scambiato viene riportato sia l'UUID dell'utente sia quello della persona incontrata.
+
+La modalità ***B*** prevede lo scambio delle stesse informazioni previste per la modalità precedente, ma solo se richiesto dalle autorità sanitarie.
+In questo modo non solo si evita che i dati siano catturati dal server in *real-time*, ma si espongono le informazioni dell'utente solo quando queste sono strettamente necessarie.
+Sia in questa modalità, che nella precedente si è scelto di non ruotare gli UUID identificativi degli utenti in modo da facilitare la generazione del grafo sul server.
+Questa soluzione può mettere a repentaglio la privacy degli utenti ed essere sfruttata da *avversari* per ottenere informazioni sulle abitudini degli utilizzatori[^catena-negozi].
+
+[^catena-negozi]: Per esempio una catena di negozi attraverso l'impiego di uno scanner bluetooth potrebbe ricostruire la *fedeltà* degli utenti, conoscere i settori del negozio preferiti ecc.
+
+L'ultima modalità, la ***C***, è quella che tutela maggiormente la privacy degli utilizzatori attraverso due accorgimenti:
+
+- Rotazione degli UUID
+- Matching locale
+
+La generazione degli UUID avviene attraverso una derivazione deterministica come visto nella @sec:tcn-protocol, in modo tale da avere lo stesso livello di privacy di una soluzione randomica, ma con una migliore scalabilità.
+Mentre il matching locale permette di condividere il minor numero di informazioni possibili e solo quando questo è strettamente necessario.
+Infatti in questa modalità l'applicazione carica le informazioni sul server solo in seguito alla richiesta delle autorità sanitarie.
+Inoltre a differenza delle prime due modalità è previsto l'upload unicamente degli UUID che il dispositivo ha assunto nel tempo, in questo modo il server non è in grado di conoscere o ricavare i contatti avuti dall'utente.
 
 ## Bluetooth
 
+L'interazione tra l'hardware bluetooth del dispositivo e l'applicazione è stata gestita attraverso l'impiego della libreria *Android Beacon Library* @AndroidBeaconLibrary che permette di gestire più facilmente le operazioni con beacon bluetooth.
+Inoltre per rendere l'applicazione più funzionale, e quindi garantirne il funzionamento anche in background o a schermo spento è stato utilizzato un *foreground service* @ServicesOverview, che consente di mantenere in *primo piano* le operazioni di trasmissione e scansione anche quando l'applicazione non lo è.
+Data la natura variegata di Android, le diverse implementazioni del sistema operativo adoperate dai vari produttori non si comportano sempre nello stesso modo, motivo per il quale alcuni dispositivi tenderanno a terminare, o mettere in pausa ugualmente l'applicazione[^dont-kill-my-app].
+Potendo opera unicamente nello spazio utente non è stato possibile superare questi limiti.
 
+[^dont-kill-my-app]: Molti produttori Android per aumentare la durata della batteria dei propri dispositivi tendono a stoppare e ridurre le funzionalità delle applicazioni. Maggiori dettagli possono essere trovati al seguente link \url{https://dontkillmyapp.com}.
 
 ### Trasmissione
 
+Il dispositivo dell'utente deve eseguire il broadcast di un beacon bluetooth contenete l'UUID identificativo.
+Questa operazione è stata svolta attraverso la classe `BeaconTransmitter` messa a disposizione dalla *Android Beacon Library*.
+Inoltre per la modalità di funzionamento *C* è stato necessario prevedere un meccanismo di rotazione delle chiavi.
+Questa rotazione viene settata attraverso la funzione `rotateTCN()` che sfrutta un `Handler` per programmare la rotazione dell'UUID.
 
+``` {.kotlin #lst:rotate-tcn caption="Codice necessario alla torazione del tcn."}
+private fun rotateTCN() {
+  val advertiseHandler = Handler()
+  val changeTCN: Runnable = object : Runnable {
+    override fun run() {
+      tcnManager.nextTcn()
+      startAdvertising()
+      advertiseHandler.postDelayed(
+        this,
+        TCNManager.ELAPSE_BETWEEN_NEW_TCN
+      )
+    }
+  }
+
+  advertiseHandler.postDelayed(
+    changeTCN,
+    TCNManager.ELAPSE_BETWEEN_NEW_TCN
+  )
+}
+```
+
+La scelta della frequenza di *advertising* è stata dettata dai vincoli tracciati dall'API di Android @AdvertiseSettings.
+Infatti la libreria permette di trasmettere un beacon con una frequenza di 1 *Hz*, 3 *Hz* o 10 *Hz*.
+Fortunatamente questi vincoli non si sono rilevati troppo limitanti infatti la frequenza di un Hertz, quindi un beacon trasmetto ogni secondo, permette di avere una buona trasmissione e di risparmiare batteria.
+Inoltre in fase di scanning evita che siano registrate più interazioni nello stesso ciclo.
+
+Sempre attraverso l'API di Android è stata settata la potenza di trasmissione del beacon.
+Anche in questo caso la scelta era limitata a poche alternative:
+
+- HIGH
+- MEDIUM
+- LOW
+- ULTRA_LOW
+
+Com'è possibile dedurre anche dai nomi dei vari livelli, l'API non fornisce nessuna stima quantitativa[^dispositivi-non-omogenei], ma solo delle indicazioni qualitative delle intensità del segnale trasmesso.
+L'individuazione del livello più adatto è stata svolta per via sperimentale utilizzando cinque dispositivi differenti.
+I due livelli più alti sono stati immediatamente scartati in quanto permettevano di rilevare i beacon a distanze elevate cosa che avrebbe minato la bontà dell'applicazione.
+Con il livello ULTRA_LOW si è notato che venivano rilevate unicamente le interazioni inferiori al metro in contesti *free space*.
+Poiché l'organizzazione mondiale della sanità raccomanda una distanza di almeno un metro @AdvicePublicCOVID19 questo livello di trasmissione non consente di rilevare contatti potenzialmente a rischio.
+Per questo motivo si è scelto di utilizzare il livello LOW che permette di rilevare contatti fino a circa due metri.
+
+[^dispositivi-non-omogenei]: D'altronde, data la natura non omogenea dei vari dispositivi Android, una stima quantitativa sarebbe stata impossibile da ottenere.
 
 ### Scansione
 

makefile

@@ -1,5 +1,8 @@
 out/documentation.pdf: header.yaml documentazione.md out
-	pandoc header.yaml documentazione.md -F pandoc-crossref -o out/documentazione.pdf
+	pandoc header.yaml documentazione.md	\
+		-F pandoc-crossref									\
+		-F pandoc-citeproc									\
+		-o out/documentazione.pdf
 
 out:
 	mkdir out