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
|
### 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](https://classic.mceliece.org) 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](https://bench.cr.yp.to/call-kem.html)
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.
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`.
### THE f VARIANTS
The `f` variants are internally more complicated than the non-`f` variants
but provide faster key generation.
The `f` variants are interoperable with the non-`f` variants:
for example, a key generated with `mceliece6960119f_keypair`
can decapsulate ciphertexts that were encapsulated with `mceliece6960119_enc`.
The secret-key sizes (and formats) are the same,
the `enc` functions are the same, and
the `dec` functions are the same.
### SEE ALSO
**mceliece**(1), **randombytes**(3)
|
