NCONF_NEW_EX(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 NCONF_NEW_EX(3ossl) — like, the whole config-file situation, explained

Okay bestie, so this is an OpenSSL page (3ossl, the SSL crew, you know the vibe) and it's literally all about loading and parsing configuration files manually. No cap. The little cast of characters is NCONF_new_ex, NCONF_new, NCONF_free, NCONF_default, NCONF_load, NCONF_get0_libctx, NCONF_get_section, and NCONF_get_section_names — the whole friend group. 🫶

✨ SYNOPSIS ✨

Like, here's the incantation, copy it exactly or it won't slay:

#include <openssl/conf.h>

typedef struct {
    char *section;
    char *name;
    char *value;
} CONF_VALUE;

CONF *NCONF_new_ex(OSSL_LIB_CTX *libctx, CONF_METHOD *meth);
CONF *NCONF_new(CONF_METHOD *meth);
void NCONF_free(CONF *conf);
CONF_METHOD *NCONF_default(void);
int NCONF_load(CONF *conf, const char *file, long *eline);
OSSL_LIB_CTX *NCONF_get0_libctx(const CONF *conf);

STACK_OF(CONF_VALUE) *NCONF_get_section(const CONF *conf, const char *name);
STACK_OF(OPENSSL_CSTRING) *NCONF_get_section_names(const CONF *conf);

That CONF_VALUE struct? Iconic. Three little char * fields — section, name, value — and that's the whole personality. 🎀

🌸 DESCRIPTION 🌸

Let's go function by function, mwah:

  • NCONF_new_ex() — creates a brand-new CONF object in heap memory (yes, heap, she lives on the heap now 🧚) and assigns to it a context libctx that can be used during loading. And if the method table meth is set to NULL? Then the default value of NCONF_default() gets used. Easy.
  • NCONF_new() — basically NCONF_new_ex()'s sibling, same energy, except it sets the libctx to NULL. That's the whole difference, periodt.
  • NCONF_free() — frees the data associated with conf and then frees the conf object itself. Cleanup queen. And if the argument is NULL, nothing is done — she simply does not engage. 💅
  • NCONF_load() — parses the file named filename and adds the values found to conf. And if an error occurs, file and eline list the file and line that the load failed on — but only if they're not NULL. So pass them or don't, your call.
  • NCONF_default() — gets the default method table for processing a configuration file. The blueprint, the template, the moment.
  • NCONF_get0_libctx() — gets the library context associated with the conf parameter. Just hands it right back to you.
  • NCONF_get_section_names() — gets the names of the sections associated with the conf as STACK_OF(OPENSSL_CSTRING) strings. Lowkey important caveat: the individual strings are associated with the conf and will be invalid after conf is freed. 😭 And the returned stack must be freed with sk_OPENSSL_CSTRING_free(). Don't forget, bestie, that's your job, not hers.
  • NCONF_get_section() — gets the config values associated with the conf from the config section name as STACK_OF(CONF_VALUE) structures. Same warning energy: the returned stack is associated with the conf and will be invalid after conf is freed. And this one must not be freed by the caller — nope, not yours to free, hands off. 🙈
Heads up: those two get functions hand you borrowed pointers. They are not gifts. They evaporate the second conf gets freed. 🦋

⭐ RETURN VALUES ⭐

  • NCONF_load() — returns 1 on success or 0 on error. Binary queen, no in-between.
  • NCONF_new_ex() and NCONF_new() — return a newly created CONF object, or NULL if an error occurs. So like, always vibe check that return value. 💀

👑 SEE ALSO 👑

CONF_modules_load_file(3),

(Yes, it ends with a comma in the original and I'm keeping it, character for character, don't @ me.)

🔥 HISTORY 🔥

NCONF_new_ex(), NCONF_get0_libctx(), and NCONF_get_section_names() were added in OpenSSL 3.0. The new girls on the block, and they ate. ✨

Copyright 2020-2024 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, go forth and parse your configs manually like the main character you are. 🫶

Big kiss, this was OpenSSL 3.5.6, dated 2026-04-07, and the page is NCONF_NEW_EX(3ossl) — slay, bye! 💖

📦 where this page comes from