github-keygen - bootstrap your GitHub SSH configuration
git clone https://github.com/dolmen/github-keygen.git cd github-keygen ./github-keygen <my-github-username> cd .. rm -Rf github-keygen
Windows (with msysgit or Cygwin):
git clone https://github.com/dolmen/github-keygen.git cd github-keygen github-keygen <my-github-username> cd .. rd /S /Q github-keygen
This script makes it easy to create an initial environment setup for secure GitHub exchanges. More secure that what the GitHub help pages recommends.
But it does much more than that:
This tool automates the SSH setup. Fewer human errors. And a high level of security.
It creates a new SSH private key dedicated to GitHub exchanges. This is much better than using the same SSH key to connect to multiple hosts. (If you lose that key, just revoke it in your GitHub account SSH settings, remove the key file, and re run
As the process of creating an different SSH key for GitHub now becomes easy, it is now much easier to use a different SSH key for GitHub on each computer you use to publish on GitHub. This will help you to use the best practices in SSH security. (If you lose that computer or if it is compromised, just revoke the key in your GitHub account SSH settings: you don't have to recreate a new key on all your other computers).
The GitHub manual tells to remove your existing SSH keys. But this may not be what you want. This tool avoids that: keep your keys and your existing SSH config; they will not be used for GitHub.
It setups a very secure SSH configuration for GitHub, independent of your other SSH settings:
Enable only the authentication method used with GitHub (
Use only the private key dedicated to GitHub (the
IdentitiesOnlyof SSH config)
Setup a dedicated known_hosts file with the GitHub SSH hosts and enable strict host checking (this means that if you get SSH alerts about host key problem when connecting to GitHub, this is really a serious error and you should check that someone is not altering your network link).
Use stronger encryption algorithms than your default SSH setup (following @stribika advices; this is a "best effort" that depends on your OpenSSH being recent enough);
Disable bad things that could come from the GitHub hosts ("Trust no-one")
UseRoamingoption to protect you if ever GitHub (or a MITM) tries to exploit the
It creates unique host aliases for github.com/gist.github.com that you'll be able to use in Git URLs (
git remote) to connect to a particular account. This gives the flexibility to use multiple GitHub accounts (and therefore a different SSH key for each).
<account>.github.com:<repo-owner>/<repo>.git (for each account) github.com:<repo-owner>/<repo>.git (for the default account)
in addition to:
This script will:
Create a new SSH key dedicated only to your GitHub connections in ~/.ssh/id_<github-account>@github
Create the SSH configuration optimized for GitHub and dedicated to GitHub (does not impact your other SSH configurations) in ~/.ssh/config.
Install the GitHub SSH host authentication fingerprints in ~/.ssh/known_hosts_github
As with any software that deals with the security of your computer or of communications with other computers (operating system, anti-virus, HTTPS implementation, password storage...), you have to be able to trust it. (If you haven't ever asked yourself that question about the software you already use, you should!)
Here are some arguments that should help you to make your choice:
github-keygenis written in a scripting language (Perl 5), so the code that runs is the code in the script. You can audit it (or ask someone who you trust to do it for you) to trust it. The author is a full time professional Perl developer who is well aware of all Perl best practices and works daily on Perl code maintained by a team, so the source is not the spaghetti plate for which Perl 5 got shame.
github-keygengenerates files locally on your system. It connects to github.com using public URLs only to check if your keys are properly setup on the server side. You can disable this feature with the
github-keygenonly generates configuration files for OpenSSH. So:
github-keygen, you can (and should) audit that config to check the changes it did to your system before connecting to any SSH hosts.
No part of that configuration is directly executable: it is just data that OpenSSH will use.
No executable parts of
github-keygenwill run after that (the tool itself is not installed in your system) and you can even delete it: the configuration it produced will still work.
github-keygenis very conservative in what it does to your SSH config (which means it will not corrupt what it didn't generate itself), so don't worry about configuration you may already have in your ~/.ssh/config: it will be kept as is. (still, bugs may be present, so read the license before using the software).
I (Olivier Mengué) am not an expert in software security. However this list should show you that I care enough about security to have thought about many issues, and thought to design the software to have trust in it at least as much (in fact much more) than in other security software I use every day.
I'm using the SSH configuration generated by this tool every day on multiple computers, so you can trust that any change on GitHub side that may affect that config will be immediately detected by the author and upgrades will be made available quickly.
github-keygen is not really the kind of software you have to install. This is more like a wizard that you use just once. So just get the file, run it, and delete it.
Fetch the script from GitHub:
git clone https://github.com/dolmen/github-keygen.git cd github-keygen
Unix/Linux only: install the optional
xclip tool (using your package manager). It will be used to copy your public key to the X11 clipboard once created.
To upgrade your config to the latest one, update
github-keygen and relaunch it. It will update your ~/.ssh/config and show you the diff of what it changed:
cd github-keygen git rebase ./github-keygen
github-keygen is released with Git on GitHub, you can simply use the diff feature of Git/GitHub to view exactly what happened between two releases. And you can also have a look at the commit log.
diffie-hellman-group14-sha1as it has been removed server side by GitHub: see https://githubengineering.com/crypto-deprecation-notice/.
Fix SSH options and algorithm support detection that was accidentally disabled since v1.100. This makes github-keygen work with OpenSSH 7.6+ that removed an algorithm.
Fix for support of OpenSSH down to 5.1.
Detect bad permissions on ~/.ssh/config and report them.
UseRoamingoption if OpenSSH >= 7.2 on Mac OS X Sierra (issue #31): Sierra has 7.2p2, same as on Ubuntu 16.04, but not same behaviour.
Old OpenSSH compatibility fixes:
ssh -Qerrors (when the option is not supported).
Do not use
UseRoamingoption if OpenSSH >= 7.3 (Mac OS X Sierra, issue #31): this option has been removed from OpenSSH.
Keys registered in ~/.ssh/config are now compared with keys registered on GitHub to detect keys unknown to the service. An
--offlineflag allows to disable this check.
Development is back on
masterbranch (instead of deleted
Add versioning to the generated config. This will allow to detect dangerous attempts at downgrading to an older version of github-keygen.
Preserve the position of the github-keygen section in ~/.ssh/config. Previously, the section was always put at the end of the file. This was breaking configs were the user had a
Host *section at the end of the file to set default settings: as the section was moved above us, those default settings were applied before our own.
UseRoaming noto protect against the
Config: use the official case for the
HostNameoption (instead of
For the best compatibility of the SSH configuration with old SSH versions, we now look in the ssh_config(5) man page for the list of supported options and unavailable options are then commented with '##'. If the man page is not found, we still use all options.
On msys platform (bash in msysgit), the
ControlMasteroption of OpenSSH doesn't work because msys lacks support for passing file descriptors. So we now disable this option on this platform.
We filter our lists of algorithms against the lists reported by
ssh -Q <cipher|mac|kex>. This restores compatibility with OpenSSH versions such as 6.6.1p1 bundled with msysgit that does not support ciphers named
Various fixes/workarounds to restore full support of the old SSH (4.6p1) that is bundled with msysgit (Git on Win32).
$XDG_RUNTIME_DIR(see the XDG Base Directory Specification) if available.
Doc fixes: change "Github" to "GitHub".
Improve SSH encryption by selecting stronger algorithms recommended by @stribika:
Open the ~/.ssh/known_hosts_github with mode 0600 before initializing/updating it.
Create ~/.ssh with rights 0700 if it doesn't exists because ssh-keygen(1) will fail if it is missing.
Add support for host
ssh.github.comfor SSH over https port. Add
*.ssh.github.comhost aliases for Git. Users should run again
github-keygen(without argument) to enable those new features.
Fixed issue #13: default GitHub account set with `--default` option was lost when running again
github-keygenwithout repeating the setting. The issue existed since v1.004.
Darwin: implemented pasting the public key to the clipboard. Thanks to Vincent Pit for testing!
Added support for dashes in GitHub usernames. Thanks Pedro Figueiredo!
Added connection sharing: connection to GitHub is kept alive for 60 seconds. This speeds-up any script that do multiple sequential Git interactions with GitHub.
Fixed a message that wrongly told to paste the private key (
'.pub'forgotten). Fixed at the Quack and Hack 2012 Europe hackathon, but released (too) long later.
UI improvement: when keys are created, the message about what to do with the key is now shown at the end, after the diff instead of before.
No functional changes.
Updated Pod::Simple to 3.23. Updated copyright.
Changes for compatibility with msysgit's bundled perl (an antique 5.8.8 with major core modules missing:
Pod::*). So no changes for Unix users, but a big improvement for all Windows+msysgit users: no need to install StrawberryPerl just for
No changes in the
github-keygencode, but the fatpacked build has been tweaked to use a better list of packed modules. This should improve compatibility.
No functional changes, but distribution changes: branch
masterabandoned and replaced by
release(build result) and
github-keygenis now fatpacked from
develbranch with https://metacpan.org/module/Pod::Usage|Pod::Usage and https://metacpan.org/module/Text::Diff|Text::Diff, so those modules do not have to be installed before usage.
- v1.001 and before
See the git log.
github-keygen requires a Perl runtime. It is regularly tested in the following environments:
Ubuntu with perl 5.14.2
Windows with StrawberryPerl (5.12.1 and above) and msysgit
Windows with msysgit's antique perl 5.8.8.
on Win32, ~/.ssh/config is always written in CRLF end-of-line style. This is not a bug, it's a feature.
Or fill an issue at GitHub: https://github.com/dolmen/github-keygen/issues
Olivier Mengué, mailto:email@example.com.
Eric Lefevre: documentation patch.
Pedro Figueiredo: support for GitHub account with dashes (v1.009).
If you want to contribute, have a look to CONTRIBUTING.pod.
COPYRIGHT & LICENSE
Copyright © 2011-2018 Olivier Mengué.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.