Skip to content

[Draft/POC] Add secp256k1-based HPKE (Hybrid Public Key Encryption) For Payjoin v2 #32617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

[Draft/POC] Add secp256k1-based HPKE (Hybrid Public Key Encryption) For Payjoin v2 #32617

wants to merge 1 commit into from

Conversation

w0xlt
Copy link
Contributor

@w0xlt w0xlt commented May 26, 2025 •
edited
Loading

This PR introduces an implementation of Hybrid Public Key Encryption (HPKE) using a secp256k1-based Diffie-Hellman KEM (per RFC 9180 and "secp256k1-based DHKEM for HPKE" specification). It provides the core cryptographic component needed to enable the Payjoin v2 protocol.

This is an exploratory PR intended to kickstart discussion on adding Payjoin v2 support to Bitcoin Core – feedback and reviews are very welcome.

Payjoin v2 makes use of a protocol called Oblivious HTTP (OHTTP) to strip client-identifying metadata from the request. This protocol use a binary-encoded HTTP message encapsulated through HPKE.

The core implementation is contained in the new files src/dhkem_secp256k1.h and src/dhkem_secp256k1.cpp:

  • Full HPKE Modes: All four HPKE modes are supported – Base, PSK, Auth, and AuthPSK.
  • Secp256k1 DHKEM: Uses secp256k1 for Diffie-Hellman key exchange. The Encap() and Decap() functions perform the base mode KEM (ephemeral ECDH using the receiver’s public key), while AuthEncap() and AuthDecap() extend this to authenticated mode (including the sender’s static key in the shared secret derivation). Internally, the shared secret is derived as specified by HPKE using HKDF (SHA256) extraction and expansion.
  • Key Schedule & Nonce Derivation: After KEM, the implementation runs the HPKE key schedule to derive the encryption key, base nonce, and exporter secret. It follows RFC 9180 §7.1, hashing the info and psk_id contexts and deriving the AEAD key and nonce. Per-message nonces are computed by XOR-ing the base nonce with a message sequence number as specified in RFC 9180 §5.2.
  • AEAD Encryption (ChaCha20-Poly1305): The HPKE context uses ChaCha20-Poly1305 as the authenticated encryption scheme. The code provides Seal() and Open() functions to encrypt and decrypt data using the derived context key and a given nonce. It uses Bitcoin Core’s existing ChaCha20Poly1305 implementation.

The test file validates all the functions mentioned above: Encapsulation/Decapsulation, Encryption/Decryption, Nonce and Key Schedule Logic. This uses the PDK (Payjoin Dev Kit) test vectors. The tests also show how to use the HPKE functions.

This implementation only uses HKDF-SHA256 as Key Derivation Functions and ChaCha20-Poly1305 as AEAD, since these already exist in the Bitcoin Core codebase. It does not support other KDFs (such as HKDF-SHA384 and HKDF-SHA512) or other AEADs (such as AES-128-GCM and AES-256-GCM).

To run the tests:
build/bin/test_bitcoin --log_level=all --run_test=dhkem_secp256k1_tests

@w0xlt w0xlt marked this pull request as draft May 26, 2025 08:04
@DrahtBot
Copy link
Contributor

DrahtBot commented May 26, 2025 •
edited
Loading

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32617.

Reviews

See the guideline for information on the review process.
A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

  • #33101 (cmake: Proactively avoid use of SECP256K1_DISABLE_SHARED by hebasto)
  • #28690 (build: Introduce internal kernel library by TheCharlatan)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

@w0xlt w0xlt force-pushed the secp256k1_hpke branch 2 times, most recently from 65acaaa to 9183a8e Compare May 26, 2025 09:34
@DrahtBot
Copy link
Contributor

🚧 At least one of the CI tasks failed.
Task lint: https://github.com/bitcoin/bitcoin/runs/42885844689
LLM reason (✨ experimental): The CI failure is due to a lint check raising an error over missing include guards in the header file.

Hints

Try to run the tests locally, according to the documentation. However, a CI failure may still
happen due to a number of reasons, for example:

  • Possibly due to a silent merge conflict (the changes in this pull request being
    incompatible with the current code in the target branch). If so, make sure to rebase on the latest
    commit of the target branch.

  • A sanitizer issue, which can only be found by compiling with the sanitizer and running the
    affected test.

  • An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

@w0xlt w0xlt force-pushed the secp256k1_hpke branch from 9183a8e to 588c678 Compare May 26, 2025 09:38
@1440000bytes

This comment was marked as abuse.

Sign in to view
@DrahtBot DrahtBot mentioned this pull request May 26, 2025
Open
@DanGould
Copy link

DanGould commented May 26, 2025 •
edited
Loading

The main reason for the Bitcoin Core wallet to support payjoin directly is to reduce the number of necessary dependencies for those already using the core wallet. In particular rust-payjoin requires TLS (which is optional for the protocol) and rust implementations of cryptographic primatives that core could avoid with a bespoke implementation.

@theStack
Copy link
Contributor

theStack commented Jun 3, 2025

Fore more context to reviewers, could add a link to BIP 77 in the PR description, particularly to the cryptography part: https://github.com/bitcoin/bips/blob/master/bip-0077.md#secp256k1-hybrid-public-key-encryption

Full HPKE Modes: All four HPKE modes are supported – Base, PSK, Auth, and AuthPSK.

Do we need all of the four modes for Payjoin v2 support? Didn't look in-depth yet, but at least BIP77 contains only the two modes "Base" and "Auth" explicitly (and no mentions of "PSK"):
https://github.com/bitcoin/bips/blob/72af87fc72999e3f0a26a06e6e0a7f3134236337/bip-0077.md?plain=1#L286-L287
https://github.com/bitcoin/bips/blob/72af87fc72999e3f0a26a06e6e0a7f3134236337/bip-0077.md?plain=1#L376-L378

@w0xlt
Copy link
Contributor Author

w0xlt commented Jun 4, 2025

at least BIP77 contains only the two modes "Base" and "Auth" explicitly (and no mentions of "PSK"):

Good catch. I still need to verify whether PSK is used by OHTTP in the Payjoin v2 protocol, but since the https://github.com/payjoin/bitcoin-hpke project used by PDK implements and has test vectors for PSK, I added the PSK and AuthPSK modes here as well.

@nothingmuch
Copy link
Contributor

Good catch. I still need to verify whether PSK is used by OHTTP in the Payjoin v2 protocol,

I can confirm that neither BIP 77 nor the rust-payjoin implementations depend on the PSK functionality. There are ideas for future extensions that might make use of that, but they are only ideas at this point and would not be a part of BIP 77 itself.

@DrahtBot DrahtBot mentioned this pull request Jul 30, 2025
Merged
@DrahtBot
Copy link
Contributor

DrahtBot commented Aug 6, 2025

🐙 This pull request conflicts with the target branch and needs rebase.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Needs rebase
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@w0xlt @DrahtBot @1440000bytes @DanGould @theStack @nothingmuch