ES384_PK_NEW(3)

💖 ES384_PK_NEW — bestie edition 💖

okay so this is the manual for es384_pk_new(3) and friends, living happily in the Library Functions Manual section. it's the FIDO2 COSE ES384 API and it's literally just a little squad of functions that help you move ECDSA public keys between libfido2 and OpenSSL. no cap. 🎀

✨ NAME ✨

es384_pk_new, es384_pk_free, es384_pk_from_EC_KEY, es384_pk_from_EVP_PKEY, es384_pk_from_ptr, es384_pk_to_EVP_PKEY — the FIDO2 COSE ES384 API 🦋

🌸 SYNOPSIS 🌸

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

es384_pk_t *
es384_pk_new(void);

void
es384_pk_free(es384_pk_t **pkp);

int
es384_pk_from_EC_KEY(es384_pk_t *pk, const EC_KEY *ec);

int
es384_pk_from_EVP_PKEY(es384_pk_t *pk, const EVP_PKEY *pkey);

int
es384_pk_from_ptr(es384_pk_t *pk, const void *ptr, size_t len);

EVP_PKEY *
es384_pk_to_EVP_PKEY(const es384_pk_t *pk);

👑 DESCRIPTION 👑

so ES384 is the name the CBOR Object Signing and Encryption (COSE) RFC gave to ECDSA over P-384 with SHA-384. and the COSE ES384 API in libfido2? it's an auxiliary API — a lil sidekick — with routines that convert between the different ECDSA public key types floating around in libfido2 and OpenSSL. it's giving translator energy fr fr. 🫶

in libfido2, ES384 public keys are abstracted by the es384_pk_t type. that's the moment. 💅

• es384_pk_new() — hands you back a pointer to a freshly allocated, empty es384_pk_t. if memory can't be allocated, you get NULL back. sad but true. 😭
• es384_pk_free() — releases the memory backing *pkp, and bestie, *pkp must have been previously allocated by es384_pk_new(). on return, *pkp is set to NULL. and here's the chill part: either pkp or *pkp may be NULL, and in that case es384_pk_free() is a NOP. no drama, no crash. ✨
• es384_pk_from_EC_KEY() — fills pk with the contents of ec. no references to ec are kept — it's a copy situation, not a situationship. 🙈
• es384_pk_from_EVP_PKEY() — fills pk with the contents of pkey. again, no references to pkey are kept. 🦋
• es384_pk_from_ptr() — fills pk with the contents of ptr, where ptr points to len bytes. and ptr can point to either an uncompressed point or the concatenation of the x and y coordinates — both are valid, she contains multitudes. no references to ptr are kept. 🌸
• es384_pk_to_EVP_PKEY() — converts pk into a newly allocated EVP_PKEY type with a reference count of 1. no internal references to the returned pointer are kept. and if something goes wrong? it returns NULL. 💀

🌈 RETURN VALUES 🌈

es384_pk_from_EC_KEY(), es384_pk_from_EVP_PKEY(), and es384_pk_from_ptr() all return FIDO_OK when they succeed. when they don't, you get a different error code defined over in <fido/err.h>. check it, bestie, it'll tell you what went down. 👑

lowkey important: FIDO_OK is the only happy answer here — anything else means something went sideways.

🎀 SEE ALSO 🎀

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

go read those too, they're the rest of the friend group. 🫶

and that's the whole page, bestie!! this one shipped from Debian and it's dated July 15, 2022 — iconic vintage behavior honestly. now go forth and convert those keys. slay. 💅✨💖