crypto/openssh/ssh-keyscan.1

   1 .\"     $OpenBSD: ssh-keyscan.1,v 1.38 2015/11/08 23:24:03 jmc Exp $
   2 .\"
   3 .\" Copyright 1995, 1996 by David Mazieres <dm@lcs.mit.edu>.
   4 .\"
   5 .\" Modification and redistribution in source and binary forms is
   6 .\" permitted provided that due credit is given to the author and the
   7 .\" OpenBSD project by leaving this copyright notice intact.
   8 .\"
   9 .Dd $Mdocdate: November 8 2015 $
  10 .Dt SSH-KEYSCAN 1
  11 .Os
  12 .Sh NAME
  13 .Nm ssh-keyscan
  14 .Nd gather ssh public keys
  15 .Sh SYNOPSIS
  16 .Nm ssh-keyscan
  17 .Bk -words
  18 .Op Fl 46cHv
  19 .Op Fl f Ar file
  20 .Op Fl p Ar port
  21 .Op Fl T Ar timeout
  22 .Op Fl t Ar type
  23 .Op Ar host | addrlist namelist
  24 .Ar ...
  25 .Ek
  26 .Sh DESCRIPTION
  27 .Nm
  28 is a utility for gathering the public ssh host keys of a number of
  29 hosts.
  30 It was designed to aid in building and verifying
  31 .Pa ssh_known_hosts
  32 files.
  33 .Nm
  34 provides a minimal interface suitable for use by shell and perl
  35 scripts.
  36 .Pp
  37 .Nm
  38 uses non-blocking socket I/O to contact as many hosts as possible in
  39 parallel, so it is very efficient.
  40 The keys from a domain of 1,000
  41 hosts can be collected in tens of seconds, even when some of those
  42 hosts are down or do not run ssh.
  43 For scanning, one does not need
  44 login access to the machines that are being scanned, nor does the
  45 scanning process involve any encryption.
  46 .Pp
  47 The options are as follows:
  48 .Bl -tag -width Ds
  49 .It Fl 4
  50 Forces
  51 .Nm
  52 to use IPv4 addresses only.
  53 .It Fl 6
  54 Forces
  55 .Nm
  56 to use IPv6 addresses only.
  57 .It Fl c
  58 Request certificates from target hosts instead of plain keys.
  59 .It Fl f Ar file
  60 Read hosts or
  61 .Dq addrlist namelist
  62 pairs from
  63 .Ar file ,
  64 one per line.
  65 If
  66 .Pa -
  67 is supplied instead of a filename,
  68 .Nm
  69 will read hosts or
  70 .Dq addrlist namelist
  71 pairs from the standard input.
  72 .It Fl H
  73 Hash all hostnames and addresses in the output.
  74 Hashed names may be used normally by
  75 .Nm ssh
  76 and
  77 .Nm sshd ,
  78 but they do not reveal identifying information should the file's contents
  79 be disclosed.
  80 .It Fl p Ar port
  81 Port to connect to on the remote host.
  82 .It Fl T Ar timeout
  83 Set the timeout for connection attempts.
  84 If
  85 .Ar timeout
  86 seconds have elapsed since a connection was initiated to a host or since the
  87 last time anything was read from that host, then the connection is
  88 closed and the host in question considered unavailable.
  89 Default is 5 seconds.
  90 .It Fl t Ar type
  91 Specifies the type of the key to fetch from the scanned hosts.
  92 The possible values are
  93 .Dq rsa1
  94 for protocol version 1 and
  95 .Dq dsa ,
  96 .Dq ecdsa ,
  97 .Dq ed25519 ,
  98 or
  99 .Dq rsa
 100 for protocol version 2.
 101 Multiple values may be specified by separating them with commas.
 102 The default is to fetch
 103 .Dq rsa ,
 104 .Dq ecdsa ,
 105 and
 106 .Dq ed25519
 107 keys.
 108 .It Fl v
 109 Verbose mode.
 110 Causes
 111 .Nm
 112 to print debugging messages about its progress.
 113 .El
 114 .Sh SECURITY
 115 If an ssh_known_hosts file is constructed using
 116 .Nm
 117 without verifying the keys, users will be vulnerable to
 118 .Em man in the middle
 119 attacks.
 120 On the other hand, if the security model allows such a risk,
 121 .Nm
 122 can help in the detection of tampered keyfiles or man in the middle
 123 attacks which have begun after the ssh_known_hosts file was created.
 124 .Sh FILES
 125 Input format:
 126 .Bd -literal
 127 1.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
 128 .Ed
 129 .Pp
 130 Output format for RSA1 keys:
 131 .Bd -literal
 132 host-or-namelist bits exponent modulus
 133 .Ed
 134 .Pp
 135 Output format for RSA, DSA, ECDSA, and Ed25519 keys:
 136 .Bd -literal
 137 host-or-namelist keytype base64-encoded-key
 138 .Ed
 139 .Pp
 140 Where
 141 .Ar keytype
 142 is either
 143 .Dq ecdsa-sha2-nistp256 ,
 144 .Dq ecdsa-sha2-nistp384 ,
 145 .Dq ecdsa-sha2-nistp521 ,
 146 .Dq ssh-ed25519 ,
 147 .Dq ssh-dss
 148 or
 149 .Dq ssh-rsa .
 150 .Pp
 151 .Pa /etc/ssh/ssh_known_hosts
 152 .Sh EXAMPLES
 153 Print the rsa host key for machine
 154 .Ar hostname :
 155 .Bd -literal
 156 $ ssh-keyscan hostname
 157 .Ed
 158 .Pp
 159 Find all hosts from the file
 160 .Pa ssh_hosts
 161 which have new or different keys from those in the sorted file
 162 .Pa ssh_known_hosts :
 163 .Bd -literal
 164 $ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
 165         sort -u - ssh_known_hosts | diff ssh_known_hosts -
 166 .Ed
 167 .Sh SEE ALSO
 168 .Xr ssh 1 ,
 169 .Xr sshd 8
 170 .Sh AUTHORS
 171 .An -nosplit
 172 .An David Mazieres Aq Mt dm@lcs.mit.edu
 173 wrote the initial version, and
 174 .An Wayne Davison Aq Mt wayned@users.sourceforge.net
 175 added support for protocol version 2.
 176 .Sh BUGS
 177 It generates "Connection closed by remote host" messages on the consoles
 178 of all the machines it scans if the server is older than version 2.9.
 179 This is because it opens a connection to the ssh port, reads the public
 180 key, and drops the connection as soon as it gets the key.