Skip to content

Introduce names for our cryptographic keys

Ian Jackson requested to merge Diziet/torspec:names-for-keys into main

Why names are essential

Names are important. Names for keys and nonces and so on are universally used elswhere in the cyrptographic protocol design community.

Properties that names need to have:

  • They are spelled exactly the same way whenever they are used.
  • They are relatively short.
  • They can be used directly (possibly with case conversion or other systematic adaptation) in code, as variable names.
  • They are never broken across lines.
  • The same name is not used for different things, even in different documents.

Consequences:

  • In general, easier cross-referencing of different references to the same key.
  • One can tell if two references are to the same key, even if the one lacks a mental model of the protocol, or is confused.
  • One can grep for the name to find where it is defined, and where it is used.
  • When one reads code, one can relate it to the corresponding protocol docs.
  • A name provides a mental "hook" to use as a framework for hanging one's understanding of the protocol.
  • Determining the referent of a name does not involve parsing prose.

I think that settling on some names is a blocker for Arti's Hidden Service support. Personally, when only prose is used, I find crypto design proposals almost impossible to comprehend.

Implications and non-implications of this MR

In this MR I propose some specific names for important keys.

Ideally, eventually, these names would be mentioned everywhere where a key is discussed (in all our specs and code). Obviously I do not propose to do make that change now.

Accepting this MR implies accepting future MRs that add uses of these names to places where keys (and nonces) are mentioned - in the Tor specifications, and in code. But it does not imply a commitment to a campaign of adding these names everywhere. (We probably have better things to do with our time.)

Specifics - painting the bikeshed

I do not mind precisely what names are chosen, but we should settle on some quickly. I will defer to others on this.

tor-spec.txt already speaks of KP, KS and K, so I adopted that.

Ideally it would be nice to use names which are close to the variable names already used in our codebases. But I asked around and I was told that C Tor at least doesn't name consistent naming. So I didn't actually investigate that further.

Merge request reports