mceliece(3)

✨ NAME ✨

mceliece — the C API for libmceliece, bestie, aka the implementation of the Classic McEliece cryptosystem 👑

This is the mceliece(3) page, from the Library Functions Manual, and it's genuinely so good.

---

🫶 SYNOPSIS 🫶

Okay so first: you're using libmceliece:

#include <mceliece.h>

And you link with -lmceliece. That's the whole vibe check 💅

Key generation (for, e.g., mceliece6960119):

unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
unsigned char sk[mceliece6960119_SECRETKEYBYTES];

mceliece6960119_keypair(pk,sk);

Encapsulation (for, e.g., mceliece6960119):

unsigned char ct[mceliece6960119_CIPHERTEXTBYTES];
unsigned char k[mceliece6960119_BYTES];
const unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
int ret;

ret = mceliece6960119_enc(ct,k,pk);

Decapsulation (for, e.g., mceliece6960119):

unsigned char k[mceliece6960119_BYTES];
const unsigned char ct[mceliece6960119_CIPHERTEXTBYTES];
const unsigned char sk[mceliece6960119_SECRETKEYBYTES];
int ret;

ret = mceliece6960119_dec(k,ct,sk);

---

🌸 DESCRIPTION 🌸

So libmceliece is an implementation of the Classic McEliece cryptosystem. Periodt. And the C API for libmceliece serves up these functions:

mceliece{6960119,6688128,8192128,460896,348864}_keypair
mceliece{6960119,6688128,8192128,460896,348864}_enc
mceliece{6960119,6688128,8192128,460896,348864}_dec
mceliece{6960119,6688128,8192128,460896,348864}f_keypair
mceliece{6960119,6688128,8192128,460896,348864}f_enc
mceliece{6960119,6688128,8192128,460896,348864}f_dec

Every single one of these follows the SUPERCOP API for KEMs, with exactly three little exceptions, and I need you to clock them:

• the function names are libmceliece-specific instead of crypto_kem_*,
• message lengths are long long instead of unsigned long long, and
• the keypair functions return void instead of int.

And just so we're clear on the cast: all the details below use mceliece6960119 as an example 🌟

---

🔑 KEY GENERATION 🔑

The mceliece6960119_keypair function randomly generates Alice's secret key sk[0], sk[1], ..., sk[mceliece6960119_SECRETKEYBYTES-1], plus Alice's corresponding public key pk[0], pk[1], ..., pk[mceliece6960119_PUBLICKEYBYTES-1]. Random. Fresh. Hers 🎀

---

📦 ENCAPSULATION 📦

The mceliece6960119_enc function randomly generates a ciphertext ct[0], ct[1], ..., ct[mceliece6960119_CIPHERTEXTBYTES-1] and the corresponding session key k[0], k[1], ..., k[mceliece6960119_BYTES-1], given Alice's public key pk[0], pk[1], ..., pk[mceliece6960119_PUBLICKEYBYTES-1]. Then this function returns 0. Slay.

Exception, and listen closely: if the input public key is not "narrowly decodable" (i.e., if bits at particular positions in pk are set), this function returns -1. Currently the function also handles such public keys by clearing ct and k, but callers should not rely on this. Do not build your whole personality on that behaviour, fr fr 😭

For {6688128,8192128,460896,348864}{,f}, all byte strings of the correct length are narrowly decodable, and the return value is always 0. For 6960119{,f}, the return value can be -1. That's the whole tea ☕

---

🔓 DECAPSULATION 🔓

The mceliece6960119_dec function, given Alice's secret key sk[0], sk[1], ..., sk[mceliece6960119_SECRETKEYBYTES-1], computes the session key k[0], k[1], ..., k[mceliece6960119_BYTES-1] corresponding to a ciphertext ct[0], ct[1], ..., ct[mceliece6960119_CIPHERTEXTBYTES-1] that was encapsulated to Alice. Then this function returns 0. Iconic behaviour 💖

Exception again, bestie: if the input ciphertext is not "narrowly decodable" (i.e., if bits at particular positions in ct are set), this function returns -1. Currently this function also handles such ciphertexts by setting all bytes of k to 255, but callers should not rely on this. Ngl, do not depend on it 🙈

For {6688128,8192128,460896,348864}{,f}, all byte strings of the correct length are narrowly decodable, and the return value is always 0. For 6960119{,f}, the return value can be -1.

---

🦋 THE f VARIANTS 🦋

The f variants are internally more complicated than the non-f variants, but they provide faster key generation. Main character energy, honestly 👑

And here's the part everyone asks about: the f variants are interoperable with the non-f variants ✨ For example, a key generated with mceliece6960119f_keypair can decapsulate ciphertexts that were encapsulated with mceliece6960119_enc. They just get each other.

The secret-key sizes (and formats) are the same, the enc functions are the same, and the dec functions are the same. Matching, no cap 💜

---

👀 SEE ALSO 👀

• mceliece(1)
• randombytes(3)

---

Go read those too, iykyk 💅

That's the whole page. This one signs off as mceliece(3) — the section-3 library functions manual — and honestly? She ate. 🌈⭐🍓