-rw-r--r-- 5232 libmceliece-20240812/doc/man/mceliece.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "mceliece" "3" "" "" ""
.hy
.SS NAME
.PP
mceliece - C API for the libmceliece implementation of the Classic
McEliece cryptosystem
.SS SYNOPSIS
.PP
Using libmceliece:
.IP
.nf
\f[C]
#include <mceliece.h>
\f[R]
.fi
.PP
Link with \f[V]-lmceliece\f[R].
.PP
Key generation (for, e.g., \f[V]mceliece6960119\f[R]):
.IP
.nf
\f[C]
unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
unsigned char sk[mceliece6960119_SECRETKEYBYTES];

mceliece6960119_keypair(pk,sk);
\f[R]
.fi
.PP
Encapsulation (for, e.g., \f[V]mceliece6960119\f[R]):
.IP
.nf
\f[C]
unsigned char ct[mceliece6960119_CIPHERTEXTBYTES];
unsigned char k[mceliece6960119_BYTES];
const unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
int ret;

ret = mceliece6960119_enc(ct,k,pk);
\f[R]
.fi
.PP
Decapsulation (for, e.g., \f[V]mceliece6960119\f[R]):
.IP
.nf
\f[C]
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);
\f[R]
.fi
.SS DESCRIPTION
.PP
libmceliece is an implementation of the Classic
McEliece (https://classic.mceliece.org) cryptosystem.
The C API for libmceliece provides the following functions:
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
All of these functions follow the SUPERCOP API for
KEMs (https://bench.cr.yp.to/call-kem.html) except that
.IP \[bu] 2
the function names are libmceliece-specific instead of
\f[V]crypto_kem_*\f[R],
.IP \[bu] 2
message lengths are \f[V]long long\f[R] instead of
\f[V]unsigned long long\f[R], and
.IP \[bu] 2
the \f[V]keypair\f[R] functions return \f[V]void\f[R] instead of
\f[V]int\f[R].
.PP
The details below use \f[V]mceliece6960119\f[R] as an example.
.SS KEY GENERATION
.PP
The \f[V]mceliece6960119_keypair\f[R] function randomly generates
Alice\[cq]s secret key \f[V]sk[0]\f[R], \f[V]sk[1]\f[R], \&...,
\f[V]sk[mceliece6960119_SECRETKEYBYTES-1]\f[R] and Alice\[cq]s
corresponding public key \f[V]pk[0]\f[R], \f[V]pk[1]\f[R], \&...,
\f[V]pk[mceliece6960119_PUBLICKEYBYTES-1]\f[R].
.SS ENCAPSULATION
.PP
The \f[V]mceliece6960119_enc\f[R] function randomly generates a
ciphertext \f[V]ct[0]\f[R], \f[V]ct[1]\f[R], \&...,
\f[V]ct[mceliece6960119_CIPHERTEXTBYTES-1]\f[R] and the corresponding
session key \f[V]k[0]\f[R], \f[V]k[1]\f[R], \&...,
\f[V]k[mceliece6960119_BYTES-1]\f[R] given Alice\[cq]s public key
\f[V]pk[0]\f[R], \f[V]pk[1]\f[R], \&...,
\f[V]pk[mceliece6960119_PUBLICKEYBYTES-1]\f[R].
This function then returns \f[V]0\f[R].
.PP
Exception: If the input public key is not \[lq]narrowly decodable\[rq]
(i.e., if bits at particular positions in \f[V]pk\f[R] are set), this
function returns \f[V]-1\f[R].
Currently the function also handles such public keys by clearing
\f[V]ct\f[R] and \f[V]k\f[R], but callers should not rely on this.
.PP
For \f[V]{6688128,8192128,460896,348864}{,f}\f[R], all byte strings of
the correct length are narrowly decodable, and the return value is
always \f[V]0\f[R].
For \f[V]6960119{,f}\f[R], the return value can be \f[V]-1\f[R].
.SS DECAPSULATION
.PP
The \f[V]mceliece6960119_dec\f[R] function, given Alice\[cq]s secret key
\f[V]sk[0]\f[R], \f[V]sk[1]\f[R], \&...,
\f[V]sk[mceliece6960119_SECRETKEYBYTES-1]\f[R], computes the session key
\f[V]k[0]\f[R], \f[V]k[1]\f[R], \&...,
\f[V]k[mceliece6960119_BYTES-1]\f[R] corresponding to a ciphertext
\f[V]ct[0]\f[R], \f[V]ct[1]\f[R], \&...,
\f[V]ct[mceliece6960119_CIPHERTEXTBYTES-1]\f[R] that was encapsulated to
Alice.
This function then returns \f[V]0\f[R].
.PP
Exception: If the input ciphertext is not \[lq]narrowly decodable\[rq]
(i.e., if bits at particular positions in \f[V]ct\f[R] are set), this
function returns \f[V]-1\f[R].
Currently this function also handles such ciphertexts by setting all
bytes of \f[V]k\f[R] to \f[V]255\f[R], but callers should not rely on
this.
.PP
For \f[V]{6688128,8192128,460896,348864}{,f}\f[R], all byte strings of
the correct length are narrowly decodable, and the return value is
always \f[V]0\f[R].
For \f[V]6960119{,f}\f[R], the return value can be \f[V]-1\f[R].
.SS THE f VARIANTS
.PP
The \f[V]f\f[R] variants are internally more complicated than the
non-\f[V]f\f[R] variants but provide faster key generation.
The \f[V]f\f[R] variants are interoperable with the non-\f[V]f\f[R]
variants: for example, a key generated with
\f[V]mceliece6960119f_keypair\f[R] can decapsulate ciphertexts that were
encapsulated with \f[V]mceliece6960119_enc\f[R].
The secret-key sizes (and formats) are the same, the \f[V]enc\f[R]
functions are the same, and the \f[V]dec\f[R] functions are the same.
.SS SEE ALSO
.PP
\f[B]mceliece\f[R](1), \f[B]randombytes\f[R](3)