EVP_PKEY_GETTABLE_PARAMS(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💖 EVP_PKEY_GETTABLE_PARAMS — ok bestie let's get those key params 💖

So this is the OpenSSL 3ossl manual page for the whole little family of functions that pull parameters out of an EVP_PKEY. Yes, the header literally is EVP_PKEY_GETTABLE_PARAMS(3ossl) and no, we're not typing that ever again. Let's go 🫶

🌸 NAME 🌸

EVP_PKEY_gettable_params, EVP_PKEY_get_params, EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param, EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param, EVP_PKEY_get_octet_string_param — the whole squad whose entire job is retrieve key parameters from a key. That's it. That's the vibe. ✨

🦋 SYNOPSIS 🦋

#include <openssl/evp.h>

const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]);
int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name,
                           int *out);
int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name,
                              size_t *out);
int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name,
                          BIGNUM **bn);
int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name,
                                   char *str, size_t max_buf_sz,
                                   size_t *out_len);
int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name,
                                    unsigned char *buf, size_t max_buf_sz,
                                    size_t *out_len);

Like, just look at them. All lined up. Gorgeous. 💅

🎀 DESCRIPTION 🎀

First things first — for the whole lore on parameters, go read OSSL_PARAM(3). It's giving required reading, ngl.

EVP_PKEY_get_params() retrieves parameters from the key pkey, according to the contents of params. You hand it a list, it fills it in. Simple, iconic.

EVP_PKEY_gettable_params() returns a constant list of params showing the names and types of key parameters that can actually be retrieved. Think of it as the menu at the restaurant before you order. 🍓

Okay so here's the important bit, pay attention bestie 😭 — an OSSL_PARAM(3) of type OSSL_PARAM_INTEGER or OSSL_PARAM_UNSIGNED_INTEGER is of arbitrary length. That's a big deal. Such a parameter can be obtained using any of the functions EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param() or EVP_PKEY_get_bn_param(). But — and this is the catch — attempting to obtain an integer value that does not fit into a native C int type will cause EVP_PKEY_get_int_param() to fail. Similarly, attempting to obtain an integer value that is negative or does not fit into a native C size_t type using EVP_PKEY_get_size_t_param() will also fail. Don't set yourself up like that. 💀

  • EVP_PKEY_get_int_param() — retrieves a key pkey integer value *out associated with a name of key_name, if it fits into int type. For parameters that do not fit into int, use EVP_PKEY_get_bn_param(). Periodt.
  • EVP_PKEY_get_size_t_param() — retrieves a key pkey size_t value *out associated with a name of key_name, if it fits into size_t type. For parameters that do not fit into size_t, use EVP_PKEY_get_bn_param(). Same energy, bigger bucket.
  • EVP_PKEY_get_bn_param() — retrieves a key pkey BIGNUM value **bn associated with a name of key_name. If *bn is NULL then the BIGNUM is allocated by the method. So you can come empty-handed and it'll hook you up 🫶
  • EVP_PKEY_get_utf8_string_param() — gets a key pkey UTF8 string value into a buffer str of maximum size max_buf_sz associated with a name of key_name. The maximum size must be large enough to accommodate the string value including a terminating NUL byte, or this function will fail. If out_len is not NULL, *out_len is set to the length of the string not including the terminating NUL byte. And the required buffer size (again, not including the terminating NUL byte) can be obtained from *out_len by calling the function with str set to NULL. Sneaky little two-step, we love her ✨
  • EVP_PKEY_get_octet_string_param() — gets a key pkey's octet string value into a buffer buf of maximum size max_buf_sz associated with a name of key_name. If out_len is not NULL, *out_len is set to the length of the contents. The required buffer size can be obtained from *out_len by calling the function with buf set to NULL. Same trick, different data. 🎀

🧚 NOTES 🧚

These functions only work for EVP_PKEYs that contain a provider side key. That's the whole vibe check. No provider side key, no results. 🙈

⭐ RETURN VALUES ⭐

  • EVP_PKEY_gettable_params() returns NULL on error or if it is not supported.
  • All other methods return 1 if a value associated with the key's key_name was successfully returned, or 0 if there was an error.
  • An error may be returned by methods EVP_PKEY_get_utf8_string_param() and EVP_PKEY_get_octet_string_param() if max_buf_sz is not big enough to hold the value. And if out_len is not NULL, *out_len will be assigned the required buffer size to hold the value. Literally so helpful of it. 💖

🔥 EXAMPLES 🔥

#include <openssl/evp.h>

char curve_name[64];
unsigned char pub[256];
BIGNUM *bn_priv = NULL;

/*
 * NB: assumes 'key' is set up before the next step. In this example the key
 * is an EC key.
 */

if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME,
                                    curve_name, sizeof(curve_name), &len)) {
  /* Error */
}
if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
                                     pub, sizeof(pub), &len)) {
    /* Error */
}
if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
    /* Error */
}

BN_clear_free(bn_priv);

Look at that. Three params, three wins. And then BN_clear_free(bn_priv); at the end because you clean up after yourself, main character energy only. 👑

🌈 SEE ALSO 🌈

Go read them, iykyk 📚

👑 HISTORY 👑

These functions were added in OpenSSL 3.0. So they're not ancient, they're established. Lowkey a classic already.

Copyright 2020-2022 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 retrieve those parameters 💅✨

Signing off from version 3.5.6, dated 2026-04-07 — this was EVP_PKEY_GETTABLE_PARAMS(3ossl), and she ate. 🎀🦋

📦 where this page comes from