libmceliece: API

### 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 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 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), randombytes(3)

Version: This is version 2024.05.02 of the "API" web page.