EC_KEY_NEW(3)

🦋 EC_KEY_NEW(3) — the EC_KEY glow-up guide 🦋

okay so this is from the Library Functions Manual, and bestie, it's literally the whole encyclopedia of making, duplicating, and yeeting EC_KEY objects. sit down, hydrate, let's go 💅

---

✨ NAME ✨

EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, EC_KEY_print, EC_KEY_print_fp — create, destroy and manipulate EC_KEY objects 🎀

like… that's the whole squad. all of them. no one's left out.

---

🧚 SYNOPSIS 🧚

first you gotta pull in the headers, obviously:

#include <openssl/ec.h>
#include <openssl/bn.h>

and here's every single signature, character for character, because we do not paraphrase signatures in this house 💖

EC_KEY *
EC_KEY_new(void);

int
EC_KEY_get_flags(const EC_KEY *key);

void
EC_KEY_set_flags(EC_KEY *key, int flags);

void
EC_KEY_clear_flags(EC_KEY *key, int flags);

EC_KEY *
EC_KEY_new_by_curve_name(int nid);

void
EC_KEY_free(EC_KEY *key);

EC_KEY *
EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);

EC_KEY *
EC_KEY_dup(const EC_KEY *src);

int
EC_KEY_up_ref(EC_KEY *key);

const EC_GROUP *
EC_KEY_get0_group(const EC_KEY *key);

int
EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);

const BIGNUM *
EC_KEY_get0_private_key(const EC_KEY *key);

int
EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);

const EC_POINT *
EC_KEY_get0_public_key(const EC_KEY *key);

int
EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);

unsigned int
EC_KEY_get_enc_flags(const EC_KEY *key);

void
EC_KEY_set_enc_flags(EC_KEY *key, unsigned int flags);

point_conversion_form_t
EC_KEY_get_conv_form(const EC_KEY *key);

void
EC_KEY_set_conv_form(EC_KEY *key, point_conversion_form_t cform);

void
EC_KEY_set_asn1_flag(EC_KEY *key, int asn1_flag);

int
EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);

int
EC_KEY_generate_key(EC_KEY *key);

int
EC_KEY_check_key(const EC_KEY *key);

int
EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x,
    BIGNUM *y);

int
EC_KEY_print(BIO *bp, const EC_KEY *key, int off);

int
EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off);

---

🌸 DESCRIPTION 🌸

so. an EC_KEY is literally a public key plus, like, optionally its private key bestie. the public key is a point on a curve, represented by an EC_POINT (go read EC_POINT_new(3) if you want the lore 🦋). the private key is just a BIGNUM, see BN_new(3).

you can make a brand new EC_KEY with no curve attached by calling EC_KEY_new(). the reference count on the fresh baby object starts at 1. then you attach a curve to it with EC_KEY_set_group().

or!! you can skip that whole two-step and just call EC_KEY_new_by_curve_name() with the nid of the curve you want. curve names are described over in EC_GROUP_new(3). literally all this function does is wrap calls to EC_KEY_new() and EC_GROUP_new_by_curve_name(). it's giving delegation. iconic.

EC_KEY_free() decrements the reference count and — only if it dropped all the way to zero — frees the memory. and if key is a NULL pointer? nothing happens. no drama. 🫶

EC_KEY_copy() copies the contents of the EC_KEY in src into dst.

EC_KEY_dup() makes a whole new EC_KEY object and copies src into it. new phone, who dis.

EC_KEY_up_ref() bumps the reference count on the EC_KEY object. keep it alive, queen 👑

EC_KEY_generate_key() generates a shiny new public and private key for the key object you hand it. heads up though — key must already have an EC_GROUP object associated with it before you call this. no group, no key, that's the vibe check. the private key is a random integer where 0 < priv_key < order, and order is the order of the EC_GROUP object. the public key is an EC_POINT on the curve, calculated by multiplying the generator for the curve by the private key. math ate, honestly 🔥

EC_KEY_check_key() runs a bunch of sanity checks on the EC_KEY object to confirm it's actually valid and not, like, a mess.

EC_KEY_set_public_key_affine_coordinates() sets the public key for key based on its affine coordinates — meaning it builds an EC_POINT object out of the x and y values you give it, and sets the public key to be that EC_POINT. it also does some sanity checks on the key to confirm it's valid. double duty 💅

okay so this next crew: EC_KEY_get0_group(), EC_KEY_set_group(), EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key, and the EC_POINT public key for the key, respectively. important 🚨 — the setters copy the group and key objects without sanity checks, and it is the caller's responsibility to make sure the resulting key is valid, for example using EC_KEY_check_key(). so like… you're the main character here, you gotta do the checking yourself.

EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the encoding flags for the key. there are two encoding flags currently defined:

• EC_PKEY_NO_PARAMETERS
• EC_PKEY_NO_PUBKEY

these flags define the behaviour of how the key is converted into ASN.1 in a call to i2d_ECPrivateKey(). if EC_PKEY_NO_PARAMETERS is set, then the public parameters for the curve are not encoded along with the private key. if EC_PKEY_NO_PUBKEY is set, then the public key is not encoded along with the private key. choose your fighter 🎀

the format of the external representation of the public key written by i2d_ECPrivateKey(3) — like whether it's stored in a compressed form or not — is described by the point_conversion_form. EC_GROUP_copy(3) has the full description of point_conversion_form if you want the deep dive.

when you're reading a private key that was encoded without an associated public key — for example if EC_PKEY_NO_PUBKEY was used — d2i_ECPrivateKey(3) generates the missing public key automatically. but private keys encoded without parameters, for example if EC_PKEY_NO_PARAMETERS was used, cannot be loaded using d2i_ECPrivateKey(3). that's a hard no, bestie 😭

EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the point_conversion_form for the key. for a description of point_conversion_form, refer to EC_GROUP_copy(3).

EC_KEY_set_flags() sets the flags in the flags parameter on the EC_KEY object. any flags already set are left set — nothing gets unset, we respect the existing commitments. the currently defined standard flags are:

• EC_FLAG_NON_FIPS_ALLOW
• EC_FLAG_FIPS_CHECKED

and in addition there's the ECDH-specific flag:

• EC_FLAG_COFACTOR_ECDH

EC_KEY_get_flags() returns the current flags set for this EC_KEY. EC_KEY_clear_flags() clears the flags indicated by the flags parameter, and all the other flags are left in their existing state. only the named ones get cleared. ✨

EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object (if set). EC_GROUP_copy(3) has more info on the asn1_flag.

EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator so point multiplication goes faster later. see also EC_POINT_add(3). it's giving prepping ahead of time, we love a planner 🍓

EC_KEY_print() and EC_KEY_print_fp() print out the content of key to the BIO bp or to the FILE pointer fp, respectively. each line is indented by indent spaces. (the parameter's called off in the signature, but the description calls it indent spaces — just sayin', that's what it says 💀)

---

👑 RETURN VALUES 👑

EC_KEY_new(), EC_KEY_new_by_curve_name(), and EC_KEY_dup() return a pointer to the newly created EC_KEY object, or NULL on error.

EC_KEY_get_flags() returns the flags associated with the EC_KEY object.

EC_KEY_copy() returns a pointer to the destination key, or NULL on error. and in that error case? part of the content may already have been copied. so, like, it's not a clean nothing-happened situation, be aware 🙈

EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_private_key(), EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(), EC_KEY_print(), and EC_KEY_print_fp() return 1 on success or 0 on error.

EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY.

EC_KEY_get0_private_key() and EC_KEY_get0_public_key() return the private or public keys, respectively, associated with the EC_KEY.

EC_KEY_get_enc_flags() returns the value of the current encoding flags for the EC_KEY.

EC_KEY_get_conv_form() returns the point_conversion_form for the EC_KEY.

---

🎀 SEE ALSO 🎀

literally the whole friend group:

d2i_ECPKParameters(3), EC_GROUP_copy(3), EC_GROUP_new(3), EC_KEY_METHOD_new(3), EC_POINT_add(3), EC_POINT_new(3), ECDH_compute_key(3), ECDSA_SIG_new(3), EVP_PKEY_set1_EC_KEY(3)

---

🌈 HISTORY 🌈

EC_KEY_new(), EC_KEY_new_by_curve_name(), EC_KEY_free(), EC_KEY_copy(), EC_KEY_dup(), EC_KEY_up_ref(), EC_KEY_get0_group(), EC_KEY_set_group(), EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), EC_KEY_set_public_key(), EC_KEY_get_enc_flags(), EC_KEY_set_enc_flags(), EC_KEY_get_conv_form(), EC_KEY_set_conv_form(), EC_KEY_set_asn1_flag(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), EC_KEY_check_key(), EC_KEY_print(), and EC_KEY_print_fp() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5. veterans, honestly.

EC_KEY_get_flags(), EC_KEY_set_flags(), EC_KEY_clear_flags(), and EC_KEY_set_public_key_affine_coordinates() first appeared in OpenSSL 1.0.1 and have been available since OpenBSD 5.3. the late bloomers, still iconic 💜

---

ngl that's a lot of setters that don't validate for you. EC_KEY_check_key() is your bestie for a reason — use it.

okay that's the whole page, no cap 💖 this came from the Debian build, dated March 8, 2025 — mwah, go forth and key responsibly 🌸