---
name: "mceliece"
section: "3"
platform: "linux"
package: "libmceliece-dev"
version: "0~20241009-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mceliece/3"
---

# mceliece(3)

### NAME

mceliece - C API for the libmceliece implementation of the Classic McEliece cryptosystem

### SYNOPSIS

Using libmceliece:

-

  ```
  #include <mceliece.h>
  ```

Link with -lmceliece.

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

libmceliece is an implementation of the Classic McEliece (https://classic.mceliece.org) cryptosystem. The C API for libmceliece provides the following 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
  ```

All of these functions follow the SUPERCOP API for KEMs (https://bench.cr.yp.to/call-kem.html) except that

- •

  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.

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\] and Alice’s corresponding public key pk\[0\], pk\[1\], ..., pk\[mceliece6960119\_PUBLICKEYBYTES-1\].

### 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\]. This function then returns 0.

Exception: 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.

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.

### 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. This function then returns 0.

Exception: 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.

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 provide faster key generation. 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. The secret-key sizes (and formats) are the same, the enc functions are the same, and the dec functions are the same.

### SEE ALSO

[**mceliece**(1)](/mceliece/1.md), [**randombytes**(3)](/randombytes/3.md)