Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.54
1.54 ! naddy 1: .\" $OpenBSD: ssh-agent.1,v 1.53 2010/11/21 01:01:13 djm 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.54 ! naddy 37: .Dd $Mdocdate: November 21 2010 $
1.2 deraadt 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.52 jmc 45: .Op Fl c | s
1.46 sobrado 46: .Op Fl d
1.32 markus 47: .Op Fl a Ar bind_address
1.36 marc 48: .Op Fl t Ar life
1.46 sobrado 49: .Op Ar command Op Ar arg ...
1.18 markus 50: .Nm ssh-agent
1.52 jmc 51: .Op Fl c | s
1.18 markus 52: .Fl k
1.11 aaron 53: .Sh DESCRIPTION
1.2 deraadt 54: .Nm
1.14 markus 55: is a program to hold private keys used for public key authentication
1.54 ! naddy 56: (RSA, DSA, ECDSA, ED25519).
1.10 aaron 57: The idea is that
1.2 deraadt 58: .Nm
1.1 deraadt 59: is started in the beginning of an X-session or a login session, and
1.7 markus 60: all other windows or programs are started as clients to the ssh-agent
1.10 aaron 61: program.
62: Through use of environment variables the agent can be located
1.14 markus 63: and automatically used for authentication when logging in to other
1.1 deraadt 64: machines using
1.2 deraadt 65: .Xr ssh 1 .
66: .Pp
1.7 markus 67: The options are as follows:
68: .Bl -tag -width Ds
1.32 markus 69: .It Fl a Ar bind_address
1.48 sobrado 70: Bind the agent to the
1.49 sobrado 71: .Ux Ns -domain
72: socket
1.32 markus 73: .Ar bind_address .
74: The default is
1.53 djm 75: .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
1.7 markus 76: .It Fl c
77: Generate C-shell commands on
78: .Dv stdout .
79: This is the default if
80: .Ev SHELL
81: looks like it's a csh style of shell.
1.46 sobrado 82: .It Fl d
83: Debug mode.
84: When this option is specified
85: .Nm
86: will not fork.
87: .It Fl k
88: Kill the current agent (given by the
89: .Ev SSH_AGENT_PID
90: environment variable).
1.7 markus 91: .It Fl s
92: Generate Bourne shell commands on
93: .Dv stdout .
94: This is the default if
95: .Ev SHELL
96: does not look like it's a csh style of shell.
1.36 marc 97: .It Fl t Ar life
1.37 jmc 98: Set a default value for the maximum lifetime of identities added to the agent.
1.36 marc 99: The lifetime may be specified in seconds or in a time format specified in
1.43 dtucker 100: .Xr sshd_config 5 .
1.36 marc 101: A lifetime specified for an identity with
102: .Xr ssh-add 1
103: overrides this value.
104: Without this option the default maximum lifetime is forever.
1.7 markus 105: .El
106: .Pp
107: If a commandline is given, this is executed as a subprocess of the agent.
108: When the command dies, so does the agent.
109: .Pp
1.10 aaron 110: The agent initially does not have any private keys.
111: Keys are added using
1.2 deraadt 112: .Xr ssh-add 1 .
1.11 aaron 113: When executed without arguments,
1.2 deraadt 114: .Xr ssh-add 1
1.30 stevesk 115: adds the files
1.42 djm 116: .Pa ~/.ssh/id_rsa ,
1.51 djm 117: .Pa ~/.ssh/id_dsa ,
1.54 ! naddy 118: .Pa ~/.ssh/id_ecdsa ,
! 119: .Pa ~/.ssh/id_ed25519
1.30 stevesk 120: and
1.42 djm 121: .Pa ~/.ssh/identity .
1.11 aaron 122: If the identity has a passphrase,
1.2 deraadt 123: .Xr ssh-add 1
1.50 tedu 124: asks for the passphrase on the terminal if it has one or from a small X11
125: program if running under X11.
126: If neither of these is the case then the authentication will fail.
1.10 aaron 127: It then sends the identity to the agent.
128: Several identities can be stored in the
1.1 deraadt 129: agent; the agent can automatically use any of these identities.
1.2 deraadt 130: .Ic ssh-add -l
1.1 deraadt 131: displays the identities currently held by the agent.
1.2 deraadt 132: .Pp
1.1 deraadt 133: The idea is that the agent is run in the user's local PC, laptop, or
1.10 aaron 134: terminal.
135: Authentication data need not be stored on any other
1.1 deraadt 136: machine, and authentication passphrases never go over the network.
1.2 deraadt 137: However, the connection to the agent is forwarded over SSH
1.1 deraadt 138: remote logins, and the user can thus use the privileges given by the
139: identities anywhere in the network in a secure way.
1.2 deraadt 140: .Pp
1.38 jmc 141: There are two main ways to get an agent set up:
1.40 dtucker 142: The first is that the agent starts a new subcommand into which some environment
143: variables are exported, eg
144: .Cm ssh-agent xterm & .
145: The second is that the agent prints the needed shell commands (either
1.7 markus 146: .Xr sh 1
147: or
148: .Xr csh 1
1.47 sobrado 149: syntax can be generated) which can be evaluated in the calling shell, eg
1.40 dtucker 150: .Cm eval `ssh-agent -s`
151: for Bourne-type shells such as
152: .Xr sh 1
153: or
154: .Xr ksh 1
155: and
1.41 deraadt 156: .Cm eval `ssh-agent -c`
1.40 dtucker 157: for
158: .Xr csh 1
159: and derivatives.
160: .Pp
1.7 markus 161: Later
162: .Xr ssh 1
1.23 deraadt 163: looks at these variables and uses them to establish a connection to the agent.
1.29 stevesk 164: .Pp
165: The agent will never send a private key over its request channel.
166: Instead, operations that require a private key will be performed
167: by the agent, and the result will be returned to the requester.
168: This way, private keys are not exposed to clients using the agent.
1.7 markus 169: .Pp
1.48 sobrado 170: A
1.49 sobrado 171: .Ux Ns -domain
172: socket is created and the name of this socket is stored in the
1.5 markus 173: .Ev SSH_AUTH_SOCK
1.1 deraadt 174: environment
1.10 aaron 175: variable.
176: The socket is made accessible only to the current user.
1.1 deraadt 177: This method is easily abused by root or another instance of the same
1.4 markus 178: user.
1.7 markus 179: .Pp
180: The
181: .Ev SSH_AGENT_PID
1.34 stevesk 182: environment variable holds the agent's process ID.
1.2 deraadt 183: .Pp
1.1 deraadt 184: The agent exits automatically when the command given on the command
185: line terminates.
1.2 deraadt 186: .Sh FILES
187: .Bl -tag -width Ds
1.42 djm 188: .It Pa ~/.ssh/identity
1.24 itojun 189: Contains the protocol version 1 RSA authentication identity of the user.
1.42 djm 190: .It Pa ~/.ssh/id_dsa
1.24 itojun 191: Contains the protocol version 2 DSA authentication identity of the user.
1.51 djm 192: .It Pa ~/.ssh/id_ecdsa
193: Contains the protocol version 2 ECDSA authentication identity of the user.
1.54 ! naddy 194: .It Pa ~/.ssh/id_ed25519
! 195: Contains the protocol version 2 ED25519 authentication identity of the user.
1.42 djm 196: .It Pa ~/.ssh/id_rsa
1.24 itojun 197: Contains the protocol version 2 RSA authentication identity of the user.
1.53 djm 198: .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt
1.49 sobrado 199: .Ux Ns -domain
200: sockets used to contain the connection to the authentication agent.
1.10 aaron 201: These sockets should only be readable by the owner.
202: The sockets should get automatically removed when the agent exits.
1.13 aaron 203: .El
1.39 jmc 204: .Sh SEE ALSO
205: .Xr ssh 1 ,
206: .Xr ssh-add 1 ,
207: .Xr ssh-keygen 1 ,
208: .Xr sshd 8
1.17 aaron 209: .Sh AUTHORS
1.20 markus 210: OpenSSH is a derivative of the original and free
211: ssh 1.2.12 release by Tatu Ylonen.
212: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
213: Theo de Raadt and Dug Song
214: removed many bugs, re-added newer features and
215: created OpenSSH.
216: Markus Friedl contributed the support for SSH
217: protocol versions 1.5 and 2.0.