1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<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>
|
