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