blob: d29d9d906479a319751033c3ce077523d9762058 [file] [log] [blame]
jmc@openbsd.orge72a8572015-11-08 23:24:03 +00001.\" $OpenBSD: ssh-keyscan.1,v 1.38 2015/11/08 23:24:03 jmc Exp $
Ben Lindstromb22c2b82001-03-05 06:50:47 +00002.\"
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
Ben Lindstroma238f6e2001-06-09 01:30:39 +00007.\" OpenBSD project by leaving this copyright notice intact.
Ben Lindstrom36579d32001-01-29 07:39:26 +00008.\"
djm@openbsd.org3a424cd2015-11-08 22:30:20 +00009.Dd $Mdocdate: November 8 2015 $
Ben Lindstromb22c2b82001-03-05 06:50:47 +000010.Dt SSH-KEYSCAN 1
Ben Lindstromb6434ae2000-12-05 01:15:09 +000011.Os
12.Sh NAME
13.Nm ssh-keyscan
14.Nd gather ssh public keys
15.Sh SYNOPSIS
16.Nm ssh-keyscan
Damien Miller495dca32003-04-01 21:42:14 +100017.Bk -words
jmc@openbsd.orge72a8572015-11-08 23:24:03 +000018.Op Fl 46cHv
Damien Miller9a2fdbd2005-03-02 12:04:01 +110019.Op Fl f Ar file
Ben Lindstrom325e70c2001-08-06 22:41:30 +000020.Op Fl p Ar port
21.Op Fl T Ar timeout
22.Op Fl t Ar type
Ben Lindstrom325e70c2001-08-06 22:41:30 +000023.Op Ar host | addrlist namelist
Damien Millerc1719f72008-11-03 19:27:07 +110024.Ar ...
Damien Miller495dca32003-04-01 21:42:14 +100025.Ek
Ben Lindstromb6434ae2000-12-05 01:15:09 +000026.Sh DESCRIPTION
27.Nm
28is a utility for gathering the public ssh host keys of a number of
Damien Miller495dca32003-04-01 21:42:14 +100029hosts.
30It was designed to aid in building and verifying
Ben Lindstromb6434ae2000-12-05 01:15:09 +000031.Pa ssh_known_hosts
32files.
33.Nm
34provides a minimal interface suitable for use by shell and perl
35scripts.
36.Pp
37.Nm
38uses non-blocking socket I/O to contact as many hosts as possible in
Damien Miller495dca32003-04-01 21:42:14 +100039parallel, so it is very efficient.
40The keys from a domain of 1,000
Ben Lindstromb6434ae2000-12-05 01:15:09 +000041hosts can be collected in tens of seconds, even when some of those
Damien Miller495dca32003-04-01 21:42:14 +100042hosts are down or do not run ssh.
43For scanning, one does not need
Ben Lindstrom594e2032001-09-12 18:35:30 +000044login access to the machines that are being scanned, nor does the
45scanning process involve any encryption.
Ben Lindstrom0b5afb92001-08-06 22:01:29 +000046.Pp
47The options are as follows:
Ben Lindstromb6434ae2000-12-05 01:15:09 +000048.Bl -tag -width Ds
Damien Miller9a2fdbd2005-03-02 12:04:01 +110049.It Fl 4
50Forces
51.Nm
52to use IPv4 addresses only.
53.It Fl 6
54Forces
55.Nm
56to use IPv6 addresses only.
djm@openbsd.org3a424cd2015-11-08 22:30:20 +000057.It Fl c
58Request certificates from target hosts instead of plain keys.
Damien Miller9a2fdbd2005-03-02 12:04:01 +110059.It Fl f Ar file
60Read hosts or
Damien Millerf8f35bc2014-02-04 11:09:12 +110061.Dq addrlist namelist
62pairs from
63.Ar file ,
64one per line.
Damien Miller9a2fdbd2005-03-02 12:04:01 +110065If
66.Pa -
67is supplied instead of a filename,
68.Nm
69will read hosts or
Damien Millerf8f35bc2014-02-04 11:09:12 +110070.Dq addrlist namelist
Damien Miller9a2fdbd2005-03-02 12:04:01 +110071pairs from the standard input.
Damien Millerdb7b8172005-03-01 21:48:03 +110072.It Fl H
73Hash all hostnames and addresses in the output.
74Hashed names may be used normally by
75.Nm ssh
76and
77.Nm sshd ,
78but they do not reveal identifying information should the file's contents
79be disclosed.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000080.It Fl p Ar port
81Port to connect to on the remote host.
Ben Lindstrom8d066fb2001-09-12 17:06:13 +000082.It Fl T Ar timeout
Damien Miller495dca32003-04-01 21:42:14 +100083Set the timeout for connection attempts.
84If
Damien Millerf8f35bc2014-02-04 11:09:12 +110085.Ar timeout
Ben Lindstromb6434ae2000-12-05 01:15:09 +000086seconds have elapsed since a connection was initiated to a host or since the
87last time anything was read from that host, then the connection is
Damien Miller495dca32003-04-01 21:42:14 +100088closed and the host in question considered unavailable.
89Default is 5 seconds.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000090.It Fl t Ar type
Ben Lindstrom8d066fb2001-09-12 17:06:13 +000091Specifies the type of the key to fetch from the scanned hosts.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000092The possible values are
93.Dq rsa1
94for protocol version 1 and
Damien Millereb8b60e2010-08-31 22:41:14 +100095.Dq dsa ,
Damien Miller8ba0ead2013-12-18 17:46:27 +110096.Dq ecdsa ,
97.Dq ed25519 ,
Ben Lindstrom325e70c2001-08-06 22:41:30 +000098or
Damien Millereb8b60e2010-08-31 22:41:14 +100099.Dq rsa
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000100for protocol version 2.
101Multiple values may be specified by separating them with commas.
Damien Miller839f7432012-04-22 11:24:21 +1000102The default is to fetch
Damien Miller94bfe0f2014-04-20 13:00:51 +1000103.Dq rsa ,
104.Dq ecdsa ,
Damien Miller839f7432012-04-22 11:24:21 +1000105and
Damien Miller94bfe0f2014-04-20 13:00:51 +1000106.Dq ed25519
Damien Miller839f7432012-04-22 11:24:21 +1000107keys.
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000108.It Fl v
109Verbose mode.
110Causes
111.Nm
112to print debugging messages about its progress.
Ben Lindstromd26dcf32001-01-06 15:18:16 +0000113.El
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000114.Sh SECURITY
Darren Tuckerffe88e12006-10-18 07:53:06 +1000115If an ssh_known_hosts file is constructed using
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000116.Nm
Ben Lindstrom594e2032001-09-12 18:35:30 +0000117without verifying the keys, users will be vulnerable to
Darren Tucker3ca45082004-07-17 16:13:15 +1000118.Em man in the middle
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000119attacks.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000120On the other hand, if the security model allows such a risk,
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000121.Nm
Ben Lindstrom594e2032001-09-12 18:35:30 +0000122can help in the detection of tampered keyfiles or man in the middle
123attacks which have begun after the ssh_known_hosts file was created.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000124.Sh FILES
Damien Millerf8f35bc2014-02-04 11:09:12 +1100125Input format:
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000126.Bd -literal
Ben Lindstromb6434ae2000-12-05 01:15:09 +00001271.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000128.Ed
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000129.Pp
Damien Miller94bfe0f2014-04-20 13:00:51 +1000130Output format for RSA1 keys:
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000131.Bd -literal
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000132host-or-namelist bits exponent modulus
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000133.Ed
134.Pp
sobrado@openbsd.orgf70b22b2014-08-30 15:33:50 +0000135Output format for RSA, DSA, ECDSA, and Ed25519 keys:
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000136.Bd -literal
137host-or-namelist keytype base64-encoded-key
138.Ed
139.Pp
140Where
Damien Millerf8f35bc2014-02-04 11:09:12 +1100141.Ar keytype
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000142is either
Damien Millereb8b60e2010-08-31 22:41:14 +1000143.Dq ecdsa-sha2-nistp256 ,
144.Dq ecdsa-sha2-nistp384 ,
145.Dq ecdsa-sha2-nistp521 ,
Damien Miller5be9d9e2013-12-07 11:24:01 +1100146.Dq ssh-ed25519 ,
Damien Millereb8b60e2010-08-31 22:41:14 +1000147.Dq ssh-dss
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000148or
Damien Millereb8b60e2010-08-31 22:41:14 +1000149.Dq ssh-rsa .
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000150.Pp
Damien Miller05eda432002-02-10 18:32:28 +1100151.Pa /etc/ssh/ssh_known_hosts
Damien Millerf1ce5052003-06-11 22:04:39 +1000152.Sh EXAMPLES
Damien Millerf8f35bc2014-02-04 11:09:12 +1100153Print the rsa host key for machine
154.Ar hostname :
Damien Millerf1ce5052003-06-11 22:04:39 +1000155.Bd -literal
156$ ssh-keyscan hostname
157.Ed
158.Pp
159Find all hosts from the file
160.Pa ssh_hosts
161which have new or different keys from those in the sorted file
162.Pa ssh_known_hosts :
163.Bd -literal
Damien Miller94bfe0f2014-04-20 13:00:51 +1000164$ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
Damien Millerf1ce5052003-06-11 22:04:39 +1000165 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
Darren Tucker28e8e592005-10-03 18:20:28 +1000171.An -nosplit
Damien Millerbf836e52013-07-18 16:14:13 +1000172.An David Mazieres Aq Mt dm@lcs.mit.edu
Damien Millerf1ce5052003-06-11 22:04:39 +1000173wrote the initial version, and
Damien Millerbf836e52013-07-18 16:14:13 +1000174.An Wayne Davison Aq Mt wayned@users.sourceforge.net
Damien Millerf1ce5052003-06-11 22:04:39 +1000175added support for protocol version 2.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000176.Sh BUGS
177It generates "Connection closed by remote host" messages on the consoles
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000178of all the machines it scans if the server is older than version 2.9.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000179This is because it opens a connection to the ssh port, reads the public
180key, and drops the connection as soon as it gets the key.