Add Hybrid Public Key Encryption (HPKE) API Support by sylph01 · Pull Request #1061 · ruby/openssl

sylph01 · 2026-06-05T05:31:14Z

This patch introduces Hybrid Public Key Encryption (HPKE; RFC 9180) through OpenSSL's HPKE APIs ( https://docs.openssl.org/3.5/man3/OSSL_HPKE_CTX_new/ ), added in OpenSSL 3.2.0.

Usage

suite = OpenSSL::HPKE::Suite.new_with_names(:dhkem_x25519_hkdf_sha256, :hkdf_sha256, :aes_128_gcm)
pkey = OpenSSL::HPKE.keygen_with_suite(suite)
pub = pkey.raw_public_key
s = OpenSSL::HPKE::Context::Sender.new(:base, suite)
enc = s.encap(pub, "info")
ct = s.seal("aad", "hi")
r = OpenSSL::HPKE::Context::Receiver.new(:base, suite)
r.decap(enc, pkey, "info")
puts "roundtrip: #{r.open("aad", ct) == "hi"}, export match: #{s.export(32,"l")==r.export(32,"l")}"

APIs

`OpenSSL::HPKE::Suite`

new: Instantiate cipher suite with KEM, KDF, and AEAD identifiers listed in RFC 9180
new_with_names: Instantiate cipher suite with pre-defined names. Uses the list of KEMs, KDFs, AEADs listed in RFC 9180.

`OpenSSL::HPKE`

keygen: Generate OpenSSL::PKey private key with the specified KEM, KDF, and AEAD ID.
- This exposes OpenSSL's OSSL_HPKE_keygen() API.
keygen_with_suite: Generate OpenSSL::PKey private key with the specified cipher suite

These are more like utility functions so if they look extraneous they can be removed in favor of using OpenSSL::PKey to generate corresponding keys.

`OpenSSL::HPKE::Context::Sender` and `OpenSSL::HPKE::Context::Receiver`

new: Instantiate HPKE Context.
- Currently supports :base mode only; I wanted to let the maintainers see this pull request before adding :auth, :psk, and :auth_psk modes

`OpenSSL::HPKE::Context::Sender`

encap: Encapsulates key into the specified public key. Takes receiver's public key and info (application context information)
seal: Using the encapsulated key, seal message into ciphertext. Takes aad (additional authenticated data) and ciphertext itself.

`OpenSSL::HPKE::Context::Receiver`

decap: Decapsulates the key using the private key. Takes the encapsulation, private key, and info (application context information).
open: Using the decapsulated key, decrypt the ciphertext. Takes aad and ciphertext.

Availability

This functionality is available on OpenSSL newer than 3.2.0 without FIPS mode.
- As OpenSSL's FIPS mode does not implement EC KEMs, HPKE on OpenSSL is unavailable even for curves that are supported by FIPS.
LibreSSL, AWS-LC is not supported.
- As far as I know, they do not have the corresponding APIs.

from now on this needs OpenSSL 3.2 to compile

works only with hpke.h that exposes OSSL_HPKE_CTX

The current longest possible public key size is 133 bytes, according to RFC 9180 section 7.1

- HPKE::Context.new that takes mode, role, and suite - HPKE::Context now keeps track of which KEM/KDF/AEAD it uses under instance variable - HPKE.keygen_with_suite

In this patch I also moved the `attr_reader` definitions of kem/kdf/aead_ids into C code

I am very iffy about this. Is there a safer way to handle this allocation?

The last version was not working.... - Sender and Receiver contexts get different classes - Sender gets only sender APIs, Receiver gets only receiver APIs - Sender and Receiver need Suite to initialize - Removed old Context initialization API

- Remove debug functions - 2 space indentation -> 4 space indentation

It's obvious for people who would edit this code...

rhenium · 2026-06-08T17:37:33Z

Thanks for working on this!

Regarding the Ruby API:

`OpenSSL::HPKE::Suite`

* `new`: Instantiate cipher suite with KEM, KDF, and AEAD identifiers listed in RFC 9180

* `new_with_names`: Instantiate cipher suite with pre-defined names. Uses the list of KEMs, KDFs, AEADs listed in RFC 9180.

Do you think if it makes sense to have this as an overload to .new instead of a separate method?

I'm ambivalent about maintaining our own name list in ruby/openssl. I wonder if we could use OSSL_HPKE_str2suite() (https://docs.openssl.org/master/man3/OSSL_HPKE_CTX_new/#protocol-convenience-functions).

OpenSSL::HPKE
* `keygen`: Generate `OpenSSL::PKey` private key with the specified KEM, KDF, and AEAD ID.
  
  * This exposes OpenSSL's `OSSL_HPKE_keygen()` API.

* `keygen_with_suite`: Generate `OpenSSL::PKey` private key with the specified cipher suite
These are more like utility functions so if they look extraneous they can be removed in favor of using OpenSSL::PKey to generate corresponding keys.

This seems useful to me, since there is no straightforward way to map from HPKE KEM IDs to OpenSSL algorithm object names.

However I'm less sure about .keygen method taking a triple of IDs. Since it would most likely be used together with OpenSSL::HPKE::Context::{Sender,Receiver}.new, which requires an instance of Suite anyway, perhaps the variant taking a Suite would be sufficient?

`OpenSSL::HPKE::Context::Sender` and `OpenSSL::HPKE::Context::Receiver`

* `new`: Instantiate HPKE Context.
  
  * Currently supports `:base` mode only; I wanted to let the maintainers see this pull request before adding `:auth`, `:psk`, and `:auth_psk` modes

That sounds like a good plan to me.

rhenium

For style, please add newlines at the end of files and break long lines.

rhenium · 2026-06-05T10:41:17Z

 #include "openssl_missing.h"
+#ifdef HAVE_OPENSSL_HPKE_H
+  #include <openssl/hpke.h>
+#endif


This can be moved to ossl_hpke_ctx.c since it's the only file requiring this.

(We probably should do the same to pkcs12.h/pkcs7.h/ts.h/ocsp.h/etc.)

rhenium · 2026-06-05T10:45:47Z

+    mode_table = rb_const_get_at(cContext, rb_intern("MODES"));
+    mode_id = rb_funcall(mode_table, rb_intern("[]"), 1, mode);
+
+    const char *propq = EVP_default_properties_is_fips_enabled(NULL) ? "fips=yes" : NULL;


EVP_default_properties_is_fips_enabled() == 1 enables "fips=yes" as the default query so that it doesn't have to be explicitly specified.

I think we should not need any FIPS-mode-specific handling in the extension.

rhenium · 2026-06-05T10:59:20Z

+extern VALUE mHPKE;
+extern VALUE cContext;
+extern const rb_data_type_t ossl_hpke_ctx_type;
+
+#if OSSL_OPENSSL_PREREQ(3, 2, 0)
+#define GetHpkeCtx(obj, ctx) do {\
+    TypedData_Get_Struct((obj), OSSL_HPKE_CTX, &ossl_hpke_ctx_type, (ctx)); \
+    if (!(ctx)) { \
+        rb_raise(rb_eRuntimeError, "OSSL_HPKE_CTX wasn't initialized!");\
+    } \
+} while (0)
+#endif


These can be local to the .c file.

rhenium · 2026-06-08T09:44:04Z

+  class Context
+    # supports only base mode for now
+    MODES = {
+      base: 0x00
+    }.freeze
+
+    attr_reader :kem_id, :kdf_id, :aead_id
+  end
+
+  class Suite
+    attr_reader :kem_id, :kdf_id, :aead_id


Can this class be moved to the extension? I'd prefer not to introduce circular dependency between openssl.so and openssl.rb.

rhenium · 2026-06-08T17:45:01Z

+static void
+ossl_hpke_ctx_free(void *ptr)
+{
+#if OSSL_OPENSSL_PREREQ(3, 2, 0)


If no useful feature can be provided, OpenSSL::HPKE should not be defined at all. Please take a look at ossl_ocsp.c as an example.

Also HAVE_OPENSSL_HPKE_H should be used instead of the version number, in case it is merged to LibreSSL or AWS-LC.

rhenium · 2026-06-08T17:45:33Z

+    {
+        0, ossl_hpke_ctx_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY


Suggested change

0, 0, RUBY_TYPED_FREE_IMMEDIATELY

0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,

rhenium · 2026-06-08T18:03:55Z

+    StringValue(label);
+    labellen = RSTRING_LEN(label);
+
+    secret_obj = rb_str_new(0, NUM2INT(secretlen));


Nitpicking, but NUM2INT(secretlen) can invoke Ruby code (secretlen.to_int) and potentially mutate label or return an unstable value.

Also, Ruby Strings use long as the length, so NUM2LONG() is probably better fit here, though it likely doesn't matter in practice. It also calls .to_int.

rhenium · 2026-06-08T18:05:08Z

+#else
+    EVP_PKEY *pkey;
+    VALUE pkey_obj;
+    unsigned char pub[133]; // as per RFC9180 section 7.1, the maximum size of Npk possible is 133


The list in RFC 9180 appears to be the initial content of the registry and I'd expect OpenSSL to implement new KEMs in the future, once published as an RFC: https://www.iana.org/assignments/hpke/hpke.xhtml

Is there any way to avoid hardcoding the maximum size?

sylph01 added 30 commits June 5, 2026 09:18

[hpke] initialize OSSL::HPKE::Context

9ee96bd

[hpke] check for openssl/hpke.h

e7e1f17

from now on this needs OpenSSL 3.2 to compile

[hpke] allocate/initialize context

ec8a3a2

[hpke-a] experiment: try reopening class with a ruby file

afe4bff

[hpke] HPKE.keygen

34ea7a3

[hpke] create HPKE::Context

5301f44

[hpke] encap

aaaac90

set constant buffers to a high enough number

d8b0dda

[hpke] seal

d3b0ddf

[hpke] decap

64748ed

[hpke] open and export, but getting different values?

2f5d645

[hpke] debug: keygen_pub

024c8f0

[hpke] debug: assume fixed ikme

3d0b6e3

lots of debug prints

1efad02

works only with hpke.h that exposes OSSL_HPKE_CTX

[hpke] 🎉

5411682

[hpke] fix encap so that it returns a string with correct length

e1f743e

[hpke] do not assume fixed ikm_e

e68494b

Set buffer size of OSSL_HPKE_keygen to 133

012f241

The current longest possible public key size is 133 bytes, according to RFC 9180 section 7.1

Remove debug method keygen_pub

4a1a787

Use of HPKE::Suite

1f5e54c

- HPKE::Context.new that takes mode, role, and suite - HPKE::Context now keeps track of which KEM/KDF/AEAD it uses under instance variable - HPKE.keygen_with_suite

Use OSSL_HPKE_get_ciphertext_size to determine ciphertext size

0977513

In this patch I also moved the `attr_reader` definitions of kem/kdf/aead_ids into C code

Allocate memory based on OSSL_HPKE_get_public_encap_size

efb922d

I am very iffy about this. Is there a safer way to handle this allocation?

Now that most of the things work, comment out the debug prints

e798bf2

[hpke] macro to remove code when OpenSSL is less than 3.2.0

eb533a9

Fix the guards against older OpenSSL

b73af54

Fix initialize API

f7c4278

Change class structure, fix initialize API

b181210

The last version was not working.... - Sender and Receiver contexts get different classes - Sender gets only sender APIs, Receiver gets only receiver APIs - Sender and Receiver need Suite to initialize - Removed old Context initialization API

Apply rename: ossl_pkey_new -> ossl_pkey_wrap

0212ddb

Re-add include and init

798b929

Ensure String inputs are String with StringValue

9a7cb45

sylph01 added 15 commits June 5, 2026 09:58

Use rb_str_new instead of direct malloc/free

e823e6a

No-op instead of raising inside GC-free

45e9c65

Guard against re-initialization

c07515f

Styling fix

49ec640

- Remove debug functions - 2 space indentation -> 4 space indentation

Add static to HPKE-internal functions

cc6686a

Add license header

e15b4d7

Remove todo comment

9d9e453

Add test code

a447ff3

Remove conflicting attr_reader

fb5d270

Add propq "fips=yes" when FIPS is enabled

9ba8033

Change behavior of tests based on FIPS-compatibility

c60f0cf

Omit HPKE altogether under FIPS mode

bd4cde3

Reorder statements in extconf.rb

9ec86d7

Remove comment

2f8cf4b

It's obvious for people who would edit this code...

Fix comment

161d7d7

rhenium reviewed Jun 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Hybrid Public Key Encryption (HPKE) API Support#1061

Add Hybrid Public Key Encryption (HPKE) API Support#1061
sylph01 wants to merge 45 commits into
ruby:masterfrom
sylph01:hpke

sylph01 commented Jun 5, 2026 •

edited

Loading

Uh oh!

rhenium commented Jun 8, 2026

`OpenSSL::HPKE::Suite`

`OpenSSL::HPKE`

`OpenSSL::HPKE::Context::Sender` and `OpenSSL::HPKE::Context::Receiver`

Uh oh!

rhenium left a comment

Uh oh!

rhenium Jun 5, 2026

Uh oh!

rhenium Jun 5, 2026

Uh oh!

rhenium Jun 5, 2026

Uh oh!

rhenium Jun 8, 2026

Uh oh!

rhenium Jun 8, 2026

Uh oh!

rhenium Jun 8, 2026

Uh oh!

rhenium Jun 8, 2026

Uh oh!

rhenium Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	0, 0, RUBY_TYPED_FREE_IMMEDIATELY
	0, 0, RUBY_TYPED_FREE_IMMEDIATELY \| RUBY_TYPED_WB_PROTECTED,

Conversation

sylph01 commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

APIs

OpenSSL::HPKE::Suite

OpenSSL::HPKE

OpenSSL::HPKE::Context::Sender and OpenSSL::HPKE::Context::Receiver

OpenSSL::HPKE::Context::Sender

OpenSSL::HPKE::Context::Receiver

Availability

Uh oh!

rhenium commented Jun 8, 2026

OpenSSL::HPKE::Suite

OpenSSL::HPKE

OpenSSL::HPKE::Context::Sender and OpenSSL::HPKE::Context::Receiver

Uh oh!

rhenium left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sylph01 commented Jun 5, 2026 •

edited

Loading

`OpenSSL::HPKE::Suite`

`OpenSSL::HPKE`

`OpenSSL::HPKE::Context::Sender` and `OpenSSL::HPKE::Context::Receiver`

`OpenSSL::HPKE::Context::Sender`

`OpenSSL::HPKE::Context::Receiver`

`OpenSSL::HPKE::Suite`

`OpenSSL::HPKE`

`OpenSSL::HPKE::Context::Sender` and `OpenSSL::HPKE::Context::Receiver`