EVP_PKEY_DECAPSULATE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 EVP_PKEY_DECAPSULATE — key decapsulation with a private key (this is the 3ossl girlies' page, bestie) 💖

Ok so first things first: hi, welcome, this is the OpenSSL manual page for EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init and EVP_PKEY_decapsulate — the whole decapsulation situation, KEM style, with a private key. Sit down, grab a strawberry 🍓, we're doing crypto.

✨ NAME ✨

EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init, EVP_PKEY_decapsulate — key decapsulation using a KEM algorithm with a private key. That's the vibe. No cap. 🦋

🌸 SYNOPSIS 🌸

Like, here's the shape of it:

#include <openssl/evp.h>

int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
int EVP_PKEY_auth_decapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpub,
                                  const OSSL_PARAM params[]);
int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx,
                         unsigned char *unwrapped, size_t *unwrappedlen,
                         const unsigned char *wrapped, size_t wrappedlen);

Three functions, one glow-up. ✨

🎀 DESCRIPTION 🎀

EVP_PKEY_decapsulate_init() — the setup era

It initializes a private key algorithm context ctx for a decapsulation operation, and then sets the params on the context in exactly the same way as calling EVP_PKEY_CTX_set_params(3). Two birds, one function, we love efficiency. 🫶

Little note though: ctx is usually produced using EVP_PKEY_CTX_new_from_pkey(3), specifying the private key to use. That's the main character move here — you gotta say which private key you're working with. 👑

EVP_PKEY_auth_decapsulate_init() — same but with a plus-one

This one is similar to EVP_PKEY_decapsulate_init() but also passes an authpub authentication public key that is used during decapsulation. Extra key, extra flair. 🔥

EVP_PKEY_decapsulate() — the actual moment

This performs a private key decapsulation operation using ctx. The data to be decapsulated is specified using the wrapped and wrappedlen parameters (which must both be non-NULL — that's not optional, bestie, NULL will not be slaying today).

The wrapped parameter is an output argument, to which the decapsulated shared secret is written. (Yes, the page says it like that — we're reporting faithfully, that's the assignment. 💅)

Ok but here's the part where you need to listen:

The shared secret may not match the peer's value even when decapsulation returns success. Instead, the shared secret must be used to derive a key that is used to authenticate data subsequently received from the peer.

So like, success does not mean "the secrets match". It means "the operation ran". The actual verification happens later, when you derive a key from the shared secret and use it to authenticate the data the peer sends you. That's the whole point of the design, bestie, it is not a bug. 🙈

If unwrapped is NULL then the size of the output shared secret buffer is written to *unwrappedlen and no decapsulation is performed. That's the "how big should my buffer be" run — it lets you determine the required buffer size at run time. Then you come back and do it for real. 🌈

Otherwise, the decapsulated secret data is written to unwrapped and the length of the shared secret is written to *unwrappedlen.

And ok, critical: the value pointed to by unwrappedlen (which must NOT be NULL) must be initialised to the length of unwrapped, so that the call can validate it is of sufficient size to hold the result of the operation. If you don't do that, the call has nothing to check against — so do it. It's giving "read the instructions before you touch the keyboard". 😭

And one more thing — absent detailed prior knowledge of the internals of the specific KEM algorithm, callers SHOULD NOT assume that the returned shared secret is necessarily of the maximum possible length. So don't hardcode sizes, don't assume, don't guess. The length returned via *unwrappedlen SHOULD be used to determine the actual length of the output. Trust the return value, it knows things you don't. 💜

🧚 NOTES 🧚

After the call to EVP_PKEY_decapsulate_init(), algorithm-specific parameters for the operation may be set or modified using EVP_PKEY_CTX_set_params(3). Init first, then customize. That's the order, that's the flow. ⭐

👑 RETURN VALUES 👑

EVP_PKEY_decapsulate_init(), EVP_PKEY_auth_decapsulate_init() and EVP_PKEY_decapsulate() return 1 for success and 0 or a negative value for failure.

And specifically, because this matters:

A return value of -2 indicates the operation is not supported by the private key algorithm.

So if you get -2, it's not you, it's the algorithm — it literally doesn't do this. 💀

💅 EXAMPLES 💅

Decapsulate data using RSA. Here's the whole thing, verbatim, iconic:

#include <openssl/evp.h>

/*
 * NB: assumes rsa_priv_key is an RSA private key,
 * and that in, inlen are already set up to contain encapsulated data.
 */

EVP_PKEY_CTX *ctx = NULL;
size_t secretlen = 0;
unsigned char *secret = NULL;;

ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL);
if (ctx == NULL)
    /* Error */
if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0)
    /* Error */

/* Set the mode - only 'RSASVE' is currently supported */
if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0)
    /* Error */

/* Determine buffer length */
if (EVP_PKEY_decapsulate(ctx, NULL, &secretlen, in, inlen) <= 0)
    /* Error */

secret = OPENSSL_malloc(secretlen);
if (secret == NULL)
    /* malloc failure */

/* Decapsulated secret data is secretlen bytes long */
if (EVP_PKEY_decapsulate(ctx, secret, &secretlen, in, inlen) <= 0)
    /* Error */

See how it does the NULL call first to get secretlen, then OPENSSL_mallocs, then calls again with the real buffer? That's the pattern, periodt. Note the comment: only 'RSASVE' is currently supported as the mode. 🍓

🦋 SEE ALSO 🦋

Go read these next, they're all linked lore:

🌺 HISTORY 🌺

A little timeline moment:

  • EVP_PKEY_decapsulate_init() and EVP_PKEY_decapsulate() were added in OpenSSL 3.0.
  • EVP_PKEY_auth_decapsulate_init() was added in OpenSSL 3.2.
  • Support for ML-KEM was added in OpenSSL 3.5.

Growth, evolution, slay. 🌱

Copyright 2020-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>.

Ok that's the page!! 🎀 Version 3.5.0, dated 2026-09-25, and yes bestie, that's the whole EVP_PKEY_DECAPSULATE(3ossl) situation. Go decapsulate something responsibly, initialize your unwrappedlen, and remember: success ≠ matching secrets. Mwah. 💖✨🫶

📦 where this page comes from