Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.14
1.14 ! markus 1: .\" $OpenBSD: ssh-agent.1,v 1.13 2000/07/06 04:06:56 aaron Exp $
1.7 markus 2: .\"
1.1 deraadt 3: .\" -*- nroff -*-
4: .\"
5: .\" ssh-agent.1
6: .\"
7: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
1.8 deraadt 8: .\"
1.1 deraadt 9: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
10: .\" All rights reserved
11: .\"
12: .\" Created: Sat Apr 23 20:10:43 1995 ylo
13: .\"
1.2 deraadt 14: .Dd September 25, 1999
15: .Dt SSH-AGENT 1
16: .Os
17: .Sh NAME
18: .Nm ssh-agent
19: .Nd authentication agent
20: .Sh SYNOPSIS
1.11 aaron 21: .Nm ssh-agent
1.7 markus 22: .Op Fl c Li | Fl s
23: .Op Fl k
24: .Oo
1.2 deraadt 25: .Ar command
1.7 markus 26: .Op Ar args ...
27: .Oc
1.11 aaron 28: .Sh DESCRIPTION
1.2 deraadt 29: .Nm
1.14 ! markus 30: is a program to hold private keys used for public key authentication
! 31: (RSA, DSA).
1.10 aaron 32: The idea is that
1.2 deraadt 33: .Nm
1.1 deraadt 34: is started in the beginning of an X-session or a login session, and
1.7 markus 35: all other windows or programs are started as clients to the ssh-agent
1.10 aaron 36: program.
37: Through use of environment variables the agent can be located
1.14 ! markus 38: and automatically used for authentication when logging in to other
1.1 deraadt 39: machines using
1.2 deraadt 40: .Xr ssh 1 .
41: .Pp
1.7 markus 42: The options are as follows:
43: .Bl -tag -width Ds
44: .It Fl c
45: Generate C-shell commands on
46: .Dv stdout .
47: This is the default if
48: .Ev SHELL
49: looks like it's a csh style of shell.
50: .It Fl s
51: Generate Bourne shell commands on
52: .Dv stdout .
53: This is the default if
54: .Ev SHELL
55: does not look like it's a csh style of shell.
56: .It Fl k
57: Kill the current agent (given by the
58: .Ev SSH_AGENT_PID
59: environment variable).
60: .El
61: .Pp
62: If a commandline is given, this is executed as a subprocess of the agent.
63: When the command dies, so does the agent.
64: .Pp
1.10 aaron 65: The agent initially does not have any private keys.
66: Keys are added using
1.2 deraadt 67: .Xr ssh-add 1 .
1.11 aaron 68: When executed without arguments,
1.2 deraadt 69: .Xr ssh-add 1
1.11 aaron 70: adds the
1.2 deraadt 71: .Pa $HOME/.ssh/identity
1.10 aaron 72: file.
1.11 aaron 73: If the identity has a passphrase,
1.2 deraadt 74: .Xr ssh-add 1
1.1 deraadt 75: asks for the passphrase (using a small X11 application if running
1.10 aaron 76: under X11, or from the terminal if running without X).
77: It then sends the identity to the agent.
78: Several identities can be stored in the
1.1 deraadt 79: agent; the agent can automatically use any of these identities.
1.2 deraadt 80: .Ic ssh-add -l
1.1 deraadt 81: displays the identities currently held by the agent.
1.2 deraadt 82: .Pp
1.1 deraadt 83: The idea is that the agent is run in the user's local PC, laptop, or
1.10 aaron 84: terminal.
85: Authentication data need not be stored on any other
1.1 deraadt 86: machine, and authentication passphrases never go over the network.
1.2 deraadt 87: However, the connection to the agent is forwarded over SSH
1.1 deraadt 88: remote logins, and the user can thus use the privileges given by the
89: identities anywhere in the network in a secure way.
1.2 deraadt 90: .Pp
1.10 aaron 91: There are two main ways to get an agent setup:
92: Either you let the agent
1.7 markus 93: start a new subcommand into which some environment variables are exported, or
94: you let the agent print the needed shell commands (either
95: .Xr sh 1
96: or
97: .Xr csh 1
98: syntax can be generated) which can be evalled in the calling shell.
99: Later
100: .Xr ssh 1
101: look at these variables and use them to establish a connection to the agent.
102: .Pp
1.4 markus 103: A unix-domain socket is created
1.7 markus 104: .Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> ,
1.2 deraadt 105: and the name of this socket is stored in the
1.5 markus 106: .Ev SSH_AUTH_SOCK
1.1 deraadt 107: environment
1.10 aaron 108: variable.
109: The socket is made accessible only to the current user.
1.1 deraadt 110: This method is easily abused by root or another instance of the same
1.4 markus 111: user.
1.7 markus 112: .Pp
113: The
114: .Ev SSH_AGENT_PID
115: environment variable holds the agent's PID.
1.2 deraadt 116: .Pp
1.1 deraadt 117: The agent exits automatically when the command given on the command
118: line terminates.
1.2 deraadt 119: .Sh FILES
120: .Bl -tag -width Ds
121: .It Pa $HOME/.ssh/identity
1.10 aaron 122: Contains the RSA authentication identity of the user.
123: This file should not be readable by anyone but the user.
124: It is possible to
1.1 deraadt 125: specify a passphrase when generating the key; that passphrase will be
1.10 aaron 126: used to encrypt the private part of this file.
127: This file is not used by
1.2 deraadt 128: .Nm
1.1 deraadt 129: but is normally added to the agent using
1.2 deraadt 130: .Xr ssh-add 1
1.1 deraadt 131: at login time.
1.14 ! markus 132: .It Pa $HOME/.ssh/id_dsa
! 133: Contains the DSA authentication identity of the user.
! 134: .Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> ,
1.1 deraadt 135: Unix-domain sockets used to contain the connection to the
1.10 aaron 136: authentication agent.
137: These sockets should only be readable by the owner.
138: The sockets should get automatically removed when the agent exits.
1.13 aaron 139: .El
1.2 deraadt 140: .Sh AUTHOR
1.1 deraadt 141: Tatu Ylonen <ylo@cs.hut.fi>
1.3 deraadt 142: .Pp
1.6 deraadt 143: OpenSSH
144: is a derivative of the original (free) ssh 1.2.12 release, but with bugs
1.10 aaron 145: removed and newer features re-added.
146: Rapidly after the 1.2.12 release,
147: newer versions bore successively more restrictive licenses.
148: This version of OpenSSH
1.6 deraadt 149: .Bl -bullet
150: .It
1.9 aaron 151: has all components of a restrictive nature (i.e., patents, see
1.6 deraadt 152: .Xr ssl 8 )
153: directly removed from the source code; any licensed or patented components
154: are chosen from
155: external libraries.
156: .It
157: has been updated to support ssh protocol 1.5.
158: .It
1.11 aaron 159: contains added support for
1.6 deraadt 160: .Xr kerberos 8
161: authentication and ticket passing.
162: .It
163: supports one-time password authentication with
164: .Xr skey 1 .
165: .El
166: .Pp
167: The libraries described in
1.3 deraadt 168: .Xr ssl 8
169: are required for proper operation.
1.2 deraadt 170: .Sh SEE ALSO
171: .Xr ssh 1 ,
172: .Xr ssh-add 1 ,
173: .Xr ssh-keygen 1 ,
1.3 deraadt 174: .Xr sshd 8 ,
175: .Xr ssl 8