clarify when INTERMEDIATE is used

[dvanduzer]

The common format of a "keys" object and an "intermediates" object are very similar (base32 strings indexed by CSID), which confused me initially. Some notes on my current understanding:

• It's convenient to encode secrets and public keys as base32 strings so persistence formats can be all plain text.
• It's possible to handshake without knowing all of another endpoint's public keys, as long as you have all the INTERMEDIATE hashes and one public key.
• hashnames are always rolled up from the INTERMEDIATE object, not the keys object (though it is easy to turn a keys object into an INTERMEDIATE object)

The example here is confusing because the same 52-character string is reused for VALUE and INTERMEDIATE: https://github.com/telehash/telehash.org/tree/master/v3/hashname#final-rollup

Somewhat related, I think it will help to provide more clear examples of when to transmit keys versus intermediates here: https://github.com/telehash/telehash.org/tree/master/v3/e3x/cs#exchanging-cs-keys

The "Packet" version of INTERMEDIATE is used in handshakes, and the "JSON" encoding of full public keys is used for URIs. It might help to note that the full JSON representation of all the public keys is only used for URIs (or explicit list other limited cases, e.g. peer introduction?).

Misc suggestions:

• rename INTERMEDIATE to KEYHASH
• emphasize convention of SECRET versus KEY (as public key only)
• state simple rule for all key material representation: binary in body, base32 in JSON
• keys -> keyhashes
• keyhashes - > hashname

[quartzjer]

@dvanduzer I've made a few improvements based on your good suggestions here, let me know if they've helped, there's still parts that could be made better, but I want to make sure I'm on the right track.

I'm not sure about renaming INTERMEDIATE as a term to KEYHASH yet, it's pretty minor really, but I just want to make sure it's generally less confusing not more... on the fence :)

[dvanduzer]

On reflection, the confusion stems from a document convention of using QUOTED CAPS for binary on the wire.

It appears intermediate hashes of public keys will always be exchanged base32-encoded in JSON, and never in binary. But since the binary form is the input to the hashname calculation, it's tempting to capitalize the word intermediate. My confusion was compounded because VALUE refers to the binary representation in the hashname doc, but KEY is used to mean the same thing in all the cipherset docs.

Conceptually, I think intermediate hash is preferable to INTERMEDIATE but keyhash is nice because keyhash is still distinct without the markup. Another thought is hashprint.