openssh bugs - Apr 2016 - [Bug 2560] New: sshd: Description of hashed known_hosts file does not make sense and format is outdated

https://bugzilla.mindrot.org/show_bug.cgi?id=2560

            Bug ID: 2560
           Summary: sshd: Description of hashed known_hosts file does not
                    make sense and format is outdated
           Product: Portable OpenSSH
           Version: -current
          Hardware: Other
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P5
         Component: Documentation
          Assignee: unassigned-bugs at mindrot.org
          Reporter: jjelen at redhat.com

Manual page for  sshd  states:

    Alternately, hostnames may be stored in a hashed form which hides
    host names and addresses should the file's contents be disclosed.

The ending part "should the file's contents be disclosed" does not
fit
into the sentence and I am not sure what is meant by that.

It is there for a long time, since
e1776155d19db4f3ab2ff42323d6499f0712cfa4


Also the format, described as:

    Each line in these files contains the following fields: markers
(optional),
    hostnames, bits, exponent, modulus, comment.

is outdated (describes RSA1 keys). In current situation the part "bits,
exponent, modulus" is substituted by "keytype, base64-encoded
key" as
described for example in  authorized_keys  section.


I hit this problem while referencing to the format of this file.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=2560

Damien Miller <djm at mindrot.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |djm at mindrot.org

--- Comment #1 from Damien Miller <djm at mindrot.org> ---
It's saying that (In reply to Jakub Jelen from comment
#0)
> Manual page for  sshd  states:
> 
>     Alternately, hostnames may be stored in a hashed form which hides
>     host names and addresses should the file's contents be disclosed.
> 
> The ending part "should the file's contents be disclosed"
does not
> fit into the sentence and I am not sure what is meant by that.
> 
> It is there for a long time, since
> e1776155d19db4f3ab2ff42323d6499f0712cfa4
It's saying that if someone gets a hold ("be disclosed") of your
known_hosts file then the host name/address will still have some
privacy. AFAIK it's grammatical, but I'm open to a better wording.

> Also the format, described as:
> 
>     Each line in these files contains the following fields: markers
> (optional),
>     hostnames, bits, exponent, modulus, comment.
> 
> is outdated (describes RSA1 keys). In current situation the part
> "bits, exponent, modulus" is substituted by "keytype,
base64-encoded
> key" as described for example in  authorized_keys  section.
How about:

-hostnames, bits, exponent, modulus, comment.
+hostnames, key type, key content (base-64 encoded), comment.

We're taking the habit of referring to SSH protocol 2 features only in
anticipation of a future removal of SSH 1 code in a few years.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=2560

--- Comment #2 from Jakub Jelen <jjelen at redhat.com> ---
(In reply to Damien Miller from comment #1)
> >     Alternately, hostnames may be stored in a hashed form which hides
> >     host names and addresses should the file's contents be
disclosed.
> 
> It's saying that if someone gets a hold ("be disclosed") of
your
> known_hosts file then the host name/address will still have some
> privacy. AFAIK it's grammatical, but I'm open to a better wording.
I am not native, so finally I checked in the dictionary, and there is
really such a meaning, but it is the first time I saw word "should" in
meaning of "in case"/"if". I got the idea about the meaning,
but IMHO
language of manual pages does not have to be super-fancy, but rather
simple if we want people to read them. Proposal:

    Alternately, hostnames may be stored in a hashed form which hides
    host names and addresses in case of the file's contents disclosure.
> -hostnames, bits, exponent, modulus, comment.
> +hostnames, key type, key content (base-64 encoded), comment.
I am fine with that. I based my proposal on the same format description
in authorized_keys section:

    Protocol 2 public key consist of: options, keytype, base64-encoded
key, comment. 

Your sounds better, but it would be nice to have the format consistent
across manual pages (in the same words) not to confuse people more than
is necessary.

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=2560

Damien Miller <djm at mindrot.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|---                         |FIXED

--- Comment #3 from Damien Miller <djm at mindrot.org> ---
I've tweaked the wording of HashKnownHosts and the RSA1-specific format
description is long gone

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
You are watching someone on the CC list of the bug.

https://bugzilla.mindrot.org/show_bug.cgi?id=2560

Damien Miller <djm at mindrot.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |CLOSED

--- Comment #4 from Damien Miller <djm at mindrot.org> ---
closing resolved bugs as of 8.6p1 release

-- 
You are receiving this mail because:
You are watching someone on the CC list of the bug.
You are watching the assignee of the bug.