-rw-r--r-- 5232 libmceliece-20240513/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)