NAME

github-keygen - bootstrap your GitHub SSH configuration

SYNOPSIS

Unix/Linux/MacOS X:

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

DESCRIPTION

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 github-keygen).

• 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 used to tell 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 (publickey)

  • Use only the private key dedicated to GitHub (the IdentitiesOnly of 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")

  • Disable the UseRoaming option to protect you if ever GitHub (or a MITM) tries to exploit the OpenSSH roaming vulnerability.

• It enables SSH connection sharing (see the ControlMaster option in ssh_config(5) and this blog post)

• 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:

  git@github.com:<repo-owner>/<repo>.git

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

TRUST

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-keygen is 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.

• When running, github-keygen generates 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 --offline flag.

• github-keygen only generates configuration files for OpenSSH. So:

  • After running 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-keygen will 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-keygen is 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.

INSTALL

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.

Windows only: the tool is written in Perl, but you don't have to install StrawberryPerl (or Cygwin or ActivePerl); the perl bundled with msysgit will be automatically detected and used.

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.

UPGRADE

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

HISTORY

Note: As 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.

v1.306

On key creation, switch default key size from 2048 bits to 4096 bits.

Update ~/.ssh/known_hosts_github to include only the ssh-ed25519 public keys of GitHub servers (`ssh-rsa` and `ssh-dss` keys are removed).

Disallow ssh-rsa public keys for GitHub servers.

v1.305

Remove MAC algorithm hmac-ripemd160 as it has been removed from OpenSSH 7.6. It is also not supported by GitHub anymore. Thanks to [Laggard Kernel](https://github.com/laggardkernel) for the patch.

Hide warnings about known deprecated OpenSSH options (Protocol, UseRoaming). We still support them to secure old OpenSSH clients.

v1.304

Remove algorithm diffie-hellman-group14-sha1 as it has been removed server side by GitHub: see https://githubengineering.com/crypto-deprecation-notice/.

v1.303

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.

v1.302

Remove UseRoaming option 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:

• Hide ssh -Q errors (when the option is not supported).

• Do not use %n in ControlPath option.

v1.301

Remove UseRoaming option if OpenSSH >= 7.3 (Mac OS X Sierra, issue #31): this option has been removed from OpenSSH.

v1.300

Keys registered in ~/.ssh/config are now compared with keys registered on GitHub to detect keys unknown to the service. An --offline flag allows to disable this check.

Development is back on master branch (instead of deleted devel).

v1.200

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.

v1.101

Config: set UseRoaming no to protect against the OpenSSH roaming vulnerability.

v1.100

Config: use the official case for the HostName option (instead of Hostname).

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 ControlMaster option 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 aes*-gcm@openssh.com.

Various fixes/workarounds to restore full support of the old SSH (4.6p1) that is bundled with msysgit (Git on Win32).

Store the ControlPath in $XDG_RUNTIME_DIR (see the XDG Base Directory Specification) if available.

Doc fixes: change "Github" to "GitHub".

v1.020

Improve SSH encryption by selecting stronger algorithms recommended by @stribika: aes256-ctr instead of aes128-ctr, and hmac-sha2-512 instead of hmac-sha1.

Open the ~/.ssh/known_hosts_github with mode 0600 before initializing/updating it.

v1.011

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.com for SSH over https port. Add *.ssh.github.com host 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-keygen without repeating the setting. The issue existed since v1.004.

v1.010

Darwin: implemented pasting the public key to the clipboard. Thanks to Vincent Pit for testing!

v1.009

Added support for dashes in GitHub usernames. Thanks Pedro Figueiredo!

v1.008

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.

v1.007

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.

v1.006

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.

v1.005

No functional changes.

Updated Pod::Simple to 3.23. Updated copyright.

v1.004

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 github-keygen!

v1.003

No changes in the github-keygen code, but the fatpacked build has been tweaked to use a better list of packed modules. This should improve compatibility.

Documentation fixes.

v1.002

No functional changes, but distribution changes: branch master abandoned and replaced by release (build result) and devel (source).

github-keygen is now fatpacked from bin/github-keygen in the devel branch 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.

BUGS

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.

Known issues:

• on Win32, ~/.ssh/config is always written in CRLF end-of-line style. This is not a bug, it's a feature.

SUPPORT

IRC: ask dolmen on irc.perl.org.

Or fill an issue at GitHub: https://github.com/dolmen/github-keygen/issues

AUTHOR

Olivier Mengué, mailto:dolmen@cpan.org.

Thanks

Eric Lefevre: documentation patch.

Eu Beng Hee: blog post about SSH connection sharing that inspired changes in 1.008.

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-2022 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/.