Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.31.2.1
1.31.2.1! jason 1: .\" $OpenBSD: ssh-agent.1,v 1.35 2002/06/24 13:12:23 markus 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.22 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.31.2.1! jason 45: .Op Fl a Ar bind_address
1.27 stevesk 46: .Op Fl c Li | Fl s
47: .Op Fl d
48: .Op Ar command Op Ar args ...
1.18 markus 49: .Nm ssh-agent
1.7 markus 50: .Op Fl c Li | Fl s
1.18 markus 51: .Fl k
1.11 aaron 52: .Sh DESCRIPTION
1.2 deraadt 53: .Nm
1.14 markus 54: is a program to hold private keys used for public key authentication
55: (RSA, DSA).
1.10 aaron 56: The idea is that
1.2 deraadt 57: .Nm
1.1 deraadt 58: is started in the beginning of an X-session or a login session, and
1.7 markus 59: all other windows or programs are started as clients to the ssh-agent
1.10 aaron 60: program.
61: Through use of environment variables the agent can be located
1.14 markus 62: and automatically used for authentication when logging in to other
1.1 deraadt 63: machines using
1.2 deraadt 64: .Xr ssh 1 .
65: .Pp
1.7 markus 66: The options are as follows:
67: .Bl -tag -width Ds
1.31.2.1! jason 68: .It Fl a Ar bind_address
! 69: Bind the agent to the unix-domain socket
! 70: .Ar bind_address .
! 71: The default is
! 72: .Pa /tmp/ssh-XXXXXXXX/agent.<ppid> .
1.7 markus 73: .It Fl c
74: Generate C-shell commands on
75: .Dv stdout .
76: This is the default if
77: .Ev SHELL
78: looks like it's a csh style of shell.
79: .It Fl s
80: Generate Bourne shell commands on
81: .Dv stdout .
82: This is the default if
83: .Ev SHELL
84: does not look like it's a csh style of shell.
85: .It Fl k
86: Kill the current agent (given by the
87: .Ev SSH_AGENT_PID
88: environment variable).
1.25 markus 89: .It Fl d
90: Debug mode. When this option is specified
91: .Nm
1.26 stevesk 92: will not fork.
1.7 markus 93: .El
94: .Pp
95: If a commandline is given, this is executed as a subprocess of the agent.
96: When the command dies, so does the agent.
97: .Pp
1.10 aaron 98: The agent initially does not have any private keys.
99: Keys are added using
1.2 deraadt 100: .Xr ssh-add 1 .
1.11 aaron 101: When executed without arguments,
1.2 deraadt 102: .Xr ssh-add 1
1.30 stevesk 103: adds the files
104: .Pa $HOME/.ssh/id_rsa ,
1.31.2.1! jason 105: .Pa $HOME/.ssh/id_dsa
1.30 stevesk 106: and
107: .Pa $HOME/.ssh/identity .
1.11 aaron 108: If the identity has a passphrase,
1.2 deraadt 109: .Xr ssh-add 1
1.1 deraadt 110: asks for the passphrase (using a small X11 application if running
1.10 aaron 111: under X11, or from the terminal if running without X).
112: It then sends the identity to the agent.
113: Several identities can be stored in the
1.1 deraadt 114: agent; the agent can automatically use any of these identities.
1.2 deraadt 115: .Ic ssh-add -l
1.1 deraadt 116: displays the identities currently held by the agent.
1.2 deraadt 117: .Pp
1.1 deraadt 118: The idea is that the agent is run in the user's local PC, laptop, or
1.10 aaron 119: terminal.
120: Authentication data need not be stored on any other
1.1 deraadt 121: machine, and authentication passphrases never go over the network.
1.2 deraadt 122: However, the connection to the agent is forwarded over SSH
1.1 deraadt 123: remote logins, and the user can thus use the privileges given by the
124: identities anywhere in the network in a secure way.
1.2 deraadt 125: .Pp
1.10 aaron 126: There are two main ways to get an agent setup:
1.28 deraadt 127: Either the agent starts a new subcommand into which some environment
128: variables are exported, or the agent prints the needed shell commands
129: (either
1.7 markus 130: .Xr sh 1
131: or
132: .Xr csh 1
133: syntax can be generated) which can be evalled in the calling shell.
134: Later
135: .Xr ssh 1
1.23 deraadt 136: looks at these variables and uses them to establish a connection to the agent.
1.29 stevesk 137: .Pp
138: The agent will never send a private key over its request channel.
139: Instead, operations that require a private key will be performed
140: by the agent, and the result will be returned to the requester.
141: This way, private keys are not exposed to clients using the agent.
1.7 markus 142: .Pp
1.4 markus 143: A unix-domain socket is created
1.2 deraadt 144: and the name of this socket is stored in the
1.5 markus 145: .Ev SSH_AUTH_SOCK
1.1 deraadt 146: environment
1.10 aaron 147: variable.
148: The socket is made accessible only to the current user.
1.1 deraadt 149: This method is easily abused by root or another instance of the same
1.4 markus 150: user.
1.7 markus 151: .Pp
152: The
153: .Ev SSH_AGENT_PID
1.31.2.1! jason 154: environment variable holds the agent's process ID.
1.2 deraadt 155: .Pp
1.1 deraadt 156: The agent exits automatically when the command given on the command
157: line terminates.
1.2 deraadt 158: .Sh FILES
159: .Bl -tag -width Ds
160: .It Pa $HOME/.ssh/identity
1.24 itojun 161: Contains the protocol version 1 RSA authentication identity of the user.
1.14 markus 162: .It Pa $HOME/.ssh/id_dsa
1.24 itojun 163: Contains the protocol version 2 DSA authentication identity of the user.
164: .It Pa $HOME/.ssh/id_rsa
165: Contains the protocol version 2 RSA authentication identity of the user.
1.31.2.1! jason 166: .It Pa /tmp/ssh-XXXXXXXX/agent.<ppid>
1.1 deraadt 167: Unix-domain sockets used to contain the connection to the
1.10 aaron 168: authentication agent.
169: These sockets should only be readable by the owner.
170: The sockets should get automatically removed when the agent exits.
1.13 aaron 171: .El
1.17 aaron 172: .Sh AUTHORS
1.20 markus 173: OpenSSH is a derivative of the original and free
174: ssh 1.2.12 release by Tatu Ylonen.
175: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
176: Theo de Raadt and Dug Song
177: removed many bugs, re-added newer features and
178: created OpenSSH.
179: Markus Friedl contributed the support for SSH
180: protocol versions 1.5 and 2.0.
1.2 deraadt 181: .Sh SEE ALSO
182: .Xr ssh 1 ,
183: .Xr ssh-add 1 ,
184: .Xr ssh-keygen 1 ,
1.21 itojun 185: .Xr sshd 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