Arti key manager documentation

About the project

  • Contact: @gabi-250
  • Chat: #tor-dev on irc.oftc.net
  • Video room: TBD

Participants

Summary

The Arti team has been implementing a key management backend for handling the various keys and certificates required by Arti to operate (see tpo/core/arti#728 (closed) for a brief overview).

The projects I'm proposing here aim to improve the various bits of documentation related to key management in Arti.

Project A: Set up a protocol name registry

The main (and currently only) Arti key store is an on-disk store that stores keys in OpenSSH key format. Some of the key types we need to support don't have a predefined SSH public key algorithm name, so we've had to define several custom SSH algorithm names (for example, we have a custom algorithm name for x25519 keys, which don't have a predefined algorithm name). See tpo/core/arti#936 (closed) and tpo/core/arti#1049 (closed) for more details. As per RFC4251 § 6, our custom ssh algorithm names use the <something@subdomain.torproject.org> format.

In order to manage the local namespacing of our (Tor Project's) custom SSH algorithm names, we will need a protocol name registry. This protocol name registry will live in torspec repo.

This comment lists the algorithm strings that will need to be documented, and can be used as a starting point for this project.

Project B: Improve documentation in the tor-keymgr crate

I think the documentation of the tor-keymgr crate could use some improvements:

  • the ArtiNativeKeystore docs are very sparse (i.e. we should at least document the key format it's using)
  • it would be nice to have some docs explaining how to implement a custom key store
  • it would be nice to have some docs explaining how to mock a Keystore
  • etc

Project C: Document Arti's future key management CLI

We will eventually want to have a CLI for managing keys in Arti.

We should document various use-cases for it, and the corresponding command invocation (i.e. its arguments).

(This may or may not be within the scope of Hackweek).

Skills

  • Git/GitLab.
  • Markdown.
  • Writing documentation.

Project A requires some knowledge (or willingness to learn) about the OpenSSH key format used for keys stored in the Arti key store.

Project B requires some knowledge (or willingness to learn) about the internals of Arti's key manager/key store implementations.

Links

  • a sketch of the key manager/keystore APIs we have in Arti
  • the currently supported key types are listed here
  • a more comprehensive (but somewhat out of date) list of keys that we want to support can be found here