jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: ssh-add.1,v 1.88 2025/09/11 02:54:42 djm 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.\"
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
64adds private key identities to the authentication agent,
65.Xr ssh-agent 1 .
66When 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
71and
72.Pa ~/.ssh/id_ed25519_sk .
73After loading a private key,
74.Nm
75will try to load corresponding certificate information from the
76filename obtained by appending
77.Pa -cert.pub
78to the name of the private key file.
79Alternative file names can be given on the command line.
80.Pp
81If any file requires a passphrase,
82.Nm
83asks for the passphrase from the user.
84The passphrase is read from the user's tty.
85.Nm
86retries the last passphrase if multiple identity files are given.
87.Pp
88The authentication agent must be running and the
89.Ev SSH_AUTH_SOCK
90environment variable must contain the name of its socket for
91.Nm
92to work.
93.Pp
94The options are as follows:
95.Bl -tag -width Ds
96.It Fl C
97When loading keys into or deleting keys from the agent, process
98certificates only and skip plain keys.
99.It Fl c
100Indicates that added identities should be subject to confirmation before
101being used for authentication.
102Confirmation is performed by
103.Xr ssh-askpass 1 .
104Successful confirmation is signaled by a zero exit status from
105.Xr ssh-askpass 1 ,
106rather than text entered into the requester.
107.It Fl D
108Deletes all identities from the agent.
109.It Fl d
110Instead of adding identities, removes identities from the agent.
111If
112.Nm
113has been run without arguments, the keys for the default identities and
114their corresponding certificates will be removed.
115Otherwise, the argument list will be interpreted as a list of paths to
116public key files to specify keys and certificates to be removed from the agent.
117If no public key is found at a given path,
118.Nm
119will append
120.Pa .pub
121and retry.
122If the argument list consists of
123.Dq -
124then
125.Nm
126will read public keys to be removed from standard input.
127.It Fl E Ar fingerprint_hash
128Specifies the hash algorithm used when displaying key fingerprints.
129Valid options are:
130.Dq md5
131and
132.Dq sha256 .
133The default is
134.Dq sha256 .
135.It Fl e Ar pkcs11
136Remove keys provided by the PKCS#11 shared library
137.Ar pkcs11 .
138.It Fl H Ar hostkey_file
139Specifies a known hosts file to look up hostkeys when using
140destination-constrained keys via the
141.Fl h
142flag.
143This option may be specified multiple times to allow multiple files to be
144searched.
145If no files are specified,
146.Nm
147will use the default
148.Xr ssh_config 5
149known hosts files:
150.Pa ~/.ssh/known_hosts ,
151.Pa ~/.ssh/known_hosts2 ,
152.Pa /etc/ssh/ssh_known_hosts ,
153and
154.Pa /etc/ssh/ssh_known_hosts2 .
155.It Fl h Ar destination_constraint
156When adding keys, constrain them to be usable only through specific hosts or to
157specific destinations.
158.Pp
159Destination constraints of the form
160.Sq [user@]dest-hostname
161permit use of the key only from the origin host (the one running
162.Xr ssh-agent 1 )
163to the listed destination host, with optional user name.
164.Pp
165Constraints of the form
166.Sq src-hostname>[user@]dst-hostname
167allow a key available on a forwarded
168.Xr ssh-agent 1
169to be used through a particular host (as specified by
170.Sq src-hostname )
171to authenticate to a further host,
172specified by
173.Sq dst-hostname .
174.Pp
175Multiple destination constraints may be added when loading keys.
176When attempting authentication with a key that has destination constraints,
177the whole connection path, including
178.Xr ssh-agent 1
179forwarding, is tested against those constraints and each
180hop must be permitted for the attempt to succeed.
181For example, if key is forwarded to a remote host,
182.Sq host-b ,
183and is attempting authentication to another host,
184.Sq host-c ,
185then the operation will be successful only if
186.Sq host-b
187was permitted from the origin host and the subsequent
188.Sq host-b>host-c
189hop is also permitted by destination constraints.
190.Pp
191Hosts are identified by their host keys, and are looked up from known hosts
192files by
193.Nm .
194Wildcards patterns may be used for hostnames and certificate host
195keys are supported.
196By default, keys added by
197.Nm
198are not destination constrained.
199.Pp
200Destination constraints were added in OpenSSH release 8.9.
201Support in both the remote SSH client and server is required when using
202destination-constrained keys over a forwarded
203.Xr ssh-agent 1
204channel.
205.Pp
206It is also important to note that destination constraints can only be
207enforced by
208.Xr ssh-agent 1
209when a key is used, or when it is forwarded by a
210.Sy cooperating
211.Xr ssh 1 .
212Specifically, it does not prevent an attacker with access to a remote
213.Ev SSH_AUTH_SOCK
214from forwarding it again and using it on a different host (but only to
215a permitted destination).
216.It Fl K
217Load resident keys from a FIDO authenticator.
218.It Fl k
219When loading keys into or deleting keys from the agent, process plain private
220keys only and skip certificates.
221.It Fl L
222Lists public key parameters of all identities currently represented
223by the agent.
224.It Fl l
225Lists fingerprints of all identities currently represented by the agent.
226.It Fl N
227When adding certificates, by default
228.Nm
229will request that the agent automatically delete the certificate shortly
230after the certificate's expiry date.
231This flag suppresses this behaviour and does not specify a lifetime for
232certificates added to an agent.
233.It Fl q
234Be quiet after a successful operation.
235.It Fl S Ar provider
236Specifies a path to a library that will be used when adding
237FIDO authenticator-hosted keys, overriding the default of using the
238internal USB HID support.
239.It Fl s Ar pkcs11
240Add keys provided by the PKCS#11 shared library
241.Ar pkcs11 .
242Certificate files may optionally be listed as command-line arguments.
243If these are present, then they will be loaded into the agent using any
244corresponding private keys loaded from the PKCS#11 token.
245.It Fl T Ar pubkey ...
246Tests whether the private keys that correspond to the specified
247.Ar pubkey
248files are usable by performing sign and verify operations on each.
249.It Fl t Ar life
250Set a maximum lifetime when adding identities to an agent.
251The lifetime may be specified in seconds or in a time format
252specified in
253.Xr sshd_config 5 .
254.It Fl v
255Verbose mode.
256Causes
257.Nm
258to print debugging messages about its progress.
259This is helpful in debugging problems.
260Multiple
261.Fl v
262options increase the verbosity.
263The maximum is 3.
264.It Fl X
265Unlock the agent.
266.It Fl x
267Lock 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"
272If
273.Nm
274needs a passphrase, it will read the passphrase from the current
275terminal if it was run from a terminal.
276If
277.Nm
278does not have a terminal associated with it but
279.Ev DISPLAY
280and
281.Ev SSH_ASKPASS
282are set, it will execute the program specified by
283.Ev SSH_ASKPASS
284(by default
285.Dq ssh-askpass )
286and open an X11 window to read the passphrase.
287This is particularly useful when calling
288.Nm
289from a
290.Pa .xsession
291or related script.
292.Pp
293.Ev SSH_ASKPASS_REQUIRE
294allows further control over the use of an askpass program.
295If this variable is set to
296.Dq never
297then
298.Nm
299will never attempt to use one.
300If it is set to
301.Dq prefer ,
302then
303.Nm
304will prefer to use the askpass program instead of the TTY when requesting
305passwords.
306Finally, if the variable is set to
307.Dq force ,
308then the askpass program will be used for all passphrase input regardless
309of whether
310.Ev DISPLAY
311is set.
312.It Ev SSH_AUTH_SOCK
313Identifies the path of a
314.Ux Ns -domain
315socket used to communicate with the agent.
316.It Ev SSH_SK_PROVIDER
317Specifies a path to a library that will be used when loading any
318FIDO authenticator-hosted keys, overriding the default of using
319the 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
328Contains the ECDSA, authenticator-hosted ECDSA, Ed25519,
329authenticator-hosted Ed25519 or RSA authentication identity of the user.
330.El
331.Pp
332Identity files should not be readable by anyone but the user.
333Note that
334.Nm
335ignores identity files if they are accessible by others.
336.Sh EXIT STATUS
337Exit status is 0 on success, 1 if the specified command fails,
338and 2 if
339.Nm
340is 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
348OpenSSH is a derivative of the original and free
349ssh 1.2.12 release by Tatu Ylonen.
350Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
351Theo de Raadt and Dug Song
352removed many bugs, re-added newer features and
353created OpenSSH.
354Markus Friedl contributed the support for SSH
355protocol versions 1.5 and 2.0.