From 224282095109fa5631ed54e4c65fb3c81d2c1ca9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juhani=20Krekel=C3=A4?= Date: Sat, 8 Sep 2018 20:59:22 +0300 Subject: [PATCH] Reword an awkward part of the manpage --- Makefile | 10 +++++----- sshwot-verify.1 | 42 ++++++++++++++++++++++++++---------------- 2 files changed, 31 insertions(+), 21 deletions(-) diff --git a/Makefile b/Makefile index 2f4a8a4..8ad3da8 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/sshwot-verify.1 b/sshwot-verify.1 index 87c54d9..4375b71 100644 --- a/sshwot-verify.1 +++ b/sshwot-verify.1 @@ -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