sshwot-verify.1 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110
  1. .Dd Sep 08, 2018
  2. .Dt SSHWOT-VERIFY 1
  3. .Os
  4. .Sh NAME
  5. .Nm sshwot-verify
  6. .Nd Search sshwot files for matching fingerprints
  7. .Sh SYNOPSIS
  8. .Nm
  9. .Op Fl p , Fl -port Ar port
  10. .Ar host
  11. .Ar fingerprint
  12. .Op Ar sshwot-file...
  13. .Sh DESCRIPTION
  14. .Nm
  15. searches through sshwot files for the given host and fingerprint. If no files
  16. are specified on the command line, the ones in the directory
  17. .Pa ~/.sshwot
  18. are used.
  19. .Pp
  20. If
  21. .Nm
  22. finds a matching host and a matching fingerprint, it prints
  23. .Do
  24. .Li [ok]
  25. .Dc
  26. followed by the file name (without the
  27. .Li .sshwot
  28. extension), the host and the corresponding comment.
  29. .Pp
  30. If it finds a matching host, but the fingerprint doesn't match, it prints
  31. .Do
  32. .Li [fail]
  33. .Dc
  34. followed by the same information as when the fingerprint matches.
  35. .Pp
  36. If there were no cases where both the host and the fingerprint match in a given
  37. file, but there was another host which had the same fingerprint,
  38. .Nm
  39. will print
  40. .Do
  41. .Li [same fingerprint]
  42. .Dc
  43. followed by the same fields as before. However, since the hostnames are stored
  44. hashed, it can't know what the hostname was here. Due to that it prints
  45. .Do
  46. .Li (unknown host)
  47. .Dc
  48. in its place.
  49. .Pp
  50. The reason why the
  51. .Do
  52. .Li [same fingerprint]
  53. .Dc
  54. message is not printed if there is a full match in the same file is twofold.
  55. Firstly, there are only two cases where this kind of information is useful. One
  56. is if some other host is impersonating the host you are trying to reach, and
  57. other is if the host has several different domains and you are trying to verify
  58. one that is not in the sshwot files. Neither applies in the case where there is
  59. a full match for the host and the fingerprint. Secondly, it is quite common to
  60. have several domains resolving to one host in the same sshwot file. If the
  61. .Do
  62. .Li [same fingerprint]
  63. .Dc
  64. messages were printed unconditionally, the output would have a lot of useless
  65. information.
  66. .Pp
  67. .Nm
  68. can only handle fingerprints in the SHA256 format, which begins with
  69. .Do
  70. .Li SHA256:
  71. .Dc
  72. and then follows that with 43 base64 digits.
  73. .Sh OPTIONS
  74. .Bl -tag
  75. .It Fl p , Fl -port Ar port
  76. Search for keys specifically for an sshd running in the given port on the given
  77. host.
  78. .Nm
  79. will still accept keys generally for the host if a specific port is given. This
  80. is because the same is true for the
  81. .Pa known_hosts
  82. file of OpenSSH.
  83. .El
  84. .Sh EXIT STATUS
  85. .Nm
  86. returns the code 0 if at least one match was found and there were no matching
  87. hosts with different fingerprint. A non-zero exit code is returned otherwise.
  88. .Sh EXAMPLES
  89. .Bd -literal
  90. sshwot-verify example.com SHA256:Q9E3qf0ypXqIUGUhhKIDxNnZkUIIwXuDfsaK4vLI55U
  91. .Ed
  92. .Pp
  93. Checks the fingerprint for the host
  94. .Li example.com
  95. against the files stored in
  96. .Pa ~/.sshwot
  97. .Pp
  98. .Bd -literal
  99. sshwot-verify -p 443 secret.example.com SHA256:ZCHE6V++5H/pOeZVjMBF9+9R8ayVDS7IpSa3SpptQDY example.com-keys.sshwot
  100. .Ed
  101. .Pp
  102. Checks the fingerprint for the sshd running at port 443 on
  103. .Li example.com
  104. against the fingerprints stored in the file
  105. .Pa example.com-keys.sshwot
  106. .Sh SEE ALSO
  107. .Xr sshwot-export-known-hosts 1 ,
  108. .Xr sshwot-filter 1 ,
  109. .Xr sshwot 5