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