Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dolmen/github-keygen

Easy creation of secure SSH configuration for your GitHub account(s)
https://github.com/dolmen/github-keygen

cli-app github ssh ssh-client ssh-config tool

Last synced: about 2 months ago
JSON representation

Easy creation of secure SSH configuration for your GitHub account(s)

Awesome Lists containing this project

README 

        
=pod



=for stopwords MITM versioning



=head1 NAME



github-keygen - bootstrap your GitHub SSH configuration



=head1 SYNOPSIS



Unix/Linux/MacOS X:



    git clone https://github.com/dolmen/github-keygen.git

    cd github-keygen

    ./github-keygen 

    cd ..

    rm -Rf github-keygen



Windows (with msysgit or Cygwin):



    git clone https://github.com/dolmen/github-keygen.git

    cd github-keygen

    github-keygen 

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

you don't have to recreate a new key on all your other computers).



=item *



The

L 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);



=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 vulnerability|http://www.openssh.com/txt/release-7.1p2>.



=back



=item *



It enables SSH connection sharing (see the C option in

L and L)



=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).



    .github.com:/.git  (for each account)

    github.com:/.git            (for the default account)



in addition to:



    [email protected]:/.git



=back



This script will:



=over 4



=item *



Create a new SSH key dedicated only to your GitHub connections in

F<~/.ssh/id_Igithub-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 (or Cygwin or ActivePerl); the perl

bundled with L 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



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



=over 4



=item 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 (`ssh-rsa` and `ssh-dss` keys are removed).



Disallow C public keys for GitHub servers.



=item v1.305



Remove MAC algorithm C as it has been

L.

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 (C, C).

We still support them to secure old OpenSSH clients. 



=item v1.304



Remove algorithm C as it has been removed server side

by GitHub: see L.



=item 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 F<~/.ssh/config> and report them.



=item v1.302



Remove C option if OpenSSH >= 7.2 on Mac OS X Sierra

(L): Sierra

has 7.2p2, same as on Ubuntu 16.04, but not same behaviour.



Old OpenSSH compatibility fixes:



=over 4



=item *



Hide C errors (when the option is not supported).



=item *



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



=back



=item v1.301



Remove C option if OpenSSH >= 7.3

(Mac OS X Sierra,

L):

this option has been removed from OpenSSH.



=item v1.300



Keys registered in F<~/.ssh/config> are now compared with keys registered on

L 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 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 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 v1.101



Config: set C to protect against the

L vulnerability|http://www.openssh.com/txt/release-7.1p2>.



=item 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 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), 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

against the lists reported by Ccipher|mac|kexE>. This restores

compatibility with OpenSSH versions such as 6.6.1p1 bundled with msysgit

that does not support ciphers named C.



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)

if available.



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



=item v1.020



B by selecting L:

C instead of C, and C instead of C.



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

initializing/updating it.



=item v1.011



Create F<~/.ssh> with rights 0700 if it doesn't exists because L

will fail if it is missing.



Add support for host C for

L.

Add C<*.ssh.github.com> host aliases for Git.

Users should run again C (without argument) to enable those new

features.



Fixed L: default

GitHub account set with `--default` option was lost when running again

C without repeating the setting. The issue existed since v1.004.



=item v1.010



Darwin: implemented pasting the public key to the clipboard. Thanks to Vincent

Pit for testing!



=item v1.009



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



=item 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 v1.007



Fixed a message that wrongly told to paste the I key (C<'.pub'>

forgotten). Fixed at the

L,

but released (too) long later.



=item 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 v1.005



No functional changes.



Updated Pod::Simple to 3.23. Updated copyright.



=item v1.004



Changes for compatibility with msysgit's bundled perl (an antique 5.8.8

with major core modules missing: C). So no changes for Unix users, but

a big improvement for all Windows+msysgit users: no need to install

StrawberryPerl just for C!



=item 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 v1.002



No functional changes, but distribution changes: branch C abandoned

and replaced by C (build result) and C (source).



C is now L

from C in the C branch with

L and

L, 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 with perl 5.14.2



=item *



Windows with StrawberryPerl (5.12.1 and above) and msysgit



=item *



Windows with msysgit's antique perl 5.8.8.



=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



IRC: ask C on C.



Or fill an issue at GitHub: L



=head1 AUTHOR



Olivier MenguE, L.



=head2 Thanks



L: documentation patch.



L: L that inspired

changes in 1.008.



L: support for GitHub account with

dashes (v1.009).



If you want to contribute, have a look to L.



=head1 COPYRIGHT & LICENSE



Copyright E 2011-2022 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 L.



=cut