matrix-org / matrix-org/matrix-spec
Use consistent terminology for E2EE device keys
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
The terminology is currently a bit all over the place:
- Both the Ed25519 and Curve25519 are sometimes called "identity keys". In other places they're referred to as "device keys".
- The device Ed25519 key [is introduced](https://spec.matrix.org/v1.2/client-server-api/#device-keys) as the "Ed25519 signing key" in the spec.
- [Sometimes](https://spec.matrix.org/v1.2/client-server-api/#uploading-keys) the spec will just say "Ed25519 key" or "Curve25519 key". This is somewhat problematic because there are other non-device Ed25519 and Curve25519 keys in Matrix cryptography.
- The E2EE implementation guide refers to the Ed25519 key as the "[fingerprint key pair](https://matrix.org/docs/guides/end-to-end-encryption-implementation-guide#ed25519-fingerprint-key-pair)" and the Curve25519 key as the "[identity key pair](https://matrix.org/docs/guides/end-to-end-encryption-implementation-guide#curve25519-identity-key-pair)". This is then copied in some other places such as the Android libolm bindings.
We should choose a single name for both of these keys (introducing it as a definition) and then stick to it throughout all official resources (starting with the spec, but then ideally propagating to other resources like the guide and the official SDKs).
Disambiguating using the algorithm name (Ed25519 vs Curve25519) is suboptimal because it is verbose, hard to remember and refers to an implementation detail which might as well change at some point.
I propose that we refer to the:
- Ed25519 device key as the **device fingerprint key**.
- Curve25519 device key as the **device identity key**.
- Collectively, both of these keys should be referred to as the **device keys**.
Omitting the word "device" should be fine when it is clear from context what it is referring to. I also think it's fine to omit the word "pair" to decrease verbosity, as long as it is clearly explained that this is in fact a pair / asymmetric cryptography at the time of introduction.
Contributor guide
Research direction
Start by reviewing the Matrix client-server specification sections linked in the issue, then compare the E2EE implementation guide and Android libolm bindings for existing terms. Document the chosen definitions and identify each official resource that needs consistent terminology. Done means the terminology is agreed and propagated across the named resources and official SDKs.
Written by the indexing model from the issue text.
Assessment
- Domain
- cryptography, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100