Skip to content

WIP - encrypted fragments bip outline - #10

Draft
arminsabouri wants to merge 1 commit into
mainfrom
hpke-psbt
Draft

arminsabouri wants to merge 1 commit into
mainfrom
hpke-psbt

Conversation

@arminsabouri

Copy link
Copy Markdown
Collaborator

Original description :

Super rough outline of what I think this document should cover. It may be the case that in writing this document we realize there is a much better organization or outline. Many of open questions in the comments.

The rest of the work on this document can be parallelized.

The rest of the psbt specific details such as what goes into keydata and valuedata. And what are the practical and privacy implications / tradeoffs.
Specify the rest of the HPKE details.
Specify privacy considerations (paddings, bip234 elligatorswift)
I personally sometimes need to work backwards on this type of stuff. i.e write the code and/or flow diagrams and then a spec becomes more apparent. But eventually we will need a reference and some test vectors
Please comment in this thread what parts you want to focus on @zealsham @Mshehu5 @0xZaddyy

@arminsabouri
arminsabouri marked this pull request as draft August 4, 2026 19:02
@nothingmuch

Copy link
Copy Markdown
Contributor

https://github.com/FiloSottile/hpke/blob/main/hpke-pq.md

Comment on lines +48 to +49
How can we prevent the receiver from processing teh exact same message.
i.e deterministically join two encrypted fragments.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

might be covered by #16 which has a TODO to describe generic G-set fields using idempotence ID for keydata

if the keydata is the idempotence ID, joining the same fragment twice doesn't change anything, so the receiver doesn't need to track what it already processed


## Abstract

This document specifies a method for encoding HPKE-encrypted messages within PSBT proprietary fields. Participants in multi-party transaction construction protocols use this mechanism to exchange authenticated, confidential, arbitrary-length application messages alongside the transaction data they are jointly building, without introducing a communication channel outside PSBT itself.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The Abstract claims "authenticated" messages, but the Auth mode section leaves the HPKE mode undecided; RFC 9180 defines sender authentication only for PSK, Auth, and AuthPSK modes.
In base mode there is no authentication of the remote party at all, so the security claim in the Abstract is not established by this document.


### Using Proprietary Fields

Callers MUST use proprietary field in either the input, output or global map `0xFC`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The draft mandates (MUST) carrying HPKE messages in PSBT proprietary fields (type 0xFC), but BIP 174 states the proprietary use type "is not to be used by any public specification ... This type must be used for internal processes only". A public BIP-style specification standardizing a meaning for 0xFC fields contradicts the PSBT format contract, which reserves 0xFC for internal processes only and leaves public specifications to define their own field types.

@oakagent

oakagent commented Oct 8, 2026

Copy link
Copy Markdown

Typos in what this pull request adds (automated):

encrypted-psbt-fragments.md

  • l.3 - "its best" → "it's best"
  • l.5 - "proprietart" → "proprietary"
  • l.5 - "ciphersuit" → "ciphersuite"
  • l.9 - "bootstraping" → "bootstrapping"
  • l.48 - "teh" → "the"
  • l.65 - "compatability" → "compatibility"
  • l.66 - "specifiying" → "specifying"
  • l.66 - "dicernable" → "discernible"
  • l.90 - "out goals" → "our goals"
  • l.92 - "uniformally" → "uniformly"
  • l.92 - "strucutre" → "structure"
  • l.92 - "such the ciphersuit bits" → "such as the ciphersuite bits"
  • l.100 - "should be look like" → "should look like"
  • l.105 - "participants the cannot" → "participants cannot"
  • l.111 - "retreieval" → "retrieval"

@bc1cindy bc1cindy mentioned this pull request Oct 15, 2026

Encrypted messages are encoded as PSBT proprietary fields (PSBT_*_PROPRIETARY, type 0xFC), scoped to the global, input, or output map depending on which part of the transaction the message pertains to.

A single logical message occupies exactly one proprietary field. A sender addressing multiple recipients encrypts and encodes the message separately for each, producing one field per recipient.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The draft puts the recipient-specific enc and ciphertext in valuedata and specifies no recipient-specific keydata, so fields for different recipients using the same cipher suite share the same PSBT key. BIP174 requires keys in a map to be unique and invalidates duplicates, so the per-recipient encoding needs an unspecified keydata element to represent multiple recipients.

META:
in a concurrent setting participants may need to send authenticated and confidential messages to one another. In setting where PSBTs are the main unit of communication its best if participants can continue to use PSBTs.

How can we HPKE encrypt custom messages in proprietart fields. Need to specify what version, ciphersuit (?), and include the ciphertext in the value.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Typos fail the Flake checks workflow

The added file trips the repository's typos check (ciphersuit at lines 5 and 92, exit 2); nix flake check runs typos over the tree, so the Flake checks workflow fails.

oak · automated · 5c8c737


The keydata will include the RFC9180 cipher suite ids (if we support multiple ciphersuites see below). // TODO: this will identify this field has a hpke message.

Valuedata must include `enc` (the encapsulated ephemeral key) and the ciphertext(s).

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

HPKE mode is absent from the wire format

The wire format carries cipher-suite ids but no HPKE mode, so a receiver cannot tell OpenBase from OpenAuth; is the mode intended to be communicated out of band?

oak · automated · 5c8c737


Callers MUST use proprietary field in either the input, output or global map `0xFC`.

The keydata will include the RFC9180 cipher suite ids (if we support multiple ciphersuites see below). // TODO: this will identify this field has a hpke message.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Proprietary keydata omits BIP174 identifier

BIP174 requires proprietary keydata to begin with a length-prefixed identifier and a subtype before custom keydata; this spec puts RFC 9180 cipher-suite IDs in keydata and never defines those fields. Peers therefore cannot know which identifier or subtype to use, so the field is unattributable.

oak · automated · 5c8c737

This branch has not been deployed

No deployments
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.

4 participants