Browse Source

Reword an awkward part of the manpage

Juhani Krekelä 1 year ago
parent
commit
2242820951
2 changed files with 31 additions and 21 deletions
  1. 5 5
      Makefile
  2. 26 16
      sshwot-verify.1

+ 5 - 5
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)

+ 26 - 16
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