Debian Codegraph @

upstream/fedora-44/man1/ssh-add.1

raw
1 .\" $OpenBSD: ssh-add.1,v 1.88 2025/09/11 02:54:42 djm Exp $
2 .\"
3 .\" Author: Tatu Ylonen <[email protected]>
4 .\" Copyright (c) 1995 Tatu Ylonen <[email protected]>, 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 .\"
14 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
15 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
16 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
17 .\"
18 .\" Redistribution and use in source and binary forms, with or without
19 .\" modification, are permitted provided that the following conditions
20 .\" are met:
21 .\" 1. Redistributions of source code must retain the above copyright
22 .\" notice, this list of conditions and the following disclaimer.
23 .\" 2. Redistributions in binary form must reproduce the above copyright
24 .\" notice, this list of conditions and the following disclaimer in the
25 .\" documentation and/or other materials provided with the distribution.
26 .\"
27 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .\"
38 .Dd $Mdocdate: September 11 2025 $
39 .Dt SSH-ADD 1
40 .Os
41 .Sh NAME
42 .Nm ssh-add
43 .Nd adds private key identities to the OpenSSH authentication agent
44 .Sh SYNOPSIS
45 .Nm ssh-add
46 .Op Fl CcDdKkLlNqvXx
47 .Op Fl E Ar fingerprint_hash
48 .Op Fl H Ar hostkey_file
49 .Op Fl h Ar destination_constraint
50 .Op Fl S Ar provider
51 .Op Fl t Ar life
52 .Op Ar
53 .Nm ssh-add
54 .Fl s Ar pkcs11
55 .Op Fl Cv
56 .Op Ar certificate ...
57 .Nm ssh-add
58 .Fl e Ar pkcs11
59 .Nm ssh-add
60 .Fl T
61 .Ar pubkey ...
62 .Sh DESCRIPTION
63 .Nm
64 adds private key identities to the authentication agent,
65 .Xr ssh-agent 1 .
66 When run without arguments, it adds the files
67 .Pa ~/.ssh/id_rsa ,
68 .Pa ~/.ssh/id_ecdsa ,
69 .Pa ~/.ssh/id_ecdsa_sk ,
70 .Pa ~/.ssh/id_ed25519
71 and
72 .Pa ~/.ssh/id_ed25519_sk .
73 After loading a private key,
74 .Nm
75 will try to load corresponding certificate information from the
76 filename obtained by appending
77 .Pa -cert.pub
78 to the name of the private key file.
79 Alternative file names can be given on the command line.
80 .Pp
81 If any file requires a passphrase,
82 .Nm
83 asks for the passphrase from the user.
84 The passphrase is read from the user's tty.
85 .Nm
86 retries the last passphrase if multiple identity files are given.
87 .Pp
88 The authentication agent must be running and the
89 .Ev SSH_AUTH_SOCK
90 environment variable must contain the name of its socket for
91 .Nm
92 to work.
93 .Pp
94 The options are as follows:
95 .Bl -tag -width Ds
96 .It Fl C
97 When loading keys into or deleting keys from the agent, process
98 certificates only and skip plain keys.
99 .It Fl c
100 Indicates that added identities should be subject to confirmation before
101 being used for authentication.
102 Confirmation is performed by
103 .Xr ssh-askpass 1 .
104 Successful confirmation is signaled by a zero exit status from
105 .Xr ssh-askpass 1 ,
106 rather than text entered into the requester.
107 .It Fl D
108 Deletes all identities from the agent.
109 .It Fl d
110 Instead of adding identities, removes identities from the agent.
111 If
112 .Nm
113 has been run without arguments, the keys for the default identities and
114 their corresponding certificates will be removed.
115 Otherwise, the argument list will be interpreted as a list of paths to
116 public key files to specify keys and certificates to be removed from the agent.
117 If no public key is found at a given path,
118 .Nm
119 will append
120 .Pa .pub
121 and retry.
122 If the argument list consists of
123 .Dq -
124 then
125 .Nm
126 will read public keys to be removed from standard input.
127 .It Fl E Ar fingerprint_hash
128 Specifies the hash algorithm used when displaying key fingerprints.
129 Valid options are:
130 .Dq md5
131 and
132 .Dq sha256 .
133 The default is
134 .Dq sha256 .
135 .It Fl e Ar pkcs11
136 Remove keys provided by the PKCS#11 shared library
137 .Ar pkcs11 .
138 .It Fl H Ar hostkey_file
139 Specifies a known hosts file to look up hostkeys when using
140 destination-constrained keys via the
141 .Fl h
142 flag.
143 This option may be specified multiple times to allow multiple files to be
144 searched.
145 If no files are specified,
146 .Nm
147 will use the default
148 .Xr ssh_config 5
149 known hosts files:
150 .Pa ~/.ssh/known_hosts ,
151 .Pa ~/.ssh/known_hosts2 ,
152 .Pa /etc/ssh/ssh_known_hosts ,
153 and
154 .Pa /etc/ssh/ssh_known_hosts2 .
155 .It Fl h Ar destination_constraint
156 When adding keys, constrain them to be usable only through specific hosts or to
157 specific destinations.
158 .Pp
159 Destination constraints of the form
160 .Sq [user@]dest-hostname
161 permit use of the key only from the origin host (the one running
162 .Xr ssh-agent 1 )
163 to the listed destination host, with optional user name.
164 .Pp
165 Constraints of the form
166 .Sq src-hostname>[user@]dst-hostname
167 allow a key available on a forwarded
168 .Xr ssh-agent 1
169 to be used through a particular host (as specified by
170 .Sq src-hostname )
171 to authenticate to a further host,
172 specified by
173 .Sq dst-hostname .
174 .Pp
175 Multiple destination constraints may be added when loading keys.
176 When attempting authentication with a key that has destination constraints,
177 the whole connection path, including
178 .Xr ssh-agent 1
179 forwarding, is tested against those constraints and each
180 hop must be permitted for the attempt to succeed.
181 For example, if key is forwarded to a remote host,
182 .Sq host-b ,
183 and is attempting authentication to another host,
184 .Sq host-c ,
185 then the operation will be successful only if
186 .Sq host-b
187 was permitted from the origin host and the subsequent
188 .Sq host-b>host-c
189 hop is also permitted by destination constraints.
190 .Pp
191 Hosts are identified by their host keys, and are looked up from known hosts
192 files by
193 .Nm .
194 Wildcards patterns may be used for hostnames and certificate host
195 keys are supported.
196 By default, keys added by
197 .Nm
198 are not destination constrained.
199 .Pp
200 Destination constraints were added in OpenSSH release 8.9.
201 Support in both the remote SSH client and server is required when using
202 destination-constrained keys over a forwarded
203 .Xr ssh-agent 1
204 channel.
205 .Pp
206 It is also important to note that destination constraints can only be
207 enforced by
208 .Xr ssh-agent 1
209 when a key is used, or when it is forwarded by a
210 .Sy cooperating
211 .Xr ssh 1 .
212 Specifically, it does not prevent an attacker with access to a remote
213 .Ev SSH_AUTH_SOCK
214 from forwarding it again and using it on a different host (but only to
215 a permitted destination).
216 .It Fl K
217 Load resident keys from a FIDO authenticator.
218 .It Fl k
219 When loading keys into or deleting keys from the agent, process plain private
220 keys only and skip certificates.
221 .It Fl L
222 Lists public key parameters of all identities currently represented
223 by the agent.
224 .It Fl l
225 Lists fingerprints of all identities currently represented by the agent.
226 .It Fl N
227 When adding certificates, by default
228 .Nm
229 will request that the agent automatically delete the certificate shortly
230 after the certificate's expiry date.
231 This flag suppresses this behaviour and does not specify a lifetime for
232 certificates added to an agent.
233 .It Fl q
234 Be quiet after a successful operation.
235 .It Fl S Ar provider
236 Specifies a path to a library that will be used when adding
237 FIDO authenticator-hosted keys, overriding the default of using the
238 internal USB HID support.
239 .It Fl s Ar pkcs11
240 Add keys provided by the PKCS#11 shared library
241 .Ar pkcs11 .
242 Certificate files may optionally be listed as command-line arguments.
243 If these are present, then they will be loaded into the agent using any
244 corresponding private keys loaded from the PKCS#11 token.
245 .It Fl T Ar pubkey ...
246 Tests whether the private keys that correspond to the specified
247 .Ar pubkey
248 files are usable by performing sign and verify operations on each.
249 .It Fl t Ar life
250 Set a maximum lifetime when adding identities to an agent.
251 The lifetime may be specified in seconds or in a time format
252 specified in
253 .Xr sshd_config 5 .
254 .It Fl v
255 Verbose mode.
256 Causes
257 .Nm
258 to print debugging messages about its progress.
259 This is helpful in debugging problems.
260 Multiple
261 .Fl v
262 options increase the verbosity.
263 The maximum is 3.
264 .It Fl X
265 Unlock the agent.
266 .It Fl x
267 Lock the agent with a password.
268 .El
269 .Sh ENVIRONMENT
270 .Bl -tag -width Ds
271 .It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
272 If
273 .Nm
274 needs a passphrase, it will read the passphrase from the current
275 terminal if it was run from a terminal.
276 If
277 .Nm
278 does not have a terminal associated with it but
279 .Ev DISPLAY
280 and
281 .Ev SSH_ASKPASS
282 are set, it will execute the program specified by
283 .Ev SSH_ASKPASS
284 (by default
285 .Dq ssh-askpass )
286 and open an X11 window to read the passphrase.
287 This is particularly useful when calling
288 .Nm
289 from a
290 .Pa .xsession
291 or related script.
292 .Pp
293 .Ev SSH_ASKPASS_REQUIRE
294 allows further control over the use of an askpass program.
295 If this variable is set to
296 .Dq never
297 then
298 .Nm
299 will never attempt to use one.
300 If it is set to
301 .Dq prefer ,
302 then
303 .Nm
304 will prefer to use the askpass program instead of the TTY when requesting
305 passwords.
306 Finally, if the variable is set to
307 .Dq force ,
308 then the askpass program will be used for all passphrase input regardless
309 of whether
310 .Ev DISPLAY
311 is set.
312 .It Ev SSH_AUTH_SOCK
313 Identifies the path of a
314 .Ux Ns -domain
315 socket used to communicate with the agent.
316 .It Ev SSH_SK_PROVIDER
317 Specifies a path to a library that will be used when loading any
318 FIDO authenticator-hosted keys, overriding the default of using
319 the built-in USB HID support.
320 .El
321 .Sh FILES
322 .Bl -tag -width Ds -compact
323 .It Pa ~/.ssh/id_ecdsa
324 .It Pa ~/.ssh/id_ecdsa_sk
325 .It Pa ~/.ssh/id_ed25519
326 .It Pa ~/.ssh/id_ed25519_sk
327 .It Pa ~/.ssh/id_rsa
328 Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
329 authenticator-hosted Ed25519 or RSA authentication identity of the user.
330 .El
331 .Pp
332 Identity files should not be readable by anyone but the user.
333 Note that
334 .Nm
335 ignores identity files if they are accessible by others.
336 .Sh EXIT STATUS
337 Exit status is 0 on success, 1 if the specified command fails,
338 and 2 if
339 .Nm
340 is unable to contact the authentication agent.
341 .Sh SEE ALSO
342 .Xr ssh 1 ,
343 .Xr ssh-agent 1 ,
344 .Xr ssh-askpass 1 ,
345 .Xr ssh-keygen 1 ,
346 .Xr sshd 8
347 .Sh AUTHORS
348 OpenSSH is a derivative of the original and free
349 ssh 1.2.12 release by Tatu Ylonen.
350 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
351 Theo de Raadt and Dug Song
352 removed many bugs, re-added newer features and
353 created OpenSSH.
354 Markus Friedl contributed the support for SSH
355 protocol versions 1.5 and 2.0.