English
资源说明：Easy creation of secure SSH configuration for your GitHub account(s)
=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 tells 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) 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:
git@github.com:/.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 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.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 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 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). 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: support for GitHub account with
dashes (v1.009).
If you want to contribute, have a look to L.
=head1 COPYRIGHT & LICENSE
Copyright E 2011-2018 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
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
