OSSL_PARAM_INT(3SSL)

📦

version 4.0.3 · 13 versions

💖 OSSL_PARAM_INT(3SSL) 💖

okay bestie, welcome to the OpenSSL glow-up corner where we talk about OSSL_PARAM helpers, aka the little struct squad that carries your key/type/value bundles around like a friend group that always knows where the aux cord is. this is the 3SSL manual — part one, and yes there are more parts, don't leave yet 🫶

✨ NAME ✨

say hi to literally the whole cast, no one's getting cut:

OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong
OSSL_PARAM_BN
OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr
OSSL_PARAM_END, OSSL_PARAM_DEFN
the constructors: OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end
the finders: OSSL_PARAM_locate, OSSL_PARAM_locate_const
the getters: OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr, OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr
the setters: OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr, OSSL_PARAM_set_octet_string_or_ptr
the modified-state crew: OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified

…and what are all of these? OSSL_PARAM helpers. that's the whole vibe 💅

🦋 SYNOPSIS 🦋

bestie, this is the part you screenshot. here it is, character for character, no notes:

        #include <openssl/params.h>

        /*
         * TYPE in function names is one of:
         * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong
         * Corresponding TYPE in function arguments is one of:
         * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t,
         * uint64_t, unsigned long
         */

        #define OSSL_PARAM_TYPE(key, address)
        #define OSSL_PARAM_BN(key, address, size)
        #define OSSL_PARAM_utf8_string(key, address, size)
        #define OSSL_PARAM_octet_string(key, address, size)
        #define OSSL_PARAM_utf8_ptr(key, address, size)
        #define OSSL_PARAM_octet_ptr(key, address, size)
        #define OSSL_PARAM_END

        #define OSSL_PARAM_UNMODIFIED

        #define OSSL_PARAM_DEFN(key, type, addr, sz)    \
           { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }

        OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
        OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
                                           size_t bsize);
        OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
                                                    size_t bsize);
        OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
                                                     size_t bsize);
        OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
                                                 size_t bsize);
        OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
                                                  size_t bsize);
        OSSL_PARAM OSSL_PARAM_construct_end(void);

        OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
        const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
                                                  const char *key);

        int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
        int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);

        int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
        int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);

        int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
                                       size_t max_len);
        int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);

        int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
                                        size_t max_len, size_t *used_len);
        int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);

        int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
        int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);

        int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
                                     size_t *used_len);
        int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
                                     size_t used_len);

        int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val);
        int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val,
                                            size_t *used_len);

        int OSSL_PARAM_modified(const OSSL_PARAM *param);
        void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params);

       int OSSL_PARAM_set_octet_string_or_ptr(OSSL_PARAM *p, const void *val,
                                              size_t len);

a couple things to clock while you're here 👀 — the TYPE placeholder in function names is one of double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong, and the matching TYPE in the actual arguments is one of double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t, uint64_t, unsigned long. same energy, different spelling, iykyk.

okay that's the whole headline act so far — the names and the signatures. the actual tea (description, options, all the juicy getters and setters and return values) is coming in the next part, so stay seated, bestie, we're not done 💅✨

✨ DESCRIPTION ✨

okay so bestie, this whole page is a lil collection of utility functions that make working with OSSL_PARAM(3) arrays so much easier and add type safety on top 💅. Here are all the TYPE names you get to play with:

double
int
int32 (int32_t)
int64 (int64_t)
long int (long)
time_t
size_t
uint32 (uint32_t)
uint64 (uint64_t)
unsigned int (uint)
unsigned long int (ulong)

OSSL_PARAM_TYPE() — this is a whole series of macros made to help you initialise an array of OSSL_PARAM(3) structures 🫶. Each macro defines a parameter of the specified TYPE, using the key you give it and the address of the parameter variable.
OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() — these macros are the support squad for defining UTF8 strings, OCTET strings and big numbers 🌸. They define a parameter with name key, storage sitting at address, and size in bytes.
OSSL_PARAM_END — the end-of-parameter-list marker, and ngl it's kind of a big deal. It has to terminate all OSSL_PARAM(3) arrays, no exceptions periodt ⭐.
OSSL_PARAM_DEFN() — this macro lets you construct a single OSSL_PARAM(3) (usually while you're building out an OSSL_PARAM array). The key, type, addr and sz args line up with the key, data_type, data and data_size fields of the OSSL_PARAM(3) structure, exactly like it says over on the OSSL_PARAM(3) page 💜.
OSSL_PARAM_construct_TYPE() — a series of functions that build OSSL_PARAM(3) records dynamically, live, in real time ✨. A parameter with name key gets created. That parameter will use the storage pointed to by buf, and it reports back a return size of ret.
OSSL_PARAM_construct_BN() — constructs a large integer OSSL_PARAM(3) structure. You get a parameter with name key, storage buf, size bsize, and return size rsize 👑
OSSL_PARAM_construct_utf8_string() — constructs a UTF8 string OSSL_PARAM(3) structure. A parameter with name key, storage buf and size bsize is created. If bsize is zero, the string length gets figured out with strlen(3) 🎀. Pro tip straight from the source: generally just pass zero for bsize instead of calling strlen(3) yourself.
OSSL_PARAM_construct_octet_string() — constructs an OCTET string OSSL_PARAM(3) structure. A parameter with name key, storage buf and size bsize is created 💖.
OSSL_PARAM_construct_utf8_ptr() — constructs a UTF8 string pointer OSSL_PARAM(3) structure. A parameter with name key, storage pointer *buf and size bsize is created 🌈.
OSSL_PARAM_construct_octet_ptr() — constructs an OCTET string pointer OSSL_PARAM(3) structure. A parameter with name key, storage pointer *buf and size bsize is created 🦋.
OSSL_PARAM_construct_end() — constructs the terminating OSSL_PARAM(3) structure. The closer. The final girl. 💀
OSSL_PARAM_locate() — searches through an array of parameters for the one matching the key name 🔍.
OSSL_PARAM_locate_const() — literally behaves exactly like OSSL_PARAM_locate() except there's a const hanging out on the array argument and on its return value 🙈.
OSSL_PARAM_get_TYPE() — retrieves a value of type TYPE from the parameter p. The value gets copied over to the address val. Type coercion happens, and it works like the NOTES section says 📝.
OSSL_PARAM_set_TYPE() — stores a value val of type TYPE into the parameter p. If the parameter's data field is NULL, then only its return_size field gets assigned the size that the parameter's data buffer should have 👀. Type coercion again, as discussed in NOTES.
OSSL_PARAM_get_BN() — retrieves a BIGNUM from the parameter pointed to by p. The BIGNUM referenced by val is updated, and it gets allocated if *val is NULL 💅.
OSSL_PARAM_set_BN() — stores the BIGNUM val into the parameter p. If the parameter's data field is NULL, then only its return_size field gets assigned the size the parameter's data buffer should have.
OSSL_PARAM_get_utf8_string() — retrieves a UTF8 string from the parameter pointed to by p. The string goes into *val with a size limit of max_len, and max_len must be big enough to hold a terminating NUL byte, otherwise this function just fails 😭. If *val is NULL, memory gets allocated for the string (terminating NUL byte included, bestie) and max_len is ignored. If this function allocated the memory, you have to free it, no passing the chore off.
OSSL_PARAM_set_utf8_string() — sets a UTF8 string from the parameter pointed to by p to the value referenced by val. If the parameter's data field isn't NULL, its data_size must show that the buffer is big enough to hold the string val points at — not counting the terminating NUL byte — or this function fails 🚨. A terminating NUL byte only gets added if the parameter's data_size shows the buffer is longer than the string length; otherwise the string will not be NUL terminated. And if the parameter's data field is NULL, then only its return_size field gets assigned the minimum size the parameter's data buffer should have to hold the string, not including a terminating NUL byte 📏.
OSSL_PARAM_get_octet_string() — retrieves an OCTET string from the parameter pointed to by p. The OCTETs either get stored into *val with a length limit of max_len, or — if *val is NULL — memory is allocated and max_len is ignored 🍓. *used_len gets populated with the number of OCTETs stored. If val is NULL then the OCTETs aren't stored at all, but *used_len still gets populated. And if this function allocated memory, the caller has to free it, that's the rule 🫡.
OSSL_PARAM_set_octet_string() — sets an OCTET string from the parameter pointed to by p to the value referenced by val. If the parameter's data field is NULL, then only its return_size field gets assigned the size the parameter's data buffer should have ✨.
OSSL_PARAM_get_utf8_ptr() — retrieves the UTF8 string pointer from the parameter referenced by p and stores it in *val 🌸.
OSSL_PARAM_set_utf8_ptr() — sets the UTF8 string pointer in the parameter referenced by p to the values val 💜.
OSSL_PARAM_get_octet_ptr() — retrieves the OCTET string pointer from the parameter referenced by p and stores it in *val. The length of the OCTET string gets stored in *used_len 📐.
OSSL_PARAM_set_octet_ptr() — sets the OCTET string pointer in the parameter referenced by p to the values val. The length of the OCTET string is provided by used_len 🎯.
OSSL_PARAM_get_utf8_string_ptr() — retrieves the pointer to a UTF8 string from the parameter pointed to by p, and stores that pointer in *val. This is different from OSSL_PARAM_get_utf8_string(), which copies the string — this one just hands you the pointer, no copy, iykyk 👑
OSSL_PARAM_get_octet_string_ptr() — retrieves the pointer to a octet string from the parameter pointed to by p, and stores that pointer in *val, along with the string's length in *used_len. Also different from OSSL_PARAM_get_octet_string(), which copies the string 🦋.
OSSL_PARAM_UNMODIFIED — this macro is how you detect if a parameter was set 👀. On creation, whether via the macros or the construct calls, the return_size field is set to this. If the parameter gets set using the calls defined in here, the return_size field is changed. That's the tell.
OSSL_PARAM_modified() — queries whether the parameter param has been set or not, using the calls defined herein 🕵️.
OSSL_PARAM_set_all_unmodified() — resets the unused indicator for all parameters in the array params, like a little factory reset for the whole squad 💅.
OSSL_PARAM_set_octet_string_or_ptr() — sets an OCTET string or a string pointer from the parameter pointed to by p to the value referenced by val. If p is an OCTET string and the parameter's data field is NULL, then only its return_size field will be assigned the size the parameter's data buffer should have 🌟. The length of the OCTET string is provided by len.

💖 RETURN VALUES 💖

okay so here's what you actually get back:

OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() — these all return a populated OSSL_PARAM(3) structure 🎁.
OSSL_PARAM_locate() and OSSL_PARAM_locate_const() — return a pointer to the matching OSSL_PARAM(3) object. They return NULL on error, or when there's no object matching key hanging out in the array 😶.
OSSL_PARAM_modified() — returns 1 if the parameter was set, and 0 otherwise ✅❌.
All other functions — return 1 on success and 0 on failure. Simple as that.

📝 NOTES 📝

Native types will only get converted as required if the value is exactly representable by the target type or parameter 🔬. Other than that, the functions have to be used appropriately for the expected type of the parameter — so like, match them up right, don't just vibe and hope for the best.

OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative BIGNUMs when the desired data type is OSSL_PARAM_UNSIGNED_INTEGER 🚨. And OSSL_PARAM_construct_BN() currently constructs an OSSL_PARAM(3) structure with the data type OSSL_PARAM_UNSIGNED_INTEGER.

For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), bsize isn't relevant if the purpose is to send the OSSL_PARAM(3) array to a responder — like, to get parameter data back 📨. In that case, bsize can safely be given zero, so go ahead and pass that zero with confidence bestie 🫶. See "DESCRIPTION" in OSSL_PARAM(3) for further information on the possible purposes.

✨ EXAMPLES ✨

So, we're literally just borrowing the examples from OSSL_PARAM(3) again, but this time it's to show you how OSSL_PARAM(3) arrays get handled with the macros and functions we've been yapping about this whole time. 🫶

🌸 Example 1

This one's for setting parameters on some object, bestie:

#include <openssl/core.h>

const char *foo = "some string";
size_t foo_l = strlen(foo);
const char bar[] = "some other string";
const OSSL_PARAM set[] = {
    OSSL_PARAM_utf8_ptr("foo", &foo, foo_l),
    OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1),
    OSSL_PARAM_END
};

🦋 Example 2

This one's for requesting parameters on some object — and it also shows off the fact that the requester is not obligated to ask for every single parameter available. Like, you can just want some of them, and that's valid. 💅

const char *foo = NULL;
char bar[1024];
OSSL_PARAM request[] = {
    OSSL_PARAM_utf8_ptr("foo", &foo, 0),
    OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
    OSSL_PARAM_END
};

And a responder that receives this array (as params in this example, iykyk) could fill in those parameters like this:

/* OSSL_PARAM *params */

OSSL_PARAM *p;

if ((p = OSSL_PARAM_locate(params, "foo")) != NULL)
    OSSL_PARAM_set_utf8_ptr(p, "foo value");
if ((p = OSSL_PARAM_locate(params, "bar")) != NULL)
    OSSL_PARAM_set_utf8_string(p, "bar value");
if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
    OSSL_PARAM_set_utf8_ptr(p, "cookie value");

🎀 Example 3

Okay this one's a special case, and it's giving "compiler is being dramatic." It's about when -Wincompatible-pointer-types-discards-qualifiers might get set during compilation. 🙈

The thing is: the value for buf cannot be a const char * type string. And an alternative in this case would be to use the OSSL_PARAM macro abbreviated calls instead of the specific callers — because that lets you define the sha1 argument as a standard character array (char[]). 🌈

So for example, this code:

OSSL_PARAM params[2];
params[0] = OSSL_PARAM_construct_utf8_string("digest", "SHA1", 0);
params[1] = OSSL_PARAM_construct_end();

Can be made compatible with the following version:

char sha1[] = "SHA1"; /* sha1 is defined as char[] in this case */
OSSL_PARAM params[2];

params[0] = OSSL_PARAM_construct_utf8_string("digest", sha1, 0);
params[1] = OSSL_PARAM_construct_end();

See how sha1 is chilling as a char[] now? No more compiler slander. ✨

👀 SEE ALSO

openssl-core.h(7)
OSSL_PARAM(3)

📜 HISTORY

These functions were added in OpenSSL 3.0.

And OSSL_PARAM_set_octet_string_or_ptr was added in OpenSSL 3.6. Newer queen on the block. 👑

©️ 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 OSSL_PARAM_INT(3SSL), from repo version 4.0.3, dated 2026-09-29. Go forth and handle your params with main character energy. Slay. 🦋✨

📦 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