Start an SSH protocol names registry

1 files changed, 54 insertions, 0 deletions

diff --git a/spec/ssh-protocols.md b/spec/ssh-protocols.md
new file mode 100644
index 0000000..9793e59
--- /dev/null
+++ b/spec/ssh-protocols.md
@@ -0,0 +1,54 @@
+# Tor Project SSH protocol extensions
+
+The
+[SSH protocol](https://datatracker.ietf.org/doc/html/rfc4251)
+provides various extension facilities.
+
+The Tor Project has defined some extensions,
+using the
+[domain-name-based extension facility](https://datatracker.ietf.org/doc/html/rfc4250#section-4.6.1).
+The Tor Project uses names ending `@spec.torproject.org`.
+
+| Id(s)       | Namespace  | Summary  |  Specification<br>link (retrieved at)  |
+|----------|--------------|----------|-------------------------------------|
+| **`ed25519-expaneded@`**  | [Public key algorithm](https://datatracker.ietf.org/doc/html/rfc4250#section-4.11.3) (in [OpenSSH format](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.key?annotate=HEAD) key file) | Expanded ed25519 private key  | [Arti keystore](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/tor-keymgr/src/key_type/ssh.rs?ref_type=heads)  (2023-11-08) |
+| **`x25519@`**   | [Public key algorithm](https://datatracker.ietf.org/doc/html/rfc4250#section-4.11.3) (in [OpenSSH format](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.key?annotate=HEAD) key file) | X25519 private key  | [Arti keystore](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/tor-keymgr/src/key_type/ssh.rs?ref_type=heads)  (2023-11-08) |
+
+### Registration process
+
+New entries my be added to this table
+after peer review by the Tor Project developers,
+via
+[gitlab](https://gitlab.torproject.org/tpo/core/torspec)
+merge request.
+
+The specification links may be to external documents,
+not managed as part of the Tor Specifications.
+Or, they may be links to specific sections of the Tor Specifications,
+or to Proposals.
+External links should be dated, for ease of future reference.
+
+Ideally, before a protocol is deployed,
+its specification should be transferred to the Tor Specifications
+(and the link in the table adjusted).
+
+### Interpretation
+
+For example, the row for `x25519@` indicates that:
+
+ * The Tor Project has assigned `x25519@spec.torproject.org`
+ * In the namespace of public key algorithms -
+   see [RFC4250 table 4.11.3](https://datatracker.ietf.org/doc/html/rfc4250#section-4.11.3),
+   but only when found within an OpenSSH format key file,
+   as [defined by the OpenSSH Project](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.key?annotate=HEAD).
+ * The meaning of this name is summarised as "X25519 private key"
+ * The full details can be found at the linked document,
+   which is part of the Arti keystore.
+ * The link was last checked on the 8th November 2023.
+
+The registered names resemble email addresses,
+but they are **not email addresses**
+and mail to them will not be delivered.
+
+For further information, consult the,
+and the linked specifications.