matrix-org / matrix-org/matrix-spec

e2e key export uses strange AES-CTR construction

Open
#461 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-Client-Server A-E2EE clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

I've been trying to implement a reader for the exported key format (so I can have a hacky way of getting around vector-im/riot-web#6454 by downloading my entire key backup and then removing the parts which I don't want to share) in Python, but have discovered that the description of the format leads to some confusion -- I had to read the matrix-react-sdk source code to understand what was going on.

In short, currently the spec says:

> Serialize the JSON object as a UTF-8 string, and encrypt it using AES-CTR-256 with the key K generated above, and with a 128-bit cryptographically-random initialization vector, IV, that has bit 63 set to zero. (Setting bit 63 to zero in IV is needed to work around differences in implementations of AES-CTR.)

However, IV is a bit of a strange term for AES-CTR -- usually you would refer to a "counter" and "nonce" (which are combined in the construction to produce the IV). I imagine most people would assume that the "IV" is the nonce -- because almost all AES-CTR constructions share nonces and not initial counter values, but in your case you are sharing an initial counter value and have a zero-length nonce.

Two questions:

1. Is it possible to clarify this in the spec, since the current wording is ambiguous -- and given this is an unusual construction should be probably be pointed out.
2. Is there a particular reason for this kind of construction? Why not share a nonce like most AES-CTR constructions? Would there be an interest to release v2 of this format to change this?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the exported key format wording in the Matrix specification and compare it with the matrix-react-sdk source mentioned in the issue. Clarify whether the text should describe the AES-CTR counter and nonce construction explicitly, and document the rationale or status of a format revision; done means readers can implement the format without ambiguity.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cryptography, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.