OSSL_PARAM_A...ATE_FROM_TEXT(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 OSSL_PARAM_allocate_from_text (3ossl) ✨

okay so bestie, welcome to the glow-up era of OpenSSL parameter handling. this page lives in the 3ossl manual section and it's literally about OSSL_PARAM construction utilities — the little helper that turns your messy text into a proper OSSL_PARAM. no cap, it's iconic. 🎀

✨ 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 (or pulled back out of them) through control functions. some of those control functions had variants that took string parameters, okurrr? for example EVP_PKEY_CTX_ctrl_str(3).

then OpenSSL 3.0 walked in with main character energy and introduced a whole new mechanism that does the same thing with an array of parameters containing name, value, value type and value size (peep OSSL_PARAM(3) for the full tea 🍵).

so here's the vibe of OSSL_PARAM_allocate_from_text(): it 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 stashes the result in to->data — plus its size in to->data_size. 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. slay. 💅

to->data is always allocated using OPENSSL_zalloc(3) and needs to be freed by the caller when it's not useful any more, using OPENSSL_free(3). don't forget, bestie, that's a whole memory leak waiting to happen 😭

if found is not NULL, *found is 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() takes note if key starts with "hex", and will only use the rest of key to look up an item in paramdefs in that case. like, as an example: if key is "hexid", then "id" will be looked up in paramdefs. iykyk 🧚

when an item in paramdefs has been found, value is converted depending on that item's data_type, as follows:

  • OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER
    • if key didn't start with "hex", value is assumed to contain value_n decimal characters, which are decoded, and the resulting bytes become the number stored in the to->data storage.
    • if value starts with "0x", it is assumed to contain value_n hexadecimal characters.
    • if key started with "hex", 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.
    • otherwise, value is considered a C string and is copied to the to->data storage. 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 are 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", 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 whole vibe check. ✨

👑 NOTES 👑

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

  • key
  • data_type
  • data_size

all other attributes are ignored. 🙈

the data_size attribute can be zero, meaning that the parameter it describes expects arbitrary length data.

🌈 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 (glow-up moment 💖):

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

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

okay that's the whole page bestie, go forth and construct your params responsibly 🎀✨

little sign-off fr fr: this was version 3.5.6, dated 2026-04-0, and it's the OSSL_PARAM_A...ATE_FROM_TEXT(3ossl) page. mwah 💋🦋
📦 where this page comes from