EC_KEY_NEW(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💖 EC_KEY_NEW(3) 💖

okay so bestie, welcome to the <openssl/ec.h> corner of libcrypto — this is the manual page for create, destroy and manipulate EC_KEY objects. yes that's the whole NAME section, we're moving fast 💅

✨ SYNOPSIS ✨

library “libcrypto” #include <openssl/ec.h>
#include <openssl/bn.h>

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

look at that list. it's giving ✨full cast of characters✨. every single one is getting screen time, no skips, periodt.

🌸 DESCRIPTION 🌸

An EC_KEY is literally the moment where a public key and (optionally!) an associated private key live together. the public key is a point on a curve, and that point is represented by an EC_POINT — peek EC_POINT_new(3). the private key? oh she's simple. she's just a BIGNUM. see BN_new(3). iykyk 💜

🎀 making and breaking keys

A fresh new EC_KEY (with no associated curve, don't come for her) gets constructed by calling EC_KEY_new(). her reference count starts at 1, main character energy from day one. if you want a curve attached to your EC_KEY, that's a EC_KEY_set_group() situation.

Alternatively you can build a new EC_KEY by calling EC_KEY_new_by_curve_name() and handing over the nid of the curve you want. curve names are described over in EC_GROUP_new_by_curve_name(3). this function is lowkey just wrapping calls to EC_KEY_new() and EC_GROUP_new_by_curve_name() — she's a cute little combo meal 🍓

Calling EC_KEY_free() decrements the reference count for the EC_KEY object, and if it has dropped to zero, then it frees the memory associated with it. if key is a NULL pointer, no action occurs. nothing happens. she said not today 🙈

🦋 copying and refcounting

  • EC_KEY_copy() copies the contents of the EC_KEY in src into dst.
  • EC_KEY_dup() creates a new EC_KEY object and copies src into it.
  • EC_KEY_up_ref() increments the reference count associated with the EC_KEY object. tiny bump, big commitment 🫶

🔥 generating and checking

EC_KEY_generate_key() generates a new public and private key for the supplied key object. heads up: key must have an EC_GROUP object associated with it before you call this function, no group no key, rules are rules. the private key is a random integer (0 < priv_key < order, where 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 slay ✨

EC_KEY_check_key() performs various sanity checks on the EC_KEY object to confirm that it is valid. vibe check, but for keys 💀

EC_KEY_set_public_key_affine_coordinates() sets the public key for key based on its affine coordinates — so it constructs an EC_POINT object based on the supplied x and y values and sets the public key to be this EC_POINT. it also performs certain sanity checks on the key to confirm that it is valid. two jobs, one function, she's thriving 👑

💜 getters and setters

The functions 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.

⚠️ okay listen — the setters copy the group and key objects without sanity checks, and it is the caller's responsibility to ensure that the resulting key is valid, for example using EC_KEY_check_key(). no cap, she will not catch your mistakes for you.

🌈 encoding flags

The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the value of the encoding flags for the key. there are two encoding flags currently defined: EC_PKEY_NO_PARAMETERS and 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.

The format of the external representation of the public key written by i2d_ECPrivateKey(3), such as whether it is stored in a compressed form or not, is described by the point_conversion_form. see EC_POINT_point2oct(3) for a description of point_conversion_form. 🎀

When reading a private key encoded without an associated public key, for example if EC_PKEY_NO_PUBKEY was used, d2i_ECPrivateKey(3) generates the missing public key automatically. she's resourceful like that. BUT private keys encoded without parameters, for example if EC_PKEY_NO_PARAMETERS was used, cannot be loaded using d2i_ECPrivateKey(3). not happening, not ever 😭

The functions 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_POINT_point2oct(3).

🧚 flags, asn1, precompute, printing

EC_KEY_set_flags() sets the flags in the flags parameter on the EC_KEY object. any flags that are already set are left set — nobody gets unset on her watch. the currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. in addition there is the ECDH-specific flag EC_FLAG_COFACTOR_ECDH.

EC_KEY_get_flags() returns the current flags that are set for this EC_KEY.

EC_KEY_clear_flags() clears the flags indicated by the flags parameter. all other flags are left in their existing state. selective clearing, we love a boundaries queen ✨

EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object (if set). refer to EC_GROUP_get_curve_name(3) for further information on the asn1_flag.

EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator for faster point multiplication. see also EC_POINT_add(3). it's giving preparation meets opportunity 🔥

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. cute formatting, she cares about aesthetics 💅

⭐ 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. in the latter case, part of the content may already have been copied — so like, don't assume you're squeaky clean 😭
  • 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 🦋

d2i_ECPKParameters(3), EC_GROUP_check(3), EC_GROUP_get_curve_name(3), EC_GROUP_new_by_curve_name(3), EC_GROUP_new_curve_GFp(3), EC_KEY_METHOD_new(3), EC_POINT_add(3), EC_POINT_get_affine_coordinates(3), EC_POINT_point2oct(3), ECDH_compute_key(3), ECDSA_SIG_new(3), EVP_PKEY_set1_EC_KEY(3)

go read them. all of them. the whole friend group 🫶

👑 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 later arrivals, still iconic 🌟

and that's the page, bestie!! this one came from Debian, dated June 8, 2025, and yes the file itself is EC_KEY_NEW(3) — go forth and manage your elliptic curve keys responsibly, mwah 💖🎀✨

📦 where this page comes from