EVP_PKEY_DECAPSULATE(3ossl)

💅 NAME 💅

EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init, EVP_PKEY_decapsulate — key decapsulation using a KEM algorithm with a private key. bestie, this is the OpenSSL 3ossl manual and we're gonna get into it 🎀

---

✨ SYNOPSIS ✨

#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);

---

🌸 DESCRIPTION 🌸

okay so. EVP_PKEY_decapsulate_init() sets up a private key algorithm context ctx for a decapsulation operation, and then it sets the params on that context the exact same way calling EVP_PKEY_CTX_set_params(3) would. lowkey important: ctx is usually made with EVP_PKEY_CTX_new_from_pkey(3), and that's where you say which private key you're using 💜

EVP_PKEY_auth_decapsulate_init() is basically EVP_PKEY_decapsulate_init()'s sister — same vibe — but it also passes an authpub authentication public key that gets used during decapsulation. extra key, extra power 🫶

EVP_PKEY_decapsulate() is the one that actually does the private key decapsulation using ctx. the data you wanna decapsulate goes in through the wrapped and wrappedlen parameters — and heads up, both of them must be non-NULL 😤

the wrapped parameter is an output argument, and the decapsulated shared secret gets written to it. and here's the plot twist: the shared secret may not match your peer's value even when decapsulation returns success. not a bug, that's just how it is 🙈 instead, you take that shared secret and use it to derive a key, and that key authenticates the data you get from the peer afterwards. if unwrapped is NULL then the size of the output shared secret buffer gets written to *unwrappedlen and no decapsulation happens at all — which is honestly so convenient, it lets you figure out the buffer size you need at run time. otherwise, the decapsulated secret data goes into unwrapped and the length of the shared secret gets written to *unwrappedlen ✨

no cap: the value pointed to by unwrappedlen — which must NOT be NULL — has to be initialised to the length of unwrapped, so the call can check it's big enough to hold the result of the operation. skip this and it's over for you 💀

and unless you have detailed prior knowledge of the internals of the specific KEM algorithm, callers SHOULD NOT assume the returned shared secret is necessarily the maximum possible length. use the length returned via *unwrappedlen to determine the actual length of the output. periodt 💅

---

📝 NOTES 📝

after you call EVP_PKEY_decapsulate_init(), you can set or modify algorithm-specific parameters for the operation using EVP_PKEY_CTX_set_params(3). that's it, that's the note 🎀

---

👑 RETURN VALUES 👑

EVP_PKEY_decapsulate_init(), EVP_PKEY_auth_decapsulate_init() and EVP_PKEY_decapsulate() all return 1 for success, and 0 or a negative value for failure. and specifically? a return value of -2 means the operation is not supported by the private key algorithm. so if you see -2, that's what's up 🔥

---

🌈 EXAMPLES 🌈

decapsulate data using RSA, bestie:

#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 ALSO 🦋

EVP_PKEY_CTX_new_from_pkey(3), EVP_PKEY_encapsulate(3), EVP_KEM-RSA(7), EVP_KEM-X25519(7), EVP_KEM-EC(7), EVP_KEM-ML-KEM-512(7), EVP_KEM-ML-KEM-768(7), EVP_KEM-ML-KEM-1024(7)

---

🧚 HISTORY 🧚

• 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.

---

💖 COPYRIGHT 💖

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

---

and that's the whole page, bestie — this was the EVP_PKEY_DECAPSULATE(3ossl) manpage from OpenSSL version 3.5.9, dated 2026-09-29. slay, go decapsulate something 💅✨🎀