Reword an awkward part of the manpage

This commit is contained in:
Juhani Krekelä 2018-09-08 20:59:22 +03:00
parent ef51f70342
commit 2242820951
2 changed files with 31 additions and 21 deletions

View File

@ -6,7 +6,7 @@ DATAROOTDIR?=$(PREFIX)/share
MANDIR?=$(DATAROOTDIR)/man
BINS:=sshwot-export-known-hosts sshwot-filter sshwot-verify
MANS:=sshwot-verify.1
MAN1S:=sshwot-verify.1
SSHWOT_EXPORT_KNOWN_HOSTS_MAIN:=src/main-export-known-hosts.py
SSHWOT_EXPORT_KNOWN_HOSTS_DEPS:=src/entry.py src/hashing.py src/process_known_hosts.py src/write_file.py
@ -39,15 +39,15 @@ sshwot-verify: $(SSHWOT_VERIFY_MAIN) $(SSHWOT_VERIFY_DEPS)
.PHONY: all install unininstall clean distclean buildclean
install: $(BINS) $(MANS)
install: $(BINS) $(MAN1S)
mkdir -p $(DESTDIR)$(BINDIR)
install $(BINS) $(DESTDIR)$(BINDIR)
mkdir -p $(DESTDIR)$(MANDIR)
cp $(MANS) $(DESTDIR)$(MANDIR)
mkdir -p $(DESTDIR)$(MANDIR)/man1
cp $(MAN1S) $(DESTDIR)$(MANDIR)/man1
uninstall:
rm $(DESTDIR)$(BINDIR)/sshwot-export-known-hosts $(DESTDIR)$(BINDIR)/sshwot-filter $(DESTDIR)$(BINDIR)/sshwot-verify
rm $(DESTDIR)$(MANDIR)/sshwot-verify.1
rm $(DESTDIR)$(MANDIR)/man1/sshwot-verify.1
clean:
rm -rf build $(BINS)

View File

@ -9,7 +9,7 @@
.Op Fl p , Fl -port Ar port
.Ar host
.Ar fingerprint
.Op Ar sshwot-file Op Ar sshwot-file ....
.Op Ar sshwot-file...
.Sh DESCRIPTION
.Nm
searches through either the given sshwot files or the files located in the
@ -25,8 +25,7 @@ finds a matching host and a matching fingerprint, it prints
.Dc
followed by the file name (without the
.Li .sshwot
extension), the host and the comment that was given to that host and fingerprint
combination in that file.
extension), the host and the corresponding comment.
.Pp
If it finds a matching host, but the fingerprint doesn't match, it prints
.Do
@ -42,22 +41,29 @@ will print
.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, and so it prints
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 reasoning for not printing these in case there is a full
match in the file is that these are mainly useful when some other host is
impersonating the host you are trying to reach or if the host has several
different domains and you are trying to verify one that is not in the sshwot
files. In the first case, since the given host and fingerprint combination is
verified in the same file, there is no danger of that. In the second case, this
information is likewise useless, since the file did in fact contain the given
domain. In addition to that, it for hosts that have several domains it is quite
common for them all to be in the same sshwot file, so unconditionally printing
them out would make the output contain useless noise in normal use cases.
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 the 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. Latter is only useful if the host was not found, and
if there is a full match for the host and the fingerprint, there is no danger of
another server impersonating it. Secondly, it is quite common to have several
domains resolving into 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
@ -81,14 +87,18 @@ file of OpenSSH.
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
.Li sshwot-verify example.com SHA256:Q9E3qf0ypXqIUGUhhKIDxNnZkUIIwXuDfsaK4vLI55U
.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
.Li sshwot-verify -p 443 secret.example.com SHA256:ZCHE6V++5H/pOeZVjMBF9+9R8ayVDS7IpSa3SpptQDY example.com-keys.sshwot
.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