From 1e002b14c9c7911140af69cea5999e26a1263815 Mon Sep 17 00:00:00 2001
From: Gabriela Moldovan <gabi@torproject.org>
Date: Tue, 15 Aug 2023 20:59:30 +0100
Subject: [PATCH] keymgr: Write a registry sketch.

This comment will form the basis for the protocol name registry.
---
 crates/tor-keymgr/src/key_type/ssh.rs | 51 +++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/crates/tor-keymgr/src/key_type/ssh.rs b/crates/tor-keymgr/src/key_type/ssh.rs
index 8854f28f8..4e035d69b 100644
--- a/crates/tor-keymgr/src/key_type/ssh.rs
+++ b/crates/tor-keymgr/src/key_type/ssh.rs
@@ -16,9 +16,56 @@ use std::path::PathBuf;
 use std::sync::Arc;
 
 /// The algorithm string for x25519 SSH keys.
-//
+///
 // TODO HSS: start a protocol name registry in the torspec repo and document the usage and purpose
-// of this "protocol" name.
+// of this "protocol" name:
+//
+// ### Assigned Additional Algorithm Names
+//
+// #### Registration Procedure(s)
+//
+// TODO
+//
+// #### NOTE
+//
+// The algorithm names MUST meet the criteria for additional algorithm names described in [RFC4251
+// § 6].
+//
+// We reserve the following custom OpenSSH key types:
+//
+//  +---------------------------+--------------------+---------------------+------------------------+
+//  | Public Key Algorithm Name | Public Key Format  | Private Key Format  | Purpose                |
+//  |---------------------------|--------------------|---------------------|------------------------|
+//  | x25519@torproject.org     | [TODO link to spec | [TODO link to spec  | Arti keystore storage  |
+//  |                           | describing the key | describing the key  | format                 |
+//  |                           | format]            | format]             |                        |
+//  |                           |                    |                     |                        |
+//  +---------------------------+--------------------+---------------------+------------------------+
+//
+// [RFC4251 § 6]: https://www.rfc-editor.org/rfc/rfc4251.html#section-6
+//
+// <The following will go in the document that describes the x25519@torproject.org key format>
+//
+// # x25519@torproject.org OpenSSH Keys
+//
+// ## Introduction
+//
+// X25519 keys do not have a predefined SSH key algorithm name in [IANA's Secure Shell(SSH)
+// Protocol Parameters], so in order to be able to store this type of key in OpenSSH format,
+// we need to define a custom OpenSSH key type.
+//
+// ## Key Format
+//
+// An x25519@torproject.org public key file is encoded in the format specified in
+// [RFC4716 § 3.4].
+//
+// Private keys use the format specified in [PROTOCOL.key].
+//
+// TODO: flesh out the RFC and write down a concrete example for clarity.
+//
+// [IANA's Secure Shell(SSH) Protocol Parameters]: https://www.iana.org/assignments/ssh-parameters/ssh-parameters.xhtml#ssh-parameters-19
+// [RFC4716 § 3.4]: https://datatracker.ietf.org/doc/html/rfc4716#section-3.4
+// [PROTOCOL.key]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.key?annotate=HEAD
 pub(crate) const X25519_ALGORITHM_NAME: &str = "x25519@torproject.org";
 
 /// An unparsed OpenSSH key.