Annotation of src/usr.bin/ssh/ssh-add.1, Revision 1.83
1.83 ! jmc 1: .\" $OpenBSD: ssh-add.1,v 1.82 2021/12/19 22:14:12 djm Exp $
1.1 deraadt 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: .\"
1.17 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".
12: .\"
13: .\"
1.22 deraadt 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.
1.17 deraadt 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.
1.1 deraadt 26: .\"
1.17 deraadt 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.
1.1 deraadt 37: .\"
1.83 ! jmc 38: .Dd $Mdocdate: December 19 2021 $
1.2 deraadt 39: .Dt SSH-ADD 1
40: .Os
41: .Sh NAME
42: .Nm ssh-add
1.76 jmc 43: .Nd adds private key identities to the OpenSSH authentication agent
1.2 deraadt 44: .Sh SYNOPSIS
45: .Nm ssh-add
1.78 naddy 46: .Op Fl cDdKkLlqvXx
1.61 djm 47: .Op Fl E Ar fingerprint_hash
1.83 ! jmc 48: .Op Fl H Ar hostkey_file
! 49: .Op Fl h Ar destination_constraint
1.71 jmc 50: .Op Fl S Ar provider
1.33 markus 51: .Op Fl t Ar life
1.2 deraadt 52: .Op Ar
1.26 jakob 53: .Nm ssh-add
1.50 jmc 54: .Fl s Ar pkcs11
1.26 jakob 55: .Nm ssh-add
1.50 jmc 56: .Fl e Ar pkcs11
1.67 djm 57: .Nm ssh-add
58: .Fl T
1.68 jmc 59: .Ar pubkey ...
1.12 aaron 60: .Sh DESCRIPTION
1.2 deraadt 61: .Nm
1.53 djm 62: adds private key identities to the authentication agent,
1.2 deraadt 63: .Xr ssh-agent 1 .
1.28 djm 64: When run without arguments, it adds the files
1.43 djm 65: .Pa ~/.ssh/id_rsa ,
1.53 djm 66: .Pa ~/.ssh/id_dsa ,
1.59 naddy 67: .Pa ~/.ssh/id_ecdsa ,
1.72 naddy 68: .Pa ~/.ssh/id_ecdsa_sk ,
1.75 naddy 69: .Pa ~/.ssh/id_ed25519 ,
1.28 djm 70: and
1.75 naddy 71: .Pa ~/.ssh/id_ed25519_sk .
1.52 djm 72: After loading a private key,
73: .Nm
74: will try to load corresponding certificate information from the
75: filename obtained by appending
76: .Pa -cert.pub
77: to the name of the private key file.
1.11 aaron 78: Alternative file names can be given on the command line.
1.52 djm 79: .Pp
1.11 aaron 80: If any file requires a passphrase,
1.2 deraadt 81: .Nm
1.12 aaron 82: asks for the passphrase from the user.
1.25 stevesk 83: The passphrase is read from the user's tty.
1.23 markus 84: .Nm
85: retries the last passphrase if multiple identity files are given.
1.2 deraadt 86: .Pp
1.40 matthieu 87: The authentication agent must be running and the
88: .Ev SSH_AUTH_SOCK
89: environment variable must contain the name of its socket for
1.2 deraadt 90: .Nm
1.1 deraadt 91: to work.
1.2 deraadt 92: .Pp
93: The options are as follows:
94: .Bl -tag -width Ds
1.36 markus 95: .It Fl c
96: Indicates that added identities should be subject to confirmation before
1.38 jmc 97: being used for authentication.
1.62 jmc 98: Confirmation is performed by
99: .Xr ssh-askpass 1 .
100: Successful confirmation is signaled by a zero exit status from
101: .Xr ssh-askpass 1 ,
102: rather than text entered into the requester.
1.42 jmc 103: .It Fl D
104: Deletes all identities from the agent.
105: .It Fl d
1.46 jmc 106: Instead of adding identities, removes identities from the agent.
1.45 djm 107: If
108: .Nm
1.57 djm 109: has been run without arguments, the keys for the default identities and
1.58 jmc 110: their corresponding certificates will be removed.
1.45 djm 111: Otherwise, the argument list will be interpreted as a list of paths to
1.57 djm 112: public key files to specify keys and certificates to be removed from the agent.
1.45 djm 113: If no public key is found at a given path,
114: .Nm
115: will append
116: .Pa .pub
117: and retry.
1.80 djm 118: If the argument list consists of
119: .Dq -
120: then
121: .Nm
122: will read public keys to be removed from standard input.
1.61 djm 123: .It Fl E Ar fingerprint_hash
124: Specifies the hash algorithm used when displaying key fingerprints.
125: Valid options are:
126: .Dq md5
127: and
128: .Dq sha256 .
129: The default is
130: .Dq sha256 .
1.49 markus 131: .It Fl e Ar pkcs11
1.51 markus 132: Remove keys provided by the PKCS#11 shared library
1.49 markus 133: .Ar pkcs11 .
1.82 djm 134: .It Fl H Ar hostkey_file
1.83 ! jmc 135: Specifies a known hosts file to look up hostkeys when using
! 136: destination-constrained keys via the
1.82 djm 137: .Fl h
138: flag.
139: This option may be specified multiple times to allow multiple files to be
140: searched.
141: If no files are specified,
142: .Nm
143: will use the default
144: .Xr ssh_config 5
145: known hosts files:
146: .Pa ~/.ssh/known_hosts ,
147: .Pa ~/.ssh/known_hosts2 ,
148: .Pa /etc/ssh/ssh_known_hosts ,
149: and
150: .Pa /etc/ssh/ssh_known_hosts2 .
151: .It Fl h Ar destination_constraint
152: When adding keys, constrain them to be usable only through specific hosts or to
153: specific destinations.
154: .Pp
155: Destination constraints of the form
156: .Sq [user@]dest-hostname
157: permit use of the key only from the origin host (the one running
158: .Xr ssh-agent 1 )
159: to the listed destination host, with optional user name.
160: .Pp
161: Constraints of the form
162: .Sq src-hostname>[user@]dst-hostname
163: allow a key available on a forwarded
164: .Xr ssh-agent 1
165: to be used through a particular host (as specified by
166: .Sq src-hostname )
167: to authenticate to a further host,
168: specified by
169: .Sq dst-hostname .
170: .Pp
171: Multiple destination constraints may be added when loading keys.
172: When attempting authentication with a key that has destination constraints,
173: the whole connection path, including
174: .Xr ssh-agent 1
175: forwarding, is tested against those constraints and each
176: hop must be permitted for the attempt to succeed.
177: For example, if key is forwarded to a remote host,
178: .Sq host-b ,
179: and is attempting authentication to another host,
180: .Sq host-c ,
181: then the operation will be successful only if
182: .Sq host-b
183: was permitted from the origin host and the subsequent
184: .Sq host-b>host-c
185: hop is also permitted by destination constraints.
186: .Pp
187: Hosts are identified by their host keys, and are looked up from known hosts
188: files by
189: .Nm .
190: Wildcards patterns may be used for hostnames and certificate host
191: keys are supported.
192: By default, keys added by
193: .Nm
194: are not destination constrained.
195: .Pp
196: Destination constraints were added in OpenSSH release 8.9.
197: Support in both the remote SSH client and server is required when using
198: destination-constrained keys over a forwarded
199: .Xr ssh-agent 1
200: channel.
201: .Pp
202: It is also important to note that destination constraints can only be
203: enforced by
204: .Xr ssh-agent 1
205: when a key is used, or when it is forwarded by a
206: .Sy cooperating
207: .Xr ssh 1 .
208: Specifically, it does not prevent an attacker with access to a remote
209: .Ev SSH_AUTH_SOCK
210: from forwarding it again and using it on a different host (but only to
211: a permitted destination).
1.78 naddy 212: .It Fl K
213: Load resident keys from a FIDO authenticator.
1.56 djm 214: .It Fl k
1.57 djm 215: When loading keys into or deleting keys from the agent, process plain private
216: keys only and skip certificates.
1.42 jmc 217: .It Fl L
218: Lists public key parameters of all identities currently represented
219: by the agent.
220: .It Fl l
221: Lists fingerprints of all identities currently represented by the agent.
1.66 jmc 222: .It Fl q
223: Be quiet after a successful operation.
1.70 djm 224: .It Fl S Ar provider
1.77 naddy 225: Specifies a path to a library that will be used when adding
226: FIDO authenticator-hosted keys, overriding the default of using the
1.74 jmc 227: internal USB HID support.
1.71 jmc 228: .It Fl s Ar pkcs11
229: Add keys provided by the PKCS#11 shared library
230: .Ar pkcs11 .
1.68 jmc 231: .It Fl T Ar pubkey ...
1.67 djm 232: Tests whether the private keys that correspond to the specified
233: .Ar pubkey
234: files are usable by performing sign and verify operations on each.
1.42 jmc 235: .It Fl t Ar life
236: Set a maximum lifetime when adding identities to an agent.
237: The lifetime may be specified in seconds or in a time format
238: specified in
239: .Xr sshd_config 5 .
1.69 djm 240: .It Fl v
241: Verbose mode.
242: Causes
243: .Nm
244: to print debugging messages about its progress.
245: This is helpful in debugging problems.
246: Multiple
247: .Fl v
248: options increase the verbosity.
249: The maximum is 3.
1.42 jmc 250: .It Fl X
251: Unlock the agent.
252: .It Fl x
253: Lock the agent with a password.
1.2 deraadt 254: .El
1.9 markus 255: .Sh ENVIRONMENT
256: .Bl -tag -width Ds
1.81 djm 257: .It Ev "DISPLAY", "SSH_ASKPASS" and "SSH_ASKPASS_REQUIRE"
1.1 deraadt 258: If
1.2 deraadt 259: .Nm
1.1 deraadt 260: needs a passphrase, it will read the passphrase from the current
1.11 aaron 261: terminal if it was run from a terminal.
262: If
1.2 deraadt 263: .Nm
1.1 deraadt 264: does not have a terminal associated with it but
1.2 deraadt 265: .Ev DISPLAY
1.8 markus 266: and
267: .Ev SSH_ASKPASS
268: are set, it will execute the program specified by
269: .Ev SSH_ASKPASS
1.62 jmc 270: (by default
271: .Dq ssh-askpass )
1.11 aaron 272: and open an X11 window to read the passphrase.
273: This is particularly useful when calling
1.2 deraadt 274: .Nm
275: from a
1.41 jmc 276: .Pa .xsession
1.11 aaron 277: or related script.
1.81 djm 278: .Pp
279: .Ev SSH_ASKPASS_REQUIRE
280: allows further control over the use of an askpass program.
281: If this variable is set to
282: .Dq never
283: then
284: .Nm
285: will never attempt to use one.
286: If it is set to
287: .Dq prefer ,
288: then
289: .Nm
290: will prefer to use the askpass program instead of the TTY when requesting
291: passwords.
292: Finally, if the variable is set to
293: .Dq force ,
294: then the askpass program will be used for all passphrase input regardless
295: of whether
296: .Ev DISPLAY
297: is set.
1.31 markus 298: .It Ev SSH_AUTH_SOCK
1.47 sobrado 299: Identifies the path of a
1.48 sobrado 300: .Ux Ns -domain
301: socket used to communicate with the agent.
1.70 djm 302: .It Ev SSH_SK_PROVIDER
1.79 djm 303: Specifies a path to a library that will be used when loading any
304: FIDO authenticator-hosted keys, overriding the default of using
305: the built-in USB HID support.
1.16 itojun 306: .El
1.39 jmc 307: .Sh FILES
1.77 naddy 308: .Bl -tag -width Ds -compact
1.43 djm 309: .It Pa ~/.ssh/id_dsa
1.53 djm 310: .It Pa ~/.ssh/id_ecdsa
1.72 naddy 311: .It Pa ~/.ssh/id_ecdsa_sk
1.59 naddy 312: .It Pa ~/.ssh/id_ed25519
1.75 naddy 313: .It Pa ~/.ssh/id_ed25519_sk
1.43 djm 314: .It Pa ~/.ssh/id_rsa
1.77 naddy 315: Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
316: authenticator-hosted Ed25519 or RSA authentication identity of the user.
1.39 jmc 317: .El
318: .Pp
319: Identity files should not be readable by anyone but the user.
320: Note that
321: .Nm
322: ignores identity files if they are accessible by others.
1.54 jmc 323: .Sh EXIT STATUS
1.29 markus 324: Exit status is 0 on success, 1 if the specified command fails,
325: and 2 if
326: .Nm
327: is unable to contact the authentication agent.
1.39 jmc 328: .Sh SEE ALSO
329: .Xr ssh 1 ,
330: .Xr ssh-agent 1 ,
1.62 jmc 331: .Xr ssh-askpass 1 ,
1.39 jmc 332: .Xr ssh-keygen 1 ,
333: .Xr sshd 8
1.18 aaron 334: .Sh AUTHORS
1.19 markus 335: OpenSSH is a derivative of the original and free
336: ssh 1.2.12 release by Tatu Ylonen.
337: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
338: Theo de Raadt and Dug Song
339: removed many bugs, re-added newer features and
340: created OpenSSH.
341: Markus Friedl contributed the support for SSH
342: protocol versions 1.5 and 2.0.
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh-add.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh