RS256_PK_NEW(3)

💖 RS256_PK_NEW 💖

okay bestie, gather round, because we're about to talk about rs256_pk_new(3) — that's the manual page name, and the manual itself is the Library Functions Manual. yes it's giving "niche cryptography" but trust me, it's lowkey iconic once you get it. 🎀

✨ NAME ✨

rs256_pk_new, rs256_pk_free, rs256_pk_from_RSA, rs256_pk_from_EVP_PKEY, rs256_pk_from_ptr, rs256_pk_to_EVP_PKEY — the FIDO2 COSE RS256 API, aka your little conversion station between RSA public key types 🦋

🌸 SYNOPSIS 🌸

#include <openssl/rsa.h>
#include <fido/rs256.h>

rs256_pk_t *
rs256_pk_new(void);

void
rs256_pk_free(rs256_pk_t **pkp);

int
rs256_pk_from_EVP_PKEY(rs256_pk_t *pk, const EVP_PKEY *pkey);

int
rs256_pk_from_RSA(rs256_pk_t *pk, const RSA *rsa);

int
rs256_pk_from_ptr(rs256_pk_t *pk, const void *ptr, size_t len);

EVP_PKEY *
rs256_pk_to_EVP_PKEY(const rs256_pk_t *pk);

no cap, that's the whole lineup 💅

💜 DESCRIPTION 💜

okay so first things first: RS256 is the name that the CBOR Object Signing and Encryption (COSE) RFC gives to PKCS#1.5 2048-bit RSA with SHA-256. yes, that's a mouthful, and yes, it ate. 🔥

The COSE RS256 API of libfido2 is an auxiliary API — think of it as the little side quest with routines that convert between the different RSA public key types used in libfido2 and OpenSSL. it's giving "translator friend who speaks both languages." 🌈

In libfido2, RS256 public keys are abstracted by the rs256_pk_t type. that's the main character of this whole page, periodt. 👑

• rs256_pk_new() — returns a pointer to a newly allocated, empty rs256_pk_t type. if memory cannot be allocated, NULL is returned. (sad girl moment, but that's the deal.) 😭
• rs256_pk_free() — releases the memory backing *pkp, where *pkp must have been previously allocated by rs256_pk_new(). on return, *pkp is set to NULL. either pkp or *pkp may be NULL, and in that case rs256_pk_free() is a NOP. so it just... does nothing. chillest function ever. 🧚
• rs256_pk_from_EVP_PKEY() — fills pk with the contents of pkey. no references to pkey are kept. 🫶
• rs256_pk_from_RSA() — fills pk with the contents of rsa. no references to rsa are kept. ✨
• rs256_pk_from_ptr() — fills pk with the contents of ptr, where ptr points to len bytes. no references to ptr are kept. 🌸
• rs256_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, rs256_pk_to_EVP_PKEY() returns NULL. 💀

heads up bestie: all those "no references are kept" lines are real and they matter — the API is not holding onto your stuff for you. 🔍

⭐ RETURN VALUES ⭐

The rs256_pk_from_EVP_PKEY(), rs256_pk_from_RSA(), and rs256_pk_from_ptr() functions return FIDO_OK on success. slay. ✅

On error, a different error code defined in <fido/err.h> is returned. so if it's not FIDO_OK, go check that header, because the tea is in there. 🍓

🦋 SEE ALSO 🦋

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

go read the whole friend group, they're all connected, iykyk 💫

Debian 🎀 July 15, 2022 — that's the source, the version vibe, and the date, all wrapped up like a little gift. mwah, that's the whole page bestie, you understood it perfectly, no cap. 💖✨🦋