Outils d'utilisateurs
Hello,
Je me suis décidé à configurer ma Yubikey 4 qui prenait la poussière depuis quelques temps. Bon, je suis pas sur que le temps passé dessus en valait la chandelle mais c'est fait, du coup je vous fais un tuto pour utiliser une Yubikey 4 en tant que smartcard OpenPGP.
Introduction
La grande majorité du tutoriel devrait être transposable à n'importe quelle carte OpenPGP. Cela vous permettra de:
- Chiffrer/déchiffrer/signer des fichiers
- S'authentifier en SSH (à un serveur ou un service comme Github qui accepte l'authent SSH)
- Signer des commits avec Git (ou autre)
- Chiffrer des mails (puis vous rendre compte que vous connaissez personne qui fournit une clé publique :D)
- Tout autre chose qui utilise GPG
Malheureusement tout ça n'est tellement pas plug & play que ça en retire une partie des avantages et des possibilités. Il serait bien sympa de pouvoir utiliser la clé de façon plug & play pour se connecter depuis ses différents PC (voir depuis des PC non trustés vu que les clés ne sortent pas de la Yubikey) mais actuellement cela demande de la configuration sur chaque nouveau PC rencontré.
J'ai confé mon PC pour l'utiliser depuis trois environnements:
- L’hôte Win7 pour se connecter avec Putty et utiliser Kleopatra
- Git Bash/Cygwin sur l'hôte pour signer mes commits et pusher sur Github en SSH
- Une VM Debian 9
Il existe des bons tutos sur différentes parties du sujet, mais aucun qui ai marché d'un bout à l'autre pour moi. Donc voici un tutoriel qui j'espère ne sera pas un de plus sur le sujet du type “ça marche chez moi et c'est tout”. J'essaierai de vous donner des pistes pour debugger d'éventuels problèmes et pour vous adapter à d'autres environnements.
1 - Choix du stockage des clefs
Il est possible de générer les clés privés directement sur la Yubikey. L’intérêt est que les clés n'auront jamais été ailleurs que dans la yubikey, mais il vous reste plus qu'à prier pour que la clé ne meurt jamais. L'export des clés privées étant impossible.
L'autre solution est de créer ses clés sur un PC est de les transférer sur la Yubikey. Pour cela deux possibilités:
- La suffisante: depuis sa distro habituelle (ou même Windows) créez votre keyring sur une clé USB chiffrée. Il suffit de faire pointer GPG sur sa clé: export GNUPGHOME=/path/to/usb
- La parano: mettez une distro Tails sur une clé USB. Bootez dessus depuis un PC offline (les parano++ utiliseront un PC dédié aux opérations cryptographiques). Créez un stockage persistant chiffré et y gérer son keyring.
Pour la solution Tails:
- Installez Tails : https://tails.boum.org/install/index.fr.html
- Activez le stockage persistent chiffré : https://tails.boum.org/doc/first_steps/persistence/index.fr.html
Ensuite vous transférerez la ou les clés privées sur votre yubikey et vous exporterez les clés publiques pour les diffuser.
Dans les deux cas vous avez votre keyring bien à l'abri sur un support chiffré que vous garderez précieusement. Il vous servira de backup pour votre Yubikey. En cas de perte/casse il suffit de recharger une nouvelle Yubikey avec le keyring présent sur la clé USB. Il est fortement recommandé de faire un backup de la clé USB en question en la dupliquant sur une autre. Car si la clé USB meurt vous retombez en case prières.
2 - Génération des clés
Pour la création des clés il est recommandé de créer cette structure: - Une clé primaire qui sert uniquement à signer ses autres clés et qui restera dans le keyring - Une sous clé pour chaque type d'opération (signature, chiffrement, authentification) qui seront transférées sur la Yubikey
Cela permet de révoquer une seule sous clé. Par exemple renouveler la clé d'authentification régulièrement sans perdre ses fichiers chiffrés.
Pour tout le tutoriel gpg >= 2.0 est nécéssaire.
Suivez les trois tutoriels suivants:
- Génération des clés. La dernière étape (supprimer la clé privé master du keyring) n'est pas nécessaire : https://blog.eleven-labs.com/en/openpgp-almost-perfect-key-pair-part-1/
- Configurez la Yubikey et transférez les trois sous clés privées dessus: https://github.com/drduh/YubiKey-Guide#configure-smartcard
- Optionnel, activez le bouton sur la clé. Il faudra toucher le bouton tactile sur la clé pour toute opération cryptographique (intéressant car par défaut le code pin est mis en cache) : https://github.com/drduh/YubiKey-Guide#require-touch
3 - Export des clés publiques
L'étape suivante est d'exporter les clés publiques pour les fournir aux différents services qui devront les accepter. Si vous avez suivi le tuto sur la génération des clés c'est déjà fait. Si vous utilisez une clé USB chiffrées, copier les exports sur le PC. Si vous utilisez Tails sortez les via une autre clé USB.
Pour rappel, export des clés publiques:
gpg --export --armor <keyid> > <keyid>.pub.asc
Astuce: pour la plupart des commandes gpg vous pouvez utiliser tout ou partie du nom ou de l'adresse mail associée à votre clé master.
gpg --export --armor harfang > harfang.pub.asc
Le fichier .asc contiendra toutes les clés publiques (master + 3 sous clés) ainsi que les signature des 3 sous clés par la master. Pour tout le reste de la manip' il suffira toujours soit de donner ce fichier .asc, soit de donner l'ID de la clé master. Il n'est pas nécessaire de donner l'ID des sous clés, la bonne sous clé est utilisée en fonction de l'opération effectuée.
Je vous conseille aussi de sortir les infos suivantes qui seront nécéssaires plus tard. Les clés publiques au format SSH:
gpg --export-ssh-key <keyid> > <keyid>.pub.ssh
Le keygrip de la clé master, qui est un autre format d'ID dont on aura besoin:
gpg -k --with-keygrip
Prenez l'ID qui se trouve après “keygrip = ” sous l'ID classique de la clé master. Notez le quelque part.
4 - Configuration des services (Github et ssh)
On va commencer par configurer les services qui devront accepter nos clés.
SSH
Il suffit d'ajouter notre clé publique au format SSH à son compte sur le serveur distant. Copiez le contenu du fichier <keyid>.pub.ssh sur le serveur distant, ajoutez la clé dans le fichier “~/.ssh/authorized_keys”
Si vous avez pas de serveur SSH sous la main vous pouvez testez en vous connectant à git@github.com une fois que vous avez ajouté votre clé publique à votre compte Github.
Github
Renseignez à la fois votre clés publiques format GPG (<keyid>.pub.asc) et format SSH sur votre compte.
- https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account key-to-your-github-account
5 - Chiffrer, signer et se connecter en ssh
On va maintenant configurer ce qui faut pour pouvoir utiliser la Yubikey sur son PC. La grande majorité des infos sont communes à Linux et Windows donc je préciserai juste quand une info n'est pertinente que pour un seul OS.
Installation
Sous Linux, suivant la distribution les paquets installés par défaut peuvent être suffisants. Sur Debian les paquets suivants sont nécessaires : gnupg, pcscd et scdaemon. Plus d'infos sur l'utilisation des SmartCards OpenPGP sur Debian : https://wiki.debian.org/Smartcards/OpenPGP
Sous Windows installez https://www.gpg4win.org/ Gpg4Win qui fournit une version Windows de la suite GPG. Ajoutez le dossier où se trouve les binaire au PATH. Par défaut il installe aussi Kleopatra qui est un client graphique sympa pour gérer votre keyring et chiffrer/signer/verifier des fichiers.
Par la suite toutes les commandes GPG pourront aussi bien être exécutées depuis un shell sous Linux qu'un CMD sous Windows.
Configuration
Importez vos clés publiques dans votre keyring:
gpg --import <keyid>.pub.asc
Sous Windows vous pouvez aussi l'importer via Kleopatra.
On va configurer quelques fichiers de configuration de GPG. Ces fichiers se trouvent tous dans:
- Linux-: ~/.gnupg/
- Windows : \%APPDATA%/gnupg
- A chaque fois si le fichier n'existe pas créez le. Certaines options peuvent déjà être configurées.
- Linux: Ajoutez l'option “enable-ssh-support” au fichier “gpg-agent.conf” . Cela permettra à gpg d'agir comme agent de clés SSH (remplaçant ssh-agent)
- Linux: Si vous n'avez pas d'interface graphique, ajoutez “pinentry-program /usr/bin/pinentry-curses” au fichier “gpg-agent.conf”. Cela remplacera le prompt Qt par défaut par un prompt console. Il existe aussi “pinentry-tty” (pas installé par défaut) comme prompt console.
- Windows: Ajoutez l'option “enable-putty-support” au fichier “gpg-agent.conf” . Cela permettra à gpg d'agir comme agent de clés SSH pour Putty.
Linux & Windows: Ajoutez l'option “reader-port Yubico Yubikey” au fichier scdaemon.conf” . Cela aide le démon scdaemon à trouver la Yubikey.
Linux & Windows : Ajouter le keygrip de la clé publique que vous aviez noté précédemment dans le fichier “sshcontrol” (le fichier doit être composé d'un keygrip par ligne)
Relancez l'agent GPG:
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
Testez si la Yubikey est bien reconnue:
gpg --card-status
Vous pouvez normalement effectuer des opérations cryptographiques. Essayez de signer un fichier:
gpg --clearsign file.txt
Si tout se passe bien un prompt devrait apparaitre vous demandant le code pin de la Yubikey. Après avoir validé le code pin si vous avez activé le bouton tactile il faudra le toucher (la Yubikey clignote pour vous prévenir, vous avez 15 secondes). Le code pin est mis en cache et si vous répétez l'opération il ne vous sera pas demandé. Cela nous pose un problème car on va vouloir tester que SSH nous prompt bien pour le code pin quand c'est nécéssaire.
Videz le cache du code pin en relançant l'agent gpg.
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
Vous pouvez ensuite essayer de vous connecter en SSH au serveur distant sur le compte que vous avez précédemment configuré pour accepter votre clé publique. Vous pouvez aussi essayer de vous connecter en SSH à git@github.com si vous avez configurer votre compte Github. SSH devrait d'abord tenter l'authentification par clé et ouvrir un dialog vous demandant le code pin.
Pour finir, il sera nécessaire de lancer l'agent gpg à l'ouverture de la sessions. C'est le cas par défaut sur ma Debian, pour Windows j'ai ajouté un .bat exécuté à l'ouverture de session qui contient:
gpgconf --launch gpg-agent
Debug
Sous Windows je n'ai pas eu de soucis particulier pour faire fonctionner ma Yubikey avec Putty. En revanche j'ai passé beaucoup de temps sous Linux pour avoir un résultat un peu mieux que de tomber en marche de temps en temps. La suite de cette partie sera donc concentrée sur Linux.
Si SSH vous demande directement le mot de passe du compte c'est qu'il n'a même pas tenté l'authentification par clé. Vérifiez que l'agent SSH a bien pris en compte votre clé (celle que vous avez ajouté à “~/.gnupg/sshcontrol”) :
ssh-add -l
Votre clé publique devrait être retournée, sinon vérifiez le fichier “~/.gnupg/sshcontrol”, relancez l'agent gpg, retestez.
Si il y a une erreur type “erreur de connexion” lors du “ssh-add -l” c'est que l'agent gpg n'a pas été bien configuré en tant qu'agent SSH. Vérifiez la valeur de $SSH_AUTH_SOCK qui devrait pointer sur la socket ssh de gpg-agent au lieu de l'agent ssh par défaut (ssh-agent):
harfang@debian:~$ echo $SSH_AUTH_SOCK
/run/user/1000/gnupg/S.gpg-agent.ssh
Si SSH vous donne une erreur du type “sign_and_send_pubkey: signing failed: agent refused operation” puis vous demande un mot de passe c'est qu'il a tenté d'utiliser votre clé mais qu'une erreur s'est produite. Quand on utilise SSH l'agent gpg ne sait pas localiser votre TTY courant pour ouvrir le prompt du code pin. La commande suivante devrait régler ce problème: gpg-connect-agent updatestartuptty /bye
Sinon vous pouvez aussi essayer de setter la variable $GPG_TTY:
GPG_TTY=$(tty)
export GPG_TTY
Si rien n'y fait, regardez si vous voyez des erreurs parlantes avec journalctl. Relancez gpg-agent, voir killez tous les process associés (gpg-agent, scdaemon, gpg-connect-agent, ssh-agent) entre vos essaies afin de vider les caches. Je me suis fait avoir par exemple quand pendant un moment la connexion SSH marchait alors que c'était en fait uniquement du au fait que le code pin avait été mis en cache par une commande gpg.
6 - Github
Installation
Cette partie là concerne uniquement Windows. Pour Linux passez directement à la partie suivante.
J'utilise Git en console je n'ai donc pas testé avec les clients Git graphiques.
Installez l'un des deux:
- https://git-scm.com/download/win Git pour Windows: il installe Git Bash, un shell (presque) prêt à l'emploi. C'est celui dont je me sert. Supprimez tous les binaires gpg* installés par défaut car nous voulons continuer d'utiliser ceux fournit par Gpg4Win. Il se trouve par défaut dans “C:\Program Files\Git\usr\bin”.
- https://cygwin.com/install.html Cygwin : installez les paquets git etssh-pagent. N'installez PAS le paquet gnupg.
Il reste à lancer ssh-pagent, qui fera le lien avec l'agent gpg. Ouvrez un shell (que ce soit Git Bash ou Cygwin):
eval $(/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME")
Cette commande lance ssh-pagent si il n'est pas déjà en cours d’exécution et configure la variable d'environnement SSH_AUTH_SOCK qui pointera sur la socket de ssh-pagent. Cette variable d’environnement est indispensable, il est donc nécessaire d'ajouter la commande précédente à son .bashrc. Celui ci se trouve dans:
- %HOMEPATH%\ pour Git Bash
- C:\cygwin64\home\username pour Cygwin
Vous pouvez essayer de vous connecter en ssh à votre serveur ou à git@github.com pour tester si votre Yubikey est bien utilisée.
Cette solution a de grosses limitations. Elle marchera pour signer et pusher des commits mais pas plus. En effet une partie des commandes gpg fournis par Gpg4Win ne marche pas dans des shell Bash like. J'ai eu beau mixer les binaires de toutes les façons possibles entre ceux fournis par défaut et ceux fournis par Gpg4Win, je n'ai pas réussi à avoir une solution complète. Néanmoins comme ce que qui m’intéresse majoritairement est justement de pouvoir signer et pusher je m'en contenterai.
Configuration et utilisation
Allez dans un projet Git. Si c'est pas déjà le cas, mettez l'adresse du remote en SSH au lieu de HTTPS:
git remote set-url origin git@github.com:USERNAME/REPOSITORY.git
A partir de là vu, et si vous aviez bien attaché votre clé SSH à votre compte Github, vous vous connecterez via SSH et donc via votre clé.
Pour signer les commits, il faut préciser la clé à utiliser dans la configuration de Git. Récupérer l'ID de votre clé master au format LONG (8octets):
gpg --list-secret-keys --keyid-format LONG
Et ajouter cette id à votre config git:
git config --global user.signingkey 3AA5C34371567BD2
https://help.github.com/en/articles/telling-git-about-your-signing-key
Il reste plus qu'à créer un commit signé:
git commit -S -m "un commit signé"
Pour signer par défaut tous les commit (plus besoin de l'option -S):
git config --global commit.gpgsign true
Retirer l'option “–global” pour l'activer juste pour le projet courant.
Reste plus qu'à pusher normalement, git devrait vous connecter à Github avec la Yubikey. Si la signature s'est bien passée et que vous avez bien renseigné votre clé publique sur votre compte Github, un logo “Vérifié” devrait apparaitre sur le commit dans votre historique.
7 - Sources
Je vous liste tout ce qui a finit dans mes bookmarks:
- https://github.com/drduh/YubiKey-Guide Guide to using YubiKey for GPG and SSH
- https://blog.eleven-labs.com/en/openpgp-almost-perfect-key-pair-part-1/ OpenPGP - The almost perfect key pair
- https://blog.eleven-labs.com/en/openpgp-secret-keys-yubikey-part-2/ OpenPGP - Export Secret Keys to a Yubikey
- https://www.thepolyglotdeveloper.com/2019/02/use-yubikey-pgp-signing-encryption-authentication/ Use A YubiKey For PGP Signing, Encryption, And Authentication
- https://ocramius.github.io/blog/yubikey-for-ssh-gpg-git-and-local-login/ YubiKey for SSH, Login, 2FA, GPG and Git Signing
- https://medspx.fr/blog/Sysadmin/gnupg_ssh/ Utiliser son trousseau GPG avec SSH
- https://zerowidthjoiner.net/2019/01/12/using-ssh-public-key-authentication-with-a-smart-card Using SSH Public Key Authentication with a Smart Card
- https://suchsecurity.com/gpg-and-ssh-with-yubikey-on-windows.html GPG and SSH with Yubikey on Windows
- https://github.com/cuviper/ssh-pageant ssh-pageant github
Si vous tentez la manip' n'hésitez pas à commentez sur le forum si vous repérez une erreur dans le tuto ou si vous rencontrer un problème non répertorié afin de l’étoffer. Je pense partager le tuto à un plus large publique à terme (je suis en trains de regarder les https://pages.github.com/ Github Pages pour créer un blog statique). Donc d'ici là les corrections et améliorations sont les bienvenues.
A bientôt.
harfang
Commentaires des membres de Zenk-security :
- Petite information supplémentaire pour les utilisateurs de gnome pour ne pas avoir à redéfinir SSH_AUTH_SOCK à chaque ouverture d'un terminal
$ cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/gnome-keyring-ssh.desktop $ echo "X-GNOME-Autostart-enabled=false" >> ~/.config/autostart/gnome-keyring-ssh.desktop
- Vulnérabilité les clés directement sur les Yubikey 4, de mémoire elles sont vulnérables à ROCA. , ils en parlent ici, bien qu'a priori très peu d'utilisateurs ont été impacté, et une update firmware semble corriger le problème. https://www.yubico.com/keycheck/
- Si certains souhaitent administrer à tout hasard la Yubikey sur une VM pour une quelconque raison, sous VMWare vous devez activer le passthrough pour éviter d'avoir la surcouche de VMWare qui transforme la Yubikey en SmartCard générique. Pour ce faire, il faut ouvrir le .vmx, puis ajouter:
usb.generic.allowHID = "TRUE"
usb.generic.allowLastHID = "TRUE"
/Yubikey 4:
usb.quirks.device0 = "0x1050:0x0407 allow"
/Yubikey 5 NFC:
usb.quirks.device0 = "0x1050:0x0405 allow"
L'hexa correspond au PID / VID.
Pour une utilisation/administration SmartCard classique avec gnupg, pas besoin de faire cette manip.
- pour signer vos commit git. vous êtes obligé d'avoir une clé GPG correspondante à l'adresse e-mail utilisée pour vos commits.
Si vous ne voulez pas divulguer publiquement une adresse email, vous pouvez utiliser les « adresses » fournies par github :
<user>@users.noreply.github.com
plus d'infos : https://help.github.com/en/articles/associating-an-email-with-your-gpg-key
