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

FreeBSD Manual Pages


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

       ssh-keygen - OpenSSH authentication key utility

       ssh-keygen  [-q]	[-a rounds] [-b	bits] [-C comment] [-f output_keyfile]
       [-m format] [-N new_passphrase] [-O option] [-t dsa | ecdsa |  ecdsa-sk
       | ed25519 | ed25519-sk |	rsa] [-w provider]
       ssh-keygen  -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]
       [-P old_passphrase]
       ssh-keygen -i [-f input_keyfile]	[-m key_format]
       ssh-keygen -e [-f input_keyfile]	[-m key_format]
       ssh-keygen -y [-f input_keyfile]
       ssh-keygen -c [-a rounds] [-C comment] [-f keyfile] [-P passphrase]
       ssh-keygen -l [-v] [-E fingerprint_hash]	[-f input_keyfile]
       ssh-keygen -B [-f input_keyfile]
       ssh-keygen -D pkcs11
       ssh-keygen -F hostname [-lv] [-f	known_hosts_file]
       ssh-keygen -H [-f known_hosts_file]
       ssh-keygen -K [-a rounds] [-w provider]
       ssh-keygen -R hostname [-f known_hosts_file]
       ssh-keygen -r hostname [-g] [-f input_keyfile]
       ssh-keygen -M generate [-O option] output_file
       ssh-keygen -M screen [-f	input_file] [-O	option]	output_file
       ssh-keygen -I certificate_identity -s ca_key [-hU] [-D pkcs11_provider]
       [-n  principals]	 [-O option] [-V validity_interval] [-z	serial_number]
       file ...
       ssh-keygen -L [-f input_keyfile]
       ssh-keygen -A [-a rounds] [-f prefix_path]
       ssh-keygen -k -f	krl_file [-u] [-s ca_public] [-z version_number]  file
       ssh-keygen -Q [-l] -f krl_file file ...
       ssh-keygen -Y find-principals -s	signature_file -f allowed_signers_file
       ssh-keygen -Y check-novalidate -n namespace -s signature_file
       ssh-keygen -Y sign -f key_file -n namespace file	...
       ssh-keygen  -Y  verify  -f  allowed_signers_file	 -I signer_identity -n
       namespace -s signature_file [-r revocation_file]

       ssh-keygen generates, manages  and  converts  authentication  keys  for
       ssh(1).	ssh-keygen can create keys for use by SSH protocol version 2.

       The  type  of  key to be	generated is specified with the	-t option.  If
       invoked without any arguments, ssh-keygen will generate an RSA key.

       ssh-keygen is also used to generate groups for  use  in	Diffie-Hellman
       group  exchange	(DH-GEX).   See	 the MODULI GENERATION section for de-

       Finally,	ssh-keygen can be used to generate and update  Key  Revocation
       Lists,  and  to	test whether given keys	have been revoked by one.  See
       the KEY REVOCATION LISTS	section	for details.

       Normally	each user wishing to use SSH with  public  key	authentication
       runs  this  once	 to  create  the  authentication key in	~/.ssh/id_dsa,
       ~/.ssh/id_ecdsa,		~/.ssh/id_ecdsa_sk,	    ~/.ssh/id_ed25519,
       ~/.ssh/id_ed25519_sk or ~/.ssh/id_rsa.  Additionally, the system	admin-
       istrator	may use	this to	generate host keys, as seen in /etc/rc.

       Normally	this program generates the key and asks	for a file in which to
       store  the  private  key.   The public key is stored in a file with the
       same  name  but	``.pub''  appended.   The  program  also  asks	for  a
       passphrase.   The  passphrase  may  be  empty to	indicate no passphrase
       (host keys must have an empty passphrase), or it	may be a string	of ar-
       bitrary	length.	  A passphrase is similar to a password, except	it can
       be a phrase with	a series of words, punctuation,	 numbers,  whitespace,
       or any string of	characters you want.  Good passphrases are 10-30 char-
       acters long, are	not simple sentences  or  otherwise  easily  guessable
       (English	prose has only 1-2 bits	of entropy per character, and provides
       very bad	passphrases), and contain a mix	of upper  and  lowercase  let-
       ters,  numbers, and non-alphanumeric characters.	 The passphrase	can be
       changed later by	using the -p option.

       There is	no way to recover a lost passphrase.   If  the	passphrase  is
       lost  or	 forgotten,  a new key must be generated and the corresponding
       public key copied to other machines.

       ssh-keygen will by default write	keys in	 an  OpenSSH-specific  format.
       This  format  is	 preferred  as it offers better	protection for keys at
       rest as well as allowing	storage	of key comments	within the private key
       file  itself.   The key comment may be useful to	help identify the key.
       The comment is initialized to ``user@host'' when	the  key  is  created,
       but can be changed using	the -c option.

       It  is  still  possible for ssh-keygen to write the previously-used PEM
       format private keys using the -m	flag.  This may	be used	when  generat-
       ing  new	keys, and existing new-format keys may be converted using this
       option in conjunction with the -p (change passphrase) flag.

       After a key is generated, ssh-keygen will ask where the keys should  be
       placed to be activated.

       The options are as follows:

       -A     For  each	 of  the  key  types (rsa, dsa,	ecdsa and ed25519) for
	      which host keys do not exist, generate the host  keys  with  the
	      default key file path, an	empty passphrase, default bits for the
	      key type,	and default comment.  If -f has	also  been  specified,
	      its argument is used as a	prefix to the default path for the re-
	      sulting host key files.  This is used by /etc/rc to generate new
	      host keys.

       -a rounds
	      When  saving  a private key, this	option specifies the number of
	      KDF (key derivation function) rounds used.  Higher  numbers  re-
	      sult  in slower passphrase verification and increased resistance
	      to brute-force password cracking (should the  keys  be  stolen).
	      The default is 16	rounds.

       -B     Show  the	bubblebabble digest of specified private or public key

       -b bits
	      Specifies	the number of bits in the  key	to  create.   For  RSA
	      keys,  the  minimum  size	 is  1024 bits and the default is 3072
	      bits.  Generally,	3072 bits is considered	sufficient.  DSA  keys
	      must be exactly 1024 bits	as specified by	FIPS 186-2.  For ECDSA
	      keys, the	-b flag	determines the key length  by  selecting  from
	      one  of  three  elliptic curve sizes: 256, 384 or	521 bits.  At-
	      tempting to use bit lengths other	than these  three  values  for
	      ECDSA  keys  will	 fail.	 ECDSA-SK, Ed25519 and Ed25519-SK keys
	      have a fixed length and the -b flag will be ignored.

       -C comment
	      Provides a new comment.

       -c     Requests changing	the comment in	the  private  and  public  key
	      files.  The program will prompt for the file containing the pri-
	      vate keys, for the passphrase if the key has one,	 and  for  the
	      new comment.

       -D pkcs11
	      Download	the public keys	provided by the	PKCS#11	shared library
	      pkcs11.  When used in combination	with -s, this option indicates
	      that  a  CA key resides in a PKCS#11 token (see the CERTIFICATES
	      section for details).

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

       -e     This option will read a private or public	OpenSSH	key  file  and
	      print  to	stdout a public	key in one of the formats specified by
	      the -m option.  The default export format	is ``RFC4716''.	  This
	      option  allows exporting OpenSSH keys for	use by other programs,
	      including	several	commercial SSH implementations.

       -F hostname | [hostname]:port
	      Search for the specified hostname	(with optional port number) in
	      a	 known_hosts file, listing any occurrences found.  This	option
	      is useful	to find	hashed host names or addresses and may also be
	      used  in conjunction with	the -H option to print found keys in a
	      hashed format.

       -f filename
	      Specifies	the filename of	the key	file.

       -g     Use  generic  DNS	 format	 when  printing	 fingerprint  resource
	      records using the	-r command.

       -H     Hash  a  known_hosts  file.  This	replaces all hostnames and ad-
	      dresses with hashed representations within the  specified	 file;
	      the  original  content  is  moved	 to a file with	a .old suffix.
	      These hashes may be used normally	by ssh and sshd, but  they  do
	      not reveal identifying information should	the file's contents be
	      disclosed.  This option will not modify  existing	 hashed	 host-
	      names  and is therefore safe to use on files that	mix hashed and
	      non-hashed names.

       -h     When signing a key, create a host	certificate instead of a  user
	      certificate.  Please see the CERTIFICATES	section	for details.

       -I certificate_identity
	      Specify  the key identity	when signing a public key.  Please see
	      the CERTIFICATES section for details.

       -i     This option will read an unencrypted  private  (or  public)  key
	      file  in	the  format  specified	by  the	-m option and print an
	      OpenSSH compatible private (or public) key to stdout.  This  op-
	      tion  allows  importing keys from	other software,	including sev-
	      eral commercial SSH implementations.  The	default	import	format
	      is ``RFC4716''.

       -K     Download	resident  keys	from a FIDO authenticator.  Public and
	      private key files	will be	written	to the current	directory  for
	      each  downloaded	key.   If multiple FIDO	authenticators are at-
	      tached, keys will	be downloaded from the first touched authenti-

       -k     Generate	a  KRL file.  In this mode, ssh-keygen will generate a
	      KRL file at the location specified via the -f flag that  revokes
	      every   key  or  certificate  presented  on  the	command	 line.
	      Keys/certificates	to be revoked may be specified by  public  key
	      file  or	using the format described in the KEY REVOCATION LISTS

       -L     Prints the contents of one or more certificates.

       -l     Show fingerprint of specified public key file.  For RSA and  DSA
	      keys  ssh-keygen	tries to find the matching public key file and
	      prints its fingerprint.  If combined with	-v, a visual ASCII art
	      representation of	the key	is supplied with the fingerprint.

       -M generate
	      Generate candidate Diffie-Hellman	Group Exchange (DH-GEX)	param-
	      eters for	eventual use by	the  `diffie-hellman-group-exchange-*'
	      key  exchange  methods.  The numbers generated by	this operation
	      must be further screened before use.  See	the MODULI  GENERATION
	      section for more information.

       -M screen
	      Screen  candidate	 parameters for	Diffie-Hellman Group Exchange.
	      This will	accept a list of candidate numbers and test that  they
	      are  safe	 (Sophie Germain) primes with acceptable group genera-
	      tors.  The results  of  this  operation  may  be	added  to  the
	      /usr/local/usr/local/etc/ssh/moduli file.	 See the MODULI	GENER-
	      ATION section for	more information.

       -m key_format
	      Specify a	key format for key generation,	the  -i	 (import),  -e
	      (export) conversion options, and the -p change passphrase	opera-
	      tion.  The latter	may be used to convert between OpenSSH private
	      key and PEM private key formats.	The supported key formats are:
	      ``RFC4716'' (RFC 4716/SSH2 public	 or  private  key),  ``PKCS8''
	      (PKCS8  public  or private key) or ``PEM'' (PEM public key).  By
	      default OpenSSH will write newly-generated private keys  in  its
	      own  format,  but	when converting	public keys for	export the de-
	      fault format is ``RFC4716''.  Setting a format of	 ``PEM''  when
	      generating  or  updating a supported private key type will cause
	      the key to be stored in the legacy PEM private key format.

       -N new_passphrase
	      Provides the new passphrase.

       -n principals
	      Specify one or more principals (user or host names)  to  be  in-
	      cluded in	a certificate when signing a key.  Multiple principals
	      may be specified,	separated by commas.  Please see the  CERTIFI-
	      CATES section for	details.

       -O option
	      Specify a	key/value option.  These are specific to the operation
	      that ssh-keygen has been requested to perform.

	      When signing certificates, one of	the options listed in the CER-
	      TIFICATES	section	may be specified here.

	      When  performing	moduli generation or screening,	one of the op-
	      tions listed in the MODULI GENERATION section may	be specified.

	      When generating a	key that will be hosted	on a FIDO  authentica-
	      tor,  this  flag	may  be	 used to specify key-specific options.
	      Those supported at present are:

	      Override the default FIDO	application/origin string of ``ssh:''.
	      This may be useful when generating host or domain-specific resi-
	      dent keys.  The specified	application  string  must  begin  with

	      Specifies	 a  path  to a challenge string	that will be passed to
	      the FIDO token during key	generation.  The challenge string  may
	      be used as part of an out-of-band	protocol for key enrollment (a
	      random challenge is used by default).

       device Explicitly specify a fido(4) device to use, rather than  letting
	      the token	middleware select one.

	      Indicate that the	generated private key should not require touch
	      events  (user  presence)	when  making  signatures.   Note  that
	      sshd(8)  will refuse such	signatures by default, unless overrid-
	      den via an authorized_keys option.

	      Indicate that the	key should be stored on	the FIDO authenticator
	      itself.  Resident	keys may be supported on FIDO2 tokens and typ-
	      ically require that a PIN	be set on the token prior  to  genera-
	      tion.   Resident	keys  may  be  loaded off the token using ssh-

       user   A	username to be associated with a resident key, overriding  the
	      empty  default  username.	  Specifying  a	username may be	useful
	      when generating multiple resident	keys for the same  application

	      Indicate	that this private key should require user verification
	      for each signature.  Not all FIDO	tokens	support	 this  option.
	      Currently	 PIN authentication is the only	supported verification
	      method, but other	methods	may be supported in the	future.

	      May be used at key generation time  to  record  the  attestation
	      data  returned  from  FIDO tokens	during key generation.	Please
	      note that	this information is  potentially  sensitive.   By  de-
	      fault, this information is discarded.

	      The -O option may	be specified multiple times.

       -P passphrase
	      Provides the (old) passphrase.

       -p     Requests	changing  the passphrase of a private key file instead
	      of creating a new	private	key.  The program will prompt for  the
	      file  containing	the  private  key, for the old passphrase, and
	      twice for	the new	passphrase.

       -Q     Test whether keys	have been revoked in a KRL.  If	the -l	option
	      is also specified	then the contents of the KRL will be printed.

       -q     Silence ssh-keygen.

       -R hostname | [hostname]:port
	      Removes  all  keys belonging to the specified hostname (with op-
	      tional port number) from a known_hosts  file.   This  option  is
	      useful to	delete hashed hosts (see the -H	option above).

       -r hostname
	      Print  the  SSHFP	fingerprint resource record named hostname for
	      the specified public key file.

       -s ca_key
	      Certify (sign) a public key using	the specified CA key.	Please
	      see the CERTIFICATES section for details.

	      When  generating	a  KRL,	-s specifies a path to a CA public key
	      file used	to revoke certificates directly	by key	ID  or	serial
	      number.  See the KEY REVOCATION LISTS section for	details.

       -t dsa |	ecdsa |	ecdsa-sk | ed25519 | ed25519-sk	| rsa
	      Specifies	 the  type  of key to create.  The possible values are
	      ``dsa'', ``ecdsa'', ``ecdsa-sk'',	 ``ed25519'',  ``ed25519-sk'',
	      or ``rsa''.

	      This flag	may also be used to specify the	desired	signature type
	      when signing certificates	using an RSA CA	 key.	The  available
	      RSA  signature  variants	are  ``ssh-rsa'' (SHA1 signatures, not
	      recommended), ``rsa-sha2-256'', and  ``rsa-sha2-512''  (the  de-

       -U     When  used  in combination with -s, this option indicates	that a
	      CA key resides in	a ssh-agent(1).	 See the CERTIFICATES  section
	      for more information.

       -u     Update  a	KRL.  When specified with -k, keys listed via the com-
	      mand line	are added to the existing KRL rather than  a  new  KRL
	      being created.

       -V validity_interval
	      Specify  a  validity interval when signing a certificate.	 A va-
	      lidity interval may consist of a single  time,  indicating  that
	      the  certificate	is  valid  beginning  now and expiring at that
	      time, or may consist of two times	separated by a colon to	 indi-
	      cate an explicit time interval.

	      The  start time may be specified as the string ``always''	to in-
	      dicate the certificate has no specified start time,  a  date  in
	      YYYYMMDD	format,	 a time	in YYYYMMDDHHMM[SS] format, a relative
	      time (to the current time) consisting of a minus	sign  followed
	      by  an interval in the format described in the TIME FORMATS sec-
	      tion of sshd_config(5).

	      The end time may be specified as a  YYYYMMDD  date,  a  YYYYMMD-
	      DHHMM[SS]	 time,	a relative time	starting with a	plus character
	      or the string ``forever''	to indicate that the  certificate  has
	      no expiry	date.

	      For  example: ``+52w1d'' (valid from now to 52 weeks and one day
	      from now), ``-4w:+4w'' (valid from four weeks ago	to four	 weeks
	      from  now),  ``20100101123000:20110101123000'' (valid from 12:30
	      PM,  January  1st,  2010	to  12:30  PM,	January	 1st,	2011),
	      ``-1d:20110101'' (valid from yesterday to	midnight, January 1st,
	      2011).  ``-1m:forever'' (valid from one minute ago and never ex-

       -v     Verbose  mode.   Causes  ssh-keygen  to print debugging messages
	      about its	progress.  This	is helpful for debugging moduli	gener-
	      ation.  Multiple -v options increase the verbosity.  The maximum
	      is 3.

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

       -Y find-principals
	      Find the principal(s) associated with the	public key of a	signa-
	      ture,  provided  using the -s flag in an authorized signers file
	      provided using the -f flag.  The format of the  allowed  signers
	      file is documented in the	ALLOWED	SIGNERS	section	below.	If one
	      or more matching principals are  found,  they  are  returned  on
	      standard output.

       -Y check-novalidate
	      Checks that a signature generated	using ssh-keygen -Y sign has a
	      valid structure.	This does not validate if  a  signature	 comes
	      from an authorized signer.  When testing a signature, ssh-keygen
	      accepts a	message	on standard input and  a  signature  namespace
	      using  -n.   A  file containing the corresponding	signature must
	      also be supplied using the -s flag.  Successful testing  of  the
	      signature	 is signalled by ssh-keygen returning a	zero exit sta-

       -Y sign
	      Cryptographically	sign a file or some  data  using  a  SSH  key.
	      When  signing,  ssh-keygen accepts zero or more files to sign on
	      the command-line - if no files  are  specified  then  ssh-keygen
	      will  sign  data	presented  on  standard	input.	Signatures are
	      written to the path of the input file with ``.sig'' appended, or
	      to  standard  output  if	the message to be signed was read from
	      standard input.

	      The key used for signing is specified using the  -f  option  and
	      may refer	to either a private key, or a public key with the pri-
	      vate half	available via ssh-agent(1).  An	 additional  signature
	      namespace,  used to prevent signature confusion across different
	      domains of use (e.g. file	signing	vs email signing) must be pro-
	      vided  via  the  -n flag.	 Namespaces are	arbitrary strings, and
	      may include: ``file'' for	 file  signing,	 ``email''  for	 email
	      signing.	 For  custom uses, it is recommended to	use names fol-
	      lowing a NAMESPACE@YOUR.DOMAIN pattern to	 generate  unambiguous

       -Y verify
	      Request to verify	a signature generated using ssh-keygen -Y sign
	      as described above.  When	verifying a signature, ssh-keygen  ac-
	      cepts  a message on standard input and a signature namespace us-
	      ing -n.  A file containing the corresponding signature must also
	      be  supplied  using  the -s flag,	along with the identity	of the
	      signer using -I and a list of allowed signers via	the  -f	 flag.
	      The  format of the allowed signers file is documented in the AL-
	      LOWED SIGNERS section below.  A file containing revoked keys can
	      be  passed  using	the -r flag.  The revocation file may be a KRL
	      or a one-per-line	list of	public keys.  Successful  verification
	      by  an  authorized signer	is signalled by	ssh-keygen returning a
	      zero exit	status.

       -y     This option will read a private OpenSSH format file and print an
	      OpenSSH public key to stdout.

       -z serial_number
	      Specifies	 a  serial number to be	embedded in the	certificate to
	      distinguish this certificate from	others from the	same  CA.   If
	      the serial_number	is prefixed with a `+' character, then the se-
	      rial number will be incremented for each certificate signed on a
	      single command-line.  The	default	serial number is zero.

	      When generating a	KRL, the -z flag is used to specify a KRL ver-
	      sion number.

       ssh-keygen may be used to generate groups for the Diffie-Hellman	 Group
       Exchange	 (DH-GEX)  protocol.   Generating  these  groups is a two-step
       process:	first, candidate primes	are generated using a fast, but	memory
       intensive  process.   These  candidate primes are then tested for suit-
       ability (a CPU-intensive	process).

       Generation of primes is performed using the -M  generate	 option.   The
       desired	length	of  the	primes may be specified	by the -O bits option.
       For example:

       Dl # ssh-keygen -M generate -O bits=2048	moduli-2048.candidates

       By default, the search for primes begins	at a random point in  the  de-
       sired  length range.  This may be overridden using the -O start option,
       which specifies a different start point (in hex).

       Once a set of candidates	have been generated, they must be screened for
       suitability.   This  may	 be  performed using the -M screen option.  In
       this mode ssh-keygen will read candidates from  standard	 input	(or  a
       file specified using the	-f option).  For example:

       Dl # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048

       By  default,  each  candidate will be subjected to 100 primality	tests.
       This may	be overridden using the	-O prime-tests option.	The DH genera-
       tor  value  will	be chosen automatically	for the	prime under considera-
       tion.  If a specific generator is desired, it may  be  requested	 using
       the -O generator	option.	 Valid generator values	are 2, 3, and 5.

       Screened	  DH   groups	may   be   installed   in   /usr/local/usr/lo-
       cal/etc/ssh/moduli.  It is important that this file contains moduli  of
       a  range	of bit lengths and that	both ends of a connection share	common

       A number	of options are available for moduli generation	and  screening
       via the -O flag:

       lines Ns	= Ns number
	      Exit  after  screening  the specified number of lines while per-
	      forming DH candidate screening.

       start-line Ns = Ns line-number
	      Start screening at the specified line number while performing DH
	      candidate	screening.

       checkpoint Ns = Ns filename
	      Write  the  last line processed to the specified file while per-
	      forming DH candidate screening.  This will be used to skip lines
	      in the input file	that have already been processed if the	job is

       memory Ns = Ns mbytes
	      Specify the amount of memory to use (in megabytes) when generat-
	      ing candidate moduli for DH-GEX.

       start Ns	= Ns hex-value
	      Specify  start  point  (in hex) when generating candidate	moduli
	      for DH-GEX.

       generator Ns = Ns value
	      Specify desired generator	(in decimal)  when  testing  candidate
	      moduli for DH-GEX.

       ssh-keygen supports signing of keys to produce certificates that	may be
       used for	user or	host authentication.  Certificates consist of a	public
       key,  some  identity information, zero or more principal	(user or host)
       names and a set of options that are signed by a Certification Authority
       (CA) key.  Clients or servers may then trust only the CA	key and	verify
       its signature on	a certificate  rather  than  trusting  many  user/host
       keys.   Note  that  OpenSSH certificates	are a different, and much sim-
       pler, format to the X.509 certificates used in ssl(8).

       ssh-keygen supports two types of	certificates:  user  and  host.	  User
       certificates  authenticate  users to servers, whereas host certificates
       authenticate server hosts to users.  To generate	a user certificate:

       Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/

       The resultant certificate will be placed	in /path/to/
       A host certificate requires the -h option:

       Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/

       The host	certificate will be output to /path/to/

       It is possible to sign using a CA key stored in a PKCS#11 token by pro-
       viding the token	library	using -D and identifying the CA	key by provid-
       ing its public half as an argument to -s	:

       Dl $ ssh-keygen -s -D -I	key_id

       Similarly,  it  is  possible  for  the  CA  key	to be hosted in	a ssh-
       agent(1).  This is indicated by the -U flag and,	again, the CA key must
       be identified by	its public half.

       Dl $ ssh-keygen -Us -I key_id

       In all cases, key_id is a "key identifier" that is logged by the	server
       when the	certificate is used for	authentication.

       Certificates may	be  limited  to	 be  valid  for	 a  set	 of  principal
       (user/host)  names.   By	 default, generated certificates are valid for
       all users or hosts.  To generate	a certificate for a specified  set  of

       Dl  $  ssh-keygen -s ca_key -I key_id -n	user1,user2 Dl "$
       ssh-keygen -s ca_key -I key_id -h -n host.domain"

       Additional limitations on the validity and use of user certificates may
       be  specified  through  certificate  options.  A	certificate option may
       disable features	of the SSH session, may	be valid only  when  presented
       from  particular	 source	 addresses  or may force the use of a specific

       The options that	are valid for user certificates	are:

       clear  Clear all	enabled	permissions.  This is useful for clearing  the
	      default set of permissions so permissions	may be added individu-

       critical	: Ns name Ns [Ns = Ns contents]

       extension : Ns name Ns [Ns = Ns contents]
	      Includes an arbitrary certificate	critical option	or  extension.
	      The   specified  name  should  include  a	 domain	 suffix,  e.g.
	      ``''.  If	contents is specified then it  is  in-
	      cluded  as  the  contents	 of  the extension/option encoded as a
	      string, otherwise	the extension/option is	created	with  no  con-
	      tents (usually indicating	a flag).  Extensions may be ignored by
	      a	client or server that does not recognise them, whereas unknown
	      critical options will cause the certificate to be	refused.

       force-command Ns	= Ns command
	      Forces  the execution of command instead of any shell or command
	      specified	by the user when the certificate is used for authenti-

	      Disable ssh-agent(1) forwarding (permitted by default).

	      Disable port forwarding (permitted by default).

       no-pty Disable PTY allocation (permitted	by default).

	      Disable  execution  of  ~/.ssh/rc	 by  sshd(8) (permitted	by de-

	      Disable X11 forwarding (permitted	by default).

	      Allows ssh-agent(1) forwarding.

	      Allows port forwarding.

	      Allows PTY allocation.

	      Allows execution of ~/.ssh/rc by sshd(8).

	      Allows X11 forwarding.

	      Do not require signatures	made using this	key include demonstra-
	      tion of user presence (e.g. by having the	user touch the authen-
	      ticator).	 This option only makes	sense for the FIDO authentica-
	      tor algorithms ecdsa-sk and ed25519-sk.

       source-address Ns = Ns address_list
	      Restrict the source addresses from which the certificate is con-
	      sidered valid.  The address_list is a  comma-separated  list  of
	      one or more address/netmask pairs	in CIDR	format.

	      Require  signatures  made	 using this key	indicate that the user
	      was first	verified.  This	option only makes sense	for  the  FIDO
	      authenticator algorithms ecdsa-sk	and ed25519-sk.	 Currently PIN
	      authentication is	the only supported  verification  method,  but
	      other methods may	be supported in	the future.

	      At present, no standard options are valid	for host keys.

	      Finally,	certificates  may be defined with a validity lifetime.
	      The -V option allows specification of certificate	start and  end
	      times.   A  certificate that is presented	at a time outside this
	      range will not be	considered valid.   By	default,  certificates
	      are valid	from UNIX Epoch	to the distant future.

	      For certificates to be used for user or host authentication, the
	      CA public	key must be trusted by sshd(8) or ssh(1).  Please  re-
	      fer to those manual pages	for details.

       ssh-keygen  is  able  to	 manage	 OpenSSH  format  Key Revocation Lists
       (KRLs).	These binary files specify keys	or certificates	to be  revoked
       using  a	compact	format,	taking as little as one	bit per	certificate if
       they are	being revoked by serial	number.

       KRLs may	be generated using the -k flag.	 This option reads one or more
       files from the command line and generates a new KRL.  The files may ei-
       ther contain a KRL specification	(see below) or public keys, listed one
       per  line.  Plain public	keys are revoked by listing their hash or con-
       tents in	the KRL	and certificates revoked by serial number  or  key  ID
       (if the serial is zero or not available).

       Revoking	 keys  using  a	KRL specification offers explicit control over
       the types of record used	to revoke keys and may be used to directly re-
       voke  certificates  by  serial number or	key ID without having the com-
       plete original certificate on hand.  A KRL  specification  consists  of
       lines  containing  one  of the following	directives followed by a colon
       and some	directive-specific information.

       serial: serial_number[-serial_number]
	      Revokes a	certificate with the specified serial number.	Serial
	      numbers  are  64-bit  values,  not including zero	and may	be ex-
	      pressed in decimal, hex or octal.	 If  two  serial  numbers  are
	      specified	 separated  by a hyphen, then the range	of serial num-
	      bers including and between each is revoked.   The	 CA  key  must
	      have  been specified on the ssh-keygen command line using	the -s

       id: key_id
	      Revokes a	certificate with the specified key ID string.  The  CA
	      key  must	have been specified on the ssh-keygen command line us-
	      ing the -s option.

       key: public_key
	      Revokes the specified key.  If a certificate is listed, then  it
	      is revoked as a plain public key.

       sha1: public_key
	      Revokes the specified key	by including its SHA1 hash in the KRL.

       sha256: public_key
	      Revokes  the  specified  key by including	its SHA256 hash	in the
	      KRL.  KRLs that revoke keys by SHA256 hash are not supported  by
	      OpenSSH versions prior to	7.9.

       hash: fingerprint
	      Revokes  a  key  using  a	 fingerprint  hash, as obtained	from a
	      sshd(8) authentication log message or the	 ssh-keygen  -l	 flag.
	      Only  SHA256  fingerprints are supported here and	resultant KRLs
	      are not supported	by OpenSSH versions prior to 7.9.

	      KRLs may be updated using	the -u flag in addition	to  -k.	  When
	      this  option  is specified, keys listed via the command line are
	      merged into the KRL, adding to those already there.

	      It is also possible, given a KRL,	to test	whether	it  revokes  a
	      particular  key  (or  keys).  The	-Q flag	will query an existing
	      KRL, testing each	key specified on the command line.  If any key
	      listed on	the command line has been revoked (or an error encoun-
	      tered) then ssh-keygen will exit with a non-zero exit status.  A
	      zero exit	status will only be returned if	no key was revoked.

       When  verifying signatures, ssh-keygen uses a simple list of identities
       and keys	to determine whether a	signature  comes  from	an  authorized
       source.	 This "allowed signers"	file uses a format patterned after the
       AUTHORIZED_KEYS FILE FORMAT described in	sshd(8).   Each	 line  of  the
       file  contains  the  following  space-separated fields: principals, op-
       tions, keytype, base64-encoded key.  Empty  lines  and  lines  starting
       with a `#' are ignored as comments.

       The  principals field is	a pattern-list (See PATTERNS in	ssh_config(5))
       consisting of one or more comma-separated USER@DOMAIN identity patterns
       that  are accepted for signing.	When verifying,	the identity presented
       via the -I option must match a principals pattern in order for the cor-
       responding key to be considered acceptable for verification.

       The  options  (if present) consist of comma-separated option specifica-
       tions.  No spaces are permitted,	except within double quotes.  The fol-
       lowing  option  specifications are supported (note that option keywords
       are case-insensitive):

	      Indicates	that this key is accepted as a	certificate  authority
	      (CA) and that certificates signed	by this	CA may be accepted for

	      Specifies	a pattern-list of namespaces  that  are	 accepted  for
	      this  key.   If  this option is present, the signature namespace
	      embedded in the signature	object and presented on	the  verifica-
	      tion  command-line  must match the specified list	before the key
	      will be considered acceptable.

	      When verifying signatures	made  by  certificates,	 the  expected
	      principal	name must match	both the principals pattern in the al-
	      lowed signers file and the principals embedded in	 the  certifi-
	      cate itself.

	      An example allowed signers file:

	      #	Comments allowed at start of line, ssh-rsa AAAAX1...
	      #	 A  certificate	authority, trusted for all principals in a do-
	      * cert-authority ssh-ed25519 AAAB4...
	      #	A key that is accepted only for	file signing.	namespaces="file" ssh-ed25519 AAA41...

	      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.	 This file should not be readable by  anyone  but  the
	      user.   It  is  possible to specify a passphrase when generating
	      the key; that passphrase will be used  to	 encrypt  the  private
	      part of this file	using 128-bit AES.  This file is not automati-
	      cally accessed by	ssh-keygen but it is offered  as  the  default
	      file for the private key.	 ssh(1)	will read this file when a lo-
	      gin attempt is made.






	      Contains the DSA,	ECDSA,	authenticator-hosted  ECDSA,  Ed25519,
	      authenticator-hosted  Ed25519  or	RSA public key for authentica-
	      tion.  The contents of this file should be added	to  ~/.ssh/au-
	      thorized_keys  on	 all  machines where the user wishes to	log in
	      using public key authentication.	There is no need to  keep  the
	      contents of this file secret.

	      Contains Diffie-Hellman groups used for DH-GEX.  The file	format
	      is described in moduli(5).

       ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)

       The Secure Shell	(SSH) Public Key File Format, RFC 4716,	2006.

       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.

			       September 9 2020			 SSH-KEYGEN(1)


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

home | help