Keychain
1.
Introduction
Many of us use the excellent OpenSSH
as a secure, encrypted replacement for the venerable telnet
and rsh commands. One of OpenSSH's (and the commercial
SSH2's) intriguing features is its ability to
authenticate users using the RSA and DSA authentication
protocols, which are based upon a pair of complementary
numerical "keys". And one of the main appeals of RSA and
DSA authentication is the promise of being able to establish
connections to remote systems without supplying a
password. The keychain script makes handling
RSA and DSA keys both convenient and secure. It acts as a
front-end to ssh-agent, allowing you to easily have
one long-running ssh-agent process per system,
rather than per login session. This dramatically reduces
the number of times you need to enter your passphrase from
once per new login session to once every time your local
machine is rebooted.
Keychain was first introduced in a series of IBM developerWorks articles.
The
first article introduces the concepts behind RSA/DSA
key authentication and shows you how to set up primitive (with
passphrase) RSA/DSA authentication. The second
article shows you how to use keychain to set up secure,
passwordless ssh access in an extremely convenient way.
keychain also provides a clean, secure way for cron jobs to take
advantage of RSA/DSA keys without having to use insecure unencrypted private
keys. The third
article shows you how to use
ssh-agent's authentication forwarding mechanism.
Current versions of keychain are known to run on
Linux, BSD, Cygwin,
Tru64 UNIX,
HP-UX,
Mac OS X, and
Solaris
using whatever variant of Bourne shell you have available.
2.
Screenshot
Figure 2.1: Keychain in action |
 |
Above, agriffis starts keychain, which starts ssh-agent
and loads id_dsa. Next agriffis sources the variables into the
environment, and logs in to dev.gentoo.org. Usually
keychain (and the subsequent environment loading) would be
started in shell initialization files, but the invocation is
illustrated here.
Figure 2.2: More keychain action |
 |
This time when agriffis starts keychain, it finds the
long-running ssh-agent and uses it. It's not necessary to load id_dsa
a second time. Next agriffis sources the variables into the
environment, and logs in to dev.gentoo.org. Again,
keychain (and the subsequent environment loading) would usually
be started in shell initialization files, but the invocation is
illustrated here.
3.
Download and install
Gentoo Linux
Installation on Gentoo is easy, just emerge of course!
Code Listing 3.1: Keychain installation on Gentoo |
# emerge keychain -pv
# emerge keychain
# keychain --help
|
Red Hat and other RPM-based distributions
Download the current rpm from http://dev.gentoo.org/~agriffis/keychain/.
After downloading, execute these commands (as root) to install the
public GPG used to sign the RPM, then verify the RPM and install it:
Code Listing 3.2: Keychain RPM installation |
# gpg --keyserver subkeys.pgp.net --recv-key 20104eb0
# gpg --fingerprint 20104eb0
pub 1024D/20104EB0 2003-09-28 Aron Griffis <agriffis@gentoo.org>
Key fingerprint = E3B6 8734 C2D6 B5E5 AE76 FB3A 26B1 C5E3 2010 4EB0
sub 1024g/A2D963E7 2003-09-28
# gpg --export --armor 20104eb0 > /tmp/20104eb0.pub
# rpm --import /tmp/20104eb0.pub
# rm /tmp/20104eb0.pub
# rpm -K keychain-2.6.8-1.noarch.rpm
# rpm -Uvh keychain-2.6.8-1.noarch.rpm
|
Note:
If your firewall blocks GPG connections to the keyserver, you can install the
GPG key manually by running wget -O -
http://gentoo.org/~agriffis/gpg-pubkey-20104eb0.asc | gpg --import
|
Finally, as a normal user, run keychain --help for setup instructions.
Source
Tarballs of keychain can be found at
http://dev.gentoo.org/~agriffis/keychain/.
4.
ChangeLog
Code Listing 4.1: ChangeLog for Keychain |
* keychain 2.6.8 (24 Oct 2006)
24 Oct 2006; Aron Griffis <agriffis@gentoo.org>:
Save LC_ALL for gpg invocation so that pinentry-curses works. This affected
peper and kloeri, though it seems to work for me in any case.
* keychain 2.6.7 (24 Oct 2006)
24 Oct 2006; Aron Griffis <agriffis@gentoo.org>:
Prevent gpg_listmissing from accidentally loading keys
* keychain 2.6.6 (08 Sep 2006)
08 Sep 2006; Aron Griffis <agriffis@gentoo.org>:
Make --lockwait -1 mean forever. Previously 0 meant forever but was
undocumented. Add more locking regression tests #137981
* keychain 2.6.5 (08 Sep 2006)
08 Sep 2006; Aron Griffis <agriffis@gentoo.org>:
Break out of loop when empty lockfile can't be removed #127471. Add locking
regression tests:
100_lock_stale 101_lock_held 102_lock_empty 103_lock_empty_cant_remove
* keychain 2.6.4 (08 Sep 2006)
08 Sep 2006; Aron Griffis <agriffis@gentoo.org>:
Add validinherit function so that validity of SSH_AUTH_SOCK and friends can be
validated from startagent rather than up front. The advantage is that warning
messages aren't emitted unnecessarily when --inherit *-once.
Fix --eval for fish, and add new testcases:
053_start_with_--eval_ksh
054_start_with_--eval_fish
055_start_with_--eval_csh
* keychain 2.6.3 (07 Sep 2006)
07 Sep 2006; Aron Griffis <agriffis@gentoo.org>:
Support fish: http://roo.no-ip.org/fish/
Thanks to Ilkka Poutanen for the patch.
* keychain 2.6.2 (20 Mar 2006)
20 Mar 2006; Aron Griffis <agriffis@gentoo.org>:
Add --confirm option and corresponding regression tests for Debian bug 296382.
Thanks to Liyang HU for the patch. Also add initialization for $ssh_timeout
which was being inherited from the environment and add regression tests for
--timeout
* keychain 2.6.1 (10 Oct 2005)
10 Oct 2005; Aron Griffis <agriffis@gentoo.org>:
Change "unset evalopt" to "evalopt=false" and run through *all* the regression
tests instead of just the new ones. *sigh*
* keychain 2.6.0 (10 Oct 2005)
10 Oct 2005; Aron Griffis <agriffis@gentoo.org>:
Add the --eval option which makes keychain startup easier. See the man-page
for examples. Get rid of the release notes from README, so now this file is
where changes are tracked.
* keychain 2.5.5 (28 Jul 2005)
28 Jul 2005; Aron Griffis <agriffis@gentoo.org>:
Add the --env option and automatic reading of .keychain/env. This allows
variables such as PATH to be overridden for peculiar environments
* keychain 2.5.4.1 (11 May 2005)
11 May 2005; Aron Griffis <agriffis@gentoo.org>:
A minor bug in 2.5.4 resulted in always exiting with non-zero status. Change
back to the correct behavior of zero for success, non-zero for failure
* keychain 2.5.4 (11 May 2005)
11 May 2005; Aron Griffis <agriffis@gentoo.org>:
Fix bug 92316: If any locale variables are set, override them with LC_ALL=C.
This fixes a multibyte issue with awk that could keep a running ssh-agent from
being found.
Fix bug 87340: Use files instead of symlinks for locking, since symlink
creation is not atomic on cygwin.
* keychain 2.5.3.1 (10 Mar 2005)
10 Mar 2005; Aron Griffis <agriffis@gentoo.org>:
Fix problem introduced in 2.5.3 wrt adding gpg keys to the agent. Thanks
to Azarah for spotting it.
* keychain 2.5.3 (09 Mar 2005)
09 Mar 2005; Aron Griffis <agriffis@gentoo.org>:
Improve handling of DISPLAY by unsetting if blank. Call gpg with
--use-agent explicitly.
* keychain 2.5.2 (06 Mar 2005)
06 Mar 2005; Aron Griffis <agriffis@gentoo.org>:
Fix bug 78974 "keychain errors on Big/IP (x86 BSD variant)" by refraining
from using ! in conditional expressions. Fix RSA fingerprint extraction
on Solaris, reported in email by Travis Fitch. Use $HOSTNAME when
possible instead of calling uname -n to improve bash_profile
compatibility.
* keychain 2.5.1 (12 Jan 2005)
12 Jan 2005; Aron Griffis <agriffis@gentoo.org>:
Don't accidentally inherit a forwarded agent when
inheritwhich=local-once. Move the --stop warning after the version
splash.
* keychain 2.5.0 (07 Jan 2005)
07 Jan 2005; Aron Griffis <agriffis@gentoo.org>:
Add inheritance support via --inherit. Add parameters to --stop for
more control. Change the default behavior of keychain to inherit if
there's no keychain agent running ("--inherit local-once"), and
refrain from killing other agents unless "--stop others" is
specified.
* keychain 2.4.3 (17 Nov 2004)
17 Nov 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 69879: Update findpids to work again on BSD; it has been
broken since the changes in version 2.4.2. Now we use OSTYPE (bash)
or uname to determine the system type and call ps appropriately.
* keychain 2.4.2.1 (30 Sep 2004)
30 Sep 2004; Aron Griffis <agriffis@gentoo.org>:
Fix minor issues in the test for existing gpg keys wrt DISPLAY
* keychain 2.4.2 (29 Sep 2004)
29 Sep 2004; Aron Griffis <agriffis@gentoo.org>:
Make gpg support more complete. Allow adding keys, clearing the
agent, etc. Fix --quick support to work properly again; it was
broken since 2.4.0. Change default --attempts to 1 since the progs
ask multiple times anyway.
* keychain 2.4.1 (22 Sep 2004)
22 Sep 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bugs 64174 and 64178; support Sun SSH, which is really OpenSSH
in disguise and a few critical outputs changed. Thanks to Nathan
Bardsley for lots of help debugging on Solaris 9
15 Sep 2004; Aron Griffis <agriffis@gentoo.org>:
Fix pod2man output so it formats properly on SGI systems. Thanks to
Matthew Moore for reporting the problem.
* keychain 2.4.0 (09 Sep 2004)
09 Sep 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 26970 with first pass at gpg-agent support
Fix Debian bug 269722; don't filter output of ssh-add
Fix bug reported by Marko Myllynen regarding keychain and Solaris
awk's inability to process -F'[ :]'
Fix bug in now_seconds calculation, noticed by me.
* keychain 2.3.5 (28 Jul 2004)
28 Jul 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 58623 with patch from Daniel Westermann-Clark; don't put an
extra newline in the output of listmissing
Generate keychain.spec from keychain.spec.in automatically so that
the version can be set appropriately.
* keychain 2.3.4 (24 Jul 2004)
24 Jul 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 28599 reported by Bruno Pelaia; ignore defunct processes in
ps output
* keychain 2.3.3 (30 Jun 2004)
30 Jun 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug reported by Matthew S. Moore in email; escape the backticks
in --help output
Fix bug reported by Herbie Ong in email; set pidf, cshpidf and lockf
variables after parsing command-line to honor --dir setting
Fix bug reported by Stephan Stahl in email; make spaces in filenames
work throughout keychain, even in pure Bourne shell
Fix operation on HP-UX with older OpenSSH by interpreting output of
ssh-add as well as the error status
* keychain 2.3.2 (16 Jun 2004)
16 Jun 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 53837 (keychain needs ssh-askpass) by unsetting SSH_ASKPASS
when --nogui is specified
* keychain 2.3.1 (03 Jun 2004)
03 Jun 2004; Aron Griffis <agriffis@gentoo.org>:
Fix bug 52874: problems when the user is running csh
* keychain 2.3.0 (14 May 2004)
14 May 2004; Aron Griffis <agriffis@gentoo.org>:
Rewrite the locking code to avoid procmail
* keychain 2.2.2 (03 May 2004)
03 May 2004; Aron Griffis <agriffis@gentoo.org>:
Call loadagent prior to generating HOSTNAME-csh file so that
variables are set.
* keychain 2.2.1 (27 Apr 2004)
27 Apr 2004; Aron Griffis <agriffis@gentoo.org>:
Find running ssh-agent processes by searching for /[s]sh-agen/
instead of /[s]sh-agent/ for the sake of Solaris, which cuts off ps
-u output at 8 characters. Thanks to Clay England for reporting the
problem and testing the fix.
* keychain 2.2.0 (21 Apr 2004)
21 Apr 2004; Aron Griffis <agriffis@gentoo.org>:
Rewrote most of the code, organized into functions, fixed speed
issues involving ps, fixed compatibility issues for various UNIXes,
hopefully didn't introduce too many bugs. This version has a
--quick option (for me) and a --timeout option (for carpaski).
Also added a Makefile and converted the man-page to pod for easier
editing. See perlpod(1) for information on the format. Note that
the pod is sucked into keychain and colorized when you run make.
* keychain 2.0.3 (06 Apr 2003)
06 Apr 2003; Seth Chandler <sethbc@gentoo.org>:
Added keychain man page, fixed bugs with displaying colors for keychain
--help. Also added a $grepopts to fix the grepping for a pid on cygwin
Also added a TODO document
color fix based on submission by Luke Holden <email@alterself.org>
* keychain 2.0.2 (26 Aug 2002)
26 Aug 2002; the Tru64 fix didn't work; it was being caused by "trap - foo"
rather than "tail +2 -". Now really fixed.
26 Aug 2002; fixed "ssh-add" call to only redirect stdin (thus enabling
ssh-askpass) if ssh_askpass happens to be set; this is to work around a bug
in openssh were redirecting stdin will enable ssh-askpass even if ssh_askpass
isn't set, which contradicts the openssh 3.4_p1 man page. to enable
ssh-askpass, keychain now requires that the ssh_askpass var be set to point
to your askpass program.
* keychain 2.0.1 (24 Aug 2002)
24 Aug 2002; "--help" fixes; the keychain files were listed as sh-${HOSTNAME}
rather than ${HOSTNAME}-sh. Now consistent with the actual program. Thanks to
Christian Plessl <plessl@tik.ee.ethz.ch>, others for reporting this issue.
24 Aug 2002; cycloon <cycloon@linux-de.org>: "If you add < /dev/null when
adding the missingkeys via "ssh-add ${missingkeys}" (at line 454 of version
2.0) so that it reads: "ssh-add ${missingkeys} < /dev/null" then users can
use program like x11-ssh-askpass in xfree to type in their passphrase. It
then still works for users on shell, depending if $DISPLAY is set." Added.
24 Aug 2002; A fix to calling "tail" that *should* fix things for Tru64 Unix;
unfortunately, I have no way to test but the solution should be portable to
all other flavors of systems. Thanks to Mark Scarborough
<Mark.Scarborough@broadwing.com> for reporting the issue.
24 Aug 2002; Changed around the psopts detection stuff so that "-x -u $me f"
is used; this is needed on MacOS X. Thanks to Brian Bergstrand
<brian@classicalguitar.net>, others for reporting this issue.
* keychain 2.0 (17 Aug 2002)
17 Aug 2002; (Many submitters): A fix for keychain when running on HP-UX
10.20.
17 Aug 2002; Patrice DUMAS - DOCT <dumas@centre-cired.fr>: Now perform help
early on to avoid unnecessary processing. Also added --dir option to allow
keychain to look in an alternate location for the .keychain directory (use
like this: "keychain --dir /var/foo")
17 Aug 2002; Martial MICHEL <martial@users.sourceforge.net>: Martial also
suggested moving help processing to earlier in the script. He also submitted
a patch to place .ssh-agent-* files in a ~/.keychain/ directory, which makes
sense particularly for NFS users so I integrated the concept into the code.
17 Aug 2002; Fred Carter <fred.carter@amberpoint.com>: Cygwin fix to use
proper "ps" options.
17 Aug 2002; Adrian Howard <adrianh@quietstars.com>: patch so that lockfile
gets removed even if --noask is specified.
17 Aug 2002; Mario Wolff <wolff@voll.prima.de>: Replaced an awk dependency
with a shell construct for improved performance.
17 Aug 2002; Marcus Stoegbauer <marcus@grmpf.org>, Dmitry Frolov
<frolov@riss-telecom.ru>: I (Daniel Robbins) solved problems reported by
Marcus and Dmitry (mis-parsed command line issues) by following Dmitry's good
suggestion of performing argument parsing all at once at the top of the
script.
17 Aug 2002; Brian W. Curry <truth@bcurry.cjb.net>: Added commercial SSH2
client support; improved output readability by initializing myfail=0;
integrated Cygwin support into the main keychain script; improved Cygwin
support by setting "trap" appropriately. Thanks Brian!
* keychain 1.9 (04 Mar 2002)
04 Mar 2002; changed license from "GPL, v2 or later" to "GPL v2".
04 Mar 2002; added "keychain.cygwin" for Cygwin systems. It may be time to
follow this pattern and start building separate, optimized scripts for each
platform so they don't get too sluggish. Maybe I could use a C preprocessor
for this.
06 Dec 2001; several people: Solaris doesn't like '-e' comparisons; switched
to '-f'
* keychain 1.8 (29 Nov 2001)
29 Nov 2001; Philip Hallstrom (philip@adhesivemedia.com) Added a "--local"
option for removing the ${HOSTNAME} from the various files that keychain
creates. Handy for non-NFS users.
29 Nov 2001; Aron Griffis (agriffis@gentoo.org) Using the Bourne shell "type"
builtin rather than using the external "which" command. Should make things a
lot more robust and slightly faster.
09 Nov 2001; Mike Briseno (mike@radik.com) Solaris' "which" command outputs
"no lockfile in..." to stdout rather than stderr. A one-line fix (test the
error condition) has been applied.
09 Nov 2001; lockfile settings tweak
09 Nov 2001; Rewrote how keychain detects failed passphrase attempts. If you
stop making progress providing valid passphrases, it's three strikes and
you're out.
09 Nov 2001; Constantine P. Sapuntzakis (csapuntz@stanford.edu) Some private
keys can't be "ssh-keygen -l -f"'d; this patch causes keychain to look for
the corresponding public key if the private key doesn't work. Thanks
Constantine!
09 Nov 2001; Victor Leitman (vleitman@yahoo.com) CYAN color misdefined;
fixed.
27 Oct 2001; Brian Wellington (bwelling@xbill.org) A "quiet mode" (--quiet)
fix; I missed an "echo".
27 Oct 2001; J.A. Neitzel (jan@belvento.org) Missed another "kill -9"; it's
now gone.
* keychain 1.7 (21 Oct 2001)
21 Oct 2001; Frederic Gobry (frederic.gobry@smartdata.ch) Frederic suggested
using procmail's lockfile to serialize the execution of critical parts of
keychain, thus avoiding multiple ssh-agent processes being started if you
happen to have multiple xterms open automatically when you log in.
Initially, I didn't think I could add this, since systems may not have the
lockfile command; however, keychain will now auto-detect whether lockfile is
installed; if it is, keychain will automatically use it, thus preventing
multiple ssh-agent processes from being spawned.
21 Oct 2001; Raymond Wu (ursus@usa.net): --nocolor test is no longer inside
the test for whether "echo -e" works. According to Raymond, this works
optimally on his Solaris box.
21 Oct 2001; J.A. Neitzel (jan@belvento.org): No longer "kill -9" our
ssh-agent processes. SIGTERM should be sufficient and will allow ssh-agent to
clean up after itself (this reverses a previously-applied patch).
21 Oct 2001; Thomas Finneid (tfinneid@online.no): Added argument "--quiet |
-q" to make the program less intrusive to the user; with it, only error and
interactive messages will appear.
21 Oct 2001; Thomas Finneid (tfinneid@online.no): Changed the format of some
arguments to bring them more in line with common *nix programs: added "-h" as
alias for "--help"; added "-k" as alias for "--stop"
21 Oct 2001; Mark Stosberg (mark@summersault.com): $pidf to "$pidf" fixes to
allow keychain to work with paths that include spaces (for Darwin and MacOS X
in particular).
21 Oct 2001; Jonathan Wakely (redi@redi.uklinux.net): Small patch to convert
"echo -n -e" to "echo -e "\c"" for FreeBSD compatibility.
* keychain 1.6 (15 Oct 2001)
13 Oct 2001; Ralf Horstmann (ralf.horstmann@webwasher.com): Add /usr/ucb to
path for Solaris systems.
11 Oct 2001; Idea from Joe Reid (jreid@vnet.net): Try to add multiple keys
using ssh-add; avoid typing in identical passphrases more than once. Good
idea!
*keychain 1.5 (21 Sep 2001)
21 Sep 2001; David Hull (hull@paracel.com): misc. compatibility, signal
handling, cleanup fixes
21 Sep 2001; "ps" test to find the right one for your OS.
20 Sep 2001; Marko Myllynen (myllynen@lut.fi): "grep [s]sh-agent" to "grep
[s]sh-agent" (zsh fix)
*keychain 1.4 (20 Sep 2001)
20 Sep 2001; David Hull (hull@paracel.com): "touch $foo" to ">$foo"
optimization and other "don't fork" fixes. Converted ${foo#--} to a case
statement for Solaris sh compatibility.
20 Sep 2001; Try an alternate "ps" syntax if our default one fails. This
should give us Solaris and IRIX (sysV) compatibility without breaking BSD.
20 Sep 2001; Hans Peter Verne (h.p.verne@usit.uio.no); "echo -e" to "echo $E"
(for IRIX compatibility with --nocolor), optimization of grep ("grep
[s]sh-agent")
17 Sep 2001; Marko Myllynen (myllynen@lut.fi): Various fixes: trap signal 2
if signal INT not supported (NetBSD); handle invalid keys correctly; ancient
version of ash didn't support ~, so using $HOME; correct zsh instruction;
minor cleanups
*keychain 1.3 (12 Sep 2001)
12 Sep 2001; Minor color changes; the cyan was hard to read on xterm-colored
terms so it was switched to bold. Additional --help text added.
10 Sep 2001; We now use .ssh-agent-[hostname] instead of .ssh-agent. We now
create a .ssh-agent-csh-[hostname] file that can be sourced by csh-compatible
shells. We also now kill all our existing ssh-agent processes before
starting a new one.
10 Sep 2001; Robert R. Wal (rrw@hell.pl): Very nice NFS fixes, colorization
fixes, tcsh redirect -> grep -v fix. Thanks go out to others who sent me
similar patches.
10 Sep 2001; Johann Visagie (johann@egenetics.com): "source" to "."
shell-compatibility fixes. Thanks for the FreeBSD port.
10 Sep 2001; Marko Myllynen (myllynen@lut.fi): rm -f $pidf after stopping
ssh-agent fix
*keychain 1.2
09 Sep 2001; README updates to reflect new changes.
09 Sep 2001; Marko Myllynen (myllynen@lut.fi): bash 1/zsh/sh compatibility;
now only tries to kill *your* ssh-agent processes, version fix, .ssh-agent
file creation error detection. Thanks!
*keychain 1.1; fixes for calling "pidof"; README; ChangeLog
07 Sep 2001; Addition of README stating that keychain requires bash 2.0 or
greater, as well as quick install directions and web URL.
07 Sep 2001; Explicitly added /sbin and /usr/sbin to path, and then called
"pidof". I think that this is a bit more robust.
06 Sep 2001; from John Ellson (ellson@lucent.com): "pidof" changed to
"/sbin/pidof", since it's probably not in $PATH
06 Sep 2001; New ChangeLog! :)
*keychain 1.0; initial release (Aug 2001)
|
|
|
