ssh-protocols: Document Arti keystore key types

Fixes tpo/core/arti#1109

1 files changed, 90 insertions, 0 deletions

diff --git a/spec/ssh-protocols.md b/spec/ssh-protocols.md
index c6498ff..989eb9c 100644
--- a/spec/ssh-protocols.md
+++ b/spec/ssh-protocols.md
@@ -51,3 +51,93 @@ but they are **not email addresses**
 and mail to them will not be delivered.
 
 For further information, consult the linked specifications.
+
+## SSH key types for the Arti keystore
+
+The
+[Arti keystore](https://tpo.pages.torproject.net/core/doc/rust/tor_keymgr/index.html)
+stores private keys (and, sometimes, public keys)
+in OpenSSH key format.
+But it needs to store some key types that are
+not used in the SSH protocols.
+So the following key types are defined.
+
+These are in the namespace of Public Key Algorithms
+([RFC4250 4.11.3](https://datatracker.ietf.org/doc/html/rfc4250#section-4.11.3))
+but they are only meaningful in
+SSH public key files
+([RFC4716 3.4](https://datatracker.ietf.org/doc/html/rfc4716#section-3.4))
+and
+OpenSSH format private key files
+([OpenSSH `PROTOCOL.key` document](https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.key?annotate=HEAD)).
+
+In each case we specify/reference
+ * the name of the "public key algorithm" (RFC4250 4.11.3),
+ * the underlying cryptographic algorithm(s),
+ * the public key data
+   ("key/certificate data" in RFC4716 3.4)
+ * the private key data
+   (`privatekey1`, `privatekey2`, `privatekeyN` in `PROTOCOL.key`)
+
+### `x25519@spec.torproject.org`
+
+These refer to keys for
+X25519,
+ie, Diffie-Hellman on
+Curve25519
+([RFC7748 6.1](https://datatracker.ietf.org/doc/html/rfc7748#section-6.1))
+using the encoding conventions from
+standardised ed25519
+([RFC8032](https://datatracker.ietf.org/doc/html/rfc8032)).
+
+The public data is `ENC(A)` ([RFC8032 3.2](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2)).
+
+The private data is
+`k` ([RFC8032 3.2](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2)).
+
+> These are in the same formats as 
+> keys for the `ed25519` SSH public key algorithm,
+> which is an EdDSA signature algorithm.
+> Keys for ed25519 and x25519 are functionally interchangeable;
+> however, we use a different key type 
+> to avoid key type punning and accidental key misuse:
+> using the same key material for different algorithms is a poor idea.
+
+### `ed25519-expanded@spec.torproject.org`
+
+These refer to the expanded form of private keys for
+ed25519
+([RFC8032](https://datatracker.ietf.org/doc/html/rfc8032)).
+
+This type is not used in RFC4716 public key files:
+the `ed25519` SSH public key algorithm
+is used for the public half of
+`ed25519-expanded@spec.torproject.org` private keys.
+However,
+the
+`ed25519-expanded@spec.torproject.org`
+type *is* used in OpenSSH private key files,
+for the *public* keys matching such private keys.
+
+The public data is `ENC(A)` ([RFC8032 3.2](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2)).
+
+The private data is the 64-byte string made by concatenating:
+ * `ENC(s)` as per [RFC8032 3.2](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2), the actual "expanded secret key";
+ * `h_b || ... || h_(2b-1)` as per [RFC8032 3.3](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2), , the "domain separation nonce".
+
+This private key format does not provide a way to convey or establish
+a corresponding (unexpanded, standard) ed25519 private key `k`.
+
+> The ed25519 standards define the private key for ed25519
+> as a 32-byte secret `k`.
+> `k` is then hashed and processed into parameters used for signing,
+> and the public key for verification.
+> The `ed25519-expanded@spec.torproject.org` can represent private keys
+> which can be used with the ed25519 signature algorithm,
+> and for which a corresponding working public key is known,
+> but for which there is no known value of `k`
+> (the "real ed25519" private key).
+> Allowing such keys can be convenient when
+> one wishes to find private keys whose public keys have particular patterns,
+> for example when trying to find a `.onion` domain
+> for a [Tor Hidden Service](rend-spec/).