Comment gérer ses clés SSH

Quand utiliser ce guide

Utilise ce guide quand tu veux :

Ajouter une clé SSH depuis une nouvelle machine
Générer une clé plus sécurisée (ed25519 au lieu de RSA)
Vérifier l'empreinte d'une clé avant de l'ajouter
Supprimer une clé d'une machine perdue ou compromise
Diagnostiquer une erreur Permission denied (publickey)

Pré-requis

Un compte gitrust actif
Un terminal avec ssh-keygen disponible (ssh-keygen --version doit répondre)

Étapes

1. Générer une clé ed25519 (recommandé)

ed25519 est l'algorithme recommandé : clés courtes, très rapides, résistantes aux attaques modernes.

ssh-keygen -t ed25519 -C "description-de-la-machine"

Exemple de description : laptop-maison-2026, serveur-ci, poste-bureau.

Sortie attendue :

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/toi/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Your identification has been saved in /home/toi/.ssh/id_ed25519
Your public key has been saved in /home/toi/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx description-de-la-machine

Une passphrase est fortement recommandée : elle chiffre la clé privée sur le disque. Si ta machine est volée, la clé reste inutilisable sans la passphrase.

2. Générer une clé RSA-4096 (alternative)

Si un outil ou un service impose RSA :

ssh-keygen -t rsa -b 4096 -C "description-de-la-machine"

La clé sera dans ~/.ssh/id_rsa et ~/.ssh/id_rsa.pub. RSA-4096 est sûr mais plus lent qu'ed25519.

3. Afficher la clé publique à copier

La clé publique (fichier .pub) est faite pour être partagée :

cat ~/.ssh/id_ed25519.pub

Sortie (une ligne) :

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx description-de-la-machine

Copie cette ligne entière.

4. Ajouter la clé dans gitrust (`/settings/keys`)

Dans ton navigateur, navigue vers Paramètres → Clés SSH (/settings/keys).

Clique Ajouter une clé SSH :

Titre : le même que la description (ex. laptop-maison-2026)
Clé : colle la ligne ssh-ed25519 … copiée

Clique Enregistrer.

Page /settings/keys avec une clé ajoutée

5. Lister les clés enregistrées

La page /settings/keys affiche toutes tes clés avec :

Leur titre
Leur empreinte SHA256 (pour vérification)
La date d'ajout
Un bouton Supprimer

6. Vérifier l'empreinte SHA256 d'une clé locale

Pour confirmer qu'une clé locale correspond bien à une clé enregistrée dans gitrust :

ssh-keygen -lf ~/.ssh/id_ed25519.pub

Sortie :

256 SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx description-de-la-machine (ED25519)

Compare ce SHA256 avec celui affiché dans /settings/keys. Ils doivent être identiques.

7. Tester la connexion SSH

ssh -T git@gitrust.example.com -p 2222

Sortie attendue :

Bonjour tonpseudo ! Vous êtes authentifié, mais gitrust ne fournit pas d'accès shell.

Si tu as plusieurs clés, spécifie laquelle utiliser :

ssh -T -i ~/.ssh/id_ed25519 git@gitrust.example.com -p 2222

8. Supprimer une clé

Dans /settings/keys, clique Supprimer à côté de la clé concernée. La suppression est immédiate — toute connexion utilisant cette clé sera refusée dès la prochaine tentative.

Variantes

Plusieurs machines, plusieurs clés

Tu peux enregistrer autant de clés que nécessaire dans gitrust. Chaque machine a sa propre paire de clés — tu ne copies jamais une clé privée d'une machine à l'autre.

Pour avoir plusieurs clés sur la même machine et choisir laquelle utiliser selon le serveur, crée un fichier ~/.ssh/config :

Host gitrust.example.com
    HostName gitrust.example.com
    User git
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_gitrust

Ensuite git clone git@gitrust.example.com:owner/repo.git utilisera automatiquement cette clé.

Ajouter la clé à l'agent SSH (évite de saisir la passphrase à chaque push)

ssh-add ~/.ssh/id_ed25519

Sur macOS, ajoute --apple-use-keychain pour que la passphrase soit mémorisée dans le trousseau système.

Dépannage `ssh -T`

Symptôme	Cause probable	Correction
`Permission denied (publickey)`	La clé privée locale ne correspond pas à une clé publique enregistrée, ou l'agent ne la connaît pas	Exécute `ssh-add ~/.ssh/id_ed25519`, puis réessaie. Vérifie que la bonne clé `.pub` est dans `/settings/keys`
`Connection refused`	Le port 2222 est bloqué ou le service SSH de gitrust est arrêté	Essaie le port 22 : `ssh -T git@gitrust.example.com -p 22`. Contacte l'administrateur
`Host key verification failed`	L'empreinte du serveur a changé ou est inconnue	Exécute `ssh-keyscan -p 2222 gitrust.example.com >> ~/.ssh/known_hosts`. Vérifie l'empreinte avec l'administrateur avant d'accepter
`Too many authentication failures`	L'agent SSH propose trop de clés	Spécifie explicitement : `ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -T git@… -p 2222`

Voir aussi

Tutoriel 02 — Cloner et pousser : mise en place complète SSH + premier clone
Comprendre la sécurité côté utilisateur : pourquoi les clés SSH sont plus sûres que les mots de passe
Créer un Personal Access Token : alternative SSH pour les accès HTTPS et les scripts

Eric / documentation