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