dajiaji / pyhpke

A Python Implementation of HPKE (Hybrid Public Key Encryption)

PyHPKE - A Python implementation of HPKE

PyHPKE is a HPKE (Hybrid Public Key Encryption) implementation written in Python.

You can install PyHPKE with pip:

$ pip install pyhpke

And then, you can use it as follows:

from pyhpke import AEADId, CipherSuite, KDFId, KEMId, KEMKey

# The sender side:
suite_s = CipherSuite.new(
    KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM
)
pkr = KEMKey.from_jwk(  # from_pem is also available.
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
    }
)
enc, sender = suite_s.create_sender_context(pkr)
ct = sender.seal(b"Hello world!")

# The recipient side:
suite_r = CipherSuite.new(
    KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM
)
skr = KEMKey.from_jwk(
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
        "d": "r_kHyZ-a06rmxM3yESK84r1otSg-aQcVStkRhA-iCM8",
    }
)
recipient = suite_r.create_recipient_context(enc, skr)
pt = recipient.open(ct)

assert pt == b"Hello world!"


# deriving a KEMKeyPair
keypair = suite_s.kem.derive_key_pair(b"some_ikm_bytes_used_for_key_derivation")

Index

• Installation
• Supported HPKE Modes and Cipher Suites
• Warnings and Restrictions
• Usage
• API Reference
• Test
• Contributing

Installation

You can install PyHPKE with pip:

$ pip install pyhpke

Supported HPKE Modes and Cipher Suites

PyHPKE supports all of the HPKE modes and cipher suites defined in RFC9180 below.

• modes
  • ✅ Base
  • ✅ PSK
  • ✅ Auth
  • ✅ AuthPSK
• KEMs (Key Encapsulation Machanisms)
  • ✅ DHKEM (P-256, HKDF-SHA256)
  • ✅ DHKEM (P-384, HKDF-SHA384)
  • ✅ DHKEM (P-521, HKDF-SHA512)
  • ✅ DHKEM (X25519, HKDF-SHA256)
  • ✅ DHKEM (X448, HKDF-SHA512)
• KDFs (Key Derivation Functions)
  • ✅ HKDF-SHA256
  • ✅ HKDF-SHA384
  • ✅ HKDF-SHA512
• AEADs (Authenticated Encryption with Associated Data)
  • ✅ AES-128-GCM
  • ✅ AES-256-GCM
  • ✅ ChaCha20Poly1305
  • ✅ Export Only

Warnings and Restrictions

Although this library has been passed all of the following official test vectors, it has not been formally audited.

• RFC9180 official test vectors provided on github.com/cfrg/draft-irtf-cfrg-hpke

Usage

from pyhpke import AEADId, CipherSuite, KDFId, KEMId, KEMKey

# The sender side:
suite_s = CipherSuite.new(
    KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM
)
pkr = KEMKey.from_jwk(
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
    }
)
enc, sender = suite_s.create_sender_context(pkr)
ct = sender.seal(b"Hello world!")

# The recipient side:
suite_r = CipherSuite.new(
    KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM
)
skr = KEMKey.from_jwk(
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
        "d": "r_kHyZ-a06rmxM3yESK84r1otSg-aQcVStkRhA-iCM8",
    }
)
recipient = suite_r.create_recipient_context(enc, skr)
pt = recipient.open(ct)

assert pt == b"Hello world!"

API Reference

See Documentation.

Test

You can run tests from the project root after cloning with:

$ tox

Contributing

We welcome all kind of contributions, filing issues, suggesting new features or sending PRs.

pyhpke's Issues

Bump pyca/cryptography to 41.0.0 or upper.

Drop support for Python 3.7.

Add support for Python 3.11.

DeriveKeyPair Implementation?

Hello,

First of all thanks for the great work.

And another question are there any plans to implement the DeriveKeyPair function specified in the RFC?
Or did i maybe miss something?

with best regards
Aurvandil

Improve test coverage to over 95%.

KEM._nsecret Question

a short Question in Regards to the _nsecretAttribute. Is that attribute the Nsk from the RFC?
if yes then shouldn't it be

• 56 for KEMId.DHKEM_X448_HKDF_SHA512 instead of 64
• 66 for KEMId.DHKEM_P521_HKDF_SHA512 instead of 64

?

(according to https://www.rfc-editor.org/rfc/rfc9180.html#name-key-encapsulation-mechanism)

with best regards
Aurvandill

Implement DeriveKeyPair to KEM.

Decapsulate a encapped key from a ciphertext in base mode

I have cypher texts with an encapsulated symmetric key send by third party. Is it possible to decapsulate the symetric key using the private key? I think rust-hpke can.

So for instance:

enc = suite_r.kem.decap(ct,skr)

However, when I try that I get "ValueError: Unsupported elliptic curve point type".

from pyhpke import AEADId, CipherSuite, KDFId, KEMId, KEMKey

# The sender side:
suite_s = CipherSuite.new(KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM)
pkr = KEMKey.from_jwk(  # from_pem is also available.
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
    }
)
enc, sender = suite_s.create_sender_context(pkr)
ct = sender.seal(b"Hello world!")

# The recipient side:
suite_r = CipherSuite.new(KEMId.DHKEM_P256_HKDF_SHA256, KDFId.HKDF_SHA256, AEADId.AES128_GCM)
skr = KEMKey.from_jwk(
    {
        "kid": "01",
        "kty": "EC",
        "crv": "P-256",
        "x": "Ze2loSV3wrroKUN_4zhwGhCqo3Xhu1td4QjeQ5wIVR0",
        "y": "HlLtdXARY_f55A3fnzQbPcm6hgr34Mp8p-nuzQCE0Zw",
        "d": "r_kHyZ-a06rmxM3yESK84r1otSg-aQcVStkRhA-iCM8",
    }
)

enc = suite_r.kem.decap(ct,skr)

Add docstring for public classes and interfaces.

Refactor Exceptions to follow RFC9180.

Elliptic Curve `to_private_bytes` uses DER Encoding and does not dump the private_numbers().private_value

By mistake i made a mistake when implementing the serialization of the Elliptic Curve Private Keys. Instead of just dumping the private_numbers().private_value i encoded the key with the DER encoding.

this mistake will be fixed by PR #137

Sorry for the mistake

with best regards
Aurvandill