Annotation of src/usr.bin/ssh/ssh-keyscan.1, Revision 1.42
1.42 ! jmc 1: .\" $OpenBSD: ssh-keyscan.1,v 1.41 2018/02/23 05:14:05 djm Exp $
1.4 deraadt 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
1.6 pvalchev 7: .\" OpenBSD project by leaving this copyright notice intact.
1.3 niklas 8: .\"
1.42 ! jmc 9: .Dd $Mdocdate: February 23 2018 $
1.4 deraadt 10: .Dt SSH-KEYSCAN 1
1.1 markus 11: .Os
12: .Sh NAME
13: .Nm ssh-keyscan
14: .Nd gather ssh public keys
15: .Sh SYNOPSIS
16: .Nm ssh-keyscan
1.15 jmc 17: .Bk -words
1.41 djm 18: .Op Fl 46cDHv
1.20 jmc 19: .Op Fl f Ar file
1.10 markus 20: .Op Fl p Ar port
21: .Op Fl T Ar timeout
22: .Op Fl t Ar type
23: .Op Ar host | addrlist namelist
1.25 sobrado 24: .Ar ...
1.15 jmc 25: .Ek
1.1 markus 26: .Sh DESCRIPTION
27: .Nm
28: is a utility for gathering the public ssh host keys of a number of
1.15 jmc 29: hosts.
30: It was designed to aid in building and verifying
1.1 markus 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
1.15 jmc 39: parallel, so it is very efficient.
40: The keys from a domain of 1,000
1.1 markus 41: hosts can be collected in tens of seconds, even when some of those
1.15 jmc 42: hosts are down or do not run ssh.
43: For scanning, one does not need
1.12 deraadt 44: login access to the machines that are being scanned, nor does the
45: scanning process involve any encryption.
1.9 mpech 46: .Pp
47: The options are as follows:
1.1 markus 48: .Bl -tag -width Ds
1.20 jmc 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.
1.37 djm 57: .It Fl c
58: Request certificates from target hosts instead of plain keys.
1.41 djm 59: .It Fl D
60: Print keys found as SSHFP DNS records.
61: The default is to print keys in a format usable as a
62: .Xr ssh 1
63: .Pa known_hosts
64: file.
1.20 jmc 65: .It Fl f Ar file
66: Read hosts or
1.34 jmc 67: .Dq addrlist namelist
68: pairs from
69: .Ar file ,
70: one per line.
1.20 jmc 71: If
72: .Pa -
73: is supplied instead of a filename,
74: .Nm
75: will read hosts or
1.34 jmc 76: .Dq addrlist namelist
1.20 jmc 77: pairs from the standard input.
1.19 djm 78: .It Fl H
79: Hash all hostnames and addresses in the output.
80: Hashed names may be used normally by
81: .Nm ssh
82: and
83: .Nm sshd ,
84: but they do not reveal identifying information should the file's contents
85: be disclosed.
1.10 markus 86: .It Fl p Ar port
87: Port to connect to on the remote host.
1.11 stevesk 88: .It Fl T Ar timeout
1.15 jmc 89: Set the timeout for connection attempts.
90: If
1.34 jmc 91: .Ar timeout
1.1 markus 92: seconds have elapsed since a connection was initiated to a host or since the
93: last time anything was read from that host, then the connection is
1.15 jmc 94: closed and the host in question considered unavailable.
95: Default is 5 seconds.
1.10 markus 96: .It Fl t Ar type
1.11 stevesk 97: Specifies the type of the key to fetch from the scanned hosts.
1.10 markus 98: The possible values are
1.29 djm 99: .Dq dsa ,
1.33 naddy 100: .Dq ecdsa ,
101: .Dq ed25519 ,
1.29 djm 102: or
1.40 jmc 103: .Dq rsa .
1.10 markus 104: Multiple values may be specified by separating them with commas.
1.30 djm 105: The default is to fetch
1.35 naddy 106: .Dq rsa ,
107: .Dq ecdsa ,
1.30 djm 108: and
1.35 naddy 109: .Dq ed25519
1.30 djm 110: keys.
1.10 markus 111: .It Fl v
112: Verbose mode.
113: Causes
114: .Nm
115: to print debugging messages about its progress.
1.2 itojun 116: .El
1.9 mpech 117: .Sh SECURITY
1.22 ray 118: If an ssh_known_hosts file is constructed using
1.9 mpech 119: .Nm
1.12 deraadt 120: without verifying the keys, users will be vulnerable to
1.18 brad 121: .Em man in the middle
1.9 mpech 122: attacks.
1.12 deraadt 123: On the other hand, if the security model allows such a risk,
1.9 mpech 124: .Nm
1.12 deraadt 125: can help in the detection of tampered keyfiles or man in the middle
126: attacks which have begun after the ssh_known_hosts file was created.
1.1 markus 127: .Sh FILES
1.34 jmc 128: Input format:
1.10 markus 129: .Bd -literal
1.1 markus 130: 1.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
1.10 markus 131: .Ed
132: .Pp
1.36 sobrado 133: Output format for RSA, DSA, ECDSA, and Ed25519 keys:
1.10 markus 134: .Bd -literal
135: host-or-namelist keytype base64-encoded-key
136: .Ed
137: .Pp
138: Where
1.34 jmc 139: .Ar keytype
1.10 markus 140: is either
1.29 djm 141: .Dq ecdsa-sha2-nistp256 ,
142: .Dq ecdsa-sha2-nistp384 ,
143: .Dq ecdsa-sha2-nistp521 ,
1.32 markus 144: .Dq ssh-ed25519 ,
1.29 djm 145: .Dq ssh-dss
1.10 markus 146: or
1.29 djm 147: .Dq ssh-rsa .
1.1 markus 148: .Pp
1.13 deraadt 149: .Pa /etc/ssh/ssh_known_hosts
1.17 jmc 150: .Sh EXAMPLES
1.34 jmc 151: Print the rsa host key for machine
152: .Ar hostname :
1.17 jmc 153: .Bd -literal
154: $ ssh-keyscan hostname
155: .Ed
156: .Pp
157: Find all hosts from the file
158: .Pa ssh_hosts
159: which have new or different keys from those in the sorted file
160: .Pa ssh_known_hosts :
161: .Bd -literal
1.35 naddy 162: $ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
1.17 jmc 163: sort -u - ssh_known_hosts | diff ssh_known_hosts -
164: .Ed
1.1 markus 165: .Sh SEE ALSO
1.4 deraadt 166: .Xr ssh 1 ,
1.1 markus 167: .Xr sshd 8
1.42 ! jmc 168: .Rs
! 169: .%D 2006
1.41 djm 170: .%R RFC 4255
1.42 ! jmc 171: .%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
1.41 djm 172: .Re
1.7 mpech 173: .Sh AUTHORS
1.21 jaredy 174: .An -nosplit
1.31 schwarze 175: .An David Mazieres Aq Mt dm@lcs.mit.edu
1.10 markus 176: wrote the initial version, and
1.31 schwarze 177: .An Wayne Davison Aq Mt wayned@users.sourceforge.net
1.10 markus 178: added support for protocol version 2.
1.17 jmc 179: .Sh BUGS
180: It generates "Connection closed by remote host" messages on the consoles
181: of all the machines it scans if the server is older than version 2.9.
182: This is because it opens a connection to the ssh port, reads the public
183: key, and drops the connection as soon as it gets the key.