#format wiki
#LANGUAGE it
<<BR>>
<<Include(NuoviStrumentiWiki/PaginaDiProva)>>
<<Indice(depth=2)>>

= Introduzione =

Questa guida descrive l'installazione, la configurazione e l'utilizzo di '''!QtPass''', un'interfaccia grafica (GUI) basata su Qt per `pass`, il gestore di password standard di Unix.<<BR>>Utilizza il sistema di crittografia [[Sicurezza/GnuPg|GnuPG]] (GPG) per proteggere i dati e può sincronizzarsi tramite [[Programmazione/Git|Git]]. La filosofia del software si basa sulla semplicità e sull'uso di file di testo cifrati organizzati in una struttura a cartelle.

= Installazione =

{{{#!wiki note
'''!QtPass''' è incluso nei repository ufficiali di Ubuntu.
}}}

== Da repository ==

[[AmministrazioneSistema/InstallareProgrammi|Installare]] i pacchetti [[apt://qtpass|qtpass]], [[apt://pass|pass]] e [[apt://gnupg2|gnupg2]].

{{{#!wiki tip
Per la sincronizzazione del database delle password in un server o servizio web, installare [[Programmazione/Git|Git]].
}}}

= Prequisiti iniziali =

Prima di procedere per crittografare e decrittografare le password, è necessario:

== Generare chiavi Gpg ==

[[Sicurezza/GnuPg#Generare_una_chiave|Generare]] una coppia di chiavi GPG (pubblica e privata), digitare nel [[AmministrazioneSistema/Terminale|terminale]] il seguente comando:{{{
gpg --full-generate-key
}}} Al termine della procedura, è necessario annotare l'ID della chiave generata (un codice alfanumerico di 8 o 16 caratteri).

{{{#!wiki tip
Si consiglia di selezionare l'algoritmo '''(1) RSA e RSA''' (opzione predefinita) e una lunghezza di almeno 3072 bit.
}}}

{{{#!wiki important
È fondamentale conservare in sicurezza la passphrase della chiave GPG, poiché lo smarrimento comporterebbe l'impossibilità di accedere alle password.
}}}

== Inizializzazione database delle password ==

Inizializzare il database delle password, digitando  nel [[AmministrazioneSistema/Terminale|terminale]] il seguente comando:{{{
pass init "id_della_chiave_gpg"
}}} Sostituire `"id_della_chiave_gpg"` con l'identificativo creato nel [[#Generare_chiavi_Gpg|passaggio precedente]].

{{{#!wiki important
'''!QtPass''' ignora i file che non seguono la convenzione dell'estensione `.gpg` nella cartella.
}}}

= Avvio =

[[AmbienteGrafico/AvviareProgrammi|Avviare]] '''!QtPass'''.

Al primo avvio, l'applicazione cercherà automaticamente i percorsi degli eseguibili e della cartella delle password situata in `~/.password-store`.<<BR>>Se ciò non accade, è possibile specificare il percorso manuale nelle [[#Configurazione|impostazioni]] '''Programmi''' del programma.

== Avvio Solo Tray ==

All'interno di '''!QtPass''', è necessario abilitare la gestione della tray icon affinché l'applicazione rimanga attiva in background:

 0. Accedere alla scheda menu '''Impostazioni'''.
 0. Individuare e selezionare le seguenti opzioni:
  * '''Usa l'icona sulla barra delle applicazioni''' (Tray icon): abilita la visualizzazione dell'icona accanto all'orologio di sistema.
  * '''Avvia minimizzato''': avvia l'app direttamente come icona.
  * '''Nascondi alla chiusura''' e '''Sempre visibile''': permette all'applicazione di continuare l'esecuzione nel vassoio di sistema invece di chiudersi completamente quando viene premuta la "X" della finestra.

=== Universale (XDG Autostart) ===

{{{#!wiki note
Questo metodo funziona su tutte le distribuzioni derivate poiché sfruttano lo standard XDG.
}}}

Consultare la [[AmministrazioneSistema/AvvioAutomatico|seguente pagina]]

 0. Compilare i campi:
  * '''Nome''': ''`QtPass`''
  * '''Comando''': ''`qtpass --minimized`''
  * '''Ritardo all'avvio''': ''`5 secondi`'' (opzionale, utile per garantire che l'area di notifica sia già caricata).
 0. Cliccare su '''Aggiungi'''.

= Configurazione =

Accedendo alla sezione "Configurazione", è possibile personalizzare il comportamento del software:

 * '''Impostazioni''': nascondere i caratteri durante la digitazione, la lunghezza delle password durante la generazione automatica, attivare/disattivare la generazione automatica delle password.
 * '''Programmi''': impostare il programma e i percorsi di `gpg`, `pass` e `git`.
 {{{#!wiki tip
 Si consiglia di verificare che i percorsi verso gli eseguibili gpg e pass siano corretti (solitamente `/usr/bin/gpg` e `/usr/bin/pass`).
 }}}
 * '''Profili''': Impostare il profilo utente.
 * '''Modelli''': modelli preimpostati.

= Utilizzo =

== Creazione di una nuova password ==

 0. Cliccare sul pulsante "Aggiungi password".
 0. Inserire il nome del servizio a cui associare la password (es. `Email/Gmail` o `Social/GitHub`).
 0. Digitare la password o cliccare sul pulsante "Genera" per generare una password sicura tramite il generatore integrato.
 0. Cliccare su "OK". Salvare la voce. Il file verrà creato come `~/.password-store/Email/Gmail.gpg`.

== Recupero di una password ==

Dall'elenco principale, selezionando una voce, sono disponibili diverse opzioni:

 * '''Copia Password''': copia la password negli appunti per un tempo limitato.
 * '''Mostra/Nascondi''': visualizza la password all'interno dell'interfaccia.
 * '''Copia Utente''': copia il nome utente associato.

Il backup dei dati consiste in due elementi fondamentali:

 0. La cartella nascosta `~/.password-store`.
 0. La chiave privata GPG, esportabile con:{{{
 gpg --export-secret-keys --armor > private.key
 }}}

{{{#!wiki important
Il possesso della cartella senza la chiave GPG (o viceversa) non permette il recupero delle password.
}}}

== Sincronizzazione Git ==

Se '''!QtPass''' deve essere condiviso tra più dispositivi:

 0. Inizializzare un [[Programmazione/Git|repository git]] nella cartella del password store.
 0. Nelle impostazioni di '''!QtPass''', abilitare l'opzione '''Usa git'''.
 0. Configurare i comandi di '''push''' e '''pull''' automatici per mantenere i dati aggiornati su un server remoto (es. un server privato o piattaforme come [[Programmazione/Git|GitLab/GitHub]]).

{{{#!wiki important
Questa sincronizzazione è una delle funzioni più avanzate di '''!QtPass''', ma può presentare criticità legate all'autenticazione, alla configurazione dei repository remoti o a conflitti tra versioni dei file.
}}}

{{{#!wiki note
Consultare [[#Fallimento_dell.27autenticazione_.28SSH.2FHTTPS.29|questo paragrafo]] per risolvere i problemi più frequenti e le relative procedure.
}}}

== Integrazione con il Browser ==

Sebbene '''!QtPass''' sia un'applicazione standalone, è possibile integrare il database delle password con i [[InternetRete/Navigazione#Browser_per_navigare|browser]] (Firefox, Chrome/Chromium) utilizzando estensioni come `passff` o `browserpass`. Queste estensioni comunicano con il backend pass e permettono l'inserimento automatico delle credenziali nei moduli di login.

= Risoluzione problemi =

== la Tray Icon non è visualizzata ==

Nei sistemi [[AmbienteGrafico/Gnome|GNOME]] l'icona nell'area di notifica non è visualizzata, è necessaria l'[[AmbienteGrafico/Gnome/Estensioni|estensione]] `gnome-shell-extension-appindicator`.

== "GPG Decryption failed: No secret key" ==

Un errore comune durante l'utilizzo di '''!QtPass''' è il fallimento della decrittazione dei dati perché la chiave GPG utilizzata per inizializzare il password store non è presente nel portachiavi locale o è stata eliminata.

 0. [[Sicurezza/GnuPg#Visualizzare_la_lista_delle_chiavi_GnuPG|Verificare le chiavi segrete]] presenti nel sistema.
 0. Assicurarsi che l'ID della chiave corrisponda a quello impostato in '''!QtPass'''.
 {{{#!wiki note
 L'identificativo da utilizzare nei file di configurazione si trova sempre nella riga che inizia con `sec`, immediatamente dopo il carattere `/`.
  * Se l'ID visualizzato è di 8 caratteri: formato Short.
  * Se l'ID visualizzato è di 16 caratteri: formato Long (scelta raccomandata per evitare collisioni).
 }}}
 0. Se la chiave è corretta ma l'errore persiste, tentare una decrittazione manuale via terminale per isolare il problema:{{{
pass NomeServizio/NomePassword
}}} Se richiede la password e la mostra correttamente, il problema risiede nella configurazione del percorso GPG all'interno di '''!QtPass'''.

== Inappropriate ioctl for device ==

Questo errore si verifica quando [[Sicurezza/GnuPg|GPG]] tenta di chiedere la passphrase della chiave privata, ma non riesce a far apparire la finestra di inserimento (pinentry).<<BR>><<BR>>Il sistema sta tentando di utilizzare un'interfaccia di inserimento testuale in un ambiente grafico, oppure il componente pinentry non è configurato correttamente.

 0. [[AmministrazioneSistema/InstallareProgrammi|Installare]] una versione grafica di `pinentry` compatibile con l'ambiente desktop:
  * [[AmbienteGrafico/Kde|KDE]] / [[AmbienteGrafico/Lxqt|LXQt]]:{{{
  sudo apt install pinentry-qt
  }}}
  * [[AmbienteGrafico/Gnome|GNOME]]:{{{
  sudo apt install pinentry-gnome3
  }}}
 0. Configurare GPG per utilizzare il programma corretto modificando il file di configurazione dell'agente, digitare nel [[AmministrazioneSistema/Terminale|terminale]] il seguente comando:{{{
 nano ~/.gnupg/gpg-agent.conf
 }}} Aggiungere o modificare la riga (esempio per GNOME):{{{
 pinentry-program /usr/bin/pinentry-gnome3
 }}}
 0. Riavviare l'agente GPG:{{{
 gpgconf --kill gpg-agent
 }}}

== GPG: decryption failed: secret key not available ==

Se i file delle password sono stati copiati da un altro computer o da un backup.<<BR>>Sono stati trasferiti i file crittografati (.gpg) ma non è stata importata la chiave privata GPG associata.

 0. Esportare la chiave dal computer di origine:{{{
 gpg --export-secret-keys ID_CHIAVE > chiave_privata.asc
 }}}
 0. Importare la chiave nel nuovo sistema:{{{
 gpg --import chiave_privata.asc
 }}}
 0. Impostare la fiducia della chiave (Trust) affinché sia utilizzabile:{{{
 gpg --edit-key ID_CHIAVE
 }}} Digitare "trust", selezionare "5" (assoluta), confermare con "quit".

== gpg: decryption failed: Bad passphrase ==

L'errore appare quando la password della chiave GPG inserita è errata. Errore di digitazione o mancata corrispondenza tra tastiera impostata e caratteri digitati.

 0. Controllare il [[Hardware/Periferiche/Tastiere|layout della tastiera]] (es. IT vs US).
 0. Provare a digitare la password in un editor di testo in chiaro per verificarne la correttezza, quindi incollarla nel prompt di GPG.

== Schermata vuota o errore di percorso eseguibile ==

'''!QtPass''' non mostra alcun errore specifico ma non decritta nulla. I percorsi degli eseguibili `gpg` o `pass` nelle impostazioni di '''!QtPass''' sono errati.

 0. Aprire le [[#Configurazione|Impostazioni]] di '''!QtPass'''.
 0. Assicurarsi che il campo '''GPG Executable''' contenga `/usr/bin/gpg` e il campo '''pass Executable''' contenga `/usr/bin/pass`.
 0. Cliccare sul pulsante '''Autodetect''' per forzare il software a cercare i percorsi corretti nel sistema.

== Fallimento dell'autenticazione (SSH/HTTPS) ==

Questo è il problema più comune quando si tenta di eseguire operazioni di Push o Pull. L'operazione '''Git''' fallisce con messaggi del tipo `Permission denied (publickey)` o `Authentication failed`.
'''!QtPass''' non ha accesso alle credenziali necessarie per comunicare con il server remoto (!GitHub, !GitLab, server privato).

 0. '''Utilizzo di SSH''': È la modalità consigliata. Verificare che la chiave pubblica SSH sia stata aggiunta al profilo del server remoto.
 0. '''Configurazione dell'agente SSH''': Assicurarsi che la chiave privata sia caricata nell'agente all'avvio della sessione, digitando nel [[AmministrazioneSistema/Terminale|terminale]] il seguente comando:{{{
 ssh-add ~/.ssh/id_rsa
 }}}
 0. '''Evitare HTTPS''': L'uso di HTTPS spesso richiede l'inserimento manuale di nome utente e password (o Personal Access Token), operazione che può fallire se l'interfaccia grafica di '''!QtPass''' non riesce a mostrare il prompt di inserimento. È preferibile convertire il repository all'uso di SSH:{{{
 cd ~/.password-store
 git remote set-url origin git@github.com:utente/repo.git
 }}}

== Repository remoto non configurato ==

'''!QtPass''' potrebbe non eseguire alcuna operazione di sincronizzazione se il repository locale non è collegato a uno remoto. I pulsanti Git sono disabilitati o non producono alcun effetto. Il password store è stato inizializzato localmente ma non è stato aggiunto un "remote".

 0. Accedere alla cartella del database, digitando nel [[AmministrazioneSistema/Terminale|terminale]] il seguente comando:{{{
 cd ~/.password-store
 }}}
 0. Aggiungere il server remoto manualmente:{{{
 git remote add origin indirizzo_del_server_git
 }}}
 0. Effettuare il primo push per stabilire il tracciamento del ramo (branch):
 git push -u origin master
 }}}

== Percorso dell'eseguibile Git non rilevato ==

Se '''!QtPass''' non trova l'eseguibile di Git, le funzioni di sincronizzazione risulteranno inattive. Errore nelle impostazioni o impossibilità di selezionare opzioni Git.

 0. Aprire le [[#Configurazzione|Impostazioni]] di '''!QtPass'''.
 0. Nella sezione relativa ai programmi, verificare che il campo '''Git Executable''' punti a `/usr/bin/git`.
 0. Utilizzare il pulsante '''Autodetect''' per correggere eventuali percorsi errati.

== Conflitti di unione (Merge Conflicts) ==

Si verificano quando la stessa password viene modificata contemporaneamente su due dispositivi diversi. Messaggio di errore durante il Pull: Automatic merge failed; fix conflicts and then commit the result.

Git non è in grado di decidere quale versione del file crittografato mantenere.

Poiché i file sono crittografati, non è possibile risolvere i conflitti riga per riga come in un normale file di testo.
 0. Aprire il [[AmministrazioneSistema/Terminale|terminale]] nella cartella del database, digitando il seguente comando:{{{
 cd ~/.password-store
 }}}
 0. Decidere quale versione mantenere (quella locale o quella remota):
 * Per mantenere la versione locale:{{{
 git checkout --ours percorso/del/file.gpg
 }}}
 * Per mantenere la versione del server:{{{
 git checkout --theirs percorso/del/file.gpg
 }}} Concludere l'operazione:{{{
 git add .
 git commit -m "Risoluzione conflitto manuale"
 }}}

== Mancata sincronizzazione automatica ==

In alcuni casi, '''!QtPass''' non esegue il push automatico dopo l'aggiunta di una password. Le password salvate rimangono solo sul computer locale.

 0. Accedere alle [[#Configurazione|Impostazioni]] di '''!QtPass'''.
 0. Verificare che l'opzione Auto-push and auto-pull (o voci simili a seconda della versione) sia attivata.
 0. Assicurarsi che il repository sia configurato correttamente per evitare richieste di password GPG o SSH durante il processo automatico, poiché queste bloccano l'esecuzione in background.

== GPG signature ==

Alcune configurazioni di Git richiedono che ogni commit sia firmato digitalmente. L'operazione Git fallisce perché '''!QtPass''' non riesce a firmare il commit.

Consultare [[Programmazione/Git/Commit#GPG_signature|questa pagina]].

##Assicurarsi che le chiavi SSH siano correttamente configurate nel sistema se si utilizza un server remoto come !GitHub o !GitLab.

##= Ulteriori risorse =

----
CategoryHomepage CategoryNuoviDocumenti