~ubuntu-branches/ubuntu/raring/keychain/raring : revision 6

1

========================

2

Introduction to Keychain

3

========================

4

5

:keywords: keychain, funtoo, gentoo, Daniel Robbins

6

:description:

7

8

This page contains information about Keychain, an OpenSSH and

9

commercial SSH2-compatible RSA/DSA key management application.

10

11

:version: 2010.05.07

12

:author: Daniel Robbins

13

:contact: drobbins@funtoo.org

14

:copyright: funtoo

15

:language: English

16

17

Introduction

18

============

19

20

.. _keychain git repository: http://www.github.com/funtoo/keychain

21

.. _Common Threads\: OpenSSH key management, Part 1: http://www.ibm.com/developerworks/library/l-keyc.html

22

.. _Common Threads\: OpenSSH key management, Part 2: http://www.ibm.com/developerworks/library/l-keyc2/

23

.. _Common Threads\: OpenSSH key management, Part 3: http://www.ibm.com/developerworks/library/l-keyc3/

24

.. _OpenSSH: http://www.openssh.com

25

.. _funtoo-dev mailing list: http://groups.google.com/group/funtoo-dev

26

.. _#funtoo irc channel: irc://irc.freenode.net/funtoo

27

28

``Keychain`` helps you to manage ssh and GPG keys in a convenient and secure

29

manner. It acts as a frontend to ``ssh-agent`` and ``ssh-add``, but allows you

30

to easily have one long running ``ssh-agent`` process per system, rather than

31

the norm of one ``ssh-agent`` per login session.

32

33

This dramatically reduces the number of times you need to enter your

34

passphrase. With ``keychain``, you only need to enter a passphrase once every

35

time your local machine is rebooted. ``Keychain`` also makes it easy for remote

36

cron jobs to securely "hook in" to a long running ``ssh-agent`` process,

37

allowing your scripts to take advantage of key-based logins.

38

39

Download and Resources

40

======================

41

42

The latest release of keychain is version ``2.7.1``, and was released on

43

May 7, 2010. The current version of keychain supports ``gpg-agent`` as

44

well as ``ssh-agent``.

45

46

Keychain is compatible with many operating systems, including ``AIX``,

47

``*BSD``, ``Cygwin``, ``MacOS X``, ``Linux``, ``HP/UX``, ``Tru64 UNIX``,

48

``IRIX``, ``Solaris`` and ``GNU Hurd``.

49

50

51

.. _keychain 2.7.1: http://www.funtoo.org/archive/keychain/keychain-2.7.1.tar.bz2

52

53

.. _keychain 2.7.0 MacOS X package: http://www.funtoo.org/archive/keychain/keychain-2.7.0-macosx.tar.gz

54

.. _keychain 2.6.9 MacOS X package: http://www.funtoo.org/archive/keychain/keychain-2.6.9-macosx.tar.gz

55

56

Download

57

--------

58

59

- *Release Archive*

60

61

- `keychain 2.7.1`_

62

63

- *Apple MacOS X Packages*

64

65

- `keychain 2.7.0 MacOS X package`_

66

67

- `keychain 2.6.9 MacOS X package`_

68

69

Keychain development sources can be found in the `keychain git repository`_.

70

Please use the `funtoo-dev mailing list`_ and `#funtoo irc channel`_ for

71

keychain support questions as well as bug reports.

72

73

Quick Setup

74

===========

75

76

Linux

77

-----

78

79

To install under Gentoo or Funtoo Linux, type ``emerge keychain``. For other

80

Linux distributions, use your distribution's package manager. Then generate

81

RSA/DSA keys if necessary. The quick install docs assume you have a DSA key

82

pair named ``id_dsa`` and ``id_dsa.pub`` in your ``~/.ssh/`` directory. Add

83

the following to your ``~/.bash_profile``::

84

85

eval `keychain --eval --agents ssh id_dsa`

86

87

If you want to take advantage of GPG functionality, ensure that GNU Privacy

88

Guard is installed and omit the ``--agents ssh`` option above.

89

90

Apple MacOS X

91

-------------

92

93

To install under MacOS X, install the MacOS X package for keychain. Assuming

94

you have an ``id_dsa`` and ``id_dsa.pub`` key pair in your ``~/.ssh/``

95

directory, add the following to your ``~/.bash_profile``::

96

97

eval `keychain --eval --agents ssh --inherit any id_dsa`

98

99

The ``--inherit any`` option above causes keychain to inherit any ssh key

100

passphrases stored in your Apple MacOS Keychain. If you would prefer for this

101

to not happen, then this option can be omitted.

102

103

Background

104

==========

105

106

You're probably familiar with ``ssh``, which has become a secure replacement

107

for the venerable ``telnet`` and ``rsh`` commands.

108

109

Typically, when one uses ``ssh`` to connect to a remote system, one supplies

110

a secret passphrase to ``ssh``, which is then passed in encrypted form over

111

the network to the remote server. This passphrase is used by the remote

112

``sshd`` server to determine if you should be granted access to the system.

113

114

However, `OpenSSH` and nearly all other SSH clients and servers have the

115

ability to perform another type of authentication, called asymmetric public key

116

authentication, using the RSA or DSA authentication algorithms. They are

117

very useful, but can also be complicated to use. ``keychain`` has been

118

designed to make it easy to take advantage of the benefits of RSA and DSA

119

authentication.

120

121

Generating a Key Pair

122

=====================

123

124

To use RSA and DSA authentication, first you use a program called

125

``ssh-keygen`` (included with OpenSSH) to generate a *key pair* -- two small

126

files. One of the files is the *public key*. The other small file contains the

127

*private key*. ``ssh-keygen`` will ask you for a passphrase, and this

128

passphrase will be used to encrypt your private key. You will need to supply

129

this passphrase to use your private key. If you wanted to generate a DSA key

130

pair, you would do this::

131

132

# ssh-keygen -t dsa

133

Generating public/private dsa key pair.

134

135

You would then be prompted for a location to store your key pair. If you

136

do not have one currently stored in ``~/.ssh``, it is fine to accept the

137

default location::

138

139

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

140

141

Then, you are prompted for a passphrase. This passphrase is used to encrypt the

142

*private key* on disk, so even if it is stolen, it will be difficult for

143

someone else to use it to successfully authenticate as you with any accounts

144

that have been configured to recognize your public key.

145

146

Note that conversely, if you **do not** provide a passphrase for your private

147

key file, then your private key file **will not** be encrypted. This means that

148

if someone steals your private key file, *they will have the full ability to

149

authenticate with any remote accounts that are set up with your public key.*

150

151

Below, I have supplied a passphrase so that my private key file will be

152

encrypted on disk::

153

154

Enter passphrase (empty for no passphrase):

155

Enter same passphrase again:

156

Your identification has been saved in /var/tmp/id_dsa.

157

Your public key has been saved in /var/tmp/id_dsa.pub.

158

The key fingerprint is:

159

5c:13:ff:46:7d:b3:bf:0e:37:1e:5e:8c:7b:a3:88:f4 root@devbox-ve

160

The key's randomart image is:

161

+--[ DSA 1024]----+

162

| . |

163

| o . |

164

| o . ..o|

165

| . . . o +|

166

| S o. |

167

| . o.|

168

| . ..++|

169

| . o . =o*|

170

| . E .+*.|

171

+-----------------+

172

173

Setting up Authentication

174

=========================

175

176

Here's how you use these files to authenticate with a remote server. On the

177

remote server, you would append the contents of your *public key* to the

178

``~.ssh/authorized_keys`` file, if such a file exists. If it doesn't exist, you

179

can simply create a new ``authorized_keys`` file in the remote account's

180

``~/.ssh`` directory that contains the contents of your local ``id_dsa.pub``

181

file.

182

183

Then, if you weren't going to use ``keychain``, you'd perform the following

184

steps. On your local client, you would start a program called ``ssh-agent``,

185

which runs in the background. Then you would use a program called ``ssh-add``

186

to tell ``ssh-agent`` about your secret private key. Then, if you've set up

187

your environment properly, the next time you run ``ssh``, it will find

188

``ssh-agent`` running, grab the private key that you added to ``ssh-agent``

189

using ``ssh-add``, and use this key to authenticate with the remote server.

190

191

Again, the steps in the previous paragraph is what you'd do if ``keychain``

192

wasn't around to help. If you are using ``keychain``, and I hope you are, you

193

would simply add the following line to your ``~/.bash_profile``::

194

195

eval `keychain --eval id_dsa`

196

197

The next time you log in or source your ``~/.bash_profile``, ``keychain`` will

198

start, start ``ssh-agent`` for you if it has not yet been started, use

199

``ssh-add`` to add your ``id_dsa`` private key file to ``ssh-agent``, and set

200

up your shell environment so that ``ssh`` will be able to find ``ssh-agent``.

201

If ``ssh-agent`` is already running, ``keychain`` will ensure that your ``id_dsa``

202

private key has been added to ``ssh-agent`` and then set up your environment

203

so that ``ssh`` can find the already-running ``ssh-agent``. It will look

204

something like this:

205

206

.. figure:: keychain-1.png

207

:alt: Keychain starts for the first time after login

208

209

Note that when ``keychain`` runs for the first time after your local system has

210

booted, you will be prompted for a passphrase for your private key file if it

211

is encrypted. But here's the nice thing about using ``keychain`` -- even if

212

you are using an encrypted private key file, you will only need to enter your

213

passphrase when your system first boots (or in the case of a server, when you

214

first log in.) After that, ``ssh-agent`` is already running and has your

215

decrypted private key cached in memory. So if you open a new shell, you will

216

see something like this:

217

218

.. figure:: keychain-2.png

219

:alt: Keychain finds existing ssh-agent and gpg-agent, and doesn't prompt for passphrase

220

221

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

222

a passphrase.

223

224

You can also execute batch ``cron`` jobs and scripts that need

225

to use ``ssh`` or ``scp``, and they can take advantage of passwordless RSA/DSA

226

authentication as well. To do this, you would add the following line to

227

the top of a bash script::

228

229

eval `keychain --noask --eval id_dsa` || exit 1

230

231

The extra ``--noask`` option tells ``keychain`` that it should not prompt for a

232

passphrase if one is needed. Since it is not running interactively, it is

233

better for the script to fail if the decrypted private key isn't cached in

234

memory via ``ssh-agent``.

235

236

Keychain Options

237

================

238

239

Specifying Agents

240

-----------------

241

242

In the images above, you will note that ``keychain`` starts ``ssh-agent``, but also

243

starts ``gpg-agent``. Modern versions of ``keychain`` also support caching decrypted

244

GPG keys via use of ``gpg-agent``, and will start ``gpg-agent`` by default if it

245

is available on your system. To avoid this behavior and only start ``ssh-agent``,

246

modify your ``~/.bash_profile`` as follows::

247

248

eval `keychain --agents ssh --eval id_dsa` || exit 1

249

250

The additional ``--agents ssh`` option tells ``keychain`` just to manage ``ssh-agent``,

251

and ignore ``gpg-agent`` even if it is available.

252

253

Clearing Keys

254

-------------

255

256

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

257

this, type::

258

259

keychain --clear

260

261

Any agent(s) will continue to run.

262

263

Improving Security

264

------------------

265

266

To improve the security of ``keychain``, some people add the ``--clear`` option to

267

their ``~/.bash_profile`` ``keychain`` invocation. The rationale behind this is that

268

any user logging in should be assumed to be an intruder until proven otherwise. This

269

means that you will need to re-enter any passphrases when you log in, but cron jobs

270

will still be able to run when you log out.

271

272

Stopping Agents

273

---------------

274

275

If you want to stop all agents, which will also of course cause your

276

keys/identities to be flushed from memory, you can do this as follows::

277

278

keychain -k all

279

280

If you have other agents running under your user account, you can also tell

281

``keychain`` to just stop only the agents that ``keychain`` started::

282

283

keychain -k mine

284

285

Learning More

286

=============

287

288

The instructions above will work on any system that uses ``bash`` as its

289

default shell, such as most Linux systems and Mac OS X.

290

291

To learn more about the many things that ``keychain`` can do, including

292

alternate shell support, consult the keychain man page, or type ``keychain

293

--help | less`` for a full list of command options.

294

295

I also recommend you read my original series of articles about `OpenSSH`_ that

296

I wrote for IBM developerWorks, called ``OpenSSH Key Management``. Please note

297

that ``keychain`` 1.0 was released along with Part 2 of this article, which was

298

written in 2001. ``keychain`` has changed quite a bit since then. In other

299

words, read these articles for the conceptual and `OpenSSH`_ information, but

300

consult the ``keychain`` man page for command-line options and usage

301

instructions :)

302

303

- `Common Threads: OpenSSH key management, Part 1`_ - Understanding RSA/DSA Authentication

304

- `Common Threads: OpenSSH key management, Part 2`_ - Introducing ``ssh-agent`` and ``keychain``

305

- `Common Threads: OpenSSH key management, Part 3`_ - Agent forwarding and ``keychain`` improvements

306

307

As mentioned at the top of the page, ``keychain`` development sources can be

308

found in the `keychain git repository`_. Please use the `funtoo-dev mailing

309

list`_ and `#funtoo irc channel`_ for keychain support questions as well as bug

310

reports.

311

312

Project History

313

===============

314

315

Daniel Robbins originally wrote ``keychain`` 1.0 through 2.0.3. 1.0 was written

316

around June 2001, and 2.0.3 was released in late August, 2002.

317

318

After 2.0.3, ``keychain`` was maintained by various Gentoo developers,

319

including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3,

320

2003.

321

322

On April 21, 2004, Aron Griffis committed a major rewrite of ``keychain`` which

323

was released as 2.2.0. Aron continued to actively maintain and improve

324

``keychain`` through October 2006 and the ``keychain`` 2.6.8 release. He also

325

made a few commits after that date, up through mid-July, 2007. At this point,

326

``keychain`` had reached a point of maturity.

327

328

.. _bugs.gentoo.org: http://bugs.gentoo.org

329

330

In mid-July, 2009, Daniel Robbins migrated Aron's mercurial repository to git

331

and set up a new project page on funtoo.org, and made a few bug fix commits to

332

the git repo that had been collecting in `bugs.gentoo.org`_. Daniel continues

333

to maintain ``keychain`` and supporting documentation on funtoo.org, and

334

plans to make regular maintenance releases of ``keychain`` as needed.

335