EVP_PKEY_GETTABLE_PARAMS(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 EVP_PKEY_GETTABLE_PARAMS 💖

okay bestie, this is the OpenSSL manual for EVP_PKEY_gettable_params and its whole lil friend group, living in section 3SSL of the manual. It's giving "how do I pull params out of a key" energy, and honestly? iconic. 🎀

✨ 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 — retrieve key parameters from a key 💅

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

💜 DESCRIPTION 💜

first things first bestie — if you wanna know about parameters in general, go read OSSL_PARAM(3). that's the lore. 📖

EVP_PKEY_get_params() — this one grabs parameters from the key pkey, literally according to whatever is in params. no cap.

EVP_PKEY_gettable_params() — hands you back a constant list of params that tells you the names and types of the key parameters you're actually able to retrieve. like a menu. a vibe check for what's gettable. ✨

now here's the tea ☕: an OSSL_PARAM(3) of type OSSL_PARAM_INTEGER or OSSL_PARAM_UNSIGNED_INTEGER is of arbitrary length. like, it can be huge. so you can grab such a param with any of EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param(), or EVP_PKEY_get_bn_param(). but!! if you try to get an integer value that doesn't fit into a native C int type, EVP_PKEY_get_int_param() will fail. same energy with EVP_PKEY_get_size_t_param(): try to get an integer that's negative or doesn't fit into a native C size_t type and it also fails. 😭

EVP_PKEY_get_int_param() — retrieves a key pkey integer value *out tied to a name of key_name, but only if it fits into "int" type. doesn't fit? use EVP_PKEY_get_bn_param() instead. simple as.

EVP_PKEY_get_size_t_param() — retrieves a key pkey size_t value *out tied to a name of key_name, if it fits into "size_t" type. doesn't fit? again, go EVP_PKEY_get_bn_param(). 💫

EVP_PKEY_get_bn_param() — retrieves a key pkey BIGNUM value **bn tied to a name of key_name. and if *bn is NULL, then the BIGNUM gets allocated by the method. handing it to you, basically. 🫶

EVP_PKEY_get_utf8_string_param() — gets a key pkey UTF8 string value into a buffer str of maximum size max_buf_sz, tied to a name of key_name. important: 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, then *out_len is set to the length of the string not including the terminating NUL byte. and here's the trick bestie: you can get the required buffer size (not including the terminating NUL byte) from *out_len by calling the function with str set to NULL. 🌸

EVP_PKEY_get_octet_string_param() — gets a key pkey's octet string value into a buffer buf of maximum size max_buf_sz, tied to a name of key_name. if out_len is not NULL, *out_len gets set to the length of the contents. and same trick: the required buffer size can be obtained from *out_len by calling the function with buf set to NULL. 🦋

🎀 NOTES 🎀

these functions only work for EVP_PKEYs that contain a provider side key. that's the whole requirement. iykyk.

⭐ RETURN VALUES ⭐

EVP_PKEY_gettable_params() returns NULL on error, or if it's just not supported. 💀

all the other methods return 1 if a value associated with the key's key_name was successfully returned, or 0 if there was an error. and to be clear — an error may be returned by EVP_PKEY_get_utf8_string_param() and EVP_PKEY_get_octet_string_param() if max_buf_sz isn't big enough to hold the value. if out_len is not NULL, then *out_len will be assigned the required buffer size to hold the value. so even the error is kinda telling you what you need. slay. 👑

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

🌈 SEE ALSO 🌈

🧚 HISTORY 🧚

these functions were added in OpenSSL 3.0. periodt.

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 get those params 💖✨ this was version 4.0.3, dated 2026-09-29, and it's the EVP_PKEY_GETTABLE_PARAMS(3SSL) page from OpenSSL. mwah, take care of your keys 🫶🎀

📦 where this page comes from