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.