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