EVP_KEM-EC(7ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 NAME 💖

EVP_KEM-EC — the EC keytype + algorithm support for KEMs, and honestly? it ate.

✨ DESCRIPTION ✨

Okay so first thing, bestie: the EC keytype and all its little parameters live over in EVP_PKEY-EC(7) — that's the lore. And if you wanna know the actual mechanics of wrapping and unwrapping keys, go peek at EVP_PKEY_encapsulate(3) and EVP_PKEY_decapsulate(3). They've got the full details, no gatekeeping.

🎀 EC KEM parameters 🎀

👑 "operation" (OSSL_KEM_PARAM_OPERATION) <UTF8 string>

So the OpenSSL EC Key Encapsulation Mechanism lowkey only vibes with one default operation (like, the operating mode), and it is:

  • "DHKEM" (OSSL_KEM_PARAM_OPERATION_DHKEM) — okay so here's what happens: the encapsulate function spins up a whole ephemeral keypair (main character energy tbh). It makes keymaterial by doing an ECDH key exchange with the ephemeral private key and a recipient public key that you supply. Then an HKDF operation runs on that keymaterial plus a kem context, and boom — out comes a shared secret. You get back the shared secret and the ephemeral public key. Meanwhile, the decapsulate function takes the recipient private key and that ephemeral public key, produces the exact same keymaterial, and from there produces the exact same shared secret. Matching. Iconic. 💅

There's the actual spec link if you wanna read the source material (and you should, iykyk): <https://www.rfc-editor.org/rfc/rfc9180.html#name-dh-based-kem-dhkem>

You can set this using either EVP_PKEY_CTX_set_kem_op() or EVP_PKEY_CTX_set_params(). Either one, your call, both slay.

🦋 "ikme" (OSSL_KEM_PARAM_IKME) <octet string>

This one's for specifying the key material used when generating the ephemeral key. Quick PSA though — do not reuse this value for other purposes, fr fr, that's a whole security situation.

It only works with the curves "P-256", "P-384" and "P-521", and it should be at least as long as the size of the encoded private key — that's 32, 48 and 66 for the curves listed above, respectively, in case you were about to ask.

If you don't set this value at all? No stress, a random ikm gets used instead. 🫶

🔥 CONFORMING TO 🔥

RFC9180 — we stay on spec, periodt.

🌸 SEE ALSO 🌸

EVP_PKEY_CTX_set_kem_op(3), EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3) EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)

⭐ HISTORY ⭐

This whole functionality was added in OpenSSL 3.2. Baby era.

And a fun little glow-up note: the "operation" (operating mode) used to be a required parameter prior to OpenSSL 3.5. But as of OpenSSL 3.5, "DHKEM" is the default operating mode, so you don't have to specify any explicit value anymore. We love an upgrade that simplifies things. 💜

Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

Okay that's the whole page bestie, you're officially educated 💖 This was EVP_KEM-EC(7ossl) from version 3.5.6, dated 2026-04-07 — go forth and encapsulate responsibly 🧚✨

📦 where this page comes from