OSSL_PARAM_INT(3ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · fedora 43, fedora 44 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.9 · alpine 3.23, alpine 3.24
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.5 · fedora 44

hiii bestie!! 💖💅 welcome to OSSL_PARAM_INT(3ossl) — aka the OpenSSL page for the entire OSSL_PARAM helper family. It's so long it got split into three parts, so grab a lil snack 🍓, hydrate, and let's gooo 🦋✨

✨ NAME ✨

okay so literally every single one of these lives on this page, and the whole vibe is that they're all OSSL_PARAM helpers (that's the " — OSSL_PARAM helpers" tag at the end of the list, periodt 👑). Meet the squad:

the numeric macros (the ones whose name literally tells you the C type): 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
the string / bignum / pointer macros: 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, OSSL_PARAM_UNMODIFIED
the constructors (they build you an OSSL_PARAM): 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 locators (they find stuff): OSSL_PARAM_locate, OSSL_PARAM_locate_const
the getters (read a value out): 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 (write a value in): 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
the modified-tracking crew (did anyone touch this??): OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified

🦋 SYNOPSIS 🦋

first thing's first, you gotta pull in the header. She's lowkey the whole personality of this page:

#include <openssl/params.h>

now here's the little cheat-sheet comment about TYPE, bestie — because TYPE in these names is just a stand-in. In function names it's one of double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong. And the matching C type that actually goes in the arguments is one of double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t, uint64_t, unsigned long. iykyk 💅

/*
 * 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
 */

next up, the macros ✨ — some of them take a key, address and size, and the fancy OSSL_PARAM_DEFN one is literally a braced initialiser with OSSL_PARAM_UNMODIFIED baked right in:

#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 }

and now the constructors, locators, getters and setters 🫶 — every single signature, no skips:

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

and that's the whole synopsis bestie 😭 that was a lot of typing but we ate 💅 now stay tuned because the actual explanations are coming up next and there is SO much tea to spill... 👀

✨ DESCRIPTION ✨

okay bestie so this is a whole little collection of utility functions whose entire job is to make OSSL_PARAM(3) arrays less painful and way more type-safe 🫶 like they're the little helpers that hold your hand so you don't fumble the types. and the TYPE names we support are:

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)

that's the whole roster, no gatekeeping 💅

OSSL_PARAM_TYPE() is a whole series of macros built to help you initialise an array of OSSL_PARAM(3) structures. each one of these macros defines a parameter of the specified TYPE with the key you give it and the parameter variable address. yes bestie, it's giving "set it and forget it" energy ✨

OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are the macros that provide support for defining UTF8 strings, OCTET strings and big numbers. a parameter with name key gets defined. the storage for this parameter lives at address and is size bytes big. that's the whole deal 🎀

OSSL_PARAM_END provides an end of parameter list marker. this is the little "we're done here" moment and it should terminate all OSSL_PARAM(3) arrays. don't skip it, it's not optional decor 🙈

the OSSL_PARAM_DEFN() macro gives you the ability to construct a single OSSL_PARAM(3) — typically used when you're building up OSSL_PARAM arrays. the key, type, addr and sz arguments line up with the key, data_type, data and data_size fields of the OSSL_PARAM(3) structure, exactly as described on the OSSL_PARAM(3) page. icon behaviour honestly 👑

OSSL_PARAM_construct_TYPE() is a series of functions that create OSSL_PARAM(3) records dynamically, on the fly, no pre-baking required. a parameter with name key is created. the parameter will use the storage pointed to by buf and return size of ret. slay 💅

OSSL_PARAM_construct_BN() is the function that constructs a large integer OSSL_PARAM(3) structure. a parameter with name key, storage buf, size bsize and return size rsize is created. big number vibes only 🔥

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. and here's the tea: if bsize is zero, the string length is determined using strlen(3). generally you should just pass zero for bsize instead of calling strlen(3) yourself — let the function do the math, bestie, it's literally what it's here for 🌸

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. simple, clean, no notes ✨

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. pointer not copy, iykyk 🦋

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. same energy, octet edition 💜

OSSL_PARAM_construct_end() constructs the terminating OSSL_PARAM(3) structure. it's the periodt of your array 🎀

OSSL_PARAM_locate() is the function that searches an array of parameters for the one matching the key name. like a little scavenger hunt but for your data 🔍

OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() — except for the presence of const for the array argument and its return value. same function, just const-flavoured 💅

OSSL_PARAM_get_TYPE() retrieves a value of type TYPE from the parameter p. the value gets copied to the address val. type coercion takes place as discussed in the NOTES section. so go read your notes bestie, it matters 📝

OSSL_PARAM_set_TYPE() stores a value val of type TYPE into the parameter p. here's the important bit: if 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. type coercion takes place as discussed in the NOTES section. again. the notes. read them 😭

OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by p. the BIGNUM referenced by val is updated and is allocated if *val is NULL. so it'll set you up if you come empty-handed 🫶

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 will be assigned the size the parameter's data buffer should have. same deal as always 💖

OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter pointed to by p. the string is stored into *val with a size limit of max_len, which must be large enough to accommodate a terminating NUL byte — otherwise this function will fail. no room, no string, periodt. if *val is NULL, memory is allocated for the string (including the terminating NUL byte) and max_len is ignored. and if memory is allocated by this function, it must be freed by the caller. don't be the person who leaks, bestie, that's not cute 🙈

OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to by p to the value referenced by val. now focus: if the parameter's data field isn't NULL, its data_size must indicate that the buffer is large enough to accommodate the string that val points at — not including the terminating NUL byte — or this function will fail. a terminating NUL byte is added only if the parameter's data_size indicates the buffer is longer than the string length, otherwise the string will not be NUL terminated. yes, that's a real trap, be careful. if the parameter's data field is NULL, then only its return_size field will be assigned the minimum size the parameter's data buffer should have to accommodate the string, not including a terminating NUL byte. the way that this one has layers 😭

OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter pointed to by p. the OCTETs are either stored into *val with a length limit of max_len or, in the case when *val is NULL, memory is allocated and max_len is ignored. *used_len is populated with the number of OCTETs stored. and if val is NULL then the OCTETs are not stored, but *used_len is still populated — like, it'll still tell you the length, it's just not handing over the goods. if memory is allocated by this function, it must be freed by the caller. you know the drill by now 💅

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 will be assigned the size the parameter's data buffer should have. classic 🎀

OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter referenced by p and stores it in *val. just the pointer, no copying here ✨

OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter referenced by p to the values val. that's it, that's the function 🌸

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 is stored in *used_len. so you get the pointer and the length, a two-for-one 🦋

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. you supply both, it stores both 💜

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. and here's the distinction that matters: this is different from OSSL_PARAM_get_utf8_string(), which copies the string. pointer vs copy, choose wisely 👑

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. this is different from OSSL_PARAM_get_octet_string(), which copies the string. again: pointer, not copy. no cap 💅

OSSL_PARAM_UNMODIFIED is the macro used to detect if a parameter was set. on creation, via either the macros or the construct calls, the return_size field is set to this. if the parameter is set using the calls defined herein, the return_size field is changed. so it's like a little "has anyone touched this" flag 🎀

OSSL_PARAM_modified() queries if the parameter param has been set or not using the calls defined herein. just a yes/no vibe check ✨

OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters in the array params. mass reset, one call, slay 🌈

🫶 RETURN VALUES 🫶

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() all return a populated OSSL_PARAM(3) structure. a whole little gift, ready to go 🎁

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 no object matching key exists in the array. so NULL = not found or something went sideways 😭

OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. simple binary, we love to see it 💅

all other functions return 1 on success and 0 on failure. that's the whole pattern, bestie ✨

💀 NOTES 💀

native types will be converted as required only if the value is exactly representable by the target type or parameter. apart from that, the functions must be used appropriately for the expected type of the parameter. so like — don't just yeet any type in there and hope, okay? be intentional 🙈

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. so, unsigned, nonnegative, that's the lane 🔥

for OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), bsize is not relevant if the purpose is to send the OSSL_PARAM(3) array to a responder, i.e. to get parameter data back. in that case, bsize can safely be given zero. see "DESCRIPTION" in OSSL_PARAM(3) for further information on the possible purposes. yes, that's how it's spelled in the source, don't @ me 🫶

✨ EXAMPLES ✨

Okay bestie, we're reusing the examples from OSSL_PARAM(3) here, but this time it's just to show off how OSSL_PARAM(3) arrays can be handled using all the macros and functions we talked about up above. Same vibes, new tools. 💅

🌸 Example 1

This one is 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 is for requesting parameters on some object, and it also shows that the requester is not obligated to request all the available parameters. Like, you can want some of the menu and not the whole menu. Slay. 🙈

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 the 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 is the special case example, and it's giving "compiler said what now" energy. 😭 It shows a case where -Wincompatible-pointer-types-discards-qualifiers may be set during compilation.

The value for buf cannot be a const char * type string. No cap.

An alternative in this case would be to use OSSL_PARAM macro abbreviated calls rather than the specific callers, which allows you to 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 ALSO 👑

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

📜 HISTORY 📜

These APIs were introduced in OpenSSL 3.0. Iconic behavior, honestly. 🎀

💜 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 lil' masterpiece is from version 3.5.9, dated 2026-09-29, and it's the OSSL_PARAM_INT(3ossl) page — go forth and parameter responsibly. Periodt. 💅✨🌈🦋

📦 where this page comes from

fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms