Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SSH-ADD(1)		    General Commands Manual		    SSH-ADD(1)

       ssh-add	-  adds	 private  key identities to the	OpenSSH	authentication

       ssh-add [-cDdKkLlqvXx] [-E fingerprint_hash] [-H	hostkey_file] [-h des-
       tination_constraint] [-S	provider] [-t life] [file ...]
       ssh-add -s pkcs11
       ssh-add -e pkcs11
       ssh-add -T pubkey...

       ssh-add	adds  private key identities to	the authentication agent, ssh-
       agent(1).  When run without arguments, it adds the files	~/.ssh/id_rsa,
       ~/.ssh/id_ecdsa,		~/.ssh/id_ecdsa_sk,	    ~/.ssh/id_ed25519,
       ~/.ssh/id_ed25519_sk, and ~/.ssh/id_dsa.	 After loading a private  key,
       ssh-add will try	to load	corresponding certificate information from the
       filename	obtained by appending	to the name of the private key
       file.  Alternative file names can be given on the command line.

       If any file requires a passphrase, ssh-add asks for the passphrase from
       the user.  The passphrase is read from the user's tty.  ssh-add retries
       the last	passphrase if multiple identity	files are given.

       The authentication agent	must be	running	and the	SSH_AUTH_SOCK environ-
       ment variable must contain the name of its socket for ssh-add to	work.

       The options are as follows:

       -c     Indicates	that added identities should be	subject	 to  confirma-
	      tion before being	used for authentication.  Confirmation is per-
	      formed by	ssh-askpass(1).	 Successful confirmation  is  signaled
	      by  a zero exit status from ssh-askpass(1), rather than text en-
	      tered into the requester.

       -D     Deletes all identities from the agent.

       -d     Instead of adding	identities, removes identities from the	agent.
	      If  ssh-add has been run without arguments, the keys for the de-
	      fault identities and their corresponding	certificates  will  be
	      removed.	 Otherwise, the	argument list will be interpreted as a
	      list of paths to public key files	to specify keys	 and  certifi-
	      cates  to	 be removed from the agent.  If	no public key is found
	      at a given path, ssh-add will append .pub	and retry.  If the ar-
	      gument list consists of ``-'' then ssh-add will read public keys
	      to be removed from standard input.

       -E fingerprint_hash
	      Specifies	the hash algorithm used	when  displaying  key  finger-
	      prints.  Valid options are: ``md5'' and ``sha256''.  The default
	      is ``sha256''.

       -e pkcs11
	      Remove keys provided by the PKCS#11 shared library pkcs11.

       -H hostkey_file
	      Specifies	a known	hosts file to look up hostkeys when using des-
	      tination-constrained  keys  via the -h flag.  This option	may be
	      specified	multiple times to allow	multiple files to be searched.
	      If no files are specified, ssh-add will use the default ssh_con-
	      fig(5)	 known	    hosts      files:	   ~/.ssh/known_hosts,
	      ~/.ssh/known_hosts2,   /usr/local/etc/ssh/ssh_known_hosts,   and

       -h destination_constraint
	      When adding keys,	constrain them to be usable only through  spe-
	      cific hosts or to	specific destinations.

	      Destination  constraints of the form `[user@]dest-hostname' per-
	      mit use of the key only from the origin host  (the  one  running
	      ssh-agent(1)) to the listed destination host, with optional user

	      Constraints of the form `src-hostname>[user@]dst-hostname' allow
	      a	key available on a forwarded ssh-agent(1) to be	used through a
	      particular host (as specified by `src-hostname' )	 to  authenti-
	      cate to a	further	host, specified	by `dst-hostname'.

	      Multiple destination constraints may be added when loading keys.
	      When attempting authentication with a key	that  has  destination
	      constraints,  the	 whole connection path,	including ssh-agent(1)
	      forwarding, is tested against those  constraints	and  each  hop
	      must  be	permitted for the attempt to succeed.  For example, if
	      key is forwarded to a remote host, `host-b', and	is  attempting
	      authentication  to  another  host,  `host-c', then the operation
	      will be successful only if `host-b' was permitted	from the  ori-
	      gin  host	and the	subsequent `host-b>host-c' hop is also permit-
	      ted by destination constraints.

	      Hosts are	identified by their host keys, and are looked up  from
	      known hosts files	by .  Wildcards	patterns may be	used for host-
	      names and	certificate host keys are supported.  By default, keys
	      added by ssh-add are not destination constrained.

	      Destination constraints were added in OpenSSH release 8.9.  Sup-
	      port in both the remote SSH client and server is	required  when
	      using destination-constrained keys over a	forwarded ssh-agent(1)

	      It is also important to note that	 destination  constraints  can
	      only  be enforced	by ssh-agent(1)	when a key is used, or when it
	      is forwarded by a	cooperating ssh(1).  Specifically, it does not
	      prevent  an  attacker with access	to a remote SSH_AUTH_SOCK from
	      forwarding it again and using it on a different host  (but  only
	      to a permitted destination).

       -K     Load resident keys from a	FIDO authenticator.

       -k     When  loading keys into or deleting keys from the	agent, process
	      plain private keys only and skip certificates.

       -L     Lists public key parameters of all identities  currently	repre-
	      sented by	the agent.

       -l     Lists  fingerprints  of  all identities currently	represented by
	      the agent.

       -q     Be quiet after a successful operation.

       -S provider
	      Specifies	a path to a library that will be used when adding FIDO
	      authenticator-hosted  keys,  overriding the default of using the
	      internal USB HID support.

       -s pkcs11
	      Add keys provided	by the PKCS#11 shared library pkcs11.

       -T pubkey...
	      Tests whether the	private	keys that correspond to	the  specified
	      pubkey files are usable by performing sign and verify operations
	      on each.

       -t life
	      Set a maximum lifetime when adding identities to an agent.   The
	      lifetime	may be specified in seconds or in a time format	speci-
	      fied in sshd_config(5).

       -v     Verbose mode.  Causes ssh-add to print debugging messages	 about
	      its  progress.  This is helpful in debugging problems.  Multiple
	      -v options increase the verbosity.  The maximum is 3.

       -X     Unlock the agent.

       -x     Lock the agent with a password.

	      If ssh-add needs a passphrase, it	will read the passphrase  from
	      the  current terminal if it was run from a terminal.  If ssh-add
	      does not have a terminal associated  with	 it  but  DISPLAY  and
	      SSH_ASKPASS  are	set,  it will execute the program specified by
	      SSH_ASKPASS (by default ``ssh-askpass )''	and open an X11	window
	      to  read the passphrase.	This is	particularly useful when call-
	      ing ssh-add from a .xsession or related script.

	      SSH_ASKPASS_REQUIRE allows further control over the  use	of  an
	      askpass program.	If this	variable is set	to ``never'' then ssh-
	      add will never attempt to	use one.  If it	is set to  ``prefer'',
	      then  ssh-add  will prefer to use	the askpass program instead of
	      the TTY when requesting passwords.  Finally, if the variable  is
	      set  to ``force'', then the askpass program will be used for all
	      passphrase input regardless of whether DISPLAY is	set.

	      Identifies the path of a UNIX-domain socket used to  communicate
	      with the agent.

	      Specifies	a path to a library that will be used when loading any
	      FIDO authenticator-hosted	keys, overriding the default of	 using
	      the built-in USB HID support.






	      Contains	the  DSA,  ECDSA, authenticator-hosted ECDSA, Ed25519,
	      authenticator-hosted Ed25519 or RSA authentication  identity  of
	      the user.

       Identity	 files	should	not  be	readable by anyone but the user.  Note
       that ssh-add ignores identity files if they are accessible by others.

       Exit status is 0	on success, 1 if the specified command fails, and 2 if
       ssh-add is unable to contact the	authentication agent.

       ssh(1), ssh-agent(1), ssh-askpass(1), ssh-keygen(1), sshd(8)

       OpenSSH	is a derivative	of the original	and free ssh 1.2.12 release by
       Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus  Friedl,	Niels  Provos,
       Theo  de	 Raadt and Dug Song removed many bugs, re-added	newer features
       and created OpenSSH.  Markus Friedl contributed	the  support  for  SSH
       protocol	versions 1.5 and 2.0.

			       February	4 2022			    SSH-ADD(1)


Want to link to this manual page? Use this URL:

home | help