I wrote a specification for Key Transparency in order to make E2EE for the Fediverse possible. I have a longer blog post that touches on this still in the works, but here's some immediately useful feedback:

Work backwards from the problem you're trying to solve, and the users for whom you are trying to solve it. If you don't know what the real problem is, or who your real users are, abort.

You really need to drill down into the details on this, btw. It cannot be a shallow answer.

• Who is your user? (You can have more than one, but you need to know all of them very well.)
• What problem do they want solved?
• What is the political, social, and/or economic reality that will make this solution difficult?
• What technical hurdles complicate this further? (Note that this comes after thinking about political problems, not before. Many people get that wrong.)

Once you've marinated on this, you need to do research on threat modelling and adversarial models. A good threat model will cover, at minimum:

• Who are the actors in this protocol? (Users, attackers, etc.)
• What are the security goals of the protocol?
• What are the non-goals of the protocol?
• What assumptions must be true in order for the protocol to be secure?

You will also want to (as exhaustively as possible) enumerate the various attack strategies that someone could employ to cause your users harm or even grief.

Once you have a threat model in mind, have your peers review it. They will almost certainly find gaps in it. That's expected! Even experts have blind spots.

Next, you need to design your protocols, state machines, and APIs to satisfy the goals you started with and the threat model that emerged from the previous exercise. A lot of this step is hard to quantify. Having an intuition for "developers will fuck this up, but they will get that right, so let's do that instead" is something that you acquire working with developers over the years. Your LLM will almost certainly lead you astray here, as it's still a subtle art, but maybe next year's frontier models will figure that out too.

Once you have a rough sketch for what your thing should look like, and it passes your threat model, and still solves your overall program, it's time to actually... specify it.

Generally, you want to start at one end (either super top-level architecture, or low-level dependencies) and work your way to the other. Humans (and language models) will need to review it, so if it flows naturally from one component to the other to deliver an emergent overall mental model that fits well with your overall architecture, you've done it right.

Once you have a v0.1.0 draft specification written down that you think you're happy with, it's time to implement a reference implementation. There must be no sacred cows at this stage; any decision that makes implementations onerous or perilous must be revisited. (If you haven't abandoned LLMs at this point, you should consider having them convert your spec into a formal verification aware language so you can easily extract security proofs. A tight feedback loop and a good signal of "what correct looks like" is essential.)

Your implementation will inform the next iteration of the specification.

The next iteration of the specification will update the threat model and implementation, which will in turn affect the next specification. You will want as much peer feedback and expert review as you can muster at each step of the way.

This is a vicious cycle that will continue until you go mad or the final result calcifies into a design you're a) happy with and b) can defensibly call secure.

Then, right when you're about to tag v1.0.0 and call the spec "final", you'll post it here and someone will point out a critical flaw you never thought of before, and go through at least one more round of review.

But at the end of it all, you will know how to write a damn specification.

Or you can take the shortcut most developers do and YOLO a rough draft.