Annotation of src/usr.bin/ssh/ssh-keyscan.1, Revision 1.48
1.48 ! djm 1: .\" $OpenBSD: ssh-keyscan.1,v 1.47 2022/10/28 02:29:34 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.48 ! djm 9: .Dd $Mdocdate: October 28 2022 $
1.4 deraadt 10: .Dt SSH-KEYSCAN 1
1.1 markus 11: .Os
12: .Sh NAME
13: .Nm ssh-keyscan
1.45 jmc 14: .Nd gather SSH public keys from servers
1.1 markus 15: .Sh SYNOPSIS
16: .Nm ssh-keyscan
1.41 djm 17: .Op Fl 46cDHv
1.20 jmc 18: .Op Fl f Ar file
1.48 ! djm 19: .Op Fl O Ar option
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.1 markus 24: .Sh DESCRIPTION
25: .Nm
1.43 jmc 26: is a utility for gathering the public SSH host keys of a number of
1.15 jmc 27: hosts.
28: It was designed to aid in building and verifying
1.1 markus 29: .Pa ssh_known_hosts
1.44 jmc 30: files,
31: the format of which is documented in
32: .Xr sshd 8 .
1.1 markus 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.43 jmc 42: hosts are down or do not run
43: .Xr sshd 8 .
1.15 jmc 44: For scanning, one does not need
1.12 deraadt 45: login access to the machines that are being scanned, nor does the
46: scanning process involve any encryption.
1.9 mpech 47: .Pp
1.47 djm 48: Hosts to be scanned may be specified by hostname, address or by CIDR
49: network range (e.g. 192.168.16/28).
50: If a network range is specified, then all addresses in that range will
51: be scanned.
52: .Pp
1.9 mpech 53: The options are as follows:
1.1 markus 54: .Bl -tag -width Ds
1.20 jmc 55: .It Fl 4
1.43 jmc 56: Force
1.20 jmc 57: .Nm
58: to use IPv4 addresses only.
59: .It Fl 6
1.43 jmc 60: Force
1.20 jmc 61: .Nm
62: to use IPv6 addresses only.
1.37 djm 63: .It Fl c
64: Request certificates from target hosts instead of plain keys.
1.41 djm 65: .It Fl D
66: Print keys found as SSHFP DNS records.
67: The default is to print keys in a format usable as a
68: .Xr ssh 1
69: .Pa known_hosts
70: file.
1.20 jmc 71: .It Fl f Ar file
72: Read hosts or
1.34 jmc 73: .Dq addrlist namelist
74: pairs from
75: .Ar file ,
76: one per line.
1.20 jmc 77: If
1.43 jmc 78: .Sq -
1.20 jmc 79: is supplied instead of a filename,
80: .Nm
1.43 jmc 81: will read from the standard input.
1.47 djm 82: Names read from a file must start with an address, hostname or CIDR network
83: range to be scanned.
84: Addresses and hostnames may optionally be followed by comma-separated name
85: or address aliases that will be copied to the output.
86: For example:
1.44 jmc 87: .Bd -literal
1.47 djm 88: 192.168.11.0/24
89: 10.20.1.1
90: happy.example.org
91: 10.0.0.1,sad.example.org
1.44 jmc 92: .Ed
1.19 djm 93: .It Fl H
94: Hash all hostnames and addresses in the output.
95: Hashed names may be used normally by
1.43 jmc 96: .Xr ssh 1
1.19 djm 97: and
1.43 jmc 98: .Xr sshd 8 ,
1.19 djm 99: but they do not reveal identifying information should the file's contents
100: be disclosed.
1.48 ! djm 101: .It Fl O Ar option
! 102: Specify a key/value option.
! 103: At present, only a single option is supported:
! 104: .Bl -tag -width Ds
! 105: .It Cm hashalg Ns = Ns Ar algorithm
! 106: Selects a hash algorithm to use when printing SSHFP records using the
! 107: .Fl D
! 108: flag.
! 109: Valid algorithms are
! 110: .Dq sha1
! 111: and
! 112: .Dq sha256.
! 113: The default is to print both.
! 114: .El
1.10 markus 115: .It Fl p Ar port
1.43 jmc 116: Connect to
117: .Ar port
118: on the remote host.
1.11 stevesk 119: .It Fl T Ar timeout
1.15 jmc 120: Set the timeout for connection attempts.
121: If
1.34 jmc 122: .Ar timeout
1.1 markus 123: seconds have elapsed since a connection was initiated to a host or since the
1.43 jmc 124: last time anything was read from that host, the connection is
1.15 jmc 125: closed and the host in question considered unavailable.
1.43 jmc 126: The default is 5 seconds.
1.10 markus 127: .It Fl t Ar type
1.43 jmc 128: Specify the type of the key to fetch from the scanned hosts.
1.10 markus 129: The possible values are
1.29 djm 130: .Dq dsa ,
1.33 naddy 131: .Dq ecdsa ,
132: .Dq ed25519 ,
1.46 dtucker 133: .Dq ecdsa-sk ,
134: .Dq ed25519-sk ,
1.29 djm 135: or
1.40 jmc 136: .Dq rsa .
1.10 markus 137: Multiple values may be specified by separating them with commas.
1.30 djm 138: The default is to fetch
1.35 naddy 139: .Dq rsa ,
140: .Dq ecdsa ,
1.46 dtucker 141: .Dq ed25519 ,
142: .Dq ecdsa-sk ,
1.30 djm 143: and
1.46 dtucker 144: .Dq ed25519-sk
1.30 djm 145: keys.
1.10 markus 146: .It Fl v
1.43 jmc 147: Verbose mode:
148: print debugging messages about progress.
1.2 itojun 149: .El
1.43 jmc 150: .Pp
1.22 ray 151: If an ssh_known_hosts file is constructed using
1.9 mpech 152: .Nm
1.12 deraadt 153: without verifying the keys, users will be vulnerable to
1.18 brad 154: .Em man in the middle
1.9 mpech 155: attacks.
1.12 deraadt 156: On the other hand, if the security model allows such a risk,
1.9 mpech 157: .Nm
1.12 deraadt 158: can help in the detection of tampered keyfiles or man in the middle
159: attacks which have begun after the ssh_known_hosts file was created.
1.1 markus 160: .Sh FILES
1.13 deraadt 161: .Pa /etc/ssh/ssh_known_hosts
1.17 jmc 162: .Sh EXAMPLES
1.43 jmc 163: Print the RSA host key for machine
1.34 jmc 164: .Ar hostname :
1.43 jmc 165: .Pp
166: .Dl $ ssh-keyscan -t rsa hostname
1.47 djm 167: .Pp
168: Search a network range, printing all supported key types:
169: .Pp
170: .Dl $ ssh-keyscan 192.168.0.64/25
1.17 jmc 171: .Pp
172: Find all hosts from the file
173: .Pa ssh_hosts
174: which have new or different keys from those in the sorted file
175: .Pa ssh_known_hosts :
1.43 jmc 176: .Bd -literal -offset indent
1.35 naddy 177: $ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
1.17 jmc 178: sort -u - ssh_known_hosts | diff ssh_known_hosts -
179: .Ed
1.1 markus 180: .Sh SEE ALSO
1.4 deraadt 181: .Xr ssh 1 ,
1.1 markus 182: .Xr sshd 8
1.42 jmc 183: .Rs
184: .%D 2006
1.41 djm 185: .%R RFC 4255
1.42 jmc 186: .%T Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
1.41 djm 187: .Re
1.7 mpech 188: .Sh AUTHORS
1.21 jaredy 189: .An -nosplit
1.31 schwarze 190: .An David Mazieres Aq Mt dm@lcs.mit.edu
1.10 markus 191: wrote the initial version, and
1.31 schwarze 192: .An Wayne Davison Aq Mt wayned@users.sourceforge.net
1.10 markus 193: added support for protocol version 2.