BIO_GET_EX_NEW_INDEX(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 BIO_GET_EX_NEW_INDEX(3ossl) — or, "how do I stash my own lil' data on an OpenSSL object??"

okay so bestie, this is the 3ossl manual page for the entire application-specific data family — every TYPE_get_ex_new_index, TYPE_set_ex_data, TYPE_get_ex_data, and the lil' app_data convenience macros. It's giving "attach your own stuff to an OpenSSL struct without touching the struct." Obsessed. 🫶

✨ NAME ✨

These functions all deal in application-specific data 🎀, and here's the full roll call — every single one, no cap:

  • BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, BIO_set_app_data, BIO_get_app_data
  • DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data
  • DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data
  • EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data
  • ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data
  • EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data
  • RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, RSA_set_app_data, RSA_get_app_data
  • SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, SSL_set_app_data, SSL_get_app_data
  • SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data, SSL_CTX_set_app_data, SSL_CTX_get_app_data
  • SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data, SSL_SESSION_set_app_data, SSL_SESSION_get_app_data
  • UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, UI_set_app_data, UI_get_app_data
  • X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data
  • X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data
  • X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data

…and what do they do? application-specific data. That's the whole vibe. 💫

🌸 SYNOPSIS 🌸

The generic shape of everything, bestie — TYPE is the placeholder, okay, don't come for me:

#include <openssl/x509.h>

int TYPE_get_ex_new_index(long argl, void *argp,
                          CRYPTO_EX_new *new_func,
                          CRYPTO_EX_dup *dup_func,
                          CRYPTO_EX_free *free_func);

int TYPE_set_ex_data(TYPE *d, int idx, void *arg);

void *TYPE_get_ex_data(const TYPE *d, int idx);

#define TYPE_set_app_data(TYPE *d, void *arg)
#define TYPE_get_app_data(TYPE *d)
🚨 heads up!! The functions below have been deprecated since OpenSSL 3.0, and you can hide them entirely by defining OPENSSL_API_COMPAT with a suitable version value — peek openssl_user_macros(7) for that.
int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
                        CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
int DH_set_ex_data(DH *type, int idx, void *arg);
void *DH_get_ex_data(DH *type, int idx);
int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
int DSA_set_ex_data(DSA *type, int idx, void *arg);
void *DSA_get_ex_data(DSA *type, int idx);
int EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
int EC_KEY_set_ex_data(EC_KEY *type, int idx, void *arg);
void *EC_KEY_get_ex_data(EC_KEY *type, int idx);
int RSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
int RSA_set_ex_data(RSA *type, int idx, void *arg);
void *RSA_get_ex_data(RSA *type, int idx);
int RSA_set_app_data(RSA *type, void *arg);
void *RSA_get_app_data(RSA *type);
int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
int ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);
void *ENGINE_get_ex_data(ENGINE *type, int idx);

🦋 DESCRIPTION 🦋

In everything below, TYPE is a placeholder for any of the OpenSSL datatypes listed over in CRYPTO_get_ex_new_index(3). Slay, generic programming. 💜

The deprecated girlies, part one: all the functions with a TYPE of DH, DSA, RSA and EC_KEY are deprecated. 😭 Applications should instead use EVP_PKEY_set_ex_data(), EVP_PKEY_get_ex_data() and EVP_PKEY_get_ex_new_index(). That's the glow-up. ✨

The deprecated girlies, part two: all the functions with a TYPE of ENGINE are deprecated too. Applications using engines should be replaced by providers. No cap.

So what do these actually do? They handle application-specific data for OpenSSL data structures. It's literally "here's my stuff, hold it for me" energy. 🎀

  • TYPE_get_ex_new_index() — a macro that calls CRYPTO_get_ex_new_index() with the correct index value. It's giving "middle management." 💅
  • TYPE_set_ex_data() — a function that calls CRYPTO_set_ex_data() with an offset into the opaque exdata part of the TYPE object. ⚠️ d MUST NOT be NULL. Like, fr fr, don't do it.
  • TYPE_get_ex_data() — a function that calls CRYPTO_get_ex_data() with an offset into the opaque exdata part of the TYPE object. ⚠️ And yeah, d MUST NOT be NULL here either. 😤

🎀 the app_data era (for the OGs)

For compatibility with previous releases, the exdata index of zero is reserved for "application data." There are two convenience functions for this:

  • TYPE_set_app_data() — a macro that invokes TYPE_set_ex_data() with idx set to zero.
  • TYPE_get_app_data() — a macro that invokes TYPE_get_ex_data() with idx set to zero.

Zero is the main character. Index zero has main character energy. 👑

⭐ RETURN VALUES ⭐

  • TYPE_get_ex_new_index() — returns a new index on success, or -1 on error. 🍓
  • TYPE_set_ex_data() — returns 1 on success, or 0 on error.
  • TYPE_get_ex_data() — returns the application data, or NULL if an error occurred. 😭

🔥 SEE ALSO 🔥

💀 HISTORY 💀

The following functions were deprecated in OpenSSL 3.0:

  • DH_get_ex_new_index(), DH_set_ex_data(), DH_get_ex_data()
  • DSA_get_ex_new_index(), DSA_set_ex_data(), DSA_get_ex_data()
  • EC_KEY_get_ex_new_index(), EC_KEY_set_ex_data(), EC_KEY_get_ex_data()
  • ENGINE_get_ex_new_index(), ENGINE_set_ex_data(), ENGINE_get_ex_data()
  • RSA_get_ex_new_index(), RSA_set_ex_data(), RSA_get_ex_data(), RSA_set_app_data(), RSA_get_app_data()

Rest in peace besties, you had a good run. 🙈

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

okay that's the whole page!! 🧚 this was version 3.5.6, dated 2026-04-07, and it's the BIO_GET_EX_NEW_INDEX(3ossl) page. go forth and stash your data, bestie — drink water, check your return values, and iykyk 💖🌈💅

📦 where this page comes from