Skip to content

Update protocol.md with journalist dh-akem reply key and journalist self-signing procedure #105

Merged
cfm merged 4 commits intomessage-enc-flow-docfrom
add-reply-key-and-journo-signing-procedure
Sep 26, 2025
Merged

Update protocol.md with journalist dh-akem reply key and journalist self-signing procedure #105
cfm merged 4 commits intomessage-enc-flow-docfrom
add-reply-key-and-journo-signing-procedure

Conversation

@rocodes
Copy link
Contributor

@rocodes rocodes commented Sep 25, 2025

Description

  • Add dh-akem journalist reply key to table.
  • Update table headers a bit: I'd to preserve an at-a-glance way to see what specific parameter choices have been made, and I think saying SD-APKE is less clear at a glance than saying DHAKEM(X25519, HKDF-SHA256), so I've adjusted the headings a bit to make room for both types of information.
  • Update enrollment and table entry to Include journalist self-signing procedure for long-term reply key and fetching key. (The footnote that this is under discussion is preserved, but since it looks like this is the direction we are trying to go for, indicate that here so there's no ambiguity about our intention).
  • Closes switch Diffie‒Hellman operations from plain Curve25519 to Ristretto #100

Checklist

  • base branch is message-enc-flow-doc (I sorely regret the name)
  • Visual review
  • mermaid diagram looks ok - not my strong suit

@rocodes
Copy link
Contributor Author

rocodes commented Sep 25, 2025

lint is failing due to changes unrelated to this commit - I'll push to the base branch

@rocodes rocodes force-pushed the add-reply-key-and-journo-signing-procedure branch from e239c70 to b22b700 Compare September 25, 2025 14:51
@rocodes rocodes requested a review from cfm September 25, 2025 14:52
@rocodes rocodes moved this to Ready For Review in SecureDrop Sep 25, 2025
@rocodes rocodes force-pushed the message-enc-flow-doc branch from 2bc7f9f to aee27f8 Compare September 25, 2025 14:59
@rocodes rocodes force-pushed the add-reply-key-and-journo-signing-procedure branch from b22b700 to d6eb2e6 Compare September 25, 2025 15:15
@rocodes rocodes force-pushed the add-reply-key-and-journo-signing-procedure branch from d6eb2e6 to b471b68 Compare September 25, 2025 15:56
@cfm cfm moved this from Ready For Review to Under Review in SecureDrop Sep 25, 2025
Copy link
Member

@cfm cfm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update table headers a bit: I'd to preserve an at-a-glance way to see what specific parameter choices have been made, and I think saying SD-APKE is less clear at a glance than saying DHAKEM(X25519, HKDF-SHA256), so I've adjusted the headings a bit to make room for both types of information.

Nice. How would you feel about (here or in a follow-up) breaking up the columns like so (e.g.):

Owner Private key or decapsulation Public key or encapsulation Usage Purpose Direction Lifetime Algorithm Signed by
Journalist $J_{apke,sk}$ $J_{apke,pk}$ SD-APKE Message encryption Outgoing Long-term DH-AKEM(X25519, HKDF-SHA256) $J_{sig,sk}$

That way the (Usage, Purpose) tuple lines up with how the APIs are documented after #102, and the (Usage, Direction) tuple is clearer.

docs/protocol.md Outdated
Comment on lines 41 to 46
Journalist ->> Journalist: generate J{sig},sk,pk
Journalist ->> Newsroom: J{sig},pk
Newsroom ->> Journalist: σNR := newsroom's signature on J{sig},pk
Journalist ->> Journalist: generate J{fetch},sk,pk and J{dh},sk,pk
Journalist ->> Journalist: σJ := signature over J{fetch},pk and J{dh},pk using J{sig},sk
Journalist ->> Server: J{sig,fetch,dh},pk<br>σNR, σJ
Copy link
Member

@cfm cfm Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry; I know the lack of proper notation, especially super- and subscripts, makes this diagram hard both to read and revise. (I'm holding out hope for #80.) If I understand your intentions right, I think this diff can be simplified to:

Suggested change
Journalist ->> Journalist: generate J{sig},sk,pk
Journalist ->> Newsroom: J{sig},pk
Newsroom ->> Journalist: σNR := newsroom's signature on J{sig},pk
Journalist ->> Journalist: generate J{fetch},sk,pk and J{dh},sk,pk
Journalist ->> Journalist: σJ := signature over J{fetch},pk and J{dh},pk using J{sig},sk
Journalist ->> Server: J{sig,fetch,dh},pk<br>σNR, σJ
Journalist ->> Newsroom: Jsig,pk := journalist's signing key
Newsroom ->> Journalist: σNR := newsroom's signature on Jsig,pk
Journalist ->> Journalist: J{fetch,dh},pk := journalist's long-term keys
Journalist ->> Journalist: σJ := signature over J{fetch,dh},pk using Jsig,sk
Journalist ->> Server: J{sig,fetch,dh},pk<br>σNR, σJ

In other words:

  • Jsig,pk is a spelling of $J_{sig,pk}$
  • J{fetch,dh},pk is a shorthand for $J_{fetch,pk}, J_{dh,pk}$
  • Generation of private keys is implicit (but we could make it explicit throughout!)

@cfm cfm added this to the v0.3 milestone Sep 25, 2025
@cfm
Copy link
Member

cfm commented Sep 26, 2025

I've added a note at the top that this will close #100!

@rocodes rocodes moved this from Under Review to In Progress in SecureDrop Sep 26, 2025
…le. Adjust headings to include algorithm/parameter choice as well as usage.
…o journalist self-signing of fetch and dh-akem keys
@rocodes rocodes force-pushed the add-reply-key-and-journo-signing-procedure branch from b471b68 to c1d2b01 Compare September 26, 2025 18:28
@rocodes rocodes moved this from In Progress to Ready For Review in SecureDrop Sep 26, 2025
@rocodes rocodes requested a review from cfm September 26, 2025 18:28
@cfm cfm moved this from Ready For Review to Under Review in SecureDrop Sep 26, 2025
Copy link
Member

@cfm cfm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. Thanks, @rocodes!

@cfm cfm merged commit f0a0821 into message-enc-flow-doc Sep 26, 2025
2 checks passed
@github-project-automation github-project-automation bot moved this from Under Review to Done in SecureDrop Sep 26, 2025
@nathandyer nathandyer removed this from SecureDrop Oct 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Comments