377
edits
User:Rominet: Difference between revisions
Jump to navigation
Jump to search
Separate French and English major sections; add Motivation subsection in English
(Add an introduction containing a pointer to the message in the flightgear-devel archive where I described in English the “clone with SSH and update with HTTPS method”) |
(Separate French and English major sections; add Motivation subsection in English) |
||
| Line 7: | Line 7: | ||
Users who are willing to take the time to read moderately technical explanations may be interested in the [[#tutorial-on-ssh-public-key-authentication-and-ssh-agent|tutorial on creating a pair of SSH keys, setting up an SSH agent and using it to do all Git transfers with the SSH protocol]] (in French). This is an alternate method, is quite secure and convenient when set up, but requires users to understand a few technical points regarding SSH public key authentication. They are all explained below, though, for those who are ready to read carefully. | Users who are willing to take the time to read moderately technical explanations may be interested in the [[#tutorial-on-ssh-public-key-authentication-and-ssh-agent|tutorial on creating a pair of SSH keys, setting up an SSH agent and using it to do all Git transfers with the SSH protocol]] (in French). This is an alternate method, is quite secure and convenient when set up, but requires users to understand a few technical points regarding SSH public key authentication. They are all explained below, though, for those who are ready to read carefully. | ||
== Vocabulaire technique français/anglais == | == English == | ||
=== Motivation === | |||
A Git client can use various protocols to communicate with a remote server: the old <tt>git</tt> protocol, <tt>https</tt> as well as <tt>ssh</tt>. When one runs a command such as | |||
git clone ssh://... | |||
or | |||
git clone https://... | |||
the word preceding <tt>://</tt> tells the Git client which protocol to use to communicate with the remote server. | |||
Pros and cons of each of these protocols: | |||
* With the old <tt>git</tt> protocol, data is '''not encrypted''' and there is '''no authentication''' to guarantee that the remote computer is really the one you intended to contact. This implies in particular that malicious actors who can intercept and inject packets between your computer and the legitimate server can make you download what ''they'' want, instead of what the legitimate server would normally have sent (this is called a ''man-in-the-middle attack).'' This risk is partially mitigated in the particular case of Git, at the condition that after every update performed using the unsafe <tt>git</tt> protocol, you double-check from a known-good source that the last commit identifier you got for each branch of the downloaded repository is the same as on the legitimate server. Needless to say, nobody does that. Besides, the SHA-1 algorithm that Git uses to compute commit identifiers has been somewhat weakened during the last years<ref name="en-Google-work-on-SHA-1">See for instance this [https://security.googleblog.com/2017/02/announcing-first-sha1-collision.html Google report].</ref>; therefore, even if it's not the case at the time of this writing, one can't dismiss the possibility that at some point in the future, “bad guys” be able to prepare malicious commits having the same identifier as one of the commits of the legitimate repository. For these reasons (especially the possibility of a man-in-the-middle attack), it is a good idea to avoid using the obsolete <tt>git</tt> protocol. In other words, don't use <tt>git://</tt> when you clone a Git repository. | |||
* With the <tt>https</tt> protocol, all transferred data is '''encrypted''' and, more importantly here, the server you connect to is '''authenticated.''' The main problem here is that this protocol is not well implemented at [https://sourceforge.net/ SourceForge]: cloning a large repository such as [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData] using <tt>https</tt> (almost?) always fails. As far as I know, this problem doesn't happen with smaller repositories, nor does it happen when simply updating a large one that has already been cloned (it is indeed possible to clone a repository with a given protocol and later update it using another protocol; all one has to do for that is to modify the <tt>.git/config</tt> file inside the repository—this is precisely the method we are going to describe next, step by step). | |||
* With the <tt>ssh</tt> protocol, all transferred data is '''encrypted''' and the server you connect to is '''authenticated''' (this is done differently, but offers similar guarantees as the <tt>https</tt> protocol). The main problem in this case, which is generally a minor one, is that in order to download via the <tt>ssh</tt> protocol, you have to authenticate ''yourself'' to the server (in contrast with <tt>https</tt>, which allows anonymous downloads). This requires you to either enter a password or to use a (public, private) pair of SSH keys—the latter method being called ''public key authentication.'' On the other hand, getting yourself authenticated to the server is an advantage for development, because this allows server administrators to possibly grant you write access to the repository, should you be able and willing to contribute to the project (i.e., administrators could then allow you to run commands such as <code>git push</code> that update the remote repository). | |||
When <tt>download_and_compile.sh</tt> clones a new repository, it uses by default the <tt>https</tt> protocol. This works fine except for [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData], for the reasons we have just explained (very large repository, transfer problems with SourceForge). Since using the <tt>git</tt> protocol is not an acceptable solution either, I recommend to clone the FGData repository using the <tt>ssh</tt> protocol. FGData can then be updated using <tt>https</tt>, and other repositories can be cloned as well as updated using <tt>https</tt>. The next section will explain step by step how to do that. | |||
Another option is to use the <tt>ssh</tt> protocol in all cases. If you use an SSH agent in conjunction with public key authentication, this is quite a fine solution. But in case you don't, this method would require you to enter your SourceForge password every time a Git command needs to contact the remote server—assuming all repositories you work with are hosted there, which is the case for the FlightGear core repositories. Needless to say, this would be quite cumbersome unless you rarely interact with the remote server. Since setting up public key authentication requires more learning and work for users who are not already familiar with it, we are going to present the easier method here: using the <tt>ssh</tt> protocol for cloning [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData] (i.e., ''only for the initial download)'' and <tt>https</tt> for all other communications initiated by the Git client on your computer. For those interested, the method based on public key authentication is explained in detail in French [[#tutorial-on-ssh-public-key-authentication-and-ssh-agent|on this very page]]. | |||
=== Getting started with <tt>download_and_compile.sh</tt> === | |||
To be completed. In the mean time, see [https://sourceforge.net/p/flightgear/mailman/message/36633375/ this message] on the flightgear-devel mailing list (which should be fine!). | |||
== Français == | |||
=== Vocabulaire technique français/anglais === | |||
;authentification (authentication) | ;authentification (authentication) | ||
| Line 21: | Line 46: | ||
: Ensemble de fichiers et répertoires avec des métadonnées permettant de reconstituer toutes les versions antérieures « enregistrées » de chacun des fichiers. On peut obtenir une copie locale d'un dépôt existant en faisant <code>git clone ''adresse_du_dépôt_source''</code>. L'opération de clonage est donc ''la première'' qui amène un dépôt donné sur votre système (disque dur, etc.). Une fois un dépôt cloné, on peut le mettre à jour avec des commandes telles que <code>git pull --rebase</code>. Si vous utilisez <tt>download_and_compile.sh</tt>, c'est lui qui se charge d'appeler Git avec les commandes adéquates pour cloner et mettre à jour. Il ne vous reste qu'à choisir le protocole à utiliser ; ce qui suit devrait vous aider dans ce choix. | : Ensemble de fichiers et répertoires avec des métadonnées permettant de reconstituer toutes les versions antérieures « enregistrées » de chacun des fichiers. On peut obtenir une copie locale d'un dépôt existant en faisant <code>git clone ''adresse_du_dépôt_source''</code>. L'opération de clonage est donc ''la première'' qui amène un dépôt donné sur votre système (disque dur, etc.). Une fois un dépôt cloné, on peut le mettre à jour avec des commandes telles que <code>git pull --rebase</code>. Si vous utilisez <tt>download_and_compile.sh</tt>, c'est lui qui se charge d'appeler Git avec les commandes adéquates pour cloner et mettre à jour. Il ne vous reste qu'à choisir le protocole à utiliser ; ce qui suit devrait vous aider dans ce choix. | ||
== Motivation == | === Motivation === | ||
Git peut utiliser divers protocoles pour communiquer avec le serveur : le vieux protocole <tt>git</tt>, le protocole <tt>https</tt> ainsi que <tt>ssh</tt>. Quand on fait quelque chose comme | Git peut utiliser divers protocoles pour communiquer avec le serveur : le vieux protocole <tt>git</tt>, le protocole <tt>https</tt> ainsi que <tt>ssh</tt>. Quand on fait quelque chose comme | ||
git clone ssh://... | |||
ou | |||
git clone https://... | |||
le mot précédant <tt>://</tt> indique quel protocole Git doit utiliser. | le mot précédant <tt>://</tt> indique quel protocole Git doit utiliser. | ||
| Line 43: | Line 69: | ||
Plutôt que d'envoyer son mot de passe SourceForge au serveur par SSH, il y a une autre manière de prouver à SourceForge que vous êtes bien l'utilisateur ''username'' : elle utilise la cryptographie asymétrique, autrement dit une paire de clés (privée, publique) au lieu d'un mot de passe. Cette méthode est sûre et permet de n'entrer le mot de passe de votre clé privée<ref name="ne-pas-confondre-mdp-clé-privée-et-mdp-compte-SourceForge">À ne pas confondre avec le mot de passe de votre compte chez SourceForge !</ref> qu'une fois pour tous les dépôts, jusqu'à ce que vous éteigniez votre ordinateur<ref name="condition-de-cession-des-clés-par-l'agent-SSH">Pour simplifier : nous donnerons des conditions plus précises ci-dessous.</ref>, ou jusqu'à épuisement d'un certain temps, ou encore jusqu'à ce que vous décidiez de mettre fin à la « mémorisation » de votre clé par l'agent SSH (notion qui sera présentée plus loin). Le but de la section suivante est de vous apprendre à mettre en place cette méthode d'authentification sûre et pratique, qui est valable dans le cadre général de l'utilisation de SSH. | Plutôt que d'envoyer son mot de passe SourceForge au serveur par SSH, il y a une autre manière de prouver à SourceForge que vous êtes bien l'utilisateur ''username'' : elle utilise la cryptographie asymétrique, autrement dit une paire de clés (privée, publique) au lieu d'un mot de passe. Cette méthode est sûre et permet de n'entrer le mot de passe de votre clé privée<ref name="ne-pas-confondre-mdp-clé-privée-et-mdp-compte-SourceForge">À ne pas confondre avec le mot de passe de votre compte chez SourceForge !</ref> qu'une fois pour tous les dépôts, jusqu'à ce que vous éteigniez votre ordinateur<ref name="condition-de-cession-des-clés-par-l'agent-SSH">Pour simplifier : nous donnerons des conditions plus précises ci-dessous.</ref>, ou jusqu'à épuisement d'un certain temps, ou encore jusqu'à ce que vous décidiez de mettre fin à la « mémorisation » de votre clé par l'agent SSH (notion qui sera présentée plus loin). Le but de la section suivante est de vous apprendre à mettre en place cette méthode d'authentification sûre et pratique, qui est valable dans le cadre général de l'utilisation de SSH. | ||
==<span id="tutorial-on-ssh-public-key-authentication-and-ssh-agent"></span> Authentification SSH par paire de clés privée/publique == | ===<span id="tutorial-on-ssh-public-key-authentication-and-ssh-agent"></span> Authentification SSH par paire de clés privée/publique === | ||
À l'exception des manipulations effectuées sur les pages web de [https://sourceforge.net/ SourceForge], ce qui suit est valable pour toute connexion entre un client et un serveur SSH. Si l'accent est mis sur [https://sourceforge.net/ SourceForge] dans ce document, c'est pour pouvoir donner des exemples concrets et parce qu'il s'adresse en priorité aux personnes souhaitant compiler FlightGear ; or les dépôts concernés, essentiellement [https://sourceforge.net/p/flightgear/simgear/ci/next/tree/ SimGear], [https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/ FlightGear] et [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData], sont tous situés chez SourceForge. | À l'exception des manipulations effectuées sur les pages web de [https://sourceforge.net/ SourceForge], ce qui suit est valable pour toute connexion entre un client et un serveur SSH. Si l'accent est mis sur [https://sourceforge.net/ SourceForge] dans ce document, c'est pour pouvoir donner des exemples concrets et parce qu'il s'adresse en priorité aux personnes souhaitant compiler FlightGear ; or les dépôts concernés, essentiellement [https://sourceforge.net/p/flightgear/simgear/ci/next/tree/ SimGear], [https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/ FlightGear] et [https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/ FGData], sont tous situés chez SourceForge. | ||
| Line 284: | Line 310: | ||
</ol> | </ol> | ||
==<span id="alternate-method-clone-with-ssh-and-update-with-https"></span> Autre méthode : clonage avec SSH et mises à jour avec HTTPS == | ===<span id="alternate-method-clone-with-ssh-and-update-with-https"></span> Autre méthode : clonage avec SSH et mises à jour avec HTTPS === | ||
Voici une autre méthode pour obtenir et mettre à jour de manière sûre les dépôts avec <tt>download_and_compile.sh</tt> : | Voici une autre méthode pour obtenir et mettre à jour de manière sûre les dépôts avec <tt>download_and_compile.sh</tt> : | ||