logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ssh-agent.1 (9256B)


  1. .\" $OpenBSD: ssh-agent.1,v 1.82 2025/02/09 18:24:08 schwarze Exp $
  2. .\"
  3. .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
  4. .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
  5. .\" All rights reserved
  6. .\"
  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".
  12. .\"
  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.
  16. .\"
  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.
  25. .\"
  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.
  36. .\"
  37. .Dd $Mdocdate: February 9 2025 $
  38. .Dt SSH-AGENT 1
  39. .Os
  40. .Sh NAME
  41. .Nm ssh-agent
  42. .Nd OpenSSH authentication agent
  43. .Sh SYNOPSIS
  44. .Nm ssh-agent
  45. .Op Fl c | s
  46. .Op Fl \&Dd
  47. .Op Fl a Ar bind_address
  48. .Op Fl E Ar fingerprint_hash
  49. .Op Fl O Ar option
  50. .Op Fl P Ar allowed_providers
  51. .Op Fl t Ar life
  52. .Nm ssh-agent
  53. .Op Fl a Ar bind_address
  54. .Op Fl E Ar fingerprint_hash
  55. .Op Fl O Ar option
  56. .Op Fl P Ar allowed_providers
  57. .Op Fl t Ar life
  58. .Ar command Op Ar arg ...
  59. .Nm ssh-agent
  60. .Op Fl c | s
  61. .Fl k
  62. .Sh DESCRIPTION
  63. .Nm
  64. is a program to hold private keys used for public key authentication.
  65. Through use of environment variables the agent can be located
  66. and automatically used for authentication when logging in to other
  67. machines using
  68. .Xr ssh 1 .
  69. .Pp
  70. The options are as follows:
  71. .Bl -tag -width Ds
  72. .It Fl a Ar bind_address
  73. Bind the agent to the
  74. .Ux Ns -domain
  75. socket
  76. .Ar bind_address .
  77. The default is
  78. .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
  79. .It Fl c
  80. Generate C-shell commands on standard output.
  81. This is the default if
  82. .Ev SHELL
  83. looks like it's a csh style of shell.
  84. .It Fl D
  85. Foreground mode.
  86. When this option is specified,
  87. .Nm
  88. will not fork.
  89. .It Fl d
  90. Debug mode.
  91. When this option is specified,
  92. .Nm
  93. will not fork and will write debug information to standard error.
  94. .It Fl E Ar fingerprint_hash
  95. Specifies the hash algorithm used when displaying key fingerprints.
  96. Valid options are:
  97. .Dq md5
  98. and
  99. .Dq sha256 .
  100. The default is
  101. .Dq sha256 .
  102. .It Fl k
  103. Kill the current agent (given by the
  104. .Ev SSH_AGENT_PID
  105. environment variable).
  106. .It Fl O Ar option
  107. Specify an option when starting
  108. .Nm .
  109. The supported options are:
  110. .Cm allow-remote-pkcs11 ,
  111. .Cm no-restrict-websafe
  112. and
  113. .Cm websafe-allow .
  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 an
  122. .Nm
  123. client is 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. option instructs
  131. .Nm
  132. to permit signatures using FIDO keys that might be web authentication
  133. requests.
  134. By default,
  135. .Nm
  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.
  146. .Pp
  147. Alternately the
  148. .Cm websafe-allow
  149. option allows specifying a pattern-list of key application strings to
  150. replace the default application allow-list, for example:
  151. .Dq websafe-allow=ssh:*,example.org,*.example.com
  152. .Pp
  153. See PATTERNS in
  154. .Xr ssh_config 5
  155. for a description of pattern-list syntax.
  156. .It Fl P Ar allowed_providers
  157. Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO
  158. authenticator middleware shared libraries that may be used with the
  159. .Fl S
  160. or
  161. .Fl s
  162. options to
  163. .Xr ssh-add 1 .
  164. Libraries that do not match the pattern list will be refused.
  165. The default list is
  166. .Dq usr/lib*/*,/usr/local/lib*/* .
  167. .Pp
  168. See PATTERNS in
  169. .Xr ssh_config 5
  170. for a description of pattern-list syntax.
  171. .It Fl s
  172. Generate Bourne shell commands on standard output.
  173. This is the default if
  174. .Ev SHELL
  175. does not look like it's a csh style of shell.
  176. .It Fl t Ar life
  177. Set a default value for the maximum lifetime of identities added to the agent.
  178. The lifetime may be specified in seconds or in a time format specified in
  179. .Xr sshd_config 5 .
  180. A lifetime specified for an identity with
  181. .Xr ssh-add 1
  182. overrides this value.
  183. Without this option the default maximum lifetime is forever.
  184. .It Ar command Op Ar arg ...
  185. If a command (and optional arguments) is given,
  186. this is executed as a subprocess of the agent.
  187. The agent exits automatically when the command given on the command
  188. line terminates.
  189. .El
  190. .Pp
  191. There are three main ways to get an agent set up.
  192. The first is at the start of an X session,
  193. where all other windows or programs are started as children of the
  194. .Nm
  195. program.
  196. The agent starts a command under which its environment
  197. variables are exported, for example
  198. .Cm ssh-agent xterm & .
  199. When the command terminates, so does the agent.
  200. .Pp
  201. The second method is used for a login session.
  202. When
  203. .Nm
  204. is started,
  205. it prints the shell commands required to set its environment variables,
  206. which in turn can be evaluated in the calling shell, for example
  207. .Cm eval `ssh-agent -s` .
  208. .Pp
  209. In both of these cases,
  210. .Xr ssh 1
  211. looks at these environment variables
  212. and uses them to establish a connection to the agent.
  213. .Pp
  214. The third way to run
  215. .Nm
  216. is via socket activation from a supervising process, such as systemd.
  217. In this mode, the supervising process creates the listening socket and
  218. is responsible for starting
  219. .Nm
  220. as needed, and also for communicating the location of the socket listener
  221. to other programs in the user's session.
  222. Socket activation is used when
  223. .Nm
  224. is started with either of the
  225. .Fl d
  226. or
  227. .Fl D
  228. flags, no socket listening address specified by the
  229. .Fl a
  230. flag, and both the
  231. .Ev LISTEN_FDS
  232. and
  233. .Ev LISTEN_PID
  234. environment variables correctly supplied by the supervising process.
  235. .Pp
  236. The agent initially does not have any private keys.
  237. Keys are added using
  238. .Xr ssh-add 1
  239. or by
  240. .Xr ssh 1
  241. when
  242. .Cm AddKeysToAgent
  243. is set in
  244. .Xr ssh_config 5 .
  245. Multiple identities may be stored in
  246. .Nm
  247. concurrently and
  248. .Xr ssh 1
  249. will automatically use them if present.
  250. .Xr ssh-add 1
  251. is also used to remove keys from
  252. .Nm
  253. and to query the keys that are held in one.
  254. .Pp
  255. Connections to
  256. .Nm
  257. may be forwarded from further remote hosts using the
  258. .Fl A
  259. option to
  260. .Xr ssh 1
  261. (but see the caveats documented therein),
  262. avoiding the need for authentication data to be stored on other machines.
  263. Authentication passphrases and private keys never go over the network:
  264. the connection to the agent is forwarded over SSH remote connections
  265. and the result is returned to the requester,
  266. allowing the user access to their identities anywhere in the network
  267. in a secure fashion.
  268. .Pp
  269. .Nm
  270. will delete all keys it has loaded upon receiving
  271. .Dv SIGUSR1 .
  272. .Sh ENVIRONMENT
  273. .Bl -tag -width "SSH_AGENT_PID"
  274. .It Ev SSH_AGENT_PID
  275. When
  276. .Nm
  277. starts, it stores the name of the agent's process ID (PID) in this variable.
  278. .It Ev SSH_AUTH_SOCK
  279. When
  280. .Nm
  281. starts, it creates a
  282. .Ux Ns -domain
  283. socket and stores its pathname in this variable.
  284. It is accessible only to the current user,
  285. but is easily abused by root or another instance of the same user.
  286. .El
  287. .Sh FILES
  288. .Bl -tag -width Ds
  289. .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
  290. .Ux Ns -domain
  291. sockets used to contain the connection to the authentication agent.
  292. These sockets should only be readable by the owner.
  293. The sockets should get automatically removed when the agent exits.
  294. .El
  295. .Sh SEE ALSO
  296. .Xr ssh 1 ,
  297. .Xr ssh-add 1 ,
  298. .Xr ssh-keygen 1 ,
  299. .Xr ssh_config 5 ,
  300. .Xr sshd 8
  301. .Sh AUTHORS
  302. .An -nosplit
  303. OpenSSH is a derivative of the original and free ssh 1.2.12 release by
  304. .An Tatu Ylonen .
  305. .An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
  306. and
  307. .An Dug Song
  308. removed many bugs, re-added newer features and created OpenSSH.
  309. .An Markus Friedl
  310. contributed the support for SSH protocol versions 1.5 and 2.0.