NAME

=pod

=encoding utf8

=for stopwords MITM versioning

=head1 NAME

github-keygen - bootstrap and manage your SSH configuration for GitHub

=head1 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

=head1 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:

=over 4

=item *

This tool B. Fewer human errors. And a high level of security.

=item *

It creates a new SSH B 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 L<your GitHub account SSH settings|https://github.com/settings/keys>, remove the key file, and re run C).

=item *

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 L<your GitHub account SSH settings|https://github.com/settings/keys>: you don't have to recreate a new key on all your other computers).

=item *

The L<GitHub manual|https://help.github.com/articles/generating-ssh-keys> used to tell to I 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.

=item *

It setups a B, independent of your other SSH settings:

=over 4

=item *

Enable only the authentication method used with GitHub (C)

=item *

Use only the private key dedicated to GitHub (the C of SSH config)

=item *

Setup a dedicated F 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).

=item *

Use stronger encryption algorithms than your default SSH setup (following L<@stribika advices|https://stribika.github.io/2015/01/04/secure-secure-shell.html>; this is a "best effort" that depends on your OpenSSH being recent enough), including post-quantum algorithms;

=item *

Disable bad things that could come from the GitHub hosts ("Trust no-one")

=item *

Disable the C option to protect you if ever GitHub (or a MITM) tries to exploit the L<C vulnerability|https://www.openssh.com/txt/release-7.1p2>.

=back

=item *

It enables SSH connection sharing (see the C option in L<ssh_config(5)> and L<this blog post|http://interrobeng.com/2013/08/25/speed-up-git-5x-to-50x/>)

=item *

It creates unique host aliases for github.com/gist.github.com that you'll be able to use in Git URLs (C) to connect to a particular account. This gives the flexibility to use B (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

=back

This script will:

=over 4

=item *

Create a new SSH key dedicated only to your GitHub connections in F<~/.ssh/id_I<Egithub-accountE>@github>

=item *

Create the SSH configuration optimized for GitHub and dedicated to GitHub (does not impact your other SSH configurations) in F<~/.ssh/config>.

=item *

Install the GitHub SSH host authentication fingerprints in F<~/.ssh/known_hosts_github>

=back

=head1 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:

=over 4

=item *

C 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.

=item *

When running, C 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 C<--offline> flag.

=item *

C only generates configuration files for OpenSSH. So:

=over 4

=item *

After running C, you can (and should) audit that config to check the changes it did to your system before connecting to any SSH hosts.

=item *

No part of that configuration is directly executable: it is just data that OpenSSH will use.

=item *

No executable parts of C 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.

=back

=item *

C 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 F<~/.ssh/config>: it will be kept as is. (still, bugs may be present, so read the license before using the software).

=item *

I (Olivier MenguE) 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.

=back

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.

=head1 INSTALL

C 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.

I: the tool is written in Perl, but you don't have to install L<StrawberryPerl|https://strawberryperl.com> (or Cygwin or ActivePerl); the perl bundled with L<msysgit|https://gitforwindows.org/> 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 C tool (using your package manager). It will be used to copy your public key to the X11 clipboard once created.

=head1 UPGRADE

To upgrade your config to the latest one, update C and relaunch it. It will update your F<~/.ssh/config> and show you the diff of what it changed:

cd github-keygen
git rebase
./github-keygen

=head1 HISTORY

INote: As C 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 L<the commit log|https://github.com/dolmen/github-keygen/commits/release>.

=over 4

=item v1.401

Update key exchange algorithms:

=over 4

=item *

Add C, an hybrid post-quantum algorithm which the new default in L<OpenSSH 10.0|https://www.openssh.com/txt/release-10.0>. However GitHub doesn't yet support it server side.

=item *

Add C, the official (IANA) alias of Ccurve25519-sha256@libssh.org that was already used.

=item *

Remove C which isn't anymore supported by GitHub.

=back

Force option C to I. Because the SSH connections are only used for non-interactive use via Git.

On Windows:

=over 4

=item *

Disable C, C, C to avoid failure "I".

=item *

In ssh config, save paths to files using C<%d> instead of C<~> to workaround an issue in OpenSSH with tilde expansion when paths use backslashes.

=back

Thanks to L<@agnosticlines|https://github.com/agnosticlines> for contributions.

=item L<v1.400|https://github.com/dolmen/github-keygen/compare/v1.306...v1.400>

Change default key type on key creation to C (previously C) (L<GitHub #48|https://github.com/dolmen/github-keygen/issues/48>).

On key creation, custom key comment provided by C<-C> was ignored (L<GitHub #46|https://github.com/dolmen/github-keygen/issues/46>). This is fixed. Thanks to L<@tinhtruong|https://github.com/tinhtruong> for the report.

Fix typo in a comment in F<~/.ssh/config>: "I".

Improve Windows compatibility (fix in parsing of C<ssh -V>).

=item L<v1.306|https://github.com/dolmen/github-keygen/compare/v1.305...v1.306>

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

Update C<~/.ssh/known_hosts_github> to include only the C public keys of GitHub servers (C and C keys are removed).

Disallow C public keys for GitHub servers.

=item L<v1.305|https://github.com/dolmen/github-keygen/compare/v1.304...v1.305>

Remove MAC algorithm C as it has been L<removed from OpenSSH 7.6|https://www.openssh.com/txt/release-7.6>. It is also not supported by GitHub anymore. Thanks to L<Laggard Kernel|https://github.com/laggardkernel> for the patch.

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

=item L<v1.304|https://github.com/dolmen/github-keygen/compare/v1.303...v1.304>

Remove algorithm C as it has been removed server side by GitHub: see Lhttps://githubengineering.com/crypto-deprecation-notice/.

=item L<v1.303|https://github.com/dolmen/github-keygen/compare/v1.302...v1.303>

Fix SSH options and algorithm support detection that was accidentally disabled since v1.100. This makes github-keygen work with L<OpenSSH 7.6+|https://www.openssh.com/txt/release-7.6> that removed an algorithm.

Fix for support of OpenSSH down to 5.1.

Detect bad permissions on F<~/.ssh/config> and report them.

=item L<v1.302|https://github.com/dolmen/github-keygen/compare/v1.301...v1.302>

Remove C option if OpenSSH >= 7.2 on Mac OS X Sierra (L<issue #31|https://github.com/dolmen/github-keygen/issues/31>): Sierra has L<7.2p2|https://www.openssh.com/txt/release-7.2p2>, same as on Ubuntu 16.04, but not same behaviour.

Old OpenSSH compatibility fixes:

=over 4

=item *

Hide C<ssh -Q> errors (when the option is not supported).

=item *

Do not use C<%n> in C option.

=back

=item L<v1.301|https://github.com/dolmen/github-keygen/compare/v1.300...v1.301>

Remove C option if OpenSSH >= L<7.3|https://www.openssh.com/txt/release-7.3> (Mac OS X Sierra, L<issue #31|https://github.com/dolmen/github-keygen/issues/31>): this option has been removed from OpenSSH.

=item L<v1.300|https://github.com/dolmen/github-keygen/compare/v1.200...v1.300>

Keys registered in F<~/.ssh/config> are now compared with keys registered on L<GitHub|https://github.com/settings/keys> to detect keys unknown to the service. An C<--offline> flag allows to disable this check.

Development is back on C branch (instead of deleted C).

=item L<v1.200|https://github.com/dolmen/github-keygen/compare/v1.101...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 F<~/.ssh/config>. Previously, the section was always put at the end of the file. This was breaking configs were the user had a C<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.

=item L<v1.101|https://github.com/dolmen/github-keygen/compare/v1.100...v1.101>

Config: set C to protect against the L<C vulnerability|https://www.openssh.com/txt/release-7.1p2>.

=item L<v1.100|https://github.com/dolmen/github-keygen/compare/v1.020...v1.100>

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

For the best compatibility of the SSH configuration with old SSH versions, we now look in the L<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 L<msysgit|https://gitforwindows.org/>), the C 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 L<lists of algorithms|https://stribika.github.io/2015/01/04/secure-secure-shell.html> against the lists reported by C<ssh -Q Ecipher|mac|kexE>. This restores compatibility with OpenSSH versions such as 6.6.1p1 bundled with msysgit that does not support ciphers named Caes*-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 C in C<$XDG_RUNTIME_DIR> (see the L<XDG Base Directory Specification|https://specifications.freedesktop.org/basedir-spec/latest/#variables>) if available.

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

=item L<v1.020|https://github.com/dolmen/github-keygen/compare/v1.011...v1.020>

B by selecting L<stronger algorithms recommended by @stribika|https://stribika.github.io/2015/01/04/secure-secure-shell.html>: C instead of C, and C instead of C.

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

=item L<v1.011|https://github.com/dolmen/github-keygen/compare/v1.010...v1.011>

Create F<~/.ssh> with rights 0700 if it doesn't exists because L<ssh-keygen(1)> will fail if it is missing.

Add support for host C<ssh.github.com> for L<SSH over https port|https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port>. Add C<*.ssh.github.com> host aliases for Git. Users should run again C (without argument) to enable those new features.

Fixed L<issue #13|https://github.com/dolmen/github-keygen/issues/13>: default GitHub account set with --default option was lost when running again C without repeating the setting. The issue existed since v1.004.

=item L<v1.010|https://github.com/dolmen/github-keygen/compare/v1.009...v1.010>

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

=item L<v1.009|https://github.com/dolmen/github-keygen/compare/v1.008...v1.009>

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

=item L<v1.008|https://github.com/dolmen/github-keygen/compare/v1.007...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.

=item L<v1.007|https://github.com/dolmen/github-keygen/compare/v1.006...v1.007>

Fixed a message that wrongly told to paste the I key (C<'.pub'> forgotten). Fixed at the L<Quack and Hack 2012 Europe hackathon|https://act.yapc.eu/qh2012eu/>, but released (too) long later.

=item L<v1.006|https://github.com/dolmen/github-keygen/compare/v1.005...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.

=item L<v1.005|https://github.com/dolmen/github-keygen/compare/v1.004...v1.005>

No functional changes.

Updated Pod::Simple to 3.23. Updated copyright.

=item L<v1.004|https://github.com/dolmen/github-keygen/compare/v1.003...v1.004>

Changes for compatibility with msysgit's bundled perl (an antique 5.8.8 with major core modules missing: CPod::*). So no changes for Unix users, but a big improvement for all Windows+msysgit users: no need to install StrawberryPerl just for C!

=item L<v1.003|https://github.com/dolmen/github-keygen/compare/v1.002...v1.003>

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

Documentation fixes.

=item L<v1.002|https://github.com/dolmen/github-keygen/compare/v1.001...v1.002>

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

C is now L<fatpacked|https://metacpan.org/module/App::FatPacker> from C<bin/github-keygen> in the C branch with Lhttps://metacpan.org/module/Pod::Usage|Pod::Usage and Lhttps://metacpan.org/module/Text::Diff|Text::Diff, so those modules do not have to be installed before usage.

=item v1.001 and before

See the git log.

=back

=head1 BUGS

C requires a Perl runtime. It is regularly tested in the following environments:

=over 4

=item *

Ubuntu 24.04

=item *

MacOS with perl 5.40.2 and OpenSSH 9.7

=item *

Windows with StrawberryPerl (5.12.1 and above) and msysgit

=item *

Windows with perl and OpenSSH bundled with L<Git for Windows|https://gitforwindows.org>

=back

Known issues:

=over 4

=item *

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

=back

=head1 SUPPORT

Fill an issue at GitHub: Lhttps://github.com/dolmen/github-keygen/issues.

Check the L<the contributor's documentation|CONTRIBUTING.pod> I writing patches.

=head1 AUTHOR

Olivier MenguE, Lmailto:dolmen@cpan.org.

=head2 Thanks

L<Eric Lefevre|https://github.com/elefevre>: documentation patch.

L<Eu Beng Hee|https://github.com/ahbeng>: L<blog post about SSH connection sharing|http://interrobeng.com/2013/08/25/speed-up-git-5x-to-50x/> that inspired changes in 1.008.

L<Pedro Figueiredo|https://github.com/pfig>: support for GitHub account with dashes (v1.009).

If you want to contribute, have a look to L<CONTRIBUTING.pod>.

=head1 COPYRIGHT & LICENSE

Copyright E 2011-2025 Olivier MenguE.

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 Lhttps://www.gnu.org/licenses/.

=cut