Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.76
1.76 ! djm 1: .\" $OpenBSD: ssh-agent.1,v 1.75 2022/10/07 06:00:58 jmc 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.75 jmc 37: .Dd $Mdocdate: October 7 2022 $
1.2 deraadt 38: .Dt SSH-AGENT 1
39: .Os
40: .Sh NAME
41: .Nm ssh-agent
1.69 jmc 42: .Nd OpenSSH authentication agent
1.2 deraadt 43: .Sh SYNOPSIS
1.11 aaron 44: .Nm ssh-agent
1.52 jmc 45: .Op Fl c | s
1.67 jmc 46: .Op Fl \&Dd
1.32 markus 47: .Op Fl a Ar bind_address
1.57 djm 48: .Op Fl E Ar fingerprint_hash
1.74 djm 49: .Op Fl O Ar option
1.72 djm 50: .Op Fl P Ar allowed_providers
1.36 marc 51: .Op Fl t Ar life
1.71 dtucker 52: .Nm ssh-agent
53: .Op Fl a Ar bind_address
54: .Op Fl E Ar fingerprint_hash
1.74 djm 55: .Op Fl O Ar option
1.72 djm 56: .Op Fl P Ar allowed_providers
1.71 dtucker 57: .Op Fl t Ar life
58: .Ar command Op Ar arg ...
1.67 jmc 59: .Nm ssh-agent
60: .Op Fl c | s
61: .Fl k
1.11 aaron 62: .Sh DESCRIPTION
1.2 deraadt 63: .Nm
1.68 jmc 64: is a program to hold private keys used for public key authentication.
1.10 aaron 65: Through use of environment variables the agent can be located
1.14 markus 66: and automatically used for authentication when logging in to other
1.1 deraadt 67: machines using
1.2 deraadt 68: .Xr ssh 1 .
69: .Pp
1.7 markus 70: The options are as follows:
71: .Bl -tag -width Ds
1.32 markus 72: .It Fl a Ar bind_address
1.48 sobrado 73: Bind the agent to the
1.49 sobrado 74: .Ux Ns -domain
75: socket
1.32 markus 76: .Ar bind_address .
77: The default is
1.53 djm 78: .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
1.7 markus 79: .It Fl c
80: Generate C-shell commands on
81: .Dv stdout .
82: This is the default if
83: .Ev SHELL
84: looks like it's a csh style of shell.
1.58 djm 85: .It Fl D
86: Foreground mode.
1.73 naddy 87: When this option is specified,
1.58 djm 88: .Nm
89: will not fork.
1.46 sobrado 90: .It Fl d
91: Debug mode.
1.73 naddy 92: When this option is specified,
1.46 sobrado 93: .Nm
1.58 djm 94: will not fork and will write debug information to standard error.
1.57 djm 95: .It Fl E Ar fingerprint_hash
96: Specifies the hash algorithm used when displaying key fingerprints.
97: Valid options are:
98: .Dq md5
99: and
100: .Dq sha256 .
101: The default is
102: .Dq sha256 .
1.46 sobrado 103: .It Fl k
104: Kill the current agent (given by the
105: .Ev SSH_AGENT_PID
106: environment variable).
1.74 djm 107: .It Fl O Ar option
108: Specify an option when starting
1.75 jmc 109: .Nm .
1.76 ! djm 110: Currently two options are supported:
! 111: .Cm allow-remote-pkcs11
! 112: and
1.74 djm 113: .Cm no-restrict-websafe .
1.76 ! djm 114: .Pp
! 115: The
! 116: .Cm allow-remote-pkcs11
! 117: option allows clients of a forwarded
! 118: .Nm
! 119: to load PKCS#11 or FIDO provider libraries.
! 120: By default only local clients may perform this operation.
! 121: Note that signalling that a
! 122: .Nm
! 123: client remote is performed by
! 124: .Xr ssh 1 ,
! 125: and use of other tools to forward access to the agent socket may circumvent
! 126: this restriction.
! 127: .Pp
! 128: The
! 129: .Cm no-restrict-websafe ,
! 130: instructs
1.75 jmc 131: .Nm
1.74 djm 132: to permit signatures using FIDO keys that might be web authentication
133: requests.
134: By default,
1.75 jmc 135: .Nm
1.74 djm 136: refuses signature requests for FIDO keys where the key application string
137: does not start with
138: .Dq ssh:
139: and when the data to be signed does not appear to be a
140: .Xr ssh 1
141: user authentication request or a
142: .Xr ssh-keygen 1
143: signature.
144: The default behaviour prevents forwarded access to a FIDO key from also
145: implicitly forwarding the ability to authenticate to websites.
1.72 djm 146: .It Fl P Ar allowed_providers
147: Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO
148: authenticator middleware shared libraries that may be used with the
1.68 jmc 149: .Fl S
150: or
1.63 djm 151: .Fl s
1.65 djm 152: options to
1.63 djm 153: .Xr ssh-add 1 .
1.72 djm 154: Libraries that do not match the pattern list will be refused.
1.63 djm 155: See PATTERNS in
156: .Xr ssh_config 5
157: for a description of pattern-list syntax.
1.72 djm 158: The default list is
1.68 jmc 159: .Dq /usr/lib/*,/usr/local/lib/* .
1.7 markus 160: .It Fl s
161: Generate Bourne shell commands on
162: .Dv stdout .
163: This is the default if
164: .Ev SHELL
165: does not look like it's a csh style of shell.
1.36 marc 166: .It Fl t Ar life
1.37 jmc 167: Set a default value for the maximum lifetime of identities added to the agent.
1.36 marc 168: The lifetime may be specified in seconds or in a time format specified in
1.43 dtucker 169: .Xr sshd_config 5 .
1.36 marc 170: A lifetime specified for an identity with
171: .Xr ssh-add 1
172: overrides this value.
173: Without this option the default maximum lifetime is forever.
1.68 jmc 174: .It Ar command Op Ar arg ...
175: If a command (and optional arguments) is given,
176: this is executed as a subprocess of the agent.
177: The agent exits automatically when the command given on the command
178: line terminates.
1.7 markus 179: .El
180: .Pp
1.68 jmc 181: There are two main ways to get an agent set up.
182: The first is at the start of an X session,
183: where all other windows or programs are started as children of the
184: .Nm
185: program.
186: The agent starts a command under which its environment
187: variables are exported, for example
188: .Cm ssh-agent xterm & .
189: When the command terminates, so does the agent.
1.7 markus 190: .Pp
1.68 jmc 191: The second method is used for a login session.
192: When
193: .Nm
194: is started,
195: it prints the shell commands required to set its environment variables,
196: which in turn can be evaluated in the calling shell, for example
197: .Cm eval `ssh-agent -s` .
1.40 dtucker 198: .Pp
1.68 jmc 199: In both cases,
1.7 markus 200: .Xr ssh 1
1.75 jmc 201: looks at these environment variables
202: and uses them to establish a connection to the agent.
1.29 stevesk 203: .Pp
1.68 jmc 204: The agent initially does not have any private keys.
205: Keys are added using
206: .Xr ssh-add 1
207: or by
208: .Xr ssh 1
209: when
210: .Cm AddKeysToAgent
211: is set in
212: .Xr ssh_config 5 .
213: Multiple identities may be stored in
214: .Nm
215: concurrently and
216: .Xr ssh 1
217: will automatically use them if present.
218: .Xr ssh-add 1
219: is also used to remove keys from
220: .Nm
221: and to query the keys that are held in one.
1.7 markus 222: .Pp
1.68 jmc 223: Connections to
224: .Nm
225: may be forwarded from further remote hosts using the
226: .Fl A
227: option to
228: .Xr ssh 1
229: (but see the caveats documented therein),
230: avoiding the need for authentication data to be stored on other machines.
231: Authentication passphrases and private keys never go over the network:
232: the connection to the agent is forwarded over SSH remote connections
233: and the result is returned to the requester,
234: allowing the user access to their identities anywhere in the network
235: in a secure fashion.
236: .Sh ENVIRONMENT
237: .Bl -tag -width "SSH_AGENT_PID"
238: .It Ev SSH_AGENT_PID
239: When
240: .Nm
241: starts, it stores the name of the agent's process ID (PID) in this variable.
242: .It Ev SSH_AUTH_SOCK
243: When
244: .Nm
245: starts, it creates a
1.49 sobrado 246: .Ux Ns -domain
1.68 jmc 247: socket and stores its pathname in this variable.
248: It is accessible only to the current user,
249: but is easily abused by root or another instance of the same user.
250: .El
1.2 deraadt 251: .Sh FILES
252: .Bl -tag -width Ds
1.64 jmc 253: .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
1.49 sobrado 254: .Ux Ns -domain
255: sockets used to contain the connection to the authentication agent.
1.10 aaron 256: These sockets should only be readable by the owner.
257: The sockets should get automatically removed when the agent exits.
1.13 aaron 258: .El
1.39 jmc 259: .Sh SEE ALSO
260: .Xr ssh 1 ,
261: .Xr ssh-add 1 ,
262: .Xr ssh-keygen 1 ,
1.68 jmc 263: .Xr ssh_config 5 ,
1.39 jmc 264: .Xr sshd 8
1.17 aaron 265: .Sh AUTHORS
1.64 jmc 266: .An -nosplit
267: OpenSSH is a derivative of the original and free ssh 1.2.12 release by
268: .An Tatu Ylonen .
269: .An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
270: and
271: .An Dug Song
272: removed many bugs, re-added newer features and created OpenSSH.
273: .An Markus Friedl
274: contributed the support for SSH protocol versions 1.5 and 2.0.
![[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