OSSL_PARAM_BLD(3SSL)

📦

version 4.0.3 · 13 versions

💖 OSSL_PARAM_BLD — the OpenSSL param-builder glow-up 💖

hey bestie, you found OSSL_PARAM_BLD(3SSL), aka the little helper gang that makes building OSSL_PARAM arrays not a whole ordeal. pull up a chair, we're doing this together 🫶

✨ 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 — they're the functions that assist in the creation of OSSL_PARAM arrays. that's the whole job, that's the whole squad 💅

🌸 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 🦋

okay so. it's a collection of utility functions that simplify the creation of OSSL_PARAM arrays. that's the mission statement, no notes. the TYPE names are as per OSSL_PARAM_int(3) — go check that one if you need the lineup. 💜

OSSL_PARAM_BLD_new() — allocates and initialises a new OSSL_PARAM_BLD structure so that values can be added. any existing values are cleared. fresh start energy, we love that for us ✨
OSSL_PARAM_BLD_free() — deallocates the memory allocates by OSSL_PARAM_BLD_new(). if the argument is NULL, nothing is done. respect. it just minds its business 🙈
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(); if the contents of OSSL_PARAM array are confidential call OSSL_PARAM_clear_free(). OSSL_PARAM_BLD_free() can safely be called any time after this function is. two separate cleanups bestie, don't mix them up 😭
OSSL_PARAM_BLD_push_TYPE() — this is a whole series of functions which will create OSSL_PARAM objects of the specified size and correct type for the val argument. val is stored by value and an expression or auto variable can be used. so casual, so convenient 👑
when TYPE denotes an integer type, signed integer types will normally get the OSSL_PARAM type OSSL_PARAM_INTEGER params. when TYPE denotes an unsigned integer type will get the OSSL_PARAM type OSSL_PARAM_UNSIGNED_INTEGER. signed vs unsigned, the eternal vibe check ⭐
OSSL_PARAM_BLD_push_BN() — creates an OSSL_PARAM object that holds the specified BIGNUM bn. when the bn is zero or positive, its OSSL_PARAM type becomes OSSL_PARAM_UNSIGNED_INTEGER. when the 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. ⚠️ by reference means by reference, bestie — if your BIGNUM dips out early, everything falls apart. keep it alive till the conversion, fr fr.
OSSL_PARAM_BLD_push_BN_pad() — creates an OSSL_PARAM object that holds the specified BIGNUM bn. the object will be padded to occupy exactly sz bytes, if insufficient space is specified an error results. when the bn is zero or positive, its OSSL_PARAM type becomes OSSL_PARAM_UNSIGNED_INTEGER. when the 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. same lifetime drama as above, just with a padding commitment 💅
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. 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. 👀 scope. until. to_param. write that down.
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. octet bestie said "same rules" 🍓
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. 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. 🚨 ptr variant = longer lifetime window — not just till to_param(), but all the way until the array itself is freed. different clock, same rules energy.
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. yeah, same extended window as the utf8 ptr one. no cap 🧚

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

so: NULL means sad, 1 means slay, 0 means sad. got it? got it. 💖

💀 NOTES 💀

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().

not me learning this the hard way so you don't have to 😭 read the note, bestie, it's there for a reason.

🌈 EXAMPLES 🌈

both examples creating 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 example 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_clear_free(params);

🎀 Example 2 🎀

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

(yes, the second one says nld — that's exactly what the page says, so it stays exactly what the page says. copy it verbatim if you're copying, bestie, it's not my business to "fix" it 💅)

⭐ HISTORY ⭐

the functions described here were all added in OpenSSL 3.0. glow-up era, periodt. 💜

📜 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 whole page, bestie!! 💖 this was OpenSSL 4.0.3, dated 2026-09-29 — go forth and build your param arrays, you absolute icon 🦋✨👑

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms