Difference between pages "Funtoo Filesystem Guide, Part 5" and "Funtoo:Keychain"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
{{Article
{{Article
|Subtitle=Official Project Page
|Author=Drobbins
|Author=Drobbins
|Previous in Series=Funtoo Filesystem Guide, Part 4
|Next in Series=Funtoo Filesystem Guide, Part 6
}}
}}
== Introduction ==
<tt>Keychain</tt> helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to <tt>ssh-agent</tt> and <tt>ssh-add</tt>, but allows you to easily have one long running <tt>ssh-agent</tt> process per system, rather than the norm of one <tt>ssh-agent</tt> per login session.
__TOC__
This dramatically reduces the number of times you need to enter your passphrase. With <tt>keychain</tt>, you only need to enter a passphrase once every time your local machine is rebooted. <tt>Keychain</tt> also makes it easy for remote cron jobs to securely &quot;hook in&quot; to a long running <tt>ssh-agent</tt> process, allowing your scripts to take advantage of key-based logins.
{{#seo:
|title=Keychain (SSH/GPG Key Management)
|keywords=keychain,ssh,gpg,funtoo,linux,gentoo,Daniel Robbins
|description=Keychain is a shell script that helps you to manage your SSH and GPG keys more easily.
}}
== Download and Resources ==
 
The latest release of keychain is version <tt>2.7.2_beta1</tt>, and was released on July 7, 2014. The current version of keychain supports <tt>gpg-agent</tt> as well as <tt>ssh-agent</tt>.
 
Keychain is compatible with many operating systems, including <tt>AIX</tt>, <tt>*BSD</tt>, <tt>Cygwin</tt>, <tt>MacOS X</tt>, <tt>Linux</tt>, <tt>HP/UX</tt>, <tt>Tru64 UNIX</tt>, <tt>IRIX</tt>, <tt>Solaris</tt> and <tt>GNU Hurd</tt>.
 
=== Download ===
 
* ''Release Archive''
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.2_beta1.tar.bz2 keychain 2.7.2_beta1]
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1.tar.bz2 keychain 2.7.1]
 
* ''Apple MacOS X Packages''
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1-macosx.tar.gz keychain 2.7.1 MacOS X package]
 
Keychain development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [https://bugs.funtoo.org Funtoo Linux bug tracker] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
 
=== Project History ===
 
Daniel Robbins originally wrote <tt>keychain</tt> 1.0 through 2.0.3. 1.0 was written around June 2001, and 2.0.3 was released in late August, 2002.
 
After 2.0.3, <tt>keychain</tt> was maintained by various Gentoo developers, including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3, 2003.
 
On April 21, 2004, Aron Griffis committed a major rewrite of <tt>keychain</tt> which was released as 2.2.0. Aron continued to actively maintain and improve <tt>keychain</tt> through October 2006 and the <tt>keychain</tt> 2.6.8 release. He also made a few commits after that date, up through mid-July, 2007. At this point, <tt>keychain</tt> had reached a point of maturity.
 
In mid-July, 2009, Daniel Robbins migrated Aron's mercurial repository to git and set up a new project page on funtoo.org, and made a few bug fix commits to the git repo that had been collecting in [http://bugs.gentoo.org bugs.gentoo.org]. Daniel continues to maintain <tt>keychain</tt> and supporting documentation on funtoo.org, and plans to make regular maintenance releases of <tt>keychain</tt> as needed.
 
== Quick Setup ==
 
=== Linux ===


Back around 2002, when this article was originally written, Andrew Morton had a
To install under Gentoo or Funtoo Linux, type
nice little introduction to using ext3 on his Web site. His site has since
<console>
disappeared, so in this updated article, I'll summarize Andrew Morton's
###i## emerge keychain
original documentation. Then, in the second half of the article, we'll delve
</console>
into some meatier ext3 topics, ones that I think you'll find very useful.


== Ext3 QuickStart ==
For other Linux distributions, use your distribution's package manager, or download and install using the source tarball above. Then generate RSA/DSA keys if necessary. The quick install docs assume you have a DSA key pair named <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> in your <tt>~/.ssh/</tt> directory. Add the following to your <tt>~/.bash_profile</tt>:


=== (Not) Patching the Kernel ===
{{file|name=~/.bash_profile|body=
eval `keychain --eval --agents ssh id_rsa`
}}


These days, there is no need to patch your kernel for ext3. Ext3 has been
If you want to take advantage of GPG functionality, ensure that GNU Privacy Guard is installed and omit the <tt>--agents ssh</tt> option above.
incorporated into the Linux kernel for a long time, and is very mature.


=== Converting ext2 to ext3 ===
=== Apple MacOS X ===


One of the nice things about ext3 is that you can easily convert an ext2
To install under MacOS X, install the MacOS X package for keychain. Assuming you have an <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> key pair in your <tt>~/.ssh/</tt> directory, add the following to your <tt>~/.bash_profile</tt>:
filesystem to be an ext3 filesystem. All that you need to do is to create a
journal on the ext2 filesystem, as follows:


<pre>tune2fs -j /dev/sdXX</pre>
{{file|name=~/.bash_profile|body=
eval `keychain --eval --agents ssh --inherit any id_dsa`
}}


You can even do this while the filesystem is mounted. If it ''is'' currently
{{Fancynote|The <tt>--inherit any</tt> option above causes keychain to inherit any ssh key passphrases stored in your Apple MacOS Keychain. If you would prefer for this to not happen, then this option can be omitted.}}
mounted, it will not function as an ext3 filesystem until you are able to
remount it as ext3. Remember to update <tt>/etc/fstab</tt> to so that it refers
to the new filesystem as an <tt>ext3</tt> filesystem.


=== Creating New Ext3 Filesystems ===
== Background ==


Simply use the <tt>-j</tt> option with <tt>mke2fs</tt>, as follows:
You're probably familiar with <tt>ssh</tt>, which has become a secure replacement for the venerable <tt>telnet</tt> and <tt>rsh</tt> commands.


<pre>mke2fs -j /dev/sdXX</pre>
Typically, when one uses <tt>ssh</tt> to connect to a remote system, one supplies a secret passphrase to <tt>ssh</tt>, which is then passed in encrypted form over the network to the remote server. This passphrase is used by the remote <tt>sshd</tt> server to determine if you should be granted access to the system.


=== Switching Between Ext2 and Ext3 ===
However, OpenSSH and nearly all other SSH clients and servers have the ability to perform another type of authentication, called asymmetric public key authentication, using the RSA or DSA authentication algorithms. They are very useful, but can also be complicated to use. <tt>keychain</tt> has been designed to make it easy to take advantage of the benefits of RSA and DSA authentication.


It is possible to mount an ext3 filesystem as an ext2 filesystem, as long as
== Generating a Key Pair ==
the ext3 filesystem has been cleanly unmounted. Simply specify a filesystem
type of <tt>ext2</tt> when mounting an ext3 filesystem with older kernels. You
can also specify a filesystem type of <tt>auto</tt> in <tt>/etc/fstab</tt>,
which will tell the <tt>mount</tt> and <tt>fsck</tt> commands to utilize the
filesystem as ext3 if such support is available, otherwise falling back to
ext2.


=== Fixing Dirty Ext3 Filesystems ===
To use RSA and DSA authentication, first you use a program called <tt>ssh-keygen</tt> (included with OpenSSH) to generate a ''key pair'' -- two small files. One of the files is the ''public key''. The other small file contains the ''private key''. <tt>ssh-keygen</tt> will ask you for a passphrase, and this passphrase will be used to encrypt your private key. You will need to supply this passphrase to use your private key. If you wanted to generate a DSA key pair, you would do this:


If your ext3 filesystem was not cleanly unmounted, then you should be able clean it up using <tt>e2fsck</tt> as follows:
<console># ##i##ssh-keygen -t dsa
Generating public/private dsa key pair.</console>
You would then be prompted for a location to store your key pair. If you do not have one currently stored in <tt>~/.ssh</tt>, it is fine to accept the default location:


<pre>e2fsck -fy /dev/sdXX</pre>
<console>Enter file in which to save the key (/root/.ssh/id_dsa): </console>
The filesystem should now be mountable as ext2.
Then, you are prompted for a passphrase. This passphrase is used to encrypt the ''private key'' on disk, so even if it is stolen, it will be difficult for someone else to use it to successfully authenticate as you with any accounts that have been configured to recognize your public key.


=== Ext3 Root Filesystem Tricks ===
Note that conversely, if you '''do not''' provide a passphrase for your private key file, then your private key file '''will not''' be encrypted. This means that if someone steals your private key file, ''they will have the full ability to authenticate with any remote accounts that are set up with your public key.''


If you want to force a Linux kernel to mount an ext3 filesystem as an ext2
Below, I have supplied a passphrase so that my private key file will be encrypted on disk:
filesystem, add the <tt>rootfstype=ext2</tt> kernel boot parameter to the
kernel boot parameters in <tt>lilo.conf</tt> or <tt>grub.conf</tt>.


To tell the Linux kernel to mount your root ext3 filesystem using a particular
<console>Enter passphrase (empty for no passphrase): ##i#########
journaling mode, use the <tt>rootflags</tt> kernel boot parameter as follows
Enter same passphrase again: ##i#########
(using a <tt>grub.conf</tt> example):
Your identification has been saved in /var/tmp/id_dsa.
Your public key has been saved in /var/tmp/id_dsa.pub.
The key fingerprint is:
5c:13:ff:46:7d:b3:bf:0e:37:1e:5e:8c:7b:a3:88:f4 root@devbox-ve
The key's randomart image is:
+--[ DSA 1024]----+
|          .      |
|          o  . |
|          o . ..o|
|      . . . o  +|
|        S    o. |
|            . o.|
|        .  ..++|
|        . o . =o*|
|        . E .+*.|
+-----------------+</console>


<pre>kernel /boot/bzImage rootflags=data=journal root=/dev/sda3</pre>
== Setting up Authentication ==


=== Filesystem Check Intervals ===
Here's how you use these files to authenticate with a remote server. On the remote server, you would append the contents of your ''public key'' to the <tt>~.ssh/authorized_keys</tt> file, if such a file exists. If it doesn't exist, you can simply create a new <tt>authorized_keys</tt> file in the remote account's <tt>~/.ssh</tt> directory that contains the contents of your local <tt>id_dsa.pub</tt> file.


By default, <tt>e2fsck</tt> will perform an exhaustive filesystem check every
Then, if you weren't going to use <tt>keychain</tt>, you'd perform the following steps. On your local client, you would start a program called <tt>ssh-agent</tt>, which runs in the background. Then you would use a program called <tt>ssh-add</tt> to tell <tt>ssh-agent</tt> about your secret private key. Then, if you've set up your environment properly, the next time you run <tt>ssh</tt>, it will find <tt>ssh-agent</tt> running, grab the private key that you added to <tt>ssh-agent</tt> using <tt>ssh-add</tt>, and use this key to authenticate with the remote server.
now and then, even if the filesystem was cleanly unmounted. By default, this
happens every twentieth mount or every 180 days, whichever comes first.


While this might have been handy for ext2 filesystems, it's not optimal for
Again, the steps in the previous paragraph is what you'd do if <tt>keychain</tt> wasn't around to help. If you are using <tt>keychain</tt>, and I hope you are, you would simply add the following line to your <tt>~/.bash_profile</tt> or if a regular user to<tt>~/.bashrc</tt> :
ext3. To turn this automatic exhaustive filesystem check off, use the following
<tt>tune2fs</tt> command:


<pre>tune2fs -i 0 -c 0 /dev/sdXX</pre>
{{file|name=~/.bash_profile|body=
eval `keychain --eval id_dsa`
}}


You can view the filesystem check interval (as well as lots of other
The next time you log in or source your <tt>~/.bash_profile</tt> or if you use <tt>~/.bashrc</tt>, <tt>keychain</tt> will start, start <tt>ssh-agent</tt> for you if it has not yet been started, use <tt>ssh-add</tt> to add your <tt>id_dsa</tt> private key file to <tt>ssh-agent</tt>, and set up your shell environment so that <tt>ssh</tt> will be able to find <tt>ssh-agent</tt>. If <tt>ssh-agent</tt> is already running, <tt>keychain</tt> will ensure that your <tt>id_dsa</tt> private key has been added to <tt>ssh-agent</tt> and then set up your environment so that <tt>ssh</tt> can find the already-running <tt>ssh-agent</tt>. It will look something like this:
interesting information) by typing <tt>tune2fs -l /dev/sdXX</tt>.


=== External Journals ===
Note that when <tt>keychain</tt> runs for the first time after your local system has booted, you will be prompted for a passphrase for your private key file if it is encrypted. But here's the nice thing about using <tt>keychain</tt> -- even if you are using an encrypted private key file, you will only need to enter your passphrase when your system first boots (or in the case of a server, when you first log in.) After that, <tt>ssh-agent</tt> is already running and has your decrypted private key cached in memory. So if you open a new shell, you will see something like this:


Ext3 supports the ability to place the journal on a separate persistent device. To create an external journal on <tt>/dev/sdb</tt>, type:
This means that you can now <tt>ssh</tt> to your heart's content, without supplying a passphrase.
 
You can also execute batch <tt>cron</tt> jobs and scripts that need to use <tt>ssh</tt> or <tt>scp</tt>, and they can take advantage of passwordless RSA/DSA authentication as well. To do this, you would add the following line to the top of a bash script:
 
{{file|name=example-script.sh|body=
eval `keychain --noask --eval id_dsa` || exit 1
}}
 
The extra <tt>--noask</tt> option tells <tt>keychain</tt> that it should not prompt for a passphrase if one is needed. Since it is not running interactively, it is better for the script to fail if the decrypted private key isn't cached in memory via <tt>ssh-agent</tt>.
 
== Keychain Options ==
 
=== Specifying Agents ===
 
In the images above, you will note that <tt>keychain</tt> starts <tt>ssh-agent</tt>, but also starts <tt>gpg-agent</tt>. Modern versions of <tt>keychain</tt> also support caching decrypted GPG keys via use of <tt>gpg-agent</tt>, and will start <tt>gpg-agent</tt> by default if it is available on your system. To avoid this behavior and only start <tt>ssh-agent</tt>, modify your <tt>~/.bash_profile</tt> as follows:
 
{{file|name=~/.bash_profile|body=
eval `keychain --agents ssh --eval id_dsa` || exit 1
}}


<pre>mke2fs -O journal_dev /dev/sdb</pre>
The additional <tt>--agents ssh</tt> option tells <tt>keychain</tt> just to manage <tt>ssh-agent</tt>, and ignore <tt>gpg-agent</tt> even if it is available.
Then, to create an ext3 filesystem on <tt>/dev/sda3</tt> that uses this external journal, type:


<pre>mke2fs -J device=/dev/sdb /dev/sda3
=== Clearing Keys ===
mount /dev/sda3 /mnt/test -t ext3</pre>
== Ext3 Journaling Options and Write Latency ==


Ext3 allows you to choose from one of three data journaling modes at filesystem
Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:
mount time: <tt>data=writeback</tt>, <tt>data=ordered</tt>, and
<tt>data=journal</tt>.


To specify a journal mode, you can add the appropriate string
<console># ##i##keychain --clear</console>
(<tt>data=journal</tt>, for example) to the options section of your
Any agent(s) will continue to run.
<tt>/etc/fstab</tt>, or specify the <tt>-o data=journal</tt> command-line
option when calling mount directly.


As we covered earlier in this article, if you'd like to specify the data
=== Improving Security ===
journaling method used for your root filesystem (<tt>data=ordered</tt> is the
default), you can to use a special kernel boot option called
<tt>rootflags</tt>. So, if you'd like to put your root filesystem into full
data journaling mode, add <tt>rootflags=data=journal</tt> to your kernel boot
options.


=== <tt>data=writeback</tt> Mode ===
To improve the security of <tt>keychain</tt>, some people add the <tt>--clear</tt> option to their <tt>~/.bash_profile</tt> <tt>keychain</tt> invocation. The rationale behind this is that any user logging in should be assumed to be an intruder until proven otherwise. This means that you will need to re-enter any passphrases when you log in, but cron jobs will still be able to run when you log out.


In <tt>data=writeback mode</tt>, ext3 doesn't do any form of data journaling at
=== Stopping Agents ===
all, providing you with similar journaling found in the XFS, JFS, and ReiserFS
filesystems -- metadata only. As I explained in my
[http://www.funtoo.org/en/articles/linux/ffg/4/ previous article], this could
allow recently modified files to become corrupted in the event of an unexpected
reboot. Despite this drawback, <tt>data=writeback</tt> mode should give you the
best ext3 performance under most conditions.


=== <tt>data=ordered</tt> Mode ===
If you want to stop all agents, which will also of course cause your keys/identities to be flushed from memory, you can do this as follows:


In <tt>data=ordered</tt> mode, ext3 only officially journals metadata, but it logically groups metadata and data blocks into a single unit called atransaction. When it's time to write the new metadata out to disk, the associated data blocks are written first. <tt>data=ordered</tt> mode
<console># ##i##keychain -k all</console>
effectively solves the corruption problem found in <tt>data=writeback</tt> mode and most other journaled filesystems, and it does so without requiring fulldata journaling. In general, <tt>data=ordered</tt> ext3 filesystems performslightly slower than <tt>data=writeback</tt> filesystems, but significantly faster than their full data journaling counterparts.When appending data to files, <tt>data=ordered</tt> mode provides all of the integrity guarantees offered by ext3's full data journaling mode. However, ifpart of a file is being overwritten and the system crashes, it's possible that
If you have other agents running under your user account, you can also tell <tt>keychain</tt> to just stop only the agents that <tt>keychain</tt> started:
the region being written will contain a combination of original blocks
interspersed with updated blocks. This is because <tt>data=ordered</tt>
provides no guarantees as to which blocks are overwritten first, so you can't
assume that just because overwritten block x was updated, that overwrittenblock x-1 was updated as well. Instead, <tt>data=ordered</tt> leaves the writeordering up to the hard drive's write cache. In general, this limitation
doesn't end up negatively impacting people very often, since file appends are
generally much more common than file overwrites. For this reason,<tt>data=ordered</tt> mode is a good higher-performance replacement for fulldata journaling.


=== <tt>data=journal</tt> Mode ===
<console># ##i##keychain -k mine</console>


<tt>data=journal</tt> mode provides full data and metadata journaling. All new
=== GPG ===
data is written to the journal first, and then to its final location. In the
event of a crash, the journal can be replayed, bringing both data and metadata
into a consistent state.


Theoretically, <tt>data=journal</tt> mode is the slowest journaling mode of all, since data gets written to disk twice rather than once. However, it turns
Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:
out that in certain situations, <tt>data=journal</tt> mode can be blazingly
<console>
fast. Andrew Morton, after hearing reports on LKML that ext3
$##i## gpg -k
<tt>data=journal</tt> filesystems were giving people unbelievably greatinteractive filesystem performance, decided to put together a little test.
pub  2048R/DEADBEEF 2012-08-16
First, he created simple shell script designed to write data to a test
uid                  Name (Comment) <email@host.tld>
filesystem as quickly as possible:
sub  2048R/86D2FAC6 2012-08-16
</console>


<pre>while true
Note the '''DEADBEEF''' above is the ID. Then, in your login script, do your usual
do       
    dd if=/dev/zero of=largefile bs=16384 count=131072
done</pre>
While data was being written to the test filesystem, he attempted to read 16MB of data from another ext2 filesystem on the same disk, timing the results:


<pre># time cat 16-meg-file &gt; /dev/null</pre>
<console>
$##i## keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
$##i## source ~/.ssh/.keychain/$HOST-sh
$##i## source ~/.ssh/.keychain/$HOST-sh-gpg
</console>


The results were astounding. <tt>data=journal</tt> mode allowed the 16 MB file to be read from 9 to over 13 times faster than other ext3 modes, ReiserFS, and even ext2 (which has no journaling overhead):
=== Learning More ===


{| {{Table}}
The instructions above will work on any system that uses <tt>bash</tt> as its default shell, such as most Linux systems and Mac OS X.
!Filesystem||16 MB read time (seconds)
|-
|ext2
|78
|-
|ReiserFS
|67
|-
|ext3 data=ordered
|93
|-
|ext3 data=writeback
|74
|-
|ext3 data=journal
|7
|}


Andrew repeated this test, but tried to read a 16 MB file from the test filesystem (rather than a different filesystem), and he got identical results. So, what does this mean? Somehow, ext3's <tt>data=journal</tt> mode is incredibly well-suited to situations where data needs to be read from and written to disk at the same time. Therefore, ext3's <tt>data=journal</tt> mode, which was assumed to be the slowest of all ext3 modes in nearly all conditions, actually turns out to have a major performance advantage in busy environments where interactive IO performance needs to be maximized. Maybe <tt>data=journal</tt> mode isn't so sluggish after all!
To learn more about the many things that <tt>keychain</tt> can do, including alternate shell support, consult the keychain man page, or type <tt>keychain --help | less</tt> for a full list of command options.


Andrew is still trying to figure out exactly why data=journal mode is doing so much better than everything else. When he does, he may be able to add the necessary tweaks to the rest of ext3 so that data=writeback and data=ordered modes see some benefit as well.
I also recommend you read my original series of articles about [http://www.openssh.com OpenSSH] that I wrote for IBM developerWorks, called <tt>OpenSSH Key Management</tt>. Please note that <tt>keychain</tt> 1.0 was released along with Part 2 of this article, which was written in 2001. <tt>keychain</tt> has changed quite a bit since then. In other words, read these articles for the conceptual and [http://www.openssh.com OpenSSH] information, but consult the <tt>keychain</tt> man page for command-line options and usage instructions :)


I hope to see you soon when I release the next installment in the Funtoo Filesystem Guide!
* [http://www.ibm.com/developerworks/library/l-keyc.html Common Threads: OpenSSH key management, Part 1] - Understanding RSA/DSA Authentication
* [http://www.ibm.com/developerworks/library/l-keyc2/ Common Threads: OpenSSH key management, Part 2] - Introducing <tt>ssh-agent</tt> and <tt>keychain</tt>
* [http://www.ibm.com/developerworks/library/l-keyc3/ Common Threads: OpenSSH key management, Part 3] - Agent forwarding and <tt>keychain</tt> improvements


== Resources ==
As mentioned at the top of the page, <tt>keychain</tt> development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
Be sure to checkout the other articles in this series:
* [[Funtoo Filesystem Guide, Part 1|Part 1]]: Journaling and ReiserFS
* [[Funtoo Filesystem Guide, Part 2|Part 2]]: Using ReiserFS and Linux
* [[Funtoo Filesystem Guide, Part 3|Part 3]]: Tmpfs and bind mounts
* [[Funtoo Filesystem Guide, Part 4|Part 4]]: Introducing Ext3
* [[Funtoo Filesystem Guide, Part 5|Part 5]]: Ext3 in action


[[Category:Filesystem Guides]]
[[Category:HOWTO]]
[[Category:Projects]]
[[Category:First Steps]]
[[Category:Articles]]
[[Category:Articles]]
{{ArticleFooter}}
{{ArticleFooter}}

Revision as of 01:49, January 2, 2015

Official Project Page

   Support Funtoo!
Get an awesome Funtoo container and support Funtoo! See Funtoo Containers for more information.

Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to ssh-agent and ssh-add, but allows you to easily have one long running ssh-agent process per system, rather than the norm of one ssh-agent per login session.

This dramatically reduces the number of times you need to enter your passphrase. With keychain, you only need to enter a passphrase once every time your local machine is rebooted. Keychain also makes it easy for remote cron jobs to securely "hook in" to a long running ssh-agent process, allowing your scripts to take advantage of key-based logins. {{#seo: |title=Keychain (SSH/GPG Key Management) |keywords=keychain,ssh,gpg,funtoo,linux,gentoo,Daniel Robbins |description=Keychain is a shell script that helps you to manage your SSH and GPG keys more easily. }}

Download and Resources

The latest release of keychain is version 2.7.2_beta1, and was released on July 7, 2014. The current version of keychain supports gpg-agent as well as ssh-agent.

Keychain is compatible with many operating systems, including AIX, *BSD, Cygwin, MacOS X, Linux, HP/UX, Tru64 UNIX, IRIX, Solaris and GNU Hurd.

Download

Keychain development sources can be found in the keychain git repository. Please use the Funtoo Linux bug tracker and #funtoo irc channel for keychain support questions as well as bug reports.

Project History

Daniel Robbins originally wrote keychain 1.0 through 2.0.3. 1.0 was written around June 2001, and 2.0.3 was released in late August, 2002.

After 2.0.3, keychain was maintained by various Gentoo developers, including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3, 2003.

On April 21, 2004, Aron Griffis committed a major rewrite of keychain which was released as 2.2.0. Aron continued to actively maintain and improve keychain through October 2006 and the keychain 2.6.8 release. He also made a few commits after that date, up through mid-July, 2007. At this point, keychain had reached a point of maturity.

In mid-July, 2009, Daniel Robbins migrated Aron's mercurial repository to git and set up a new project page on funtoo.org, and made a few bug fix commits to the git repo that had been collecting in bugs.gentoo.org. Daniel continues to maintain keychain and supporting documentation on funtoo.org, and plans to make regular maintenance releases of keychain as needed.

Quick Setup

Linux

To install under Gentoo or Funtoo Linux, type

root # emerge keychain

For other Linux distributions, use your distribution's package manager, or download and install using the source tarball above. Then generate RSA/DSA keys if necessary. The quick install docs assume you have a DSA key pair named id_dsa and id_dsa.pub in your ~/.ssh/ directory. Add the following to your ~/.bash_profile:

   ~/.bash_profile
eval `keychain --eval --agents ssh id_rsa`

If you want to take advantage of GPG functionality, ensure that GNU Privacy Guard is installed and omit the --agents ssh option above.

Apple MacOS X

To install under MacOS X, install the MacOS X package for keychain. Assuming you have an id_dsa and id_dsa.pub key pair in your ~/.ssh/ directory, add the following to your ~/.bash_profile:

   ~/.bash_profile
eval `keychain --eval --agents ssh --inherit any id_dsa`
   Note

The --inherit any option above causes keychain to inherit any ssh key passphrases stored in your Apple MacOS Keychain. If you would prefer for this to not happen, then this option can be omitted.

Background

You're probably familiar with ssh, which has become a secure replacement for the venerable telnet and rsh commands.

Typically, when one uses ssh to connect to a remote system, one supplies a secret passphrase to ssh, which is then passed in encrypted form over the network to the remote server. This passphrase is used by the remote sshd server to determine if you should be granted access to the system.

However, OpenSSH and nearly all other SSH clients and servers have the ability to perform another type of authentication, called asymmetric public key authentication, using the RSA or DSA authentication algorithms. They are very useful, but can also be complicated to use. keychain has been designed to make it easy to take advantage of the benefits of RSA and DSA authentication.

Generating a Key Pair

To use RSA and DSA authentication, first you use a program called ssh-keygen (included with OpenSSH) to generate a key pair -- two small files. One of the files is the public key. The other small file contains the private key. ssh-keygen will ask you for a passphrase, and this passphrase will be used to encrypt your private key. You will need to supply this passphrase to use your private key. If you wanted to generate a DSA key pair, you would do this:

root # ssh-keygen -t dsa
Generating public/private dsa key pair.

You would then be prompted for a location to store your key pair. If you do not have one currently stored in ~/.ssh, it is fine to accept the default location:

Enter file in which to save the key (/root/.ssh/id_dsa): 

Then, you are prompted for a passphrase. This passphrase is used to encrypt the private key on disk, so even if it is stolen, it will be difficult for someone else to use it to successfully authenticate as you with any accounts that have been configured to recognize your public key.

Note that conversely, if you do not provide a passphrase for your private key file, then your private key file will not be encrypted. This means that if someone steals your private key file, they will have the full ability to authenticate with any remote accounts that are set up with your public key.

Below, I have supplied a passphrase so that my private key file will be encrypted on disk:

Enter passphrase (empty for no passphrase): #######
Enter same passphrase again: #######
Your identification has been saved in /var/tmp/id_dsa.
Your public key has been saved in /var/tmp/id_dsa.pub.
The key fingerprint is:
5c:13:ff:46:7d:b3:bf:0e:37:1e:5e:8c:7b:a3:88:f4 root@devbox-ve
The key's randomart image is:
+--[ DSA 1024]----+
|          .      |
|           o   . |
|          o . ..o|
|       . . . o  +|
|        S     o. |
|             . o.|
|         .   ..++|
|        . o . =o*|
|         . E .+*.|
+-----------------+

Setting up Authentication

Here's how you use these files to authenticate with a remote server. On the remote server, you would append the contents of your public key to the ~.ssh/authorized_keys file, if such a file exists. If it doesn't exist, you can simply create a new authorized_keys file in the remote account's ~/.ssh directory that contains the contents of your local id_dsa.pub file.

Then, if you weren't going to use keychain, you'd perform the following steps. On your local client, you would start a program called ssh-agent, which runs in the background. Then you would use a program called ssh-add to tell ssh-agent about your secret private key. Then, if you've set up your environment properly, the next time you run ssh, it will find ssh-agent running, grab the private key that you added to ssh-agent using ssh-add, and use this key to authenticate with the remote server.

Again, the steps in the previous paragraph is what you'd do if keychain wasn't around to help. If you are using keychain, and I hope you are, you would simply add the following line to your ~/.bash_profile or if a regular user to~/.bashrc :

   ~/.bash_profile
eval `keychain --eval id_dsa`

The next time you log in or source your ~/.bash_profile or if you use ~/.bashrc, keychain will start, start ssh-agent for you if it has not yet been started, use ssh-add to add your id_dsa private key file to ssh-agent, and set up your shell environment so that ssh will be able to find ssh-agent. If ssh-agent is already running, keychain will ensure that your id_dsa private key has been added to ssh-agent and then set up your environment so that ssh can find the already-running ssh-agent. It will look something like this:

Note that when keychain runs for the first time after your local system has booted, you will be prompted for a passphrase for your private key file if it is encrypted. But here's the nice thing about using keychain -- even if you are using an encrypted private key file, you will only need to enter your passphrase when your system first boots (or in the case of a server, when you first log in.) After that, ssh-agent is already running and has your decrypted private key cached in memory. So if you open a new shell, you will see something like this:

This means that you can now ssh to your heart's content, without supplying a passphrase.

You can also execute batch cron jobs and scripts that need to use ssh or scp, and they can take advantage of passwordless RSA/DSA authentication as well. To do this, you would add the following line to the top of a bash script:

   example-script.sh
eval `keychain --noask --eval id_dsa`

The extra --noask option tells keychain that it should not prompt for a passphrase if one is needed. Since it is not running interactively, it is better for the script to fail if the decrypted private key isn't cached in memory via ssh-agent.

Keychain Options

Specifying Agents

In the images above, you will note that keychain starts ssh-agent, but also starts gpg-agent. Modern versions of keychain also support caching decrypted GPG keys via use of gpg-agent, and will start gpg-agent by default if it is available on your system. To avoid this behavior and only start ssh-agent, modify your ~/.bash_profile as follows:

   ~/.bash_profile
eval `keychain --agents ssh --eval id_dsa`

The additional --agents ssh option tells keychain just to manage ssh-agent, and ignore gpg-agent even if it is available.

Clearing Keys

Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:

root # keychain --clear

Any agent(s) will continue to run.

Improving Security

To improve the security of keychain, some people add the --clear option to their ~/.bash_profile keychain invocation. The rationale behind this is that any user logging in should be assumed to be an intruder until proven otherwise. This means that you will need to re-enter any passphrases when you log in, but cron jobs will still be able to run when you log out.

Stopping Agents

If you want to stop all agents, which will also of course cause your keys/identities to be flushed from memory, you can do this as follows:

root # keychain -k all

If you have other agents running under your user account, you can also tell keychain to just stop only the agents that keychain started:

root # keychain -k mine

GPG

Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:

user $ gpg -k
pub   2048R/DEADBEEF 2012-08-16
uid                  Name (Comment) <email@host.tld>
sub   2048R/86D2FAC6 2012-08-16

Note the DEADBEEF above is the ID. Then, in your login script, do your usual

user $ keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
user $ source ~/.ssh/.keychain/$HOST-sh
user $ source ~/.ssh/.keychain/$HOST-sh-gpg

Learning More

The instructions above will work on any system that uses bash as its default shell, such as most Linux systems and Mac OS X.

To learn more about the many things that keychain can do, including alternate shell support, consult the keychain man page, or type keychain --help | less for a full list of command options.

I also recommend you read my original series of articles about OpenSSH that I wrote for IBM developerWorks, called OpenSSH Key Management. Please note that keychain 1.0 was released along with Part 2 of this article, which was written in 2001. keychain has changed quite a bit since then. In other words, read these articles for the conceptual and OpenSSH information, but consult the keychain man page for command-line options and usage instructions :)

As mentioned at the top of the page, keychain development sources can be found in the keychain git repository. Please use the funtoo-dev mailing list and #funtoo irc channel for keychain support questions as well as bug reports.


   Note

Browse all our available articles below. Use the search field to search for topics and keywords in real-time.

Article Subtitle
Article Subtitle
Awk by Example, Part 1 An intro to the great language with the strange name
Awk by Example, Part 2 Records, loops, and arrays
Awk by Example, Part 3 String functions and ... checkbooks?
Bash by Example, Part 1 Fundamental programming in the Bourne again shell (bash)
Bash by Example, Part 2 More bash programming fundamentals
Bash by Example, Part 3 Exploring the ebuild system
BTRFS Fun
Funtoo Filesystem Guide, Part 1 Journaling and ReiserFS
Funtoo Filesystem Guide, Part 2 Using ReiserFS and Linux
Funtoo Filesystem Guide, Part 3 Tmpfs and Bind Mounts
Funtoo Filesystem Guide, Part 4 Introducing Ext3
Funtoo Filesystem Guide, Part 5 Ext3 in Action
GUID Booting Guide
Learning Linux LVM, Part 1 Storage management magic with Logical Volume Management
Learning Linux LVM, Part 2 The cvs.gentoo.org upgrade
Libvirt
Linux Fundamentals, Part 1
Linux Fundamentals, Part 2
Linux Fundamentals, Part 3
Linux Fundamentals, Part 4
LVM Fun
Making the Distribution, Part 1
Making the Distribution, Part 2
Making the Distribution, Part 3
Maximum Swappage Getting the most out of swap
On screen annotation Write on top of apps on your screen
OpenSSH Key Management, Part 1 Understanding RSA/DSA Authentication
OpenSSH Key Management, Part 2 Introducing ssh-agent and keychain
OpenSSH Key Management, Part 3 Agent Forwarding
Partition Planning Tips Keeping things organized on disk
Partitioning in Action, Part 1 Moving /home
Partitioning in Action, Part 2 Consolidating data
POSIX Threads Explained, Part 1 A simple and nimble tool for memory sharing
POSIX Threads Explained, Part 2
POSIX Threads Explained, Part 3 Improve efficiency with condition variables
Sed by Example, Part 1
Sed by Example, Part 2
Sed by Example, Part 3
Successful booting with UUID Guide to use UUID for consistent booting.
The Gentoo.org Redesign, Part 1 A site reborn
The Gentoo.org Redesign, Part 2 The Documentation System
The Gentoo.org Redesign, Part 3 The New Main Pages
The Gentoo.org Redesign, Part 4 The Final Touch of XML
Traffic Control
Windows 10 Virtualization with KVM