ssh-protocols.md: Rewrite x25519@spec.tpo

Discussion here
  https://gitlab.torproject.org/tpo/core/torspec/-/merge_requests/223#note_2964398

1 files changed, 32 insertions, 16 deletions

diff --git a/spec/ssh-protocols.md b/spec/ssh-protocols.md
index addb894..dd80866 100644
--- a/spec/ssh-protocols.md
+++ b/spec/ssh-protocols.md
@@ -86,22 +86,38 @@ In each case we specify/reference
 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 
+Curve25519,
+as per
+[RFC7748 6.1](https://datatracker.ietf.org/doc/html/rfc7748#section-6.1).
+and
+[s5](https://datatracker.ietf.org/doc/html/rfc7748#section-5).
+
+The public key data is the u-coordinate encoded as the byte string `u[]`
+from RFC7748 s5.
+
+The private key data is the scalar k
+encoded according to RFC7748 s5
+(i.e. as a fixed-length 32-byte little endian byte string).
+It MUST be stored as the true scalar value.
+So if the private key was generated from 32 random bytes
+according to the procedure described in RFC7748 s5 as
+"in order to decode 32 random bytes as an integer scalar".
+the value stored MUST be the "clamped" form:
+that is, the value
+*after* the transformation.
+If a stored value is a byte string which doesn't represent
+a valid scalar according to RFC7748 s5
+(i.e. an "unclamped" value)
+it SHOULD be rejected;
+if it is not rejected,
+it MUST NOT be used unchanged, but MUST instead be clamped.
+
+> X25519 keys are
+> [interconvertible with ed25519 keys](../converting-to-ed25519.md).
+> So, it would be possible to store the ed25519 form instead,
+> and convert on load/save.
+> However, we use a different key type
+> to avoid needing conversions during load/save, and
 > to avoid key type punning and accidental key misuse:
 > using the same key material for different algorithms is a poor idea.