Skip to content

Use names from the spec for cryptographic keys and nonces

Now that we have agreed names for keys (torspec!105 (closed)) we should use these names in our code.

Type names

I'm not sure what the transformation ought to be from the spec names to Rust type names - the spec names don't have the right case, and the KP notation feels unnatural - but IMO the transformation should be systematic. I tentatively suggest the following:

  • KP_foo_bar => FooBarKey. For example, K_hs_id => HsIdKey (rename from OnionIdKey)
  • KS_foo_bar => FooBarSecretKey. For example KS_hs_intro_tid => HsIntroTidSecretKey (rename from IntroPtAuthSecretKey)
  • K_foo_bar => FooBarKey. For example K_desc_enc => DescEncKey.
  • N_foo_bar => FooBar. For example, N_hs_subcred => HsSubcred (rename from Subcredential).

We also frequently need to talk about hashes of keys (often thought of as "identities"). Typically these are hashes of keys ending id. Maybe:

  • H(KP_foo_bar_id) => FooBarBazId. For example, H(HP_foo_bar_id) => HsId (rename from OnionId)
  • H(KP_foo_bar_tid) => FooBarBazTid.

Variable names (paramerters, etc.)

It is less important that variable names are uniformly derived. It is often useful that they are short. And it is usually more important to distinguish a variable from other variables in its context. I propose not to make any particular rules about this. Programmers will naturally pick names related to the type or nature or purpose or use of a key.

Rationale

Changing names in the codebase may be seen as a bikeshed issue but I think it is very important. A reader should be able to:

  • Given the Rust type name (by seeing a use of it in the source code), find the text about the key in the spec
  • Given the key name from the spec, grep the codebase for it
  • Given the spec and the code, determine quickly, unambiguously, and with certainty, which of the keys in the spec, the code is dealing with

All of these should be possible:

  • Without having to indirect through the rustdocs by the Rust type definition
  • Without having to memorise two names for every key

Right now I'm trying to review !980 (merged) and I'm finding the cognitive burden of two names for everything very significant.

CC @nickm who has been working in this area.

Edited by Ian Jackson