sshwot/sshwot-verify.1

110 lines
3.0 KiB
Groff

.Dd Sep 08, 2018
.Dt SSHWOT-VERIFY 1
.Os
.Sh NAME
.Nm sshwot-verify
.Nd Search sshwot files for matching fingerprints
.Sh SYNOPSIS
.Nm
.Op Fl p , Fl -port Ar port
.Ar host
.Ar fingerprint
.Op Ar sshwot-file...
.Sh DESCRIPTION
.Nm
searches through sshwot files for the given host and fingerprint. If no files
are specified on the command line, the ones in the directory
.Pa ~/.sshwot
are used.
.Pp
If
.Nm
finds a matching host and a matching fingerprint, it prints
.Do
.Li [ok]
.Dc
followed by the file name (without the
.Li .sshwot
extension), the host and the corresponding comment.
.Pp
If it finds a matching host, but the fingerprint doesn't match, it prints
.Do
.Li [fail]
.Dc
followed by the same information as when the fingerprint matches.
.Pp
If there were no cases where both the host and the fingerprint match in a given
file, but there was another host which had the same fingerprint,
.Nm
will print
.Do
.Li [same fingerprint]
.Dc
followed by the same fields as before. However, since the hostnames are stored
hashed, it can't know what the hostname was here. Due to that it prints
.Do
.Li (unknown host)
.Dc
in its place.
.Pp
The reason why the
.Do
.Li [same fingerprint]
.Dc
message is not printed if there is a full match in the same file is twofold.
Firstly, there are only two cases where this kind of information is useful. One
is if some other host is impersonating the host you are trying to reach, and
other is if the host has several different domains and you are trying to verify
one that is not in the sshwot files. Neither applies in the case where there is
a full match for the host and the fingerprint. Secondly, it is quite common to
have several domains resolving to one host in the same sshwot file. If the
.Do
.Li [same fingerprint]
.Dc
messages were printed unconditionally, the output would have a lot of useless
information.
.Pp
.Nm
can only handle fingerprints in the SHA256 format, which begins with
.Do
.Li SHA256:
.Dc
and then follows that with 43 base64 digits.
.Sh OPTIONS
.Bl -tag
.It Fl p , Fl -port Ar port
Search for keys specifically for an sshd running in the given port on the given
host.
.Nm
will still accept keys generally for the host if a specific port is given. This
is because the same is true for the
.Pa known_hosts
file of OpenSSH.
.El
.Sh EXIT STATUS
.Nm
returns the code 0 if at least one match was found and there were no matching
hosts with different fingerprint. A non-zero exit code is returned otherwise.
.Sh EXAMPLES
.Bd -literal
sshwot-verify example.com SHA256:Q9E3qf0ypXqIUGUhhKIDxNnZkUIIwXuDfsaK4vLI55U
.Ed
.Pp
Checks the fingerprint for the host
.Li example.com
against the files stored in
.Pa ~/.sshwot
.Pp
.Bd -literal
sshwot-verify -p 443 secret.example.com SHA256:ZCHE6V++5H/pOeZVjMBF9+9R8ayVDS7IpSa3SpptQDY example.com-keys.sshwot
.Ed
.Pp
Checks the fingerprint for the sshd running at port 443 on
.Li example.com
against the fingerprints stored in the file
.Pa example.com-keys.sshwot
.Sh SEE ALSO
.Xr sshwot-export-known-hosts 1 ,
.Xr sshwot-filter 1 ,
.Xr sshwot 5