OSSL_PARAM_A...ATE_FROM_TEXT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 OSSL_PARAM_A...ATE_FROM_TEXT(3ossl) 💖

okay bestie, so this is the OpenSSL manpage for OSSL_PARAM_allocate_from_text, and it lives in the 3ossl manual section. it's a construction-utilities situation and honestly it's giving "glow-up era for parameter passing". let's get into it 🫶

✨ NAME ✨

OSSL_PARAM_allocate_from_text — OSSL_PARAM construction utilities

🌸 SYNOPSIS 🌸

#include <openssl/params.h>

int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
                                  const OSSL_PARAM *paramdefs,
                                  const char *key, const char *value,
                                  size_t value_n,
                                  int *found);

🦋 DESCRIPTION 🦋

so, back in the day — like, OpenSSL before version 3.0 — parameters got passed down to algorithm implementations (and pulled back out of them) through control functions. some of those control functions had variants that just took string parameters, for example EVP_PKEY_CTX_ctrl_str(3).

then OpenSSL 3.0 showed up and said "new mechanism, new me" 💅 — now you do the same thing with an array of parameters that hold a name, a value, a value type and a value size (peep OSSL_PARAM(3) if you want the full lore).

OSSL_PARAM_allocate_from_text() uses key to look up an item in paramdefs. if it finds one, it converts value into something suitable for that item's data_type, and stores the result in to->data along with its size in to->data_size. then to->key and to->data_type get assigned the corresponding values from the item that was found, and to->return_size is set to zero. iconic behaviour honestly.

heads up bestie: to->data is always allocated using OPENSSL_zalloc(3), and you — the caller — have to free it when it's not useful any more, using OPENSSL_free(3). no cap, don't forget, that's a leak otherwise 😭

and if found isn't NULL, then *found gets set to 1 if key could be located in paramdefs, and to 0 otherwise.

🎀 The use of key and value in detail 🎀

OSSL_PARAM_allocate_from_text() pays attention to whether key starts with "hex", and if it does, it'll only use the rest of key to look up an item in paramdefs. for example, if key is "hexid", then "id" is what gets looked up in paramdefs. sneaky but cute.

once an item in paramdefs has been found, value gets converted depending on that item's data_type, like this:

  • OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER — if key didn't start with "hex", then value is assumed to contain value_n decimal characters, which get decoded, and the resulting bytes become the number stored in the to->data storage.
    • but wait: if value starts with "0x", it's assumed to contain value_n hexadecimal characters instead.
    • and if key started with "hex", then value is assumed to contain value_n hexadecimal characters without the "0x" prefix.
    • if value contains characters that couldn't be decoded as hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text() considers that an error. 💀
  • OSSL_PARAM_UTF8_STRING — if key started with "hex", OSSL_PARAM_allocate_from_text() considers that an error. nope, not today.
    • otherwise, value is considered a C string and is copied to the to->data storage. and on systems where the native character encoding is EBCDIC, the bytes in to->data are converted to ASCII. ✨
  • OSSL_PARAM_OCTET_STRING — if key started with "hex", value is assumed to contain value_n hexadecimal characters, which get decoded, and the resulting bytes are stored in the to->data storage. if value contains characters that couldn't be decoded as hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text() considers that an error.
    • if key didn't start with "hex", then value_n bytes from value are copied to the to->data storage.

👑 RETURN VALUES 👑

OSSL_PARAM_allocate_from_text() returns 1 if key was found in paramdefs and there was no other failure. otherwise it returns 0. that's it, that's the tea. 🍓

🌈 NOTES 🌈

the parameter descriptor array comes from functions that are dedicated to returning them. the following OSSL_PARAM(3) attributes get used:

  • key
  • data_type
  • data_size

all other attributes are ignored. periodt.

the data_size attribute can be zero, which means the parameter it describes expects arbitrary length data. flexible queen 🧚

⭐ EXAMPLES ⭐

code that looked like this:

int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
{
    int rv;
    char *stmp, *vtmp = NULL;

    stmp = OPENSSL_strdup(value);
    if (stmp == NULL)
        return -1;
    vtmp = strchr(stmp, ':');
    if (vtmp != NULL)
        *vtmp++ = '\0';
    rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
    OPENSSL_free(stmp);
    return rv;
}

...

for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
    char *macopt = sk_OPENSSL_STRING_value(macopts, i);

    if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
        BIO_printf(bio_err,
                   "MAC parameter error \"%s\"\n", macopt);
        ERR_print_errors(bio_err);
        goto mac_end;
    }
}

can be written like this instead:

OSSL_PARAM *params =
    OPENSSL_zalloc(sizeof(*params)
                   * (sk_OPENSSL_STRING_num(opts) + 1));
const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
size_t params_n;
char *opt = "<unknown>";

for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
     params_n++) {
    char *stmp, *vtmp = NULL;

    opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
    if ((stmp = OPENSSL_strdup(opt)) == NULL
            || (vtmp = strchr(stmp, ':')) == NULL)
        goto err;

    *vtmp++ = '\0';
    if (!OSSL_PARAM_allocate_from_text(&params[params_n],
                                       paramdefs, stmp,
                                       vtmp, strlen(vtmp), NULL))
        goto err;
}
params[params_n] = OSSL_PARAM_construct_end();
if (!EVP_MAC_CTX_set_params(ctx, params))
    goto err;
while (params_n-- > 0)
    OPENSSL_free(params[params_n].data);
OPENSSL_free(params);
/* ... */
return;

err:
BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
ERR_print_errors(bio_err);

the glow-up is real. 🔥

💜 SEE ALSO 💜

OSSL_PARAM(3), OSSL_PARAM_int(3)

Copyright 2019-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 whole page bestie, you ate it 💅✨ this was OpenSSL 3.5.9, dated 2026-09-2, from the OSSL_PARAM_A...ATE_FROM_TEXT(3ossl) manual — go forth and allocate responsibly, and please free your to->data 🫶🎀

📦 where this page comes from