From ef51f7034246ec37e10bc8c9480dc6faa0703197 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juhani=20Krekel=C3=A4?= Date: Sat, 8 Sep 2018 20:31:07 +0300 Subject: [PATCH] Add the man page for sshwot-verify --- Makefile | 20 +++++++++- README.md | 4 +- sshwot-verify.1 | 100 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 sshwot-verify.1 diff --git a/Makefile b/Makefile index 2f646ce..2f4a8a4 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,12 @@ +DESTDIR?= +PREFIX?=/usr/local +EXEC_PREFIX?=$(PREFIX) +BINDIR?=$(DESTDIR)$(EXEC_PREFIX)/bin +DATAROOTDIR?=$(PREFIX)/share +MANDIR?=$(DATAROOTDIR)/man + BINS:=sshwot-export-known-hosts sshwot-filter sshwot-verify +MANS:=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 @@ -29,7 +37,17 @@ sshwot-verify: $(SSHWOT_VERIFY_MAIN) $(SSHWOT_VERIFY_DEPS) cp $(SSHWOT_VERIFY_MAIN) build/$@/__main__.py python3 -m zipapp -o $@ -p "/usr/bin/env python3" build/$@ -.PHONY: all clean distclean buildclean +.PHONY: all install unininstall clean distclean buildclean + +install: $(BINS) $(MANS) + mkdir -p $(DESTDIR)$(BINDIR) + install $(BINS) $(DESTDIR)$(BINDIR) + mkdir -p $(DESTDIR)$(MANDIR) + cp $(MANS) $(DESTDIR)$(MANDIR) + +uninstall: + rm $(DESTDIR)$(BINDIR)/sshwot-export-known-hosts $(DESTDIR)$(BINDIR)/sshwot-filter $(DESTDIR)$(BINDIR)/sshwot-verify + rm $(DESTDIR)$(MANDIR)/sshwot-verify.1 clean: rm -rf build $(BINS) diff --git a/README.md b/README.md index 5346b14..cd2a282 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ TODO * `egrep 'TODO|FIXME|XXX' src/*.py` * Convert format description to mandoc -* Write manpages -* Add `install` and `uninstall` makefile targets +* Write manpages for `sshwot-export-known-hosts` and `sshwot-filter` +* `sshwot-alter` * `sshwot-scan-known-hosts` * Investigate why it says sshwot-file is required in `sshwot-filter` diff --git a/sshwot-verify.1 b/sshwot-verify.1 new file mode 100644 index 0000000..87c54d9 --- /dev/null +++ b/sshwot-verify.1 @@ -0,0 +1,100 @@ +.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 Op Ar sshwot-file .... +.Sh DESCRIPTION +.Nm +searches through either the given sshwot files or the files located in the +directory +.Pa ~/.sshwot +for a matching host and fingerprint for the ones given in the command line. +.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 comment that was given to that host and fingerprint +combination in that file. +.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, and so 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. +.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 +.Li sshwot-verify example.com SHA256:Q9E3qf0ypXqIUGUhhKIDxNnZkUIIwXuDfsaK4vLI55U +.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 +.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