-r--r--r-- 8870 libmceliece-20240726/doc/html/api.html raw
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style type="text/css">
html{overflow-y:scroll}
body{font-family:"Noto Sans","Droid Sans","DejaVu Sans","Arial",sans-serif;line-height:1.5}
tt,code{background-color:#f0f0f0;font-family:"Noto Sans Mono","Droid Sans Mono","DejaVu Sans Mono","Courier New",monospace,sans-serif;font-size:1em;}
pre{margin-left:3em}
p,ul,ol,blockquote,pre{font-size:1.0em;line-height:1.6}
li p{font-size:1.0em}
blockquote p{font-size:1.0em}
h1{font-size:1.5em}
h2{font-size:1.3em}
h3{font-size:1.0em}
h1 a{text-decoration:none}
table{border-collapse:collapse}
th,td{border:1px solid black}
table a{text-decoration:none}
table tr{font-size:1.0em;line-height:1.6em}
table tr{font-size:1.0em;line-height:1.5}
tbody tr:nth-child(20n+1){background-color:#f0ffff}
tbody tr:nth-child(20n+2){background-color:#f0ffff}
tbody tr:nth-child(20n+3){background-color:#f0ffff}
tbody tr:nth-child(20n+4){background-color:#f0ffff}
tbody tr:nth-child(20n+5){background-color:#f0ffff}
tbody tr:nth-child(20n+6){background-color:#f0ffff}
tbody tr:nth-child(20n+7){background-color:#f0ffff}
tbody tr:nth-child(20n+8){background-color:#f0ffff}
tbody tr:nth-child(20n+9){background-color:#f0ffff}
tbody tr:nth-child(20n+10){background-color:#f0ffff}
tbody tr:nth-child(20n+11){background-color:#fffff0}
tbody tr:nth-child(20n+12){background-color:#fffff0}
tbody tr:nth-child(20n+13){background-color:#fffff0}
tbody tr:nth-child(20n+14){background-color:#fffff0}
tbody tr:nth-child(20n+15){background-color:#fffff0}
tbody tr:nth-child(20n+16){background-color:#fffff0}
tbody tr:nth-child(20n+17){background-color:#fffff0}
tbody tr:nth-child(20n+18){background-color:#fffff0}
tbody tr:nth-child(20n+19){background-color:#fffff0}
tbody tr:nth-child(20n+20){background-color:#fffff0}
.links a:hover{text-decoration:underline}
.links a:active{text-decoration:underline}
.links img{width:200px;padding-left:1em}
.links td{border:0px;padding-top:0.5em;padding-bottom:0.5em}
.headline{padding:0;font-weight:bold;font-size:1.5em;vertical-align:top;padding-bottom:0.5em;color:#196069}
.navt{display:inline-block;box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;
min-width:16%;margin:0;padding:0;padding-left:0.5em;padding-right:0.5em;vertical-align:center;
font-weight:bold;font-size:1.1em;text-align:center;border:1px solid black}
.here{border-bottom:0px;background-color:#ffffff}
.away{background-color:#196069;}
.away a{text-decoration:none;display:block;color:#ffffff}
.away a:hover,.away a:active{text-decoration:underline}
.main{margin:0;padding-top:0em;padding-bottom:1%;clear:both}
</style>
<title>
libmceliece: API</title>
</head>
<body>
<div class=headline>
libmceliece</div>
<div class=nav>
<div class="navt away"><a href=index.html>Intro</a>
</div><div class="navt away"><a href=download.html>Download</a>
</div><div class="navt away"><a href=install.html>Install</a>
</div><div class="navt away"><a href=test.html>Test</a>
</div><div class="navt here">API
</div><div class="navt away"><a href=cli.html>CLI</a>
</div><div class="navt away"><a href=security.html>Security</a>
</div><div class="navt away"><a href=verification.html>Verification</a>
</div><div class="navt away"><a href=speed.html>Speed</a>
</div><div class="navt away"><a href=internals.html>Internals</a>
</div><div class="navt away"><a href=people.html>People</a>
</div><div class="navt away"><a href=license.html>License</a>
</div></div>
<div class=main>
<h3>NAME</h3>
<p>mceliece - C API for the libmceliece implementation of the Classic McEliece cryptosystem</p>
<h3>SYNOPSIS</h3>
<p>Using libmceliece:</p>
<pre><code>#include <mceliece.h>
</code></pre>
<p>Link with <code>-lmceliece</code>.</p>
<p>Key generation (for, e.g., <code>mceliece6960119</code>):</p>
<pre><code>unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
unsigned char sk[mceliece6960119_SECRETKEYBYTES];
mceliece6960119_keypair(pk,sk);
</code></pre>
<p>Encapsulation (for, e.g., <code>mceliece6960119</code>):</p>
<pre><code>unsigned char ct[mceliece6960119_CIPHERTEXTBYTES];
unsigned char k[mceliece6960119_BYTES];
const unsigned char pk[mceliece6960119_PUBLICKEYBYTES];
int ret;
ret = mceliece6960119_enc(ct,k,pk);
</code></pre>
<p>Decapsulation (for, e.g., <code>mceliece6960119</code>):</p>
<pre><code>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);
</code></pre>
<h3>DESCRIPTION</h3>
<p>libmceliece is an implementation
of the <a href="https://classic.mceliece.org">Classic McEliece</a> cryptosystem.
The C API for libmceliece
provides the following functions:</p>
<pre><code>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
</code></pre>
<p>All of these functions follow the
<a href="https://bench.cr.yp.to/call-kem.html">SUPERCOP API for KEMs</a>
except that</p>
<ul>
<li>the function names are libmceliece-specific instead of <code>crypto_kem_*</code>,</li>
<li>message lengths are <code>long long</code> instead of <code>unsigned long long</code>, and</li>
<li>the <code>keypair</code> functions return <code>void</code> instead of <code>int</code>.</li>
</ul>
<p>The details below use <code>mceliece6960119</code> as an example.</p>
<h3>KEY GENERATION</h3>
<p>The <code>mceliece6960119_keypair</code> function randomly generates
Alice's secret key
<code>sk[0]</code>, <code>sk[1]</code>, ..., <code>sk[mceliece6960119_SECRETKEYBYTES-1]</code>
and
Alice's corresponding public key
<code>pk[0]</code>, <code>pk[1]</code>, ..., <code>pk[mceliece6960119_PUBLICKEYBYTES-1]</code>.</p>
<h3>ENCAPSULATION</h3>
<p>The <code>mceliece6960119_enc</code> function randomly generates
a ciphertext <code>ct[0]</code>, <code>ct[1]</code>, ..., <code>ct[mceliece6960119_CIPHERTEXTBYTES-1]</code>
and the corresponding session key
<code>k[0]</code>, <code>k[1]</code>, ..., <code>k[mceliece6960119_BYTES-1]</code>
given Alice's public key
<code>pk[0]</code>, <code>pk[1]</code>, ..., <code>pk[mceliece6960119_PUBLICKEYBYTES-1]</code>.
This function then returns <code>0</code>.</p>
<p>Exception:
If the input public key is not "narrowly decodable"
(i.e., if bits at particular positions in <code>pk</code> are set),
this function returns <code>-1</code>.
Currently the function also handles such public keys
by clearing <code>ct</code> and <code>k</code>,
but callers should not rely on this.</p>
<p>For <code>{6688128,8192128,460896,348864}{,f}</code>,
all byte strings of the correct length are narrowly decodable,
and the return value is always <code>0</code>.
For <code>6960119{,f}</code>, the return value can be <code>-1</code>.</p>
<h3>DECAPSULATION</h3>
<p>The <code>mceliece6960119_dec</code> function,
given Alice's secret key
<code>sk[0]</code>, <code>sk[1]</code>, ..., <code>sk[mceliece6960119_SECRETKEYBYTES-1]</code>,
computes the session key
<code>k[0]</code>, <code>k[1]</code>, ..., <code>k[mceliece6960119_BYTES-1]</code>
corresponding to a ciphertext
<code>ct[0]</code>, <code>ct[1]</code>, ..., <code>ct[mceliece6960119_CIPHERTEXTBYTES-1]</code>
that was encapsulated to Alice.
This function then returns <code>0</code>.</p>
<p>Exception:
If the input ciphertext is not "narrowly decodable"
(i.e., if bits at particular positions in <code>ct</code> are set),
this function returns <code>-1</code>.
Currently this function also handles such ciphertexts
by setting all bytes of <code>k</code> to <code>255</code>,
but callers should not rely on this.</p>
<p>For <code>{6688128,8192128,460896,348864}{,f}</code>,
all byte strings of the correct length are narrowly decodable,
and the return value is always <code>0</code>.
For <code>6960119{,f}</code>, the return value can be <code>-1</code>.</p>
<h3>THE f VARIANTS</h3>
<p>The <code>f</code> variants are internally more complicated than the non-<code>f</code> variants
but provide faster key generation.
The <code>f</code> variants are interoperable with the non-<code>f</code> variants:
for example, a key generated with <code>mceliece6960119f_keypair</code>
can decapsulate ciphertexts that were encapsulated with <code>mceliece6960119_enc</code>.
The secret-key sizes (and formats) are the same,
the <code>enc</code> functions are the same, and
the <code>dec</code> functions are the same.</p>
<h3>SEE ALSO</h3>
<p><strong>mceliece</strong>(1), <strong>randombytes</strong>(3)</p><hr><font size=1><b>Version:</b>
This is version 2024.05.02 of the "API" web page.
</font>
</div>
</body>
</html>