OSSL_PARAM_BLD(3ossl)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

💅 OSSL_PARAM_BLD(3ossl) — the girlies' guide to `OSSL_PARAM_BLD`

okay bestie, welcome to OSSL_PARAM_BLD(3ossl)</pink> 💖 this is the page for a little crew of helper functions that make building OSSL_PARAM arrays way less painful than doing it by hand. lowkey iconic of OpenSSL ngl.

✨ NAME ✨

OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr — literally just functions to assist in the creation of OSSL_PARAM arrays 🫶

🌸 SYNOPSIS 🌸

#include <openssl/param_build.h>

typedef struct OSSL_PARAM_BLD;

OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);

int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);

int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
                           const BIGNUM *bn);
int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
                               const BIGNUM *bn, size_t sz);

int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
                                    const char *buf, size_t bsize);
int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                 char *buf, size_t bsize);
int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
                                     const void *buf, size_t bsize);
int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                  void *buf, size_t bsize);

🦋 DESCRIPTION 🦋

so it's a whole collection of utility functions that simplify the creation of OSSL_PARAM arrays 🎀 and the TYPE names? they're as per OSSL_PARAM_int(3), iykyk.

OSSL_PARAM_BLD_new() — allocates and initialises a new OSSL_PARAM_BLD structure so you can start adding values ✨ any existing values are cleared, so it's a fresh start every time, periodt.
OSSL_PARAM_BLD_free() — deallocates the memory allocated by OSSL_PARAM_BLD_new(). and if the argument is NULL? nothing happens, it just vibes. no cap.
OSSL_PARAM_BLD_to_param() — converts a built-up OSSL_PARAM_BLD structure bld into an allocated OSSL_PARAM array 👑 the OSSL_PARAM array and all associated storage must be freed by calling OSSL_PARAM_free() with the function's return value. and yes, OSSL_PARAM_BLD_free() can safely be called any time after this function is — you're free to yeet the builder 💅
OSSL_PARAM_BLD_push_TYPE() — a whole series of functions that will create OSSL_PARAM objects of the specified size and correct type for the val argument 🌈 val is stored by value, so an expression or auto variable is totally fine to use.
when TYPE denotes an integer type, signed integer types will normally get the OSSL_PARAM type OSSL_PARAM_INTEGER params. and when TYPE denotes an unsigned integer type? it gets the OSSL_PARAM type OSSL_PARAM_UNSIGNED_INTEGER 🧚
OSSL_PARAM_BLD_push_BN() — creates an OSSL_PARAM object that holds the specified BIGNUM bn 🍓 when bn is zero or positive, its OSSL_PARAM type becomes OSSL_PARAM_UNSIGNED_INTEGER. when bn is negative, its OSSL_PARAM type becomes OSSL_PARAM_INTEGER. if bn is marked as being securely allocated, its OSSL_PARAM representation will also be securely allocated 🔐 and listen: the bn argument is stored by reference, so the underlying BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been called. do not let it ghost you.
OSSL_PARAM_BLD_push_BN_pad() — creates an OSSL_PARAM object that holds the specified BIGNUM bn, except this one gets padded to occupy exactly sz bytes — and if insufficient space is specified, an error results 💀 when bn is zero or positive, its OSSL_PARAM type becomes OSSL_PARAM_UNSIGNED_INTEGER. when bn is negative, its OSSL_PARAM type becomes OSSL_PARAM_INTEGER. if bn is marked as being securely allocated, its OSSL_PARAM representation will also be securely allocated. the bn argument is stored by reference and the underlying BIGNUM object must exist until after OSSL_PARAM_BLD_to_param() has been called 🫶
OSSL_PARAM_BLD_push_utf8_string() — creates an OSSL_PARAM object that references the UTF8 string specified by buf 🎀 the length of the string bsize should not include the terminating NUL byte, and if it is zero then it will be calculated. the string that buf points to is stored by reference and must remain in scope until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_octet_string() — creates an OSSL_PARAM object that references the octet string specified by buf and <bsize> 🌸 the memory that buf points to is stored by reference and must remain in scope until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_utf8_ptr() — creates an OSSL_PARAM object that references the UTF8 string specified by buf. the length of the string bsize should not include the terminating NUL byte, and if it is zero then it will be calculated. the string buf points to is stored by reference and must remain in scope until the OSSL_PARAM array is freed ⭐ (note: this one's a slightly longer leash than the _string versions, ok?)
OSSL_PARAM_BLD_push_octet_ptr() — creates an OSSL_PARAM object that references the octet string specified by buf 🦋 the memory buf points to is stored by reference and must remain in scope until the OSSL_PARAM array is freed.

💜 RETURN VALUES 💜

OSSL_PARAM_BLD_new() — returns the allocated OSSL_PARAM_BLD structure, or NULL on error 😭
OSSL_PARAM_BLD_to_param() — returns the allocated OSSL_PARAM array, or NULL on error 😭
all of the OSSL_PARAM_BLD_push_TYPE functions — return 1 on success and 0 on error ✨

🔥 NOTES 🔥

okay important one, no cap: OSSL_PARAM_BLD_push_BN() and OSSL_PARAM_BLD_push_BN_pad() only support nonnegative BIGNUMs. they return an error on negative BIGNUMs 💀 to pass signed BIGNUMs, use OSSL_PARAM_BLD_push_signed_BN() 👑

🌈 EXAMPLES 🌈

both examples create an OSSL_PARAM array that contains an RSA key 🗝️ for both, the predefined key variables are:

BIGNUM *n;           /* modulus */
unsigned int e;      /* public exponent */
BIGNUM *d;           /* private exponent */
BIGNUM *p, *q;       /* first two prime factors */
BIGNUM *dmp1, *dmq1; /* first two CRT exponents */
BIGNUM *iqmp;        /* first CRT coefficient */

🎀 Example 1 🎀

this one shows how to create an OSSL_PARAM array that contains an RSA private key 💅

OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
OSSL_PARAM *params = NULL;

if (bld == NULL
    || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
    || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
    || !OSSL_PARAM_BLD_push_BN(bld, "d", d)
    || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor1", p)
    || !OSSL_PARAM_BLD_push_BN(bld, "rsa-factor2", q)
    || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent1", dmp1)
    || !OSSL_PARAM_BLD_push_BN(bld, "rsa-exponent2", dmq1)
    || !OSSL_PARAM_BLD_push_BN(bld, "rsa-coefficient1", iqmp)
    || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
    goto err;
OSSL_PARAM_BLD_free(bld);
/* Use params */
...
OSSL_PARAM_free(params);

🧚 Example 2 🧚

and this one shows how to create an OSSL_PARAM array that contains an RSA public key ⭐

OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
OSSL_PARAM *params = NULL;

if (nld == NULL
    || !OSSL_PARAM_BLD_push_BN(bld, "n", n)
    || !OSSL_PARAM_BLD_push_uint(bld, "e", e)
    || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
    goto err;
OSSL_PARAM_BLD_free(bld);
/* Use params */
...
OSSL_PARAM_free(params);

🫶 SEE ALSO 🫶

OSSL_PARAM_int(3), OSSL_PARAM(3), OSSL_PARAM_free(3) — go read those too bestie, they're the whole context 💖

👑 HISTORY 👑

the functions described here were all added in OpenSSL 3.0 ✨ a classic.

💀 COPYRIGHT 💀

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!! 🦋 sign-off time: this was OpenSSL 3.5.6, dated 2026-04-07, and the whole thing is filed under OSSL_PARAM_BLD(3ossl) 🌸 go build some params, you're gonna slay 💅✨

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms