wolfssl-sys 4.0.0

System bindings for WolfSSL
Documentation 
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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377

/* mlkem.h
 *
 * Copyright (C) 2006-2026 wolfSSL Inc.
 *
 * This file is part of wolfSSL.
 *
 * wolfSSL is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * wolfSSL is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
 */

/*!
    \file wolfssl/wolfcrypt/mlkem.h
 */

#ifndef WOLF_CRYPT_MLKEM_H
#define WOLF_CRYPT_MLKEM_H

#include <wolfssl/wolfcrypt/types.h>
#include <wolfssl/wolfcrypt/random.h>

#ifdef WOLFSSL_HAVE_MLKEM

/* Number of co-efficients in polynomial. */
#define MLKEM_N             256

/* Define algorithm type when not excluded. */
#ifndef WOLFSSL_NO_ML_KEM
    #if !defined(WOLFSSL_NO_ML_KEM_512)
        #define WOLFSSL_WC_ML_KEM_512
    #endif
    #if !defined(WOLFSSL_NO_ML_KEM_768)
        #define WOLFSSL_WC_ML_KEM_768
    #endif
    #if !defined(WOLFSSL_NO_ML_KEM_1024)
        #define WOLFSSL_WC_ML_KEM_1024
    #endif

    #if !defined(WOLFSSL_WC_ML_KEM_512) && !defined(WOLFSSL_WC_ML_KEM_768) && \
        !defined(WOLFSSL_WC_ML_KEM_1024)
        #error "No ML-KEM key size chosen."
    #endif
#endif

#ifdef WOLFSSL_MLKEM_KYBER
    #ifndef WOLFSSL_NO_KYBER512
        #define WOLFSSL_KYBER512
        #define WOLFSSL_WC_ML_KEM_512
    #endif
    #ifndef WOLFSSL_NO_KYBER768
        #define WOLFSSL_KYBER768
        #define WOLFSSL_WC_ML_KEM_768
    #endif
    #ifndef WOLFSSL_NO_KYBER1024
        #define WOLFSSL_KYBER1024
        #define WOLFSSL_WC_ML_KEM_1024
    #endif

    #if !defined(WOLFSSL_KYBER512) && !defined(WOLFSSL_KYBER768) && \
        !defined(WOLFSSL_KYBER1024)
        #error "No Kyber key size chosen."
    #endif
#endif

/* Size of a polynomial vector based on dimensions. */
#define MLKEM_POLY_VEC_SZ(k) ((k) * WC_ML_KEM_POLY_SIZE)
/* Size of a compressed polynomial based on bits per coefficient. */
#define MLKEM_POLY_COMPRESSED_SZ(b) ((b) * (MLKEM_N / 8))
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define MLKEM_POLY_VEC_COMPRESSED_SZ(k, b) ((k) * ((b) * (MLKEM_N / 8)))

#ifdef WOLFSSL_WC_ML_KEM_512
#define WC_ML_KEM_512_K                     2
/* Size of a polynomial vector. */
#define WC_ML_KEM_512_POLY_VEC_SZ           MLKEM_POLY_VEC_SZ(WC_ML_KEM_512_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define WC_ML_KEM_512_POLY_COMPRESSED_SZ    MLKEM_POLY_COMPRESSED_SZ(4)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define WC_ML_KEM_512_POLY_VEC_COMPRESSED_SZ  \
    MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_512_K, 10)

/* Public key size. */
#define WC_ML_KEM_512_PUBLIC_KEY_SIZE  \
    (WC_ML_KEM_512_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ)
/* Private key size. */
#define WC_ML_KEM_512_PRIVATE_KEY_SIZE \
    (WC_ML_KEM_512_POLY_VEC_SZ + WC_ML_KEM_512_PUBLIC_KEY_SIZE + \
     2 * WC_ML_KEM_SYM_SZ)
/* Cipher text size. */
#define WC_ML_KEM_512_CIPHER_TEXT_SIZE \
    (WC_ML_KEM_512_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_512_POLY_COMPRESSED_SZ)
#endif

#ifdef WOLFSSL_WC_ML_KEM_768
#define WC_ML_KEM_768_K                     3

/* Size of a polynomial vector. */
#define WC_ML_KEM_768_POLY_VEC_SZ           MLKEM_POLY_VEC_SZ(WC_ML_KEM_768_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define WC_ML_KEM_768_POLY_COMPRESSED_SZ    MLKEM_POLY_COMPRESSED_SZ(4)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define WC_ML_KEM_768_POLY_VEC_COMPRESSED_SZ  \
    MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_768_K, 10)

/* Public key size. */
#define WC_ML_KEM_768_PUBLIC_KEY_SIZE  \
    (WC_ML_KEM_768_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ)
/* Private key size. */
#define WC_ML_KEM_768_PRIVATE_KEY_SIZE \
    (WC_ML_KEM_768_POLY_VEC_SZ + WC_ML_KEM_768_PUBLIC_KEY_SIZE + \
     2 * WC_ML_KEM_SYM_SZ)
/* Cipher text size. */
#define WC_ML_KEM_768_CIPHER_TEXT_SIZE \
    (WC_ML_KEM_768_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_768_POLY_COMPRESSED_SZ)
#endif

#ifdef WOLFSSL_WC_ML_KEM_1024
#define WC_ML_KEM_1024_K                    4

/* Size of a polynomial vector. */
#define WC_ML_KEM_1024_POLY_VEC_SZ          MLKEM_POLY_VEC_SZ(WC_ML_KEM_1024_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define WC_ML_KEM_1024_POLY_COMPRESSED_SZ   MLKEM_POLY_COMPRESSED_SZ(5)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define WC_ML_KEM_1024_POLY_VEC_COMPRESSED_SZ \
    MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_1024_K, 11)

/* Public key size. */
#define WC_ML_KEM_1024_PUBLIC_KEY_SIZE  \
    (WC_ML_KEM_1024_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ)
/* Private key size. */
#define WC_ML_KEM_1024_PRIVATE_KEY_SIZE \
    (WC_ML_KEM_1024_POLY_VEC_SZ + WC_ML_KEM_1024_PUBLIC_KEY_SIZE + \
     2 * WC_ML_KEM_SYM_SZ)
/* Cipher text size. */
#define WC_ML_KEM_1024_CIPHER_TEXT_SIZE \
    (WC_ML_KEM_1024_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_1024_POLY_COMPRESSED_SZ)
#endif

#ifndef WC_ML_KEM_MAX_K
#ifdef WOLFSSL_WC_ML_KEM_1024
#define WC_ML_KEM_MAX_K                 WC_ML_KEM_1024_K
#define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE  WC_ML_KEM_1024_PRIVATE_KEY_SIZE
#define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE   WC_ML_KEM_1024_PUBLIC_KEY_SIZE
#define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE  WC_ML_KEM_1024_CIPHER_TEXT_SIZE
#elif defined(WOLFSSL_WC_ML_KEM_768)
#define WC_ML_KEM_MAX_K                 WC_ML_KEM_768_K
#define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE  WC_ML_KEM_768_PRIVATE_KEY_SIZE
#define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE   WC_ML_KEM_768_PUBLIC_KEY_SIZE
#define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE  WC_ML_KEM_768_CIPHER_TEXT_SIZE
#elif defined(WOLFSSL_WC_ML_KEM_512)
#define WC_ML_KEM_MAX_K                 WC_ML_KEM_512_K
#define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE  WC_ML_KEM_512_PRIVATE_KEY_SIZE
#define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE   WC_ML_KEM_512_PUBLIC_KEY_SIZE
#define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE  WC_ML_KEM_512_CIPHER_TEXT_SIZE
#endif
#endif /* WC_ML_KEM_MAX_K */

#define KYBER_N             MLKEM_N

/* Size of a polynomial vector based on dimensions. */
#define KYBER_POLY_VEC_SZ(k) ((k) * KYBER_POLY_SIZE)
/* Size of a compressed polynomial based on bits per coefficient. */
#define KYBER_POLY_COMPRESSED_SZ(b) ((b) * (KYBER_N / 8))
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define KYBER_POLY_VEC_COMPRESSED_SZ(k, b) ((k) * ((b) * (KYBER_N / 8)))


/* Kyber-512 parameters */
/* Number of polynomials in a vector and vectors in a matrix. */
#define KYBER512_K          2

/* Size of a polynomial vector. */
#define KYBER512_POLY_VEC_SZ             KYBER_POLY_VEC_SZ(KYBER512_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define KYBER512_POLY_COMPRESSED_SZ      KYBER_POLY_COMPRESSED_SZ(4)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define KYBER512_POLY_VEC_COMPRESSED_SZ  \
    KYBER_POLY_VEC_COMPRESSED_SZ(KYBER512_K, 10)

/* Public key size. */
#define KYBER512_PUBLIC_KEY_SIZE  \
    (KYBER512_POLY_VEC_SZ + KYBER_SYM_SZ)
/* Private key size. */
#define KYBER512_PRIVATE_KEY_SIZE \
    (KYBER512_POLY_VEC_SZ + KYBER512_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ)
/* Cipher text size. */
#define KYBER512_CIPHER_TEXT_SIZE \
    (KYBER512_POLY_VEC_COMPRESSED_SZ + KYBER512_POLY_COMPRESSED_SZ)

/* Kyber-768 parameters */
/* Number of polynomials in a vector and vectors in a matrix. */
#define KYBER768_K          3

/* Size of a polynomial vector. */
#define KYBER768_POLY_VEC_SZ             KYBER_POLY_VEC_SZ(KYBER768_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define KYBER768_POLY_COMPRESSED_SZ      KYBER_POLY_COMPRESSED_SZ(4)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define KYBER768_POLY_VEC_COMPRESSED_SZ  \
    KYBER_POLY_VEC_COMPRESSED_SZ(KYBER768_K, 10)

/* Public key size. */
#define KYBER768_PUBLIC_KEY_SIZE  \
    (KYBER768_POLY_VEC_SZ + KYBER_SYM_SZ)
/* Private key size. */
#define KYBER768_PRIVATE_KEY_SIZE \
    (KYBER768_POLY_VEC_SZ + KYBER768_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ)
/* Cipher text size. */
#define KYBER768_CIPHER_TEXT_SIZE \
    (KYBER768_POLY_VEC_COMPRESSED_SZ + KYBER768_POLY_COMPRESSED_SZ)

/* Kyber-1024 parameters */
/* Number of polynomials in a vector and vectors in a matrix. */
#define KYBER1024_K         4

/* Size of a polynomial vector. */
#define KYBER1024_POLY_VEC_SZ             KYBER_POLY_VEC_SZ(KYBER1024_K)
/* Size of a compressed polynomial based on bits per coefficient. */
#define KYBER1024_POLY_COMPRESSED_SZ      KYBER_POLY_COMPRESSED_SZ(5)
/* Size of a compressed vector polynomial based on dimensions and bits per
 * coefficient. */
#define KYBER1024_POLY_VEC_COMPRESSED_SZ \
    KYBER_POLY_VEC_COMPRESSED_SZ(KYBER1024_K, 11)

/* Public key size. */
#define KYBER1024_PUBLIC_KEY_SIZE  \
    (KYBER1024_POLY_VEC_SZ + KYBER_SYM_SZ)
/* Private key size. */
#define KYBER1024_PRIVATE_KEY_SIZE \
    (KYBER1024_POLY_VEC_SZ + KYBER1024_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ)
/* Cipher text size. */
#define KYBER1024_CIPHER_TEXT_SIZE \
    (KYBER1024_POLY_VEC_COMPRESSED_SZ + KYBER1024_POLY_COMPRESSED_SZ)


/* Maximum dimensions and sizes of supported key types. */
#ifdef WOLFSSL_KYBER1024
#define KYBER_MAX_K                 KYBER1024_K
#define KYBER_MAX_PRIVATE_KEY_SIZE  KYBER1024_PRIVATE_KEY_SIZE
#define KYBER_MAX_PUBLIC_KEY_SIZE   KYBER1024_PUBLIC_KEY_SIZE
#define KYBER_MAX_CIPHER_TEXT_SIZE  KYBER1024_CIPHER_TEXT_SIZE
#elif defined(WOLFSSL_KYBER768)
#define KYBER_MAX_K                 KYBER768_K
#define KYBER_MAX_PRIVATE_KEY_SIZE  KYBER768_PRIVATE_KEY_SIZE
#define KYBER_MAX_PUBLIC_KEY_SIZE   KYBER768_PUBLIC_KEY_SIZE
#define KYBER_MAX_CIPHER_TEXT_SIZE  KYBER768_CIPHER_TEXT_SIZE
#elif defined(WOLFSSL_KYBER512)
#define KYBER_MAX_K                 KYBER512_K
#define KYBER_MAX_PRIVATE_KEY_SIZE  KYBER512_PRIVATE_KEY_SIZE
#define KYBER_MAX_PUBLIC_KEY_SIZE   KYBER512_PUBLIC_KEY_SIZE
#define KYBER_MAX_CIPHER_TEXT_SIZE  KYBER512_CIPHER_TEXT_SIZE
#endif

#define KYBER_SYM_SZ            WC_ML_KEM_SYM_SZ
#define KYBER_SS_SZ             WC_ML_KEM_SS_SZ
#define KYBER_MAKEKEY_RAND_SZ   WC_ML_KEM_MAKEKEY_RAND_SZ
#define KYBER_ENC_RAND_SZ       WC_ML_KEM_ENC_RAND_SZ
#define KYBER_POLY_SIZE         WC_ML_KEM_POLY_SIZE


enum {
    /* Types of Kyber keys. */
    WC_ML_KEM_512  = 0,
    WC_ML_KEM_768  = 1,
    WC_ML_KEM_1024 = 2,

    MLKEM_KYBER = 0x10,
    KYBER512  = 0 | MLKEM_KYBER,
    KYBER768  = 1 | MLKEM_KYBER,
    KYBER1024 = 2 | MLKEM_KYBER,

    KYBER_LEVEL1 = KYBER512,
    KYBER_LEVEL3 = KYBER768,
    KYBER_LEVEL5 = KYBER1024,

    /* Symmetric data size. */
    WC_ML_KEM_SYM_SZ            = 32,
    /* Shared secret size. */
    WC_ML_KEM_SS_SZ             = 32,
    /* Size of random required for making a key. */
    WC_ML_KEM_MAKEKEY_RAND_SZ   = 2 * WC_ML_KEM_SYM_SZ,
    /* Size of random required for encapsulation. */
    WC_ML_KEM_ENC_RAND_SZ       = WC_ML_KEM_SYM_SZ,

    /* Encoded polynomial size. */
    WC_ML_KEM_POLY_SIZE         = 384
};


/* Different structures for different implementations. */
typedef struct MlKemKey MlKemKey;


#ifdef __cplusplus
    extern "C" {
#endif

WOLFSSL_API MlKemKey* wc_MlKemKey_New(int type, void* heap, int devId);
WOLFSSL_API int  wc_MlKemKey_Delete(MlKemKey* key, MlKemKey** key_p);

WOLFSSL_API int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap,
    int devId);
WOLFSSL_API int wc_MlKemKey_Free(MlKemKey* key);

WOLFSSL_API int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng);
WOLFSSL_API int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key,
    const unsigned char* rand, int len);

WOLFSSL_API int wc_MlKemKey_CipherTextSize(MlKemKey* key, word32* len);
WOLFSSL_API int wc_MlKemKey_SharedSecretSize(MlKemKey* key, word32* len);

WOLFSSL_API int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* ct,
    unsigned char* ss, WC_RNG* rng);
WOLFSSL_API int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key,
    unsigned char* ct, unsigned char* ss, const unsigned char* rand, int len);
WOLFSSL_API int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
    const unsigned char* ct, word32 len);

WOLFSSL_API int wc_MlKemKey_DecodePrivateKey(MlKemKey* key,
    const unsigned char* in, word32 len);
WOLFSSL_API int wc_MlKemKey_DecodePublicKey(MlKemKey* key,
    const unsigned char* in, word32 len);

WOLFSSL_API int wc_MlKemKey_PrivateKeySize(MlKemKey* key, word32* len);
WOLFSSL_API int wc_MlKemKey_PublicKeySize(MlKemKey* key, word32* len);
WOLFSSL_API int wc_MlKemKey_EncodePrivateKey(MlKemKey* key, unsigned char* out,
    word32 len);
WOLFSSL_API int wc_MlKemKey_EncodePublicKey(MlKemKey* key, unsigned char* out,
    word32 len);


#define KyberKey            MlKemKey

#define wc_KyberKey_Init(type, key, heap, devId) \
        wc_MlKemKey_Init(key, type, heap, devId)
#define wc_KyberKey_Free                    wc_MlKemKey_Free
#define wc_KyberKey_MakeKey                 wc_MlKemKey_MakeKey
#define wc_KyberKey_MakeKeyWithRandom       wc_MlKemKey_MakeKeyWithRandom
#define wc_KyberKey_CipherTextSize          wc_MlKemKey_CipherTextSize
#define wc_KyberKey_SharedSecretSize        wc_MlKemKey_SharedSecretSize
#define wc_KyberKey_Encapsulate             wc_MlKemKey_Encapsulate
#define wc_KyberKey_EncapsulateWithRandom   wc_MlKemKey_EncapsulateWithRandom
#define wc_KyberKey_Decapsulate             wc_MlKemKey_Decapsulate
#define wc_KyberKey_DecodePrivateKey        wc_MlKemKey_DecodePrivateKey
#define wc_KyberKey_DecodePublicKey         wc_MlKemKey_DecodePublicKey
#define wc_KyberKey_PrivateKeySize          wc_MlKemKey_PrivateKeySize
#define wc_KyberKey_PublicKeySize           wc_MlKemKey_PublicKeySize
#define wc_KyberKey_EncodePrivateKey        wc_MlKemKey_EncodePrivateKey
#define wc_KyberKey_EncodePublicKey         wc_MlKemKey_EncodePublicKey


#ifdef __cplusplus
    } /* extern "C" */
#endif

#endif /* WOLFSSL_HAVE_MLKEM */

#endif /* WOLF_CRYPT_MLKEM_H */