Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.17
1.17 ! aaron 1: .\" $OpenBSD: ssh-agent.1,v 1.16 2000/09/07 20:27:54 deraadt Exp $
1.7 markus 2: .\"
1.16 deraadt 3: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5: .\" All rights reserved
1.1 deraadt 6: .\"
1.16 deraadt 7: .\" As far as I am concerned, the code I have written for this software
8: .\" can be used freely for any purpose. Any derived versions of this
9: .\" software must be clearly marked as such, and if the derived work is
10: .\" incompatible with the protocol description in the RFC file, it must be
11: .\" called by a name other than "ssh" or "Secure Shell".
1.1 deraadt 12: .\"
1.16 deraadt 13: .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14: .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15: .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
1.8 deraadt 16: .\"
1.16 deraadt 17: .\" Redistribution and use in source and binary forms, with or without
18: .\" modification, are permitted provided that the following conditions
19: .\" are met:
20: .\" 1. Redistributions of source code must retain the above copyright
21: .\" notice, this list of conditions and the following disclaimer.
22: .\" 2. Redistributions in binary form must reproduce the above copyright
23: .\" notice, this list of conditions and the following disclaimer in the
24: .\" documentation and/or other materials provided with the distribution.
1.1 deraadt 25: .\"
1.16 deraadt 26: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.1 deraadt 36: .\"
1.2 deraadt 37: .Dd September 25, 1999
38: .Dt SSH-AGENT 1
39: .Os
40: .Sh NAME
41: .Nm ssh-agent
42: .Nd authentication agent
43: .Sh SYNOPSIS
1.11 aaron 44: .Nm ssh-agent
1.7 markus 45: .Op Fl c Li | Fl s
46: .Op Fl k
47: .Oo
1.2 deraadt 48: .Ar command
1.7 markus 49: .Op Ar args ...
50: .Oc
1.11 aaron 51: .Sh DESCRIPTION
1.2 deraadt 52: .Nm
1.14 markus 53: is a program to hold private keys used for public key authentication
54: (RSA, DSA).
1.10 aaron 55: The idea is that
1.2 deraadt 56: .Nm
1.1 deraadt 57: is started in the beginning of an X-session or a login session, and
1.7 markus 58: all other windows or programs are started as clients to the ssh-agent
1.10 aaron 59: program.
60: Through use of environment variables the agent can be located
1.14 markus 61: and automatically used for authentication when logging in to other
1.1 deraadt 62: machines using
1.2 deraadt 63: .Xr ssh 1 .
64: .Pp
1.7 markus 65: The options are as follows:
66: .Bl -tag -width Ds
67: .It Fl c
68: Generate C-shell commands on
69: .Dv stdout .
70: This is the default if
71: .Ev SHELL
72: looks like it's a csh style of shell.
73: .It Fl s
74: Generate Bourne shell commands on
75: .Dv stdout .
76: This is the default if
77: .Ev SHELL
78: does not look like it's a csh style of shell.
79: .It Fl k
80: Kill the current agent (given by the
81: .Ev SSH_AGENT_PID
82: environment variable).
83: .El
84: .Pp
85: If a commandline is given, this is executed as a subprocess of the agent.
86: When the command dies, so does the agent.
87: .Pp
1.10 aaron 88: The agent initially does not have any private keys.
89: Keys are added using
1.2 deraadt 90: .Xr ssh-add 1 .
1.11 aaron 91: When executed without arguments,
1.2 deraadt 92: .Xr ssh-add 1
1.11 aaron 93: adds the
1.2 deraadt 94: .Pa $HOME/.ssh/identity
1.10 aaron 95: file.
1.11 aaron 96: If the identity has a passphrase,
1.2 deraadt 97: .Xr ssh-add 1
1.1 deraadt 98: asks for the passphrase (using a small X11 application if running
1.10 aaron 99: under X11, or from the terminal if running without X).
100: It then sends the identity to the agent.
101: Several identities can be stored in the
1.1 deraadt 102: agent; the agent can automatically use any of these identities.
1.2 deraadt 103: .Ic ssh-add -l
1.1 deraadt 104: displays the identities currently held by the agent.
1.2 deraadt 105: .Pp
1.1 deraadt 106: The idea is that the agent is run in the user's local PC, laptop, or
1.10 aaron 107: terminal.
108: Authentication data need not be stored on any other
1.1 deraadt 109: machine, and authentication passphrases never go over the network.
1.2 deraadt 110: However, the connection to the agent is forwarded over SSH
1.1 deraadt 111: remote logins, and the user can thus use the privileges given by the
112: identities anywhere in the network in a secure way.
1.2 deraadt 113: .Pp
1.10 aaron 114: There are two main ways to get an agent setup:
115: Either you let the agent
1.7 markus 116: start a new subcommand into which some environment variables are exported, or
117: you let the agent print the needed shell commands (either
118: .Xr sh 1
119: or
120: .Xr csh 1
121: syntax can be generated) which can be evalled in the calling shell.
122: Later
123: .Xr ssh 1
124: look at these variables and use them to establish a connection to the agent.
125: .Pp
1.4 markus 126: A unix-domain socket is created
1.7 markus 127: .Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> ,
1.2 deraadt 128: and the name of this socket is stored in the
1.5 markus 129: .Ev SSH_AUTH_SOCK
1.1 deraadt 130: environment
1.10 aaron 131: variable.
132: The socket is made accessible only to the current user.
1.1 deraadt 133: This method is easily abused by root or another instance of the same
1.4 markus 134: user.
1.7 markus 135: .Pp
136: The
137: .Ev SSH_AGENT_PID
138: environment variable holds the agent's PID.
1.2 deraadt 139: .Pp
1.1 deraadt 140: The agent exits automatically when the command given on the command
141: line terminates.
1.2 deraadt 142: .Sh FILES
143: .Bl -tag -width Ds
144: .It Pa $HOME/.ssh/identity
1.10 aaron 145: Contains the RSA authentication identity of the user.
146: This file should not be readable by anyone but the user.
147: It is possible to
1.1 deraadt 148: specify a passphrase when generating the key; that passphrase will be
1.10 aaron 149: used to encrypt the private part of this file.
150: This file is not used by
1.2 deraadt 151: .Nm
1.1 deraadt 152: but is normally added to the agent using
1.2 deraadt 153: .Xr ssh-add 1
1.1 deraadt 154: at login time.
1.14 markus 155: .It Pa $HOME/.ssh/id_dsa
156: Contains the DSA authentication identity of the user.
157: .Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> ,
1.1 deraadt 158: Unix-domain sockets used to contain the connection to the
1.10 aaron 159: authentication agent.
160: These sockets should only be readable by the owner.
161: The sockets should get automatically removed when the agent exits.
1.13 aaron 162: .El
1.17 ! aaron 163: .Sh AUTHORS
1.1 deraadt 164: Tatu Ylonen <ylo@cs.hut.fi>
1.3 deraadt 165: .Pp
1.6 deraadt 166: OpenSSH
167: is a derivative of the original (free) ssh 1.2.12 release, but with bugs
1.10 aaron 168: removed and newer features re-added.
169: Rapidly after the 1.2.12 release,
170: newer versions bore successively more restrictive licenses.
171: This version of OpenSSH
1.6 deraadt 172: .Bl -bullet
173: .It
1.9 aaron 174: has all components of a restrictive nature (i.e., patents, see
1.6 deraadt 175: .Xr ssl 8 )
176: directly removed from the source code; any licensed or patented components
177: are chosen from
178: external libraries.
179: .It
180: has been updated to support ssh protocol 1.5.
181: .It
1.11 aaron 182: contains added support for
1.6 deraadt 183: .Xr kerberos 8
184: authentication and ticket passing.
185: .It
186: supports one-time password authentication with
187: .Xr skey 1 .
188: .El
1.2 deraadt 189: .Sh SEE ALSO
190: .Xr ssh 1 ,
191: .Xr ssh-add 1 ,
192: .Xr ssh-keygen 1 ,
1.3 deraadt 193: .Xr sshd 8 ,
194: .Xr ssl 8
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh-agent.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh