SSH-KEYGEN(1)

NOM
ssh-keygen - Utilitaire d’OpenSSH pour la gestion des clés d’authentification

SYNOPSIS
ssh-keygen [-q] [-a passes] [-b bits] [-C commentaire] [-f fichier_clé_sortie] [-m format] [-N nouvelle_phrase_secrète] [-O option] [-t ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa] [-w fournisseur] [-Z algo_chiffrement]
ssh-keygen -p [-a passes] [-f fichier_clé] [-m format] [-N nouvelle_phrase_secrète] [-P ancienne_phrase_secrète] [-Z algo_chiffrement]
ssh-keygen -i [-f fichier_clé_entrée] [-m format_clé]
ssh-keygen -e [-f fichier_clé_entrée] [-m format_clé]
ssh-keygen -y [-f fichier_clé_entrée]
ssh-keygen -c [-a passes] [-C commentaire] [-f fichier_clé] [-P phrase_secrète]
ssh-keygen -l [-v] [-E hachage_empreinte] [-f fichier_clé_entrée]
ssh-keygen -B [-f fichier_clé_entrée]
ssh-keygen -D pkcs11
ssh-keygen -F nom_hôte [-lv] [-f fichier_hôtes_connus]
ssh-keygen -H [-f fichier_hôtes_connus]
ssh-keygen -K [-a passes] [-w fournisseur]
ssh-keygen -R nom_hôte [-f fichier_hôtes_connus]
ssh-keygen -r nom_hôte [-g] [-f fichier_clé_entrée]
ssh-keygen -M generate [-O option] fichier_sortie
ssh-keygen -M screen [-f fichier_entrée] [-O option] fichier_sortie
ssh-keygen -I identité_certificat -s clé_CA [-hU] [-D fournisseur_pkcs11] [-n principals] [-O option] [-V intervalle_validité] [-z numéro_série] file ...
ssh-keygen -L [-f fichier_clé_entrée]
ssh-keygen -A [-a passes] [-f chemin_préfixe]
ssh-keygen -k -f fichier_krl [-u] [-s clé_publique_ca] [-z numéro_version] file ...
ssh-keygen -Q [-l] -f fichier_krl file ...
ssh-keygen -Y find-principals [-O option] -s fichier_signature -f fichier_signataires_autorisés
ssh-keygen -Y match-principals -I identité_signataire -f fichier_signataires_autorisés
ssh-keygen -Y check-novalidate [-O option] -n espace_noms -s fichier_signature
ssh-keygen -Y sign [-O option] -f fichier_clé -n espace_noms file ...
ssh-keygen -Y verify [-O option] -f fichier_signataires_autorisés -I identité_signataire -n espace_noms -s fichier_signature [-r fichier_révocation]

DESCRIPTION
ssh-keygen génère, gère et convertit les clés d'authentification pour ssh(1). ssh-keygen permet de créer des clés à utiliser avec la version 2 du protocole SSH.

Le type de clé à générer est spécifié à l'aide de l'option -t. Invoquée sans argument, ssh-keygen générera une clé Ed25519.

ssh-keygen permet aussi de générer des groupes à utiliser dans le cadre de l’échange de groupe Diffie-Hellman (DH-GEX). Voir la section GÉNÉRATION DES MODULI pour les détails.

Enfin, ssh-keygen permet de générer et mettre à jour les listes de révocation de clé et de tester si certaines clés ont été révoquées par une de ces listes. Voir la section LISTES DE RÉVOCATION DE CLÉS pour les détails.

En général, chaque utilisateur souhaitant utiliser SSH avec une authentification par clé publique lance ce programme une fois pour générer la clé d'authentification dans ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519, ~/.ssh/id_ed25519_sk ou ~/.ssh/id_rsa. Éventuellement, l'administrateur système peut utiliser ce programme pour générer des clés d'hôte, comme on le voit dans /etc/rc.

Normalement, ce programme génère la clé et demande un nom de fichier pour stocker la clé privée. La clé publique est stockée dans un fichier de même nom suffixé par « .pub ». Le programme demande aussi une phrase secrète. La phrase secrète peut être vide, ce qui équivaut une absence de phrase secrète (les clés d'hôte doivent avoir une phrase secrète vide), ou une chaîne de caractères de longueur quelconque. Une phrase secrète est semblable à un mot de passe, à la différence qu’elle peut être une phrase avec des mots, des caractères de ponctuation, des chiffres, des blancs ou n'importe quelle chaîne de caractères. Une bonne phrase secrète doit comporter 10 à 30 caractères et ne doit pas être une phrase simple ou facile à deviner (pour information, la prose anglaise a seulement un à deux bits d'entropie par caractère et fournit de très mauvaises phrases secrètes) ; elle doit en outre comporter un mélange de capitales, de minuscules, de chiffres et de caractères non alphanumériques. La phrase secrète peut être modifiée par la suite à l’aide de l’option -p.

Il n'y a aucun moyen de retrouver une phrase secrète oubliée. Si on oublie la phrase secrète, il faut générer une nouvelle clé et copier la clé publique correspondante sur les autres machines.

Par défaut, ssh-keygen génère les clés sous un format spécifique à OpenSSH. Ce format est préféré, car il offre une meilleure protection des clés à son emplacement et permet le stockage des commentaires de la clé dans le fichier de clé privée lui-même. Le commentaire de la clé peut faciliter l’identification de la clé. Son contenu initial est « utilisateur@hôte » à la création de la clé, mais il peut être modifié à l’aide de l’option -c.

ssh-keygen peut encore générer des clés privées au format PEM précédemment utilisé en spécifiant l’option -m. Cette option peut être utilisée pour générer une nouvelle clé ou, pour une clé existante au nouveau format, convertir cette dernière en utilisant cette option en combinaison avec l’option -p (changer la phrase secrète).

Une fois la clé générée, ssh-keygen demandera où stocker les clés pour les activer.

Les options sont les suivantes :

-A  Générer des clés d’hôte de tous les types de clé par défaut (rsa, ecdsa et ed25519) si elles n’existent par déjà. Les clés d’hôte sont générées avec le chemin du fichier de clé par défaut, une phrase secrète vide, les bits par défaut pour le type de clé et un commentaire par défaut. Si l’option -f a aussi été spécifiée, son argument est utilisé comme préfixe pour le chemin par défaut des fichiers de clé d’hôte résultants. Cette option est utilisée par /etc/rc pour générer de nouvelles clés d’hôte.

-a passes
    Lors de l’enregistrement d’une clé privée, cette option permet de spécifier le nombre de passes KDF (key derivation function, actuellement bcrypt_pbkdf(3)) utilisé. Un nombre plus élevé implique une vérification plus lente de la phrase secrète et augmente la résistance aux tentatives de craquage du mot de passe par force brute (en cas de vol de clés). La valeur par défaut est de 16 passes.

-B  Cette option permet d’afficher un condensé « bubblebabble » (encodé en alternant consonnes et voyelles, NDT) du fichier de clé privée ou publique spécifié.

-b bits
    Cette option permet de spécifier le nombre de bits que la clé à créer devra comporter. Pour les clés RSA, la valeur minimale est de 1024 bits et la valeur par défaut est de 3072 bits. En général, on considère qu'une longueur de 3072 bits est suffisante. Pour les clés ECDSA, l’option -b détermine la longueur de la clé en spécifiant une des trois tailles de courbe elliptique suivantes : 256, 384 ou 521 bits. Toute tentative d’utiliser des tailles autres que ces trois valeurs pour une clé ECDSA échouera. Les clés ECDSA-SK, Ed25519 et Ed25519-SK possèdent une taille fixe et dans leur cas, l’option -b sera ignorée.

-C comment
    Cette option permet de fournir un nouveau commentaire.

-c  Cette option permet de changer le commentaire des fichiers de clés publique et privée. Le programme demande de fournir le nom du fichier contenant la clé privée, la phrase secrète si la clé en possède une et le nouveau commentaire.

-D pkcs11
    Cette option permet de télécharger les clés publiques fournies par la bibliothèque partagée PKCS#11 pkcs11. Lorsqu’elle est utilisée en combinaison avec l’option -s, cette option indique qu’une clé de CA réside dans un jeton PKCS#11 (voir la section CERTIFICATS pour les détails).

-E hachage_empreinte
    Cette option permet de spécifier l’algorithme de hachage utilisé pour l’affichage des empreintes de clé. Les options valables sont « md5 » et « sha256 ». La valeur par défaut est « sha256 ».

-e  Cette option lit un fichier de clé publique ou privée D’OpenSSH et affiche la clé publique sur la sortie standard sous un des formats spécifiés à l’aide de l’option -m. Le format d’export par défaut est « RFC4716 ». Cette option permet d’exporter des clés d’OpenSSH pour qu’elles puissent être utilisées par d’autres programmes, à l’instar de plusieurs implémentations commerciales de SSH.

-F nom_hôte | [nom_hôte]:port
    Rechercher le nom_hôte spécifié (avec un numéro de port optionnel) dans un fichier known_hosts en listant toutes les occurrences trouvées. Cette option s’avère utile pour trouver des adresses ou des noms d’hôte hachés et permet aussi, en combinaison avec l’option -H, d’afficher les clés trouvées sous un format haché.

-f nom_fichier
    Cette option permet de spécifier le nom du fichier de clé.

-g  Utiliser le format DNS générique pour l’affichage d’enregistrements de ressources de type empreinte à l’aide de l’option -r.

-H  Cette option permet de hacher un fichier known_hosts. Elle remplace tous les noms d’hôte et adresses par leur représentation hachée dans le fichier spécifié ; le contenu originel est déplacé vers un fichier de même nom suffixé par « .old ». Ces hachages peuvent normalement être utilisés par ssh et sshd, mais ils ne révèlent aucune information d’identification en cas de divulgation du contenu du fichier. Cette option ne modifie pas les noms d’hôte hachés existants et peut donc être utilisée en toute sécurité avec des fichiers qui mélangent des noms hachés et non hachés.

-h  Lors de la signature d’une clé, créer un certificat d’hôte au lieu d’un certificat d’utilisateur. Voir la section CERTIFICATS pour les détails.

-I identité_certificat
    Cette option permet de spécifier l’identité de la clé lors de la signature d’une clé publique. Voir la section CERTIFICATS pour les détails.

-i  Cette option lit un fichier de clé privée (ou publique) non chiffré dans le format spécifié à l’aide de l’option -m et affiche une clé privée (ou publique) compatible avec OpenSSH sur la sortie standard. Cette option permet d'importer des clés depuis d’autres logiciels, à l’instar de plusieurs implémentations commerciales de SSH.

-K  Télécharger des clés résidentes depuis un authentificateur FIDO. Les fichiers de clé publique et privée correspondant à chaque clé téléchargée seront écrits dans le répertoire actuel. Si plusieurs authentificateurs FIDO sont attachés, les clés seront téléchargées depuis le premier authentificateur atteint. Voir la section AUTHENTIFICATEUR FIDO pour plus d’informations.

-k  Cette option permet de générer un fichier KRL. Dans ce mode, ssh-keygen génère un fichier KRL à l’emplacement spécifié à l’aide de l’option -f qui révoque toute clé ou tout certificat présent sur la ligne de commande. Les clés ou certificats à révoquer peuvent être spécifiés à l’aide du fichier de clé publique correspondant ou en utilisant le format décrit dans la section LISTES DE RÉVOCATION DE CLÉS.

-L  Afficher le contenu d’un ou plusieurs certificats.

-l  Cette option permet d’afficher l’empreinte du fichier de clé publique spécifié. ssh-keygen essaie de trouver le fichier de clé publique correspondant et affiche son empreinte. En combinaison avec l’option -v, cette option affiche une représentation visuelle de la clé en art ASCII en plus de l’empreinte.

-M generate
    Cette option permet de générer une proposition de paramètres Diffie-Hellman Group Exchange (DH-GEX) pour une utilisation éventuelle par les méthodes d’échange de clés « diffie-hellman-group-exchange-* ». Les nombres générés par cette opération doivent être examinés plus en détail avant utilisation. Voir la section GÉNÉRATION DES MODULI pour plus d’informations.

-M screen
    Examiner une proposition de paramètres Diffie-Hellman Group Exchange. Cette option accepte en argument une liste de paramètres suggérés et vérifie s’ils sont des nombres premiers sûrs (nombres premiers de Sophie Germain) avec des générateurs de groupe acceptables. Les résultats de cette opération peuvent être ajoutés au fichier /etc/ssh/moduli. Voir la section GÉNÉRATION DES MODULI pour plus d’informations.

-m format_clé
    Cette option permet de spécifier un format de clé pour la création de clé, les options de conversion -i (import) et -e (export) et l’opération de changement de phrase secrète -p. Cette dernière permet d’effectuer une conversion entre les formats de clé privée OpenSSH et PEM. Les formats de clé pris en charge sont : « RFC4716 » (clé publique ou privée RFC 4716/SSH2), « PKCS8 » (clé publique ou privée PKCS8) ou « PEM » (clé publique PEM). Par défaut, OpenSSH écrit les clés privées nouvellement créées sous son format propre, mais pour la conversion de clés publiques pour l’exportation, le format par défaut est «  RFC4716 ». Si le format spécifié est « PEM » lors de la création ou de la mise à jour d’un type de clé privée pris en charge, la clé sera écrite sous le format de clé privée patrimonial PEM.

-N nouvelle_phrase_secrète
    Cette option permet de spécifier la nouvelle phrase secrète.

-n principals
    Cette option permet de spécifier un ou plusieurs « principals » (noms d’hôte ou d’utilisateur) à inclure dans un certificat lors de la signature d’une clé. Plusieurs « principals » peuvent être spécifiés en les séparant par des virgules (NDT : un « principal » est une chaîne arbitraire définie au niveau du serveur pour un utilisateur et devant être présente dans le certificat du client pour que ce dernier puisse se connecter). Voir la section CERTIFICATS pour les détails.

-O option
    Spécifier une option sous la forme d’une paire mot-clé/valeur. Cette dernière est spécifique à l’opération que ssh-keygen doit effectuer.

    Une des options répertoriées dans la section CERTIFICATS peut être spécifiée ici lors de la signature des certificats.

    Une des options répertoriées dans la section GÉNÉRATION DES MODULI peut être spécifiée lors de la génération ou la vérification des moduli.

    Les options répertoriées dans la section AUTHENTIFICATEUR FIDO peuvent être spécifiées lors de la génération de clés hébergées par un authentificateur FIDO.

    Lorsqu’on effectue des opérations en rapport avec une signature à l’aide de l’option -Y, les options suivantes sont valables :

    hashalg=algorithme
        Sélectionner l’algorithme de hachage à utiliser pour hacher le message à signer. Les algorithmes valables sont « sha256 » et « sha512 ». La valeur par défaut est« sha512 ».

    print-pubkey
        Afficher l’intégralité de la clé publique sur la sortie standard après vérification de la signature.

    verify-time=horodatage
        Spécifier une heure à utiliser à la place de l’heure actuelle pour la validation d’une signature. L’heure peut être spécifiée sous forme de date ou d’heure au format AAAAMMJJ[Z] ou AAAAMMJJHHMM[SS][Z]. Les dates et heures seront interprétées selon le fuseau horaire actuel du système, sauf si elles sont suffixées du caractère « Z », auquel cas elles seront interprétées selon le fuseau horaire UTC.

    Lors d’une génération d’enregistrements DNS SSHFP à partir de clés publiques à l’aide de l’option -r, les options valables sont les suivantes :

    hashalg=algorithme
        Sélectionner un algorithme de hachage à utiliser pour l’affichage des enregistrements SSHFP à l’aide de l’option -D. Les algorithmes disponibles sont « sha1 » et « sha256 ». Par défaut, les enregistrements sont affichés en utilisant les deux algorithmes.

    L’option -O peut être spécifiée plusieurs fois.

-P phrase_secrète
    Fournir la phrase secrète (l’ancienne).

-p  Demander de changer la phrase secrète d’un fichier de clé privée au lieu de créer une nouvelle clé privée. Le programme demandera le nom du fichier contenant la clé privée, l’ancienne phrase secrète et deux fois la nouvelle phrase secrète.

-Q  Tester si les clés ont été révoquées dans une KRL. Si l’option -l est spécifiée, le contenu de la KRL sera affiché.

-q  Rendre silencieux ssh-keygen.

-R nom_hôte | [nom_hôte]:port
    Supprimer d’un fichier known_hosts toutes les clés appartenant au nom_hôte spécifié (accompagné éventuellement du numéro de port). Cette option s’avère utile pour supprimer des hôtes hachés (voir l’option -H ci-dessus).

-r nom_hôte
    Afficher l’enregistrement de ressource d’empreinte SSHFP nommé nom_hôte pour le fichier de clé publique spécifié.

-s clé_CA
    Certifier (signer) une clé publique à l’aide de la clé de CA spécifiée. Voir la section CERTIFICATS pour les détails.

    À la génération d’une KRL (liste de révocation de clés, NDT), l’option -s permet de spécifier le chemin d’un fichier de clé publique de CA utilisé pour révoquer des certificats directement à l’aide du numéro de série ou de l’identifiant de la clé. Voir la section LISTES DE RÉVOCATION DE CLÉS pour les détails.

-t ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
    Cette option permet de spécifier le type de la clé à créer. Les valeurs possibles sont « ecdsa », « ecdsa-sk », « ed25519 » (par défaut), « ed25519-sk » ou « rsa ».

    Cette option permet aussi de spécifier le type de signature souhaité pour la signature de certificats à l’aide d’une clé de CA RSA. Les types de signature RSA disponibles sont « ssh-rsa » (signatures SHA1, non recommandé), « rsa-sha2-256 » et « rsa-sha2-512 » (par défaut pour les clés RSA).

-U  Utilisée en combinaison avec -s ou -Y sign, cette option indique qu’une clé de CA réside dans un agent ssh-agent(1). Voir la section CERTIFICATS pour plus d’informations.

-u  Mettre à jour une KRL. Si cette option est utilisée en combinaison avec l’option -k, au lieu de créer une nouvelle KRL, les clés listées sur la ligne de commande sont ajoutées à la KRL existante.

-V intervalle_validité
    Cette option permet de spécifier un intervalle de validité lors d’une signature de certificat. Un intervalle de validité peut être une simple date, indiquant que le certificat est valable à partir de maintenant et jusqu’à cette date, ou peut comporter deux dates séparées par un « : » pour indiquer un intervalle de validité explicite.

    L’heure de début peut être spécifiée par :
    •   La chaîne « always » pour indiquer que le certificat n’a pas de date de début de validité spécifiée.
    •   Une date ou heure dans le fuseau horaire du système et indiquée sous la forme AAAAMMDD ou AAAAMMDDHHMM[SS].
    •   Une date ou heure dans le fuseau horaire UTC et indiquée sous la forme AAAAMMJJZ ou AAAAMMJJHHMM[SS]Z.
    •   Une heure relative antérieure à l’heure système actuelle et comportant un signe moins suivi d’un intervalle dans le format décrit dans la section FORMATS DE TEMPS de sshd_config(5).
    •   Un nombre de secondes après l’Époque (1er janvier 1970 00:00:00 UTC) sous la forme d’un nombre hexadécimal commençant par « 0x ».

    L’heure de fin peut être spécifiée de manière similaire à l’heure de début :
    •   La chaîne « forever » pour indiquer que le certificat n’a pas de date de fin de validité spécifiée.
    •   Une date ou heure dans le fuseau horaire du système et indiquée sous la forme AAAAMMDD ou AAAAMMDDHHMM[SS].
    •   Une date ou heure dans le fuseau horaire UTC et indiquée sous la forme AAAAMMJJZ ou AAAAMMJJHHMM[SS]Z.
    •   Une heure relative postérieure à l’heure système actuelle et comportant un signe plus suivi d’un intervalle dans le format décrit dans la section FORMATS DE TEMPS de sshd_config(5).
    •   Un nombre de secondes après l’Époque (1er janvier 1970 00:00:00 UTC) sous la forme d’un nombre hexadécimal commençant par « 0x ».

    Par exemple :

    +52w1d
        Le certificat est valable à partir de maintenant et pour une durée de 52 semaines et 1 jour.

    -4w:+4w
        Le certificat était valable les quatre dernières semaines et le sera encore pendant les quatre prochaines semaines.

    20100101123000:20110101123000
        Le certificat est valable du 1er janvier 2010 à 12 h 30 au 1er janvier 2011 à 12 h 30.

    20100101123000Z:20110101123000Z
        Identique, mais exprimé en temps universel UTC.

    -1d:20110101
        Le certificat est valable depuis hier et jusqu’au 1er janvier 2011 à minuit.

    0x1:0x2000000000
        Le certificat est valable depuis le tout début de 1970 et jusqu’à mai 2033.

    -1m:forever
        Le certificat est valable depuis 1 minute et n’expirera jamais.

-v  Mode prolixe. Si cette option est utilisée, ssh-keygen affichera des messages de débogage à propos de son exécution. Cette option s’avère utile pour le débogage de la génération des moduli. Spécifier plusieurs fois l’option -v (au maximum 3) augmente la prolixité.

-w fournisseur
    Cette option permet de spécifier le chemin d’une bibliothèque qui sera utilisée pour la création de clés hébergées par un authentificateur FIDO, outrepassant par là même le comportement par défaut consistant à utiliser la prise en charge interne de USB HID.

-Y find-principals
    Cette option permet de trouver le(s) « principal(s) » associés à la clé publique d’une signature spécifiée à l’aide de l’option -s dans un fichier de signataires autorisés spécifié à l’aide de l’option -f. Le format du fichier de signataires autorisés est documenté dans la section SIGNATAIRES AUTORISÉS ci-dessous. Si un ou plusieurs « principals » correspondants sont trouvés, ils sont renvoyés sur la sortie standard.

-Y match-principals
    Trouver le « principal » correspondant au nom de principal fourni à l’aide de l’option -I dans le fichier de signataires autorisés spécifié à l’aide de l’option -f. Si un ou plusieurs « principals » qui correspondent sont trouvés, ils sont renvoyés sur la sortie standard.

-Y check-novalidate
    Vérifier qu’une signature générée à l’aide de ssh-keygen

    -Y sign possède une structure valable. Cette vérification ne garantit pas qu’une signature provient d’un signataire autorisé. Lors d’une vérification de signature, ssh-keygen peut recevoir un message sur l’entrée standard et un espace de noms de signature à l’aide de l’option -n. Le nom d’un fichier contenant la signature correspondante doit aussi être fourni à l’aide de l’option -s. Si la signature est testée avec succès, ssh-keygen renvoie un code de retour de 0.

-Y sign
    Signer de manière cryptographique un fichier ou des données quelconques en utilisant une clé SSH. Lors d’une signature, ssh-keygen reçoit zéro ou plusieurs noms de fichier sur la ligne de commande — si aucun nom de fichier n’est spécifié, ssh-keygen signera les données présentées sur l’entrée standard. Les signatures sont écrites à l’emplacement du fichier d’entrée avec l’extension « .sig » ou sur la sortie standard si le message à signer a été lu sur l’entrée standard.

    La clé utilisée pour la signature est spécifiée à l’aide de l’option -f et peut correspondre à une clé privée ou à une clé publique, la contrepartie privée étant fournie dans ce dernier cas par l’agent ssh-agent(1). Pour éviter de confondre des signatures entre différents domaines d’utilisation (signature d’un fichier vs signature d’un courriel par exemple), un espace de noms de signature additionnel doit être spécifié à l’aide de l’option -n. Les espaces de noms sont des chaînes arbitraires pouvant contenir « fichier » pour la signature d’un fichier ou « courriel » pour la signature d’un email. Pour une utilisation personnalisée, il est recommandé d’utiliser des noms suivant un motif ESPACE_NOMS@VOTRE_DOMAINE pour générer des espaces de noms dépourvus d’ambiguïté.

-Y verify
    Demander la vérification d’une signature générée en utilisant la commande ssh-keygen

    -Y sign comme décrit ci-dessus. Lors d’une vérification de signature, ssh-keygen peut recevoir un message sur l’entrée standard et un espace de noms de signature à l’aide de l’option -n. Le nom d’un fichier contenant la signature correspondante doit aussi être fourni à l’aide de l’option -s, accompagné de l’identité du signataire à l’aide de l’option -I et d’une liste de signataires autorisés à l’aide de l’option -f. Le format du fichier des signataires autorisés est documenté dans la section SIGNATAIRES AUTORISÉS ci-dessous. Le nom d’un fichier contenant la liste des clés révoquées peut être fourni à l’aide de l’option -r. Le fichier des révocations de clés peut être une KRL (Key Revocation List) ou une liste de clés publiques (une par ligne). ssh-keygen renvoie un code de retour de 0 en cas de vérification avec succès par un signataire autorisé.

-y  Cette option permet de lire un fichier privé au format OpenSSH et d’afficher une clé publique OpenSSH sur la sortie standard.

-Z algo_chiffrement
    Cette option permet de spécifier l’algorithme à utiliser pour le chiffrement d’un fichier de clé privée au format OpenSSH. La liste des algorithmes disponibles peut être obtenue à l’aide de la commande « ssh -Q cipher ». L’algorithme par défaut est « aes256-ctr ».

-z numéro_série
    Cette option permet de spécifier un numéro de série à inclure dans le certificat afin de le différencier des autres certificats du même CA. Si le numéro_série est préfixé avec le caractère « + », il sera incrémenté pour chaque certificat signé sur une seule ligne de commande. Le numéro de série par défaut est 0.

    Lorsqu’on génère une KRL, l’option -z permet de spécifier le numéro de version de cette KRL.

GÉNÉRATION DES MODULI
ssh-keygen permet de générer des groupes pour le protocole Diffie-Hellman Group Exchange (DH-GEX). La génération de ces groupes est un processus en deux étapes. D’abord, les nombres premiers candidats sont générés en utilisant un processus rapide mais gourmand en mémoire. Ces nombres premiers candidats sont alors testés pour leur pertinence (processus utilisant intensément le CPU).

La génération des nombres premiers est effectuée en utilisant l’option -M generate. La longueur souhaitée des nombres premiers peut être spécifiée à l’aide de l’option -O bits. Par exemple :

    # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates

Par défaut, la recherche de nombres premiers débute par une valeur aléatoire dans l’intervalle correspondant à la longueur souhaitée, mais il est possible de modifier cette valeur à l’aide de l’option -O start qui permet d’indiquer un point de départ différent (en hexadécimal).

Lorsqu’un jeu de candidats a été généré, ils doivent être testés pour vérifier s’ils conviennent. Pour ce faire, on utilise l’option -M screen. Dans ce mode, ssh-keygen va lire la liste des candidats sur l’entrée standard (ou dans un fichier spécifié à l’aide de l’option -f). Par exemple :

    # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048

Par défaut, chaque candidat subit 100 tests de primalité. Ce nombre peut être modifié à l’aide de l’option -O prime-tests. La valeur de générateur DH sera choisie automatiquement pour le nombre premier considéré. Si un générateur spécifique est souhaité, il sera spécifié à l’aide de l’option -O generator. Les valeurs de générateur valables sont 2, 3 et 5.

Les groupes DH testés peuvent être installés dans /etc/ssh/moduli. Il est important que ce fichier contienne des moduli dans une plage de longueurs en bits.

Plusieurs options sont disponibles pour la génération et la vérification des moduli par l’intermédiaire de l’option -O :

lines=nombre
    Quitter après avoir vérifié le nombre de lignes spécifié lors du test des candidats DH.

start-line=numéro_ligne
    Débuter la vérification au numéro de ligne spécifié pour le test des candidats DH.

checkpoint=nom_fichier
    Écrire la dernière ligne traitée dans le fichier spécifié lors du test des candidats DH. Cela permet de sauter les lignes du fichier d’entrée qui ont déjà été traitées si la tâche est relancée.

start=valeur_hexadécimale
    Spécifier un point de départ (en hexadécimal) pour la génération des moduli pour DH-GEX (Diffie-Hellman group exchange).

generator=valeur
    Spécifier le générateur souhaité (en décimal) lors du test des moduli candidats pour DH-GEX (Diffie-Hellman group exchange).

CERTIFICATS
ssh-keygen prend en charge la signature des clés pour produire des certificats qui pourront être utilisés pour l’authentification des utilisateurs ou des hôtes. Un certificat comporte une clé publique, des informations relatives à l’identité, zéro ou plusieurs noms de « principal » (utilisateur ou hôte) et un jeu d’options signés par une clé d’autorité de certification (CA). Au lieu de devoir considérer comme fiables plusieurs clés d’utilisateur ou d’hôte, les clients ou les serveurs peuvent alors se contenter de ne considérer comme fiable que la clé de CA et de vérifier sa signature sur un certificat. Notez que les certificats OpenSSH possèdent un format différent (et beaucoup plus simple) de celui des certificats X509 utilisés dans ssl(8).

ssh-keygen prend en charge deux types de certificat : utilisateur et hôte. Les certificats utilisateur authentifient les utilisateurs auprès des serveurs, alors que les certificats d’hôte authentifient les hôtes serveur auprès des utilisateurs. Pour générer un certificat utilisateur :

    $ ssh-keygen -s /path/to/ca_key -I id -n user \
          /path/to/user_key.pub

The resultant certificate will be placed in /path/to/user_key-cert.pub. The argument to -I is a key identifier that will be used in logs and may be used to revoke keys. The argument to -n is one or more (comma-separated) principals, typically usernames, that the certificate represents. A host certificate requires the -h option:

    $ ssh-keygen -s /path/to/ca_key -I id -h -n foo.example.org \
          /path/to/host_key.pub

For host certificates, the principals specified using the -n argument are hostnames and may contain wildcard characters.

Le certificat d’hôte obtenu sera placé dans /chemin/vers/clé_hôte-cert.pub.

Il est possible de signer en utilisant une clé de CA stockée dans un jeton PKCS#11 en fournissant la bibliothèque de jeton à l’aide de l’option -D et en identifiant la clé de CA en fournissant sa partie publique comme argument de l’option -s :

    $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I id -n user \
          user_key.pub

De même, il est possible de faire héberger la clé de CA par un agent ssh-agent(1) en utilisant l’option -U ; là encore, la clé de CA doit être identifiée par sa partie publique.

    $ ssh-keygen -Us ca_key.pub -I id -n user user_key.pub

Dans tous les cas, id_clé est un « identifiant de clé » qui est conservé par le serveur lorsque le certificat est utilisé pour l’authentification.

Certificates are limited to be valid for a set of principal (user/host) names. To generate a certificate for a specified set of principals:

    $ ssh-keygen -s ca_key -I id -n user1,user2 user_key.pub
    $ ssh-keygen -s ca_key -I id -h -n host.domain host_key.pub

D’autres limitations de la validité et de l’utilisation des certificats utilisateur peuvent être spécifiées à l’aide d’options de certificat. Une option de certificat pourra désactiver des fonctionnalités de la session SSH, pourra n’être valable que si présentée depuis des adresses source particulières ou pourra forcer l’utilisation d’une commande spécifique.

Les option disponibles pour les certificats utilisateur sont :

clear
    Supprimer toutes les permissions activées. Cette option s’avère utile pour supprimer le jeu de permissions par défaut de façon à pouvoir ajouter des permissions individuellement.

critical:nom[=contenu]
extension:nom[=contenu]
    Inclure une option ou extension critique de certificat arbitraire. Le nom spécifié doit contenir un suffixe de domaine comme « nom@example.com ». Si contenu est spécifié, il est inclus comme contenu de l’extension/option codée en tant que chaîne ; dans le cas contraire, l’extension/option est créée sans contenu (ce qui indique en général qu’il s’agit d’un drapeau). Un client ou un serveur qui ne reconnaît pas une extension peut l’ignorer, attendu que les options critiques inconnues entraîneront le rejet du certificat.

force-command=commande
    Forcer l’exécution de la commande à la place de toute commande ou tout interpréteur de commande spécifié par l’utilisateur quand le certificat est utilisé pour l’authentification.

no-agent-forwarding
    Désactiver la redirection de ssh-agent(1) (autorisée par défaut).

no-port-forwarding
    Désactiver la redirection de port (autorisée par défaut).

no-pty
    Désactiver l’allocation de pseudo-terminal (autorisée par défaut).

no-user-rc
    Désactiver l’exécution de ~/.ssh/rc par sshd(8) (autorisée par défaut).

no-x11-forwarding
    Désactiver la redirection de X11 (autorisée par défaut).

permit-agent-forwarding
    Autoriser la redirection de ssh-agent(1).

permit-port-forwarding
    Autoriser la redirection de port.

permit-pty
    Autoriser l’allocation de pseudo-terminal.

permit-user-rc
    Autoriser l’exécution de ~/.ssh/rc par sshd(8).

permit-X11-forwarding
    Autoriser la redirection de X11.

no-touch-required
    Ne pas exiger que les signatures effectuées à l'aide de cette clé incluent la preuve de la présence de l'utilisateur (par exemple en exigeant que l’utilisateur touche l’authentificateur). Cette option n’est pertinente que pour les algorithmes d’authentificateur FIDO ecdsa-sk et ed25519-sk.

source-address=liste_adresses
    Restreindre les adresses source à partir desquelles le certificat est considéré comme valable. liste_adresses est une liste, séparée par des virgules, d’une ou plusieurs paires adresse/masque réseau au format CIDR.

verify-required
    Exiger que les signatures faites avec cette clé mentionnent que l'utilisateur a préalablement été vérifié, par exemple avec un code ou un token biométrique. Cette option n'a de sens que pour les algorithmes de l'authentificateur FIDO ecdsa-sk and ed25519-sk.

À l’heure actuelle, aucune option standard n’est valable pour les clés d’hôte.

Pour finir, un certificat peut être défini avec une durée de validité. À cet effet, l’option -V permet de spécifier une heure de début et une heure de fin de validité pour le certificat. Un certificat présenté en dehors de cet intervalle de temps sera considéré comme non valable. Par défaut, les certificats sont valables depuis l’Époque UNIX jusqu’à un futur lointain.

Pour les certificats servant à l’authentification d’un utilisateur ou d’un hôte, la clé publique de CA doit être considérée comme fiable par sshd(8) ou ssh(1). Veuillez consulter ces pages du manuel pour les détails.

AUTHENTIFICATEUR FIDO
ssh-keygen peut générer des clés hébergées par un authentificateur FIDO ; ces dernières peuvent alors être utilisées quasiment comme tout autre type de clé pris en charge par OpenSSH, pourvu que l’authentificateur matériel soit branché lorsque les clés sont utilisées. En général, l’authentificateur FIDO a besoin que l’utilisateur le touche ou le tapote pour autoriser explicitement des opérations. Les clés FIDO comportent deux parties : une partie gestion de clé stockée dans le fichier de clé privée sur disque, et une clé privée par dispositif unique pour chaque authentificateur FIDO et qui ne peut pas être exportée depuis l’authentificateur matériel. Ces deux parties sont combinées par le matériel lors de l’authentification pour produire la clé réelle qui sera utilisée pour signer les épreuves d’authentification. Les types de clé pris en charge sont ecdsa-sk et ed25519-sk.

Les options valables pour les clés FIDO sont :

application
    Remplacer la chaîne FIDO par défaut application/origine de « ssh: ». Cette option peut s’avérer utile pour générer des clés résidentes spécifiques à un hôte ou un domaine. La chaîne application spécifiée doit commencer par « ssh: ».

challenge=chemin
    Cette option permet de spécifier le chemin d’une chaîne d’épreuve qui sera transmise à l’authentificateur FIDO pendant la génération de la clé. La chaîne d’épreuve peut être utilisée en tant que partie d’un protocole inhabituel pour l’inscription d’une clé (une épreuve aléatoire est utilisée par défaut).

device
    Spécifier explicitement un dispositif fido(4) à utiliser au lieu de laisser l’intergiciel de l’authentificateur en choisir un.

no-touch-required
    Cette option permet d’indiquer que la clé privée générée ne requiert pas de contact physique (présence de l’utilisateur) pour effectuer des signatures. Notez que par défaut, sshd(8) refusera de telles signatures, sauf mention contraire à l’aide d’une option authorized_keys.

resident
    Cette option indique que la gestion de la clé doit être stockée sur l’authentificateur FIDO lui-même, ce qui facilite l’utilisation de l’authentificateur sur plusieurs ordinateurs. Les clés résidentes peuvent être prises en charge par les authentificateurs FIDO2 et il est en général nécessaire de définir le code PIN sur l’authentificateur avant la génération. Les clés résidentes peuvent être chargées à partir de l’authentificateur à l’aide de ssh-add(1). Stocker les deux parties d’une clé sur un authentificateur FIDO augmente la probabilité qu’un attaquant parvienne à utiliser un dispositif d’authentification volé.

user
    Cette option permet de spécifier un nom d’utilisateur à associer à une clé résidente, remplaçant par là même le nom d’utilisateur par défaut vide. Spécifier un nom d’utilisateur peut s’avérer utile lors de la génération de clés résidentes multiples pour le même nom d’application.

verify-required
    Cette option indique que cette clé privée requiert une vérification de l’utilisateur pour chaque signature. Tous les authentificateurs FIDO ne prennent pas en charge cette option. Actuellement, l’authentification par code PIN est la seule méthode de vérification prise en charge, mais d’autres méthodes seront peut-être prises en charge dans le futur.

write-attestation=chemin
    Cette option peut être utilisée à la génération de la clé pour enregistrer les données d’attestation renvoyées par les authentificateurs FIDO lors de la génération de la clé. Ces informations sont potentiellement sensibles et elles sont ignorées par défaut.

LISTES DE RÉVOCATION DE CLÉS
ssh-keygen peut gérer les listes de révocation de clés au format OpenSSH (KRL). Ces fichiers binaires spécifient des clés ou certificats devant être révoqués en utilisant un format compact ne nécessitant pas plus d’un bit par certificat si ce dernier est révoqué en fonction de son numéro de série.

Les KRL peuvent être générées en utilisant l’option -k. Cette option lit un ou plusieurs fichiers spécifiés sur la ligne de commande et génère une nouvelle KRL. Les fichiers peuvent contenir soit une spécification KRL (voir ci-après), soit des clés publiques (une par ligne). Les clés publiques simples sont révoquées en listant leurs hachages ou contenus dans la KRL et les certificats le sont en spécifiant leurs numéros de série ou leurs ID de clé (si le numéro de série est égal à zéro ou indisponible).

Révoquer des clés en utilisant une spécification KRL permet de contrôler explicitement le type d’enregistrement utilisé pour révoquer les clés, et permet de révoquer directement des certificats en fonction de leurs numéros de série ou de leurs ID de clé sans avoir l’ensemble du certificat sous la main. Une spécification KRL se compose de lignes contenant une des directives suivantes suivie d’un deux-points « : » et d’informations spécifiques à la directive.

serial: numéro_série[-numéro_série]
    Révoque le certificat qui possède le numéro de série spécifié. Les numéros de série sont des valeurs différentes de zéro sur 64 bits qui peuvent être exprimées en décimal, en hexadécimal ou en octal. Si deux numéros de série sont spécifiés séparés par un trait d’union, l’intervalle de numéros de série qu’ils composent, bornes comprises, sera révoqué. La clé de CA doit avoir été spécifiée sur la ligne de commande de ssh-keygen à l’aide de l’option -s.

id: ID_clé
    Révoque le certificat possédant la chaîne ID_clé spécifiée. La clé de CA doit avoir été spécifiée sur la ligne de commande de ssh-keygen à l’aide de l’option -s.

key: clé_publique
    Révoque la clé spécifiée. S’il s’agit d’un certificat, il sera révoqué comme une simple clé publique.

sha1: clé_publique
    Révoque la clé spécifiée en incluant son hachage SHA1 dans la KRL.

sha256: clé_publique
    Révoque la clé spécifiée en incluant son hachage SHA256 dans la KRL. Les KRL qui révoquent des clés en fonction de leur hachage SHA256 ne sont pas prises en charge par les versions d’OpenSSH antérieures à 7.9.

hash: empreinte
    Révoque une clé en utilisant un hachage d’empreinte tel qu’obtenu à partir d’un message de journalisation d’authentification de sshd(8) ou à l’aide de l’option -l de ssh-keygen. Seules les empreintes SHA256 sont prises en charge ici et les KRL résultantes ne sont pas prises en charge par les versions d’OpenSSH antérieures à 7.9.

Les KRL peuvent être mises à jour en utilisant l’option -u en plus de l’option -k. Lorsque cette option est utilisée, les clés listées sur la ligne de commande sont fusionnées dans la KRL en s’ajoutant à celles qui y sont déjà.

Il est aussi possible, pour une KRL donnée, de vérifier si elle révoque une ou des clés particulières. L’option -Q permet de questionner une KRL existante en vérifiant chacune des clés spécifiées sur la ligne de commande. Si une clé spécifiée sur la ligne de commande a été révoquée (ou si une erreur se produit), ssh-keygen quittera avec un code de retour différent de zéro. Un code de retour de zéro ne sera renvoyé que si aucune clé n’a été révoquée.

SIGNATAIRES AUTORISÉS
Lors de la vérification des signatures, ssh-keygen utilise une simple liste d’identités et de clés pour déterminer si une signature provient d’une source autorisée. Ce fichier des « signataires autorisés » utilise un format calqué sur le FORMAT DU FICHIER AUTHORIZED_KEYS décrit dans sshd(8). Chaque ligne du fichier contient les champs suivants séparés par des espaces : principals, options, keytype, base64-encoded key. Les lignes vides et les lignes commençant par un « # » sont ignorées et considérées comme des commentaires.

Le champ « principals » est une liste de motifs (voir MOTIFS dans ssh_config(5)) contenant un ou plusieurs motifs d’identité UTILISATEUR@DOMAINE séparés par des virgules et acceptés pour les signatures. Lors de la vérification, l’identité présentée à l’aide de l’option -I doit correspondre à un motif de « principals » pour que la clé correspondante soit considérée comme acceptable pour la vérification.

Le champ options (si présent) contient des spécifications d’option séparées par des virgules. Aucune espace n’est permise, sauf si elle est entourée de guillemets hauts doubles. Les spécifications d’option suivantes sont prises en charge (notez que les noms d’option sont insensibles à la casse) :

cert-authority
    Indique que cette clé est considérée comme une autorité de certification (CA) et que les certificats signés par cette CA peuvent être acceptés pour la vérification.

namespaces=liste_espaces_noms
    Spécifie une liste de motifs d’espaces de noms acceptés pour cette clé. Si cette option est présente, l’espace de noms de signature intégré à l’objet signature et présenté sur la ligne de commande de vérification doit correspondre à la liste spécifiée pour que la clé soit considérée comme acceptable.

valid-after=horodatage
    Indique que la clé est valable à partir de l’horodatage spécifié qui peut être une date ou une heure au format AAAAMMJJ[Z] ou AAAAMMJJHHMM[SS][Z]. Les dates et heures sont interprétées dans le fuseau horaire actuel du système, sauf si elles sont suffixées du caractère « Z », auquel cas elles sont interprétées dans le fuseau horaire UTC.

valid-before=horodatage
    Indique que la clé est valable jusqu’à l’horodatage spécifié.

Lors de la vérification des signatures faites par des certificats, le nom de « principal » attendu doit correspondre à la fois au motif de « principals » enregistré dans le fichier des signataires autorisés et aux « principals » intégrés dans le certificat lui-même.

Un exemple de fichier des signataires autorisés :

    # Commentaires autorisés en début de ligne
    utilisateur1@example.com,utilisateur2@example.com ssh-rsa AAAAX1...
    # Une autorité de certification approuvée pour tous les « principals » d’un domaine.
    *@example.com cert-authority ssh-ed25519 AAAB4...
    # Une clé qui n’est acceptée que pour signer des fichiers.
    utilisateur2@example.com namespaces="fichier" ssh-ed25519 AAA41...

ENVIRONNEMENT

SSH_SK_PROVIDER
    Spécifie le chemin d’une bibliothèque à utiliser pour le chargement des clés hébergées par un authentificateur FIDO, outrepassant ainsi le comportement par défaut consistant à utiliser le support USB HID intégré.

FICHIERS
~/.ssh/id_ecdsa
~/.ssh/id_ecdsa_sk
~/.ssh/id_ed25519
~/.ssh/id_ed25519_sk
~/.ssh/id_rsa
    Ces fichiers contiennent l’identité d’authentification de l’utilisateur ECDSA, ECDSA hébergée par un authentificateur, Ed25519, Ed25519 hébergée par un authentificateur ou RSA. Ces fichiers ne doivent être accessibles en lecture que pour l’utilisateur. Il est possible de spécifier une phrase secrète lors de la génération de la clé ; cette phrase secrète sera utilisée pour chiffrer la partie privée de ce fichier en utilisant l’algorithme AES 128 bits. Ce fichier n’est pas automatiquement consulté par ssh-keygen, mais il correspond au fichier par défaut pour la clé privée. ssh(1) lit ce fichier lorsqu’une tentative de connexion est effectuée.

~/.ssh/id_ecdsa.pub
~/.ssh/id_ecdsa_sk.pub
~/.ssh/id_ed25519.pub
~/.ssh/id_ed25519_sk.pub
~/.ssh/id_rsa.pub
    Ces fichiers contiennent la clé publique d’authentification ECDSA, ECDSA hébergée par un authentificateur, Ed25519, Ed25519 hébergée par un authentificateur ou RSA. Le contenu de ces fichiers doit être ajouté au fichier ~/.ssh/authorized_keys de toutes les machines auxquelles l’utilisateur souhaite se connecter en utilisant une authentification par clé publique. Il n’est pas nécessaire de garder secret le contenu de ce fichier.

/etc/ssh/moduli
    Ce fichier contient les groupes Diffie-Hellman utilisés pour DH-GEX (Diffie-Hellman group exchange). Le format de ce fichier est décrit dans moduli(5).

VOIR AUSSI
ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) RFC 4716, « The Secure Shell (SSH) Public Key File Format », 2006.

AUTEURS
OpenSSH est un dérivé de la version originale et libre 1.2.12 de ssh par Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo de Raadt et Dug Song ont corrigé de nombreux bogues, rajouté de nouvelles fonctionnalités et créé OpenSSH. Markus Friedl a contribué à la prise en charge des versions 1.5 et 2.0 du protocole SSH.

TRADUCTION
La traduction française de cette page de manuel a été créée par Lucien Gentis <lucien.gentis@waika9.com>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3: https://www.gnu.org/licenses/gpl-3.0.html concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.