EVP_PKEY_ENCRYPT(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 EVP_PKEY_ENCRYPT(3ossl) — the OpenSSL glow-up 💖

okay so bestie, gather round 🫶 this is the <openssl/evp.h> page about encrypting stuff with a public key algorithm, from your friends at OpenSSL (manual section 3ossl, yes we're fancy). It's genuinely not scary, i promise — it's giving "three functions and a vibe check." ✨

🌸 SYNOPSIS 🌸

like, the actual signatures, no cap:

#include <openssl/evp.h>

int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_encrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx,
                     unsigned char *out, size_t *outlen,
                     const unsigned char *in, size_t inlen);

that's it. that's the whole entrance. 💅

🦋 DESCRIPTION 🦋

okay so three main characters, let's meet them 👑

  • EVP_PKEY_encrypt_init() — this one initializes a public key algorithm context using key pkey for an encryption operation. it's the "set the stage" moment. 🎬
  • EVP_PKEY_encrypt_init_ex() — same energy, but it also sets the algorithm specific params while it's at it. like init but with extra credit. ✨
  • EVP_PKEY_encrypt() — the actual encryption, performed using ctx. the data to be encrypted is specified using the in and inlen parameters. now here's the part where you gotta pay attention bestie 👀:
    • if out is NULL, then the maximum size of the output buffer is written to the outlen parameter. (this is the "how much room do i need" call — iconic.)
    • if out is not NULL, then before the call the outlen parameter should contain the length of the out buffer, and if the call is successful the encrypted data is written to out and the amount of data written to outlen. 🔥

🎀 NOTES 🎀

so after you call EVP_PKEY_encrypt_init(), you can do algorithm specific control operations to set any appropriate parameters for the operation. and plot twist — those same operations can just be folded into the EVP_PKEY_encrypt_init_ex() call instead. efficiency slay. 💅

also EVP_PKEY_encrypt() can be called more than once on the same context if you're doing several operations with the same parameters. reuse the vibe, it's fine. 🌈

⭐ RETURN VALUES ⭐

EVP_PKEY_encrypt_init(), EVP_PKEY_encrypt_init_ex() and EVP_PKEY_encrypt() 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 public key algorithm. that's the "wrong key type, bestie" signal 🚩

🔥 EXAMPLES 🔥

okay so here's how you encrypt data using OAEP (for RSA keys). also peep PEM_read_PUBKEY(3) or d2i_X509(3) if you need a way to load a public key — and you can literally just set eng = NULL; to start with the default OpenSSL RSA implementation. easy. 🫶

#include <openssl/evp.h>
#include <openssl/rsa.h>
#include <openssl/engine.h>

EVP_PKEY_CTX *ctx;
ENGINE *eng;
unsigned char *out, *in;
size_t outlen, inlen;
EVP_PKEY *key;

/*
 * NB: assumes eng, key, in, inlen are already set up,
 * and that key is an RSA public key
 */
ctx = EVP_PKEY_CTX_new(key, eng);
if (!ctx)
    /* Error occurred */
if (EVP_PKEY_encrypt_init(ctx) <= 0)
    /* Error */
if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)
    /* Error */

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

out = OPENSSL_malloc(outlen);

if (!out)
    /* malloc failure */

if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)
    /* Error */

/* Encrypted data is outlen bytes written to buffer out */

see how we call encrypt twice? first with NULL to find out how big the buffer needs to be, then for real. that's the whole trick. main character move honestly. 👑

💜 SEE ALSO 💜

go read these next, i'm obsessed with cross-references:

d2i_X509(3), ENGINE_by_id(3), EVP_PKEY_CTX_new(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

🌈 HISTORY 🌈

these functions were added in OpenSSL 1.0.0. ancient. vintage. still ate. 🧚

Copyright 2006-2021 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 page bestie!! 💖 this whole thing is version 3.5.6, dated 2026-04-07 — go forth and encrypt responsibly, ilysm, bye 🎀🦋✨

📦 where this page comes from