ES256_PK_NEW(3)

💖 ES256_PK_NEW 💖

okay bestie, welcome to section 3 of the manual — Library Functions Manual energy — and today we're talking about ES256_PK_NEW(3). yes this is a whole family of functions under one page name, it's giving ensemble cast 🫶

✨ NAME ✨

es256_pk_new, es256_pk_free, es256_pk_from_EC_KEY, es256_pk_from_EVP_PKEY, es256_pk_from_ptr, es256_pk_to_EVP_PKEY — the FIDO2 COSE ES256 API, no cap 💅

🌸 SYNOPSIS 🌸

#include <openssl/ec.h>
#include <fido/es256.h>

es256_pk_t *
es256_pk_new(void);

void
es256_pk_free(es256_pk_t **pkp);

int
es256_pk_from_EC_KEY(es256_pk_t *pk, const EC_KEY *ec);

int
es256_pk_from_EVP_PKEY(es256_pk_t *pk, const EVP_PKEY *pkey);

int
es256_pk_from_ptr(es256_pk_t *pk, const void *ptr, size_t len);

EVP_PKEY *
es256_pk_to_EVP_PKEY(const es256_pk_t *pk);

🦋 DESCRIPTION 🦋

so ES256 is literally the name the CBOR Object Signing and Encryption (COSE) RFC gave to ECDSA over P-256 with SHA-256. periodt. and the COSE ES256 API in libfido2 is this lil auxiliary API — a side-quest, if you will — with routines that convert between the different ECDSA public key types floating around in libfido2 and OpenSSL. it's the translator bestie of the group chat 🔥

in libfido2, ES256 public keys are abstracted by the es256_pk_t type. that's the moment, that's the icon, that's the main character 👑

es256_pk_new() — returns a pointer to a newly allocated, empty es256_pk_t type. if memory cannot be allocated, NULL is returned. that's it, that's the whole vibe ✨

es256_pk_free() — releases the memory backing *pkp, where *pkp must have been previously allocated by es256_pk_new(). on return, *pkp is set to NULL. and here's the cute part: either pkp or *pkp may be NULL, in which case es256_pk_free() is a NOP. it's just chill like that 🙈

es256_pk_from_EC_KEY() — fills pk with the contents of ec. no references to ec are kept. nope, none, zero, ghosted 🍓

es256_pk_from_EVP_PKEY() — fills pk with the contents of pkey. no references to pkey are kept either. we copy and we move on 💅

es256_pk_from_ptr() — fills pk with the contents of ptr, where ptr points to len bytes. now ptr may point to an uncompressed point, or to the concatenation of the x and y coordinates — dealer's choice, both slay. no references to ptr are kept.

es256_pk_to_EVP_PKEY() — converts pk to a newly allocated EVP_PKEY type with a reference count of 1. no internal references to the returned pointer are kept. if an error occurs, es256_pk_to_EVP_PKEY() returns NULL. 😭

⭐ RETURN VALUES ⭐

es256_pk_from_EC_KEY(), es256_pk_from_EVP_PKEY(), and es256_pk_from_ptr() return FIDO_OK on success. 🎉 on error, a different error code defined in <fido/err.h> is returned. so like, check your codes bestie, don't just assume 💀

🌈 SEE ALSO 🌈

• eddsa_pk_new(3)
• es384_pk_new(3)
• fido_assert_verify(3)
• fido_cred_pubkey_ptr(3)
• rs256_pk_new(3)

and that's the whole page, you ate it, i'm obsessed 🎀 this one came from the Debian crew and it's dated July 15, 2022 — so it's vintage, it's iconic, it's the moment. go forth and convert those keys, bestie 💜🧚