2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
35 * Maximum size for a RSA modulus (in bits). Allocated stack buffers
36 * depend on that size, so this value should be kept small. Currently,
37 * 2048-bit RSA keys offer adequate security, and should still do so for
38 * the next few decades; however, a number of widespread PKI have
39 * already set their root keys to RSA-4096, so we should be able to
42 * This value MUST be a multiple of 64.
44 #define BR_MAX_RSA_SIZE 4096
47 * Maximum size for a RSA factor (in bits). This is for RSA private-key
48 * operations. Default is to support factors up to a bit more than half
49 * the maximum modulus size.
51 * This value MUST be a multiple of 32.
53 #define BR_MAX_RSA_FACTOR ((BR_MAX_RSA_SIZE + 64) >> 1)
56 * Maximum size for an EC curve (modulus or order), in bits. Size of
57 * stack buffers depends on that parameter. This size MUST be a multiple
58 * of 8 (so that decoding an integer with that many bytes does not
61 #define BR_MAX_EC_SIZE 528
64 * Some macros to recognize the current architecture. Right now, we are
65 * interested into automatically recognizing architecture with efficient
66 * 64-bit types so that we may automatically use implementations that
67 * use 64-bit registers in that case. Future versions may detect, e.g.,
68 * availability of SSE2 intrinsics.
70 * If 'unsigned long' is a 64-bit type, then we assume that 64-bit types
71 * are efficient. Otherwise, we rely on macros that depend on compiler,
72 * OS and architecture. In any case, failure to detect the architecture
73 * as 64-bit means that the 32-bit code will be used, and that code
74 * works also on 64-bit architectures (the 64-bit code may simply be
77 * The test on 'unsigned long' should already catch most cases, the one
78 * notable exception being Windows code where 'unsigned long' is kept to
79 * 32-bit for compatbility with all the legacy code that liberally uses
80 * the 'DWORD' type for 32-bit values.
82 * Macro names are taken from: http://nadeausoftware.com/articles/2012/02/c_c_tip_how_detect_processor_type_using_compiler_predefined_macros
85 #if ((ULONG_MAX >> 31) >> 31) == 3
87 #elif defined(__ia64) || defined(__itanium__) || defined(_M_IA64)
89 #elif defined(__powerpc64__) || defined(__ppc64__) || defined(__PPC64__) \
90 || defined(__64BIT__) || defined(_LP64) || defined(__LP64__)
92 #elif defined(__sparc64__)
94 #elif defined(__x86_64__) || defined(_M_X64)
99 /* ==================================================================== */
101 * Encoding/decoding functions.
103 * 32-bit and 64-bit decoding, both little-endian and big-endian, is
104 * implemented with the inline functions below. These functions are
105 * generic: they don't depend on the architecture natural endianness,
106 * and they can handle unaligned accesses. Optimized versions for some
107 * specific architectures may be implemented at a later time.
111 br_enc16le(void *dst
, unsigned x
)
116 buf
[0] = (unsigned char)x
;
117 buf
[1] = (unsigned char)(x
>> 8);
121 br_enc16be(void *dst
, unsigned x
)
126 buf
[0] = (unsigned char)(x
>> 8);
127 buf
[1] = (unsigned char)x
;
130 static inline unsigned
131 br_dec16le(const void *src
)
133 const unsigned char *buf
;
136 return (unsigned)buf
[0] | ((unsigned)buf
[1] << 8);
139 static inline unsigned
140 br_dec16be(const void *src
)
142 const unsigned char *buf
;
145 return ((unsigned)buf
[0] << 8) | (unsigned)buf
[1];
149 br_enc32le(void *dst
, uint32_t x
)
154 buf
[0] = (unsigned char)x
;
155 buf
[1] = (unsigned char)(x
>> 8);
156 buf
[2] = (unsigned char)(x
>> 16);
157 buf
[3] = (unsigned char)(x
>> 24);
161 br_enc32be(void *dst
, uint32_t x
)
166 buf
[0] = (unsigned char)(x
>> 24);
167 buf
[1] = (unsigned char)(x
>> 16);
168 buf
[2] = (unsigned char)(x
>> 8);
169 buf
[3] = (unsigned char)x
;
172 static inline uint32_t
173 br_dec32le(const void *src
)
175 const unsigned char *buf
;
178 return (uint32_t)buf
[0]
179 | ((uint32_t)buf
[1] << 8)
180 | ((uint32_t)buf
[2] << 16)
181 | ((uint32_t)buf
[3] << 24);
184 static inline uint32_t
185 br_dec32be(const void *src
)
187 const unsigned char *buf
;
190 return ((uint32_t)buf
[0] << 24)
191 | ((uint32_t)buf
[1] << 16)
192 | ((uint32_t)buf
[2] << 8)
197 br_enc64le(void *dst
, uint64_t x
)
202 br_enc32le(buf
, (uint32_t)x
);
203 br_enc32le(buf
+ 4, (uint32_t)(x
>> 32));
207 br_enc64be(void *dst
, uint64_t x
)
212 br_enc32be(buf
, (uint32_t)(x
>> 32));
213 br_enc32be(buf
+ 4, (uint32_t)x
);
216 static inline uint64_t
217 br_dec64le(const void *src
)
219 const unsigned char *buf
;
222 return (uint64_t)br_dec32le(buf
)
223 | ((uint64_t)br_dec32le(buf
+ 4) << 32);
226 static inline uint64_t
227 br_dec64be(const void *src
)
229 const unsigned char *buf
;
232 return ((uint64_t)br_dec32be(buf
) << 32)
233 | (uint64_t)br_dec32be(buf
+ 4);
237 * Range decoding and encoding (for several successive values).
239 void br_range_dec16le(uint16_t *v
, size_t num
, const void *src
);
240 void br_range_dec16be(uint16_t *v
, size_t num
, const void *src
);
241 void br_range_enc16le(void *dst
, const uint16_t *v
, size_t num
);
242 void br_range_enc16be(void *dst
, const uint16_t *v
, size_t num
);
244 void br_range_dec32le(uint32_t *v
, size_t num
, const void *src
);
245 void br_range_dec32be(uint32_t *v
, size_t num
, const void *src
);
246 void br_range_enc32le(void *dst
, const uint32_t *v
, size_t num
);
247 void br_range_enc32be(void *dst
, const uint32_t *v
, size_t num
);
249 void br_range_dec64le(uint64_t *v
, size_t num
, const void *src
);
250 void br_range_dec64be(uint64_t *v
, size_t num
, const void *src
);
251 void br_range_enc64le(void *dst
, const uint64_t *v
, size_t num
);
252 void br_range_enc64be(void *dst
, const uint64_t *v
, size_t num
);
255 * Byte-swap a 32-bit integer.
257 static inline uint32_t
258 br_swap32(uint32_t x
)
260 x
= ((x
& (uint32_t)0x00FF00FF) << 8)
261 | ((x
>> 8) & (uint32_t)0x00FF00FF);
262 return (x
<< 16) | (x
>> 16);
265 /* ==================================================================== */
267 * Support code for hash functions.
271 * IV for MD5, SHA-1, SHA-224 and SHA-256.
273 extern const uint32_t br_md5_IV
[];
274 extern const uint32_t br_sha1_IV
[];
275 extern const uint32_t br_sha224_IV
[];
276 extern const uint32_t br_sha256_IV
[];
279 * Round functions for MD5, SHA-1, SHA-224 and SHA-256 (SHA-224 and
280 * SHA-256 use the same round function).
282 void br_md5_round(const unsigned char *buf
, uint32_t *val
);
283 void br_sha1_round(const unsigned char *buf
, uint32_t *val
);
284 void br_sha2small_round(const unsigned char *buf
, uint32_t *val
);
287 * The core function for the TLS PRF. It computes
288 * P_hash(secret, label + seed), and XORs the result into the dst buffer.
290 void br_tls_phash(void *dst
, size_t len
,
291 const br_hash_class
*dig
,
292 const void *secret
, size_t secret_len
,
293 const char *label
, const void *seed
, size_t seed_len
);
296 * Copy all configured hash implementations from a multihash context
300 br_multihash_copyimpl(br_multihash_context
*dst
,
301 const br_multihash_context
*src
)
303 memcpy(dst
->impl
, src
->impl
, sizeof src
->impl
);
306 /* ==================================================================== */
308 * Constant-time primitives. These functions manipulate 32-bit values in
309 * order to provide constant-time comparisons and multiplexers.
311 * Boolean values (the "ctl" bits) MUST have value 0 or 1.
313 * Implementation notes:
314 * =====================
316 * The uintN_t types are unsigned and with width exactly N bits; the C
317 * standard guarantees that computations are performed modulo 2^N, and
318 * there can be no overflow. Negation (unary '-') works on unsigned types
321 * The intN_t types are guaranteed to have width exactly N bits, with no
322 * padding bit, and using two's complement representation. Casting
323 * intN_t to uintN_t really is conversion modulo 2^N. Beware that intN_t
324 * types, being signed, trigger implementation-defined behaviour on
325 * overflow (including raising some signal): with GCC, while modular
326 * arithmetics are usually applied, the optimizer may assume that
327 * overflows don't occur (unless the -fwrapv command-line option is
328 * added); Clang has the additional -ftrapv option to explicitly trap on
329 * integer overflow or underflow.
335 static inline uint32_t
342 * Multiplexer: returns x if ctl == 1, y if ctl == 0.
344 static inline uint32_t
345 MUX(uint32_t ctl
, uint32_t x
, uint32_t y
)
347 return y
^ (-ctl
& (x
^ y
));
351 * Equality check: returns 1 if x == y, 0 otherwise.
353 static inline uint32_t
354 EQ(uint32_t x
, uint32_t y
)
359 return NOT((q
| -q
) >> 31);
363 * Inequality check: returns 1 if x != y, 0 otherwise.
365 static inline uint32_t
366 NEQ(uint32_t x
, uint32_t y
)
371 return (q
| -q
) >> 31;
375 * Comparison: returns 1 if x > y, 0 otherwise.
377 static inline uint32_t
378 GT(uint32_t x
, uint32_t y
)
381 * If both x < 2^31 and x < 2^31, then y-x will have its high
382 * bit set if x > y, cleared otherwise.
384 * If either x >= 2^31 or y >= 2^31 (but not both), then the
385 * result is the high bit of x.
387 * If both x >= 2^31 and y >= 2^31, then we can virtually
388 * subtract 2^31 from both, and we are back to the first case.
389 * Since (y-2^31)-(x-2^31) = y-x, the subtraction is already
395 return (z
^ ((x
^ y
) & (x
^ z
))) >> 31;
399 * Other comparisons (greater-or-equal, lower-than, lower-or-equal).
401 #define GE(x, y) NOT(GT(y, x))
402 #define LT(x, y) GT(y, x)
403 #define LE(x, y) NOT(GT(x, y))
406 * General comparison: returned value is -1, 0 or 1, depending on
407 * whether x is lower than, equal to, or greater than y.
409 static inline int32_t
410 CMP(uint32_t x
, uint32_t y
)
412 return (int32_t)GT(x
, y
) | -(int32_t)GT(y
, x
);
416 * Returns 1 if x == 0, 0 otherwise. Take care that the operand is signed.
418 static inline uint32_t
424 return ~(q
| -q
) >> 31;
428 * Returns 1 if x > 0, 0 otherwise. Take care that the operand is signed.
430 static inline uint32_t
434 * High bit of -x is 0 if x == 0, but 1 if x > 0.
439 return (~q
& -q
) >> 31;
443 * Returns 1 if x >= 0, 0 otherwise. Take care that the operand is signed.
445 static inline uint32_t
448 return ~(uint32_t)x
>> 31;
452 * Returns 1 if x < 0, 0 otherwise. Take care that the operand is signed.
454 static inline uint32_t
457 return (uint32_t)x
>> 31;
461 * Returns 1 if x <= 0, 0 otherwise. Take care that the operand is signed.
463 static inline uint32_t
469 * ~-x has its high bit set if and only if -x is nonnegative (as
470 * a signed int), i.e. x is in the -(2^31-1) to 0 range. We must
471 * do an OR with x itself to account for x = -2^31.
474 return (q
| ~-q
) >> 31;
478 * Conditional copy: src[] is copied into dst[] if and only if ctl is 1.
479 * dst[] and src[] may overlap completely (but not partially).
481 void br_ccopy(uint32_t ctl
, void *dst
, const void *src
, size_t len
);
483 #define CCOPY br_ccopy
486 * Compute the bit length of a 32-bit integer. Returned value is between 0
487 * and 32 (inclusive).
489 static inline uint32_t
490 BIT_LENGTH(uint32_t x
)
495 c
= GT(x
, 0xFFFF); x
= MUX(c
, x
>> 16, x
); k
+= c
<< 4;
496 c
= GT(x
, 0x00FF); x
= MUX(c
, x
>> 8, x
); k
+= c
<< 3;
497 c
= GT(x
, 0x000F); x
= MUX(c
, x
>> 4, x
); k
+= c
<< 2;
498 c
= GT(x
, 0x0003); x
= MUX(c
, x
>> 2, x
); k
+= c
<< 1;
504 * Compute the minimum of x and y.
506 static inline uint32_t
507 MIN(uint32_t x
, uint32_t y
)
509 return MUX(GT(x
, y
), y
, x
);
513 * Compute the maximum of x and y.
515 static inline uint32_t
516 MAX(uint32_t x
, uint32_t y
)
518 return MUX(GT(x
, y
), x
, y
);
522 * Multiply two 32-bit integers, with a 64-bit result. This default
523 * implementation assumes that the basic multiplication operator
524 * yields constant-time code.
526 #define MUL(x, y) ((uint64_t)(x) * (uint64_t)(y))
531 * Alternate implementation of MUL31, that will be constant-time on some
532 * (old) platforms where the default MUL31 is not. Unfortunately, it is
533 * also substantially slower, and yields larger code, on more modern
534 * platforms, which is why it is deactivated by default.
536 #define MUL31(x, y) ((uint64_t)((x) | (uint32_t)0x80000000) \
537 * (uint64_t)((y) | (uint32_t)0x80000000) \
538 - ((uint64_t)(x) << 31) - ((uint64_t)(y) << 31) \
539 - ((uint64_t)1 << 62))
544 * Multiply two 31-bit integers, with a 62-bit result. This default
545 * implementation assumes that the basic multiplication operator
546 * yields constant-time code.
548 #define MUL31(x, y) ((uint64_t)(x) * (uint64_t)(y))
553 * Multiply two words together; each word may contain up to 15 bits of
554 * data. If BR_CT_MUL15 is non-zero, then the macro will contain some
555 * extra operations that help in making the operation constant-time on
556 * some platforms, where the basic 32-bit multiplication is not
560 #define MUL15(x, y) (((uint32_t)(x) | (uint32_t)0x80000000) \
561 * ((uint32_t)(x) | (uint32_t)0x80000000) \
562 & (uint32_t)0x3FFFFFFF)
564 #define MUL15(x, y) ((uint32_t)(x) * (uint32_t)(y))
568 * Arithmetic right shift (sign bit is copied). What happens when
569 * right-shifting a negative value is _implementation-defined_, so it
570 * does not trigger undefined behaviour, but it is still up to each
571 * compiler to define (and document) what it does. Most/all compilers
572 * will do an arithmetic shift, the sign bit being used to fill the
573 * holes; this is a native operation on the underlying CPU, and it would
574 * make little sense for the compiler to do otherwise. GCC explicitly
575 * documents that it follows that convention.
577 * Still, if BR_NO_ARITH_SHIFT is defined (and non-zero), then an
578 * alternate version will be used, that does not rely on such
579 * implementation-defined behaviour. Unfortunately, it is also slower
580 * and yields bigger code, which is why it is deactivated by default.
582 #if BR_NO_ARITH_SHIFT
583 #define ARSH(x, n) (((uint32_t)(x) >> (n)) \
584 | ((-((uint32_t)(x) >> 31)) << (32 - (n))))
586 #define ARSH(x, n) ((*(int32_t *)&(x)) >> (n))
590 * Constant-time division. The dividend hi:lo is divided by the
591 * divisor d; the quotient is returned and the remainder is written
592 * in *r. If hi == d, then the quotient does not fit on 32 bits;
593 * returned value is thus truncated. If hi > d, returned values are
596 uint32_t br_divrem(uint32_t hi
, uint32_t lo
, uint32_t d
, uint32_t *r
);
599 * Wrapper for br_divrem(); the remainder is returned, and the quotient
602 static inline uint32_t
603 br_rem(uint32_t hi
, uint32_t lo
, uint32_t d
)
607 br_divrem(hi
, lo
, d
, &r
);
612 * Wrapper for br_divrem(); the quotient is returned, and the remainder
615 static inline uint32_t
616 br_div(uint32_t hi
, uint32_t lo
, uint32_t d
)
620 return br_divrem(hi
, lo
, d
, &r
);
623 /* ==================================================================== */
629 * The 'i32' functions implement computations on big integers using
630 * an internal representation as an array of 32-bit integers. For
632 * -- x[0] contains the "announced bit length" of the integer
633 * -- x[1], x[2]... contain the value in little-endian order (x[1]
634 * contains the least significant 32 bits)
636 * Multiplications rely on the elementary 32x32->64 multiplication.
638 * The announced bit length specifies the number of bits that are
639 * significant in the subsequent 32-bit words. Unused bits in the
640 * last (most significant) word are set to 0; subsequent words are
641 * uninitialized and need not exist at all.
643 * The execution time and memory access patterns of all computations
644 * depend on the announced bit length, but not on the actual word
645 * values. For modular integers, the announced bit length of any integer
646 * modulo n is equal to the actual bit length of n; thus, computations
647 * on modular integers are "constant-time" (only the modulus length may
652 * Compute the actual bit length of an integer. The argument x should
653 * point to the first (least significant) value word of the integer.
654 * The len 'xlen' contains the number of 32-bit words to access.
656 * CT: value or length of x does not leak.
658 uint32_t br_i32_bit_length(uint32_t *x
, size_t xlen
);
661 * Decode an integer from its big-endian unsigned representation. The
662 * "true" bit length of the integer is computed, but all words of x[]
663 * corresponding to the full 'len' bytes of the source are set.
665 * CT: value or length of x does not leak.
667 void br_i32_decode(uint32_t *x
, const void *src
, size_t len
);
670 * Decode an integer from its big-endian unsigned representation. The
671 * integer MUST be lower than m[]; the announced bit length written in
672 * x[] will be equal to that of m[]. All 'len' bytes from the source are
675 * Returned value is 1 if the decode value fits within the modulus, 0
676 * otherwise. In the latter case, the x[] buffer will be set to 0 (but
677 * still with the announced bit length of m[]).
679 * CT: value or length of x does not leak. Memory access pattern depends
680 * only of 'len' and the announced bit length of m. Whether x fits or
681 * not does not leak either.
683 uint32_t br_i32_decode_mod(uint32_t *x
,
684 const void *src
, size_t len
, const uint32_t *m
);
687 * Reduce an integer (a[]) modulo another (m[]). The result is written
688 * in x[] and its announced bit length is set to be equal to that of m[].
690 * x[] MUST be distinct from a[] and m[].
692 * CT: only announced bit lengths leak, not values of x, a or m.
694 void br_i32_reduce(uint32_t *x
, const uint32_t *a
, const uint32_t *m
);
697 * Decode an integer from its big-endian unsigned representation, and
698 * reduce it modulo the provided modulus m[]. The announced bit length
699 * of the result is set to be equal to that of the modulus.
701 * x[] MUST be distinct from m[].
703 void br_i32_decode_reduce(uint32_t *x
,
704 const void *src
, size_t len
, const uint32_t *m
);
707 * Encode an integer into its big-endian unsigned representation. The
708 * output length in bytes is provided (parameter 'len'); if the length
709 * is too short then the integer is appropriately truncated; if it is
710 * too long then the extra bytes are set to 0.
712 void br_i32_encode(void *dst
, size_t len
, const uint32_t *x
);
715 * Multiply x[] by 2^32 and then add integer z, modulo m[]. This
716 * function assumes that x[] and m[] have the same announced bit
717 * length, and the announced bit length of m[] matches its true
720 * x[] and m[] MUST be distinct arrays.
722 * CT: only the common announced bit length of x and m leaks, not
723 * the values of x, z or m.
725 void br_i32_muladd_small(uint32_t *x
, uint32_t z
, const uint32_t *m
);
728 * Extract one word from an integer. The offset is counted in bits.
729 * The word MUST entirely fit within the word elements corresponding
730 * to the announced bit length of a[].
732 static inline uint32_t
733 br_i32_word(const uint32_t *a
, uint32_t off
)
738 u
= (size_t)(off
>> 5) + 1;
739 j
= (unsigned)off
& 31;
743 return (a
[u
] >> j
) | (a
[u
+ 1] << (32 - j
));
748 * Test whether an integer is zero.
750 uint32_t br_i32_iszero(const uint32_t *x
);
753 * Add b[] to a[] and return the carry (0 or 1). If ctl is 0, then a[]
754 * is unmodified, but the carry is still computed and returned. The
755 * arrays a[] and b[] MUST have the same announced bit length.
757 * a[] and b[] MAY be the same array, but partial overlap is not allowed.
759 uint32_t br_i32_add(uint32_t *a
, const uint32_t *b
, uint32_t ctl
);
762 * Subtract b[] from a[] and return the carry (0 or 1). If ctl is 0,
763 * then a[] is unmodified, but the carry is still computed and returned.
764 * The arrays a[] and b[] MUST have the same announced bit length.
766 * a[] and b[] MAY be the same array, but partial overlap is not allowed.
768 uint32_t br_i32_sub(uint32_t *a
, const uint32_t *b
, uint32_t ctl
);
771 * Compute d+a*b, result in d. The initial announced bit length of d[]
772 * MUST match that of a[]. The d[] array MUST be large enough to
773 * accommodate the full result, plus (possibly) an extra word. The
774 * resulting announced bit length of d[] will be the sum of the announced
775 * bit lengths of a[] and b[] (therefore, it may be larger than the actual
776 * bit length of the numerical result).
778 * a[] and b[] may be the same array. d[] must be disjoint from both a[]
781 void br_i32_mulacc(uint32_t *d
, const uint32_t *a
, const uint32_t *b
);
784 * Zeroize an integer. The announced bit length is set to the provided
785 * value, and the corresponding words are set to 0.
788 br_i32_zero(uint32_t *x
, uint32_t bit_len
)
791 memset(x
, 0, ((bit_len
+ 31) >> 5) * sizeof *x
);
795 * Compute -(1/x) mod 2^32. If x is even, then this function returns 0.
797 uint32_t br_i32_ninv32(uint32_t x
);
800 * Convert a modular integer to Montgomery representation. The integer x[]
801 * MUST be lower than m[], but with the same announced bit length.
803 void br_i32_to_monty(uint32_t *x
, const uint32_t *m
);
806 * Convert a modular integer back from Montgomery representation. The
807 * integer x[] MUST be lower than m[], but with the same announced bit
808 * length. The "m0i" parameter is equal to -(1/m0) mod 2^32, where m0 is
809 * the least significant value word of m[] (this works only if m[] is
812 void br_i32_from_monty(uint32_t *x
, const uint32_t *m
, uint32_t m0i
);
815 * Compute a modular Montgomery multiplication. d[] is filled with the
816 * value of x*y/R modulo m[] (where R is the Montgomery factor). The
817 * array d[] MUST be distinct from x[], y[] and m[]. x[] and y[] MUST be
818 * numerically lower than m[]. x[] and y[] MAY be the same array. The
819 * "m0i" parameter is equal to -(1/m0) mod 2^32, where m0 is the least
820 * significant value word of m[] (this works only if m[] is an odd
823 void br_i32_montymul(uint32_t *d
, const uint32_t *x
, const uint32_t *y
,
824 const uint32_t *m
, uint32_t m0i
);
827 * Compute a modular exponentiation. x[] MUST be an integer modulo m[]
828 * (same announced bit length, lower value). m[] MUST be odd. The
829 * exponent is in big-endian unsigned notation, over 'elen' bytes. The
830 * "m0i" parameter is equal to -(1/m0) mod 2^32, where m0 is the least
831 * significant value word of m[] (this works only if m[] is an odd
832 * integer). The t1[] and t2[] parameters must be temporary arrays,
833 * each large enough to accommodate an integer with the same size as m[].
835 void br_i32_modpow(uint32_t *x
, const unsigned char *e
, size_t elen
,
836 const uint32_t *m
, uint32_t m0i
, uint32_t *t1
, uint32_t *t2
);
838 /* ==================================================================== */
844 * The 'i31' functions implement computations on big integers using
845 * an internal representation as an array of 32-bit integers. For
847 * -- x[0] encodes the array length and the "announced bit length"
848 * of the integer: namely, if the announced bit length is k,
849 * then x[0] = ((k / 31) << 5) + (k % 31).
850 * -- x[1], x[2]... contain the value in little-endian order, 31
851 * bits per word (x[1] contains the least significant 31 bits).
852 * The upper bit of each word is 0.
854 * Multiplications rely on the elementary 32x32->64 multiplication.
856 * The announced bit length specifies the number of bits that are
857 * significant in the subsequent 32-bit words. Unused bits in the
858 * last (most significant) word are set to 0; subsequent words are
859 * uninitialized and need not exist at all.
861 * The execution time and memory access patterns of all computations
862 * depend on the announced bit length, but not on the actual word
863 * values. For modular integers, the announced bit length of any integer
864 * modulo n is equal to the actual bit length of n; thus, computations
865 * on modular integers are "constant-time" (only the modulus length may
870 * Test whether an integer is zero.
872 uint32_t br_i31_iszero(const uint32_t *x
);
875 * Add b[] to a[] and return the carry (0 or 1). If ctl is 0, then a[]
876 * is unmodified, but the carry is still computed and returned. The
877 * arrays a[] and b[] MUST have the same announced bit length.
879 * a[] and b[] MAY be the same array, but partial overlap is not allowed.
881 uint32_t br_i31_add(uint32_t *a
, const uint32_t *b
, uint32_t ctl
);
884 * Subtract b[] from a[] and return the carry (0 or 1). If ctl is 0,
885 * then a[] is unmodified, but the carry is still computed and returned.
886 * The arrays a[] and b[] MUST have the same announced bit length.
888 * a[] and b[] MAY be the same array, but partial overlap is not allowed.
890 uint32_t br_i31_sub(uint32_t *a
, const uint32_t *b
, uint32_t ctl
);
893 * Compute the ENCODED actual bit length of an integer. The argument x
894 * should point to the first (least significant) value word of the
895 * integer. The len 'xlen' contains the number of 32-bit words to
896 * access. The upper bit of each value word MUST be 0.
897 * Returned value is ((k / 31) << 5) + (k % 31) if the bit length is k.
899 * CT: value or length of x does not leak.
901 uint32_t br_i31_bit_length(uint32_t *x
, size_t xlen
);
904 * Decode an integer from its big-endian unsigned representation. The
905 * "true" bit length of the integer is computed and set in the encoded
906 * announced bit length (x[0]), but all words of x[] corresponding to
907 * the full 'len' bytes of the source are set.
909 * CT: value or length of x does not leak.
911 void br_i31_decode(uint32_t *x
, const void *src
, size_t len
);
914 * Decode an integer from its big-endian unsigned representation. The
915 * integer MUST be lower than m[]; the (encoded) announced bit length
916 * written in x[] will be equal to that of m[]. All 'len' bytes from the
919 * Returned value is 1 if the decode value fits within the modulus, 0
920 * otherwise. In the latter case, the x[] buffer will be set to 0 (but
921 * still with the announced bit length of m[]).
923 * CT: value or length of x does not leak. Memory access pattern depends
924 * only of 'len' and the announced bit length of m. Whether x fits or
925 * not does not leak either.
927 uint32_t br_i31_decode_mod(uint32_t *x
,
928 const void *src
, size_t len
, const uint32_t *m
);
931 * Zeroize an integer. The announced bit length is set to the provided
932 * value, and the corresponding words are set to 0. The ENCODED bit length
936 br_i31_zero(uint32_t *x
, uint32_t bit_len
)
939 memset(x
, 0, ((bit_len
+ 31) >> 5) * sizeof *x
);
943 * Right-shift an integer. The shift amount must be lower than 31
946 void br_i31_rshift(uint32_t *x
, int count
);
949 * Reduce an integer (a[]) modulo another (m[]). The result is written
950 * in x[] and its announced bit length is set to be equal to that of m[].
952 * x[] MUST be distinct from a[] and m[].
954 * CT: only announced bit lengths leak, not values of x, a or m.
956 void br_i31_reduce(uint32_t *x
, const uint32_t *a
, const uint32_t *m
);
959 * Decode an integer from its big-endian unsigned representation, and
960 * reduce it modulo the provided modulus m[]. The announced bit length
961 * of the result is set to be equal to that of the modulus.
963 * x[] MUST be distinct from m[].
965 void br_i31_decode_reduce(uint32_t *x
,
966 const void *src
, size_t len
, const uint32_t *m
);
969 * Multiply x[] by 2^31 and then add integer z, modulo m[]. This
970 * function assumes that x[] and m[] have the same announced bit
971 * length, the announced bit length of m[] matches its true
974 * x[] and m[] MUST be distinct arrays. z MUST fit in 31 bits (upper
977 * CT: only the common announced bit length of x and m leaks, not
978 * the values of x, z or m.
980 void br_i31_muladd_small(uint32_t *x
, uint32_t z
, const uint32_t *m
);
983 * Encode an integer into its big-endian unsigned representation. The
984 * output length in bytes is provided (parameter 'len'); if the length
985 * is too short then the integer is appropriately truncated; if it is
986 * too long then the extra bytes are set to 0.
988 void br_i31_encode(void *dst
, size_t len
, const uint32_t *x
);
991 * Compute -(1/x) mod 2^31. If x is even, then this function returns 0.
993 uint32_t br_i31_ninv31(uint32_t x
);
996 * Compute a modular Montgomery multiplication. d[] is filled with the
997 * value of x*y/R modulo m[] (where R is the Montgomery factor). The
998 * array d[] MUST be distinct from x[], y[] and m[]. x[] and y[] MUST be
999 * numerically lower than m[]. x[] and y[] MAY be the same array. The
1000 * "m0i" parameter is equal to -(1/m0) mod 2^31, where m0 is the least
1001 * significant value word of m[] (this works only if m[] is an odd
1004 void br_i31_montymul(uint32_t *d
, const uint32_t *x
, const uint32_t *y
,
1005 const uint32_t *m
, uint32_t m0i
);
1008 * Convert a modular integer to Montgomery representation. The integer x[]
1009 * MUST be lower than m[], but with the same announced bit length.
1011 void br_i31_to_monty(uint32_t *x
, const uint32_t *m
);
1014 * Convert a modular integer back from Montgomery representation. The
1015 * integer x[] MUST be lower than m[], but with the same announced bit
1016 * length. The "m0i" parameter is equal to -(1/m0) mod 2^32, where m0 is
1017 * the least significant value word of m[] (this works only if m[] is
1020 void br_i31_from_monty(uint32_t *x
, const uint32_t *m
, uint32_t m0i
);
1023 * Compute a modular exponentiation. x[] MUST be an integer modulo m[]
1024 * (same announced bit length, lower value). m[] MUST be odd. The
1025 * exponent is in big-endian unsigned notation, over 'elen' bytes. The
1026 * "m0i" parameter is equal to -(1/m0) mod 2^31, where m0 is the least
1027 * significant value word of m[] (this works only if m[] is an odd
1028 * integer). The t1[] and t2[] parameters must be temporary arrays,
1029 * each large enough to accommodate an integer with the same size as m[].
1031 void br_i31_modpow(uint32_t *x
, const unsigned char *e
, size_t elen
,
1032 const uint32_t *m
, uint32_t m0i
, uint32_t *t1
, uint32_t *t2
);
1035 * Compute d+a*b, result in d. The initial announced bit length of d[]
1036 * MUST match that of a[]. The d[] array MUST be large enough to
1037 * accommodate the full result, plus (possibly) an extra word. The
1038 * resulting announced bit length of d[] will be the sum of the announced
1039 * bit lengths of a[] and b[] (therefore, it may be larger than the actual
1040 * bit length of the numerical result).
1042 * a[] and b[] may be the same array. d[] must be disjoint from both a[]
1045 void br_i31_mulacc(uint32_t *d
, const uint32_t *a
, const uint32_t *b
);
1047 /* ==================================================================== */
1049 static inline size_t
1050 br_digest_size(const br_hash_class
*digest_class
)
1052 return (size_t)(digest_class
->desc
>> BR_HASHDESC_OUT_OFF
)
1053 & BR_HASHDESC_OUT_MASK
;
1057 * Get the output size (in bytes) of a hash function.
1059 size_t br_digest_size_by_ID(int digest_id
);
1062 * Get the OID (encoded OBJECT IDENTIFIER value, without tag and length)
1063 * for a hash function. If digest_id is not a supported digest identifier
1064 * (in particular if it is equal to 0, i.e. br_md5sha1_ID), then NULL is
1065 * returned and *len is set to 0.
1067 const unsigned char *br_digest_OID(int digest_id
, size_t *len
);
1069 /* ==================================================================== */
1071 * DES support functions.
1075 * Apply DES Initial Permutation.
1077 void br_des_do_IP(uint32_t *xl
, uint32_t *xr
);
1080 * Apply DES Final Permutation (inverse of IP).
1082 void br_des_do_invIP(uint32_t *xl
, uint32_t *xr
);
1085 * Key schedule unit: for a DES key (8 bytes), compute 16 subkeys. Each
1086 * subkey is two 28-bit words represented as two 32-bit words; the PC-2
1087 * bit extration is NOT applied.
1089 void br_des_keysched_unit(uint32_t *skey
, const void *key
);
1092 * Reversal of 16 DES sub-keys (for decryption).
1094 void br_des_rev_skey(uint32_t *skey
);
1097 * DES/3DES key schedule for 'des_tab' (encryption direction). Returned
1098 * value is the number of rounds.
1100 unsigned br_des_tab_keysched(uint32_t *skey
, const void *key
, size_t key_len
);
1103 * DES/3DES key schedule for 'des_ct' (encryption direction). Returned
1104 * value is the number of rounds.
1106 unsigned br_des_ct_keysched(uint32_t *skey
, const void *key
, size_t key_len
);
1109 * DES/3DES subkey decompression (from the compressed bitsliced subkeys).
1111 void br_des_ct_skey_expand(uint32_t *sk_exp
,
1112 unsigned num_rounds
, const uint32_t *skey
);
1115 * DES/3DES block encryption/decryption ('des_tab').
1117 void br_des_tab_process_block(unsigned num_rounds
,
1118 const uint32_t *skey
, void *block
);
1121 * DES/3DES block encryption/decryption ('des_ct').
1123 void br_des_ct_process_block(unsigned num_rounds
,
1124 const uint32_t *skey
, void *block
);
1126 /* ==================================================================== */
1128 * AES support functions.
1132 * The AES S-box (256-byte table).
1134 extern const unsigned char br_aes_S
[];
1137 * AES key schedule. skey[] is filled with n+1 128-bit subkeys, where n
1138 * is the number of rounds (10 to 14, depending on key size). The number
1139 * of rounds is returned. If the key size is invalid (not 16, 24 or 32),
1140 * then 0 is returned.
1142 * This implementation uses a 256-byte table and is NOT constant-time.
1144 unsigned br_aes_keysched(uint32_t *skey
, const void *key
, size_t key_len
);
1147 * AES key schedule for decryption ('aes_big' implementation).
1149 unsigned br_aes_big_keysched_inv(uint32_t *skey
,
1150 const void *key
, size_t key_len
);
1153 * AES block encryption with the 'aes_big' implementation (fast, but
1154 * not constant-time). This function encrypts a single block "in place".
1156 void br_aes_big_encrypt(unsigned num_rounds
, const uint32_t *skey
, void *data
);
1159 * AES block decryption with the 'aes_big' implementation (fast, but
1160 * not constant-time). This function decrypts a single block "in place".
1162 void br_aes_big_decrypt(unsigned num_rounds
, const uint32_t *skey
, void *data
);
1165 * AES block encryption with the 'aes_small' implementation (small, but
1166 * slow and not constant-time). This function encrypts a single block
1169 void br_aes_small_encrypt(unsigned num_rounds
,
1170 const uint32_t *skey
, void *data
);
1173 * AES block decryption with the 'aes_small' implementation (small, but
1174 * slow and not constant-time). This function decrypts a single block
1177 void br_aes_small_decrypt(unsigned num_rounds
,
1178 const uint32_t *skey
, void *data
);
1181 * The constant-time implementation is "bitsliced": the 128-bit state is
1182 * split over eight 32-bit words q* in the following way:
1184 * -- Input block consists in 16 bytes:
1185 * a00 a10 a20 a30 a01 a11 a21 a31 a02 a12 a22 a32 a03 a13 a23 a33
1186 * In the terminology of FIPS 197, this is a 4x4 matrix which is read
1189 * -- Each byte is split into eight bits which are distributed over the
1190 * eight words, at the same rank. Thus, for a byte x at rank k, bit 0
1191 * (least significant) of x will be at rank k in q0 (if that bit is b,
1192 * then it contributes "b << k" to the value of q0), bit 1 of x will be
1193 * at rank k in q1, and so on.
1195 * -- Ranks given to bits are in "row order" and are either all even, or
1196 * all odd. Two independent AES states are thus interleaved, one using
1197 * the even ranks, the other the odd ranks. Row order means:
1198 * a00 a01 a02 a03 a10 a11 a12 a13 a20 a21 a22 a23 a30 a31 a32 a33
1200 * Converting input bytes from two AES blocks to bitslice representation
1201 * is done in the following way:
1202 * -- Decode first block into the four words q0 q2 q4 q6, in that order,
1203 * using little-endian convention.
1204 * -- Decode second block into the four words q1 q3 q5 q7, in that order,
1205 * using little-endian convention.
1206 * -- Call br_aes_ct_ortho().
1208 * Converting back to bytes is done by using the reverse operations. Note
1209 * that br_aes_ct_ortho() is its own inverse.
1213 * Perform bytewise orthogonalization of eight 32-bit words. Bytes
1214 * of q0..q7 are spread over all words: for a byte x that occurs
1215 * at rank i in q[j] (byte x uses bits 8*i to 8*i+7 in q[j]), the bit
1216 * of rank k in x (0 <= k <= 7) goes to q[k] at rank 8*i+j.
1218 * This operation is an involution.
1220 void br_aes_ct_ortho(uint32_t *q
);
1223 * The AES S-box, as a bitsliced constant-time version. The input array
1224 * consists in eight 32-bit words; 32 S-box instances are computed in
1225 * parallel. Bits 0 to 7 of each S-box input (bit 0 is least significant)
1226 * are spread over the words 0 to 7, at the same rank.
1228 void br_aes_ct_bitslice_Sbox(uint32_t *q
);
1231 * Like br_aes_bitslice_Sbox(), but for the inverse S-box.
1233 void br_aes_ct_bitslice_invSbox(uint32_t *q
);
1236 * Compute AES encryption on bitsliced data. Since input is stored on
1237 * eight 32-bit words, two block encryptions are actually performed
1240 void br_aes_ct_bitslice_encrypt(unsigned num_rounds
,
1241 const uint32_t *skey
, uint32_t *q
);
1244 * Compute AES decryption on bitsliced data. Since input is stored on
1245 * eight 32-bit words, two block decryptions are actually performed
1248 void br_aes_ct_bitslice_decrypt(unsigned num_rounds
,
1249 const uint32_t *skey
, uint32_t *q
);
1252 * AES key schedule, constant-time version. skey[] is filled with n+1
1253 * 128-bit subkeys, where n is the number of rounds (10 to 14, depending
1254 * on key size). The number of rounds is returned. If the key size is
1255 * invalid (not 16, 24 or 32), then 0 is returned.
1257 unsigned br_aes_ct_keysched(uint32_t *comp_skey
,
1258 const void *key
, size_t key_len
);
1261 * Expand AES subkeys as produced by br_aes_ct_keysched(), into
1262 * a larger array suitable for br_aes_ct_bitslice_encrypt() and
1263 * br_aes_ct_bitslice_decrypt().
1265 void br_aes_ct_skey_expand(uint32_t *skey
,
1266 unsigned num_rounds
, const uint32_t *comp_skey
);
1269 * For the ct64 implementation, the same bitslicing technique is used,
1270 * but four instances are interleaved. First instance uses bits 0, 4,
1271 * 8, 12,... of each word; second instance uses bits 1, 5, 9, 13,...
1276 * Perform bytewise orthogonalization of eight 64-bit words. Bytes
1277 * of q0..q7 are spread over all words: for a byte x that occurs
1278 * at rank i in q[j] (byte x uses bits 8*i to 8*i+7 in q[j]), the bit
1279 * of rank k in x (0 <= k <= 7) goes to q[k] at rank 8*i+j.
1281 * This operation is an involution.
1283 void br_aes_ct64_ortho(uint64_t *q
);
1286 * Interleave bytes for an AES input block. If input bytes are
1287 * denoted 0123456789ABCDEF, and have been decoded with little-endian
1288 * convention (w[0] contains 0123, with '3' being most significant;
1289 * w[1] contains 4567, and so on), then output word q0 will be
1290 * set to 08192A3B (again little-endian convention) and q1 will
1291 * be set to 4C5D6E7F.
1293 void br_aes_ct64_interleave_in(uint64_t *q0
, uint64_t *q1
, const uint32_t *w
);
1296 * Perform the opposite of br_aes_ct64_interleave_in().
1298 void br_aes_ct64_interleave_out(uint32_t *w
, uint64_t q0
, uint64_t q1
);
1301 * The AES S-box, as a bitsliced constant-time version. The input array
1302 * consists in eight 64-bit words; 64 S-box instances are computed in
1303 * parallel. Bits 0 to 7 of each S-box input (bit 0 is least significant)
1304 * are spread over the words 0 to 7, at the same rank.
1306 void br_aes_ct64_bitslice_Sbox(uint64_t *q
);
1309 * Like br_aes_bitslice_Sbox(), but for the inverse S-box.
1311 void br_aes_ct64_bitslice_invSbox(uint64_t *q
);
1314 * Compute AES encryption on bitsliced data. Since input is stored on
1315 * eight 64-bit words, four block encryptions are actually performed
1318 void br_aes_ct64_bitslice_encrypt(unsigned num_rounds
,
1319 const uint64_t *skey
, uint64_t *q
);
1322 * Compute AES decryption on bitsliced data. Since input is stored on
1323 * eight 64-bit words, four block decryptions are actually performed
1326 void br_aes_ct64_bitslice_decrypt(unsigned num_rounds
,
1327 const uint64_t *skey
, uint64_t *q
);
1330 * AES key schedule, constant-time version. skey[] is filled with n+1
1331 * 128-bit subkeys, where n is the number of rounds (10 to 14, depending
1332 * on key size). The number of rounds is returned. If the key size is
1333 * invalid (not 16, 24 or 32), then 0 is returned.
1335 unsigned br_aes_ct64_keysched(uint64_t *comp_skey
,
1336 const void *key
, size_t key_len
);
1339 * Expand AES subkeys as produced by br_aes_ct64_keysched(), into
1340 * a larger array suitable for br_aes_ct64_bitslice_encrypt() and
1341 * br_aes_ct64_bitslice_decrypt().
1343 void br_aes_ct64_skey_expand(uint64_t *skey
,
1344 unsigned num_rounds
, const uint64_t *comp_skey
);
1346 /* ==================================================================== */
1352 * Type for generic EC parameters: curve order (unsigned big-endian
1353 * encoding) and encoded conventional generator.
1357 const unsigned char *order
;
1359 const unsigned char *generator
;
1360 size_t generator_len
;
1363 extern const br_ec_curve_def br_secp256r1
;
1364 extern const br_ec_curve_def br_secp384r1
;
1365 extern const br_ec_curve_def br_secp521r1
;
1368 * Type for the parameters for a "prime curve":
1369 * coordinates are in GF(p), with p prime
1370 * curve equation is Y^2 = X^3 - 3*X + b
1371 * b is in Montgomery representation
1372 * curve order is n and is prime
1373 * base point is G (encoded) and has order n
1379 } br_ec_prime_i31_curve
;
1381 extern const br_ec_prime_i31_curve br_ec_prime_i31_secp256r1
;
1382 extern const br_ec_prime_i31_curve br_ec_prime_i31_secp384r1
;
1383 extern const br_ec_prime_i31_curve br_ec_prime_i31_secp521r1
;
1385 #define BR_EC_I31_LEN ((BR_MAX_EC_SIZE + 61) / 31)
1388 * Decode some bytes as an i31 integer, with truncation (corresponding
1389 * to the 'bits2int' operation in RFC 6979). The target ENCODED bit
1390 * length is provided as last parameter. The resulting value will have
1391 * this declared bit length, and consists the big-endian unsigned decoding
1392 * of exactly that many bits in the source (capped at the source length).
1394 void br_ecdsa_i31_bits2int(uint32_t *x
,
1395 const void *src
, size_t len
, uint32_t ebitlen
);
1397 /* ==================================================================== */
1399 * SSL/TLS support functions.
1405 #define BR_SSL_CHANGE_CIPHER_SPEC 20
1406 #define BR_SSL_ALERT 21
1407 #define BR_SSL_HANDSHAKE 22
1408 #define BR_SSL_APPLICATION_DATA 23
1411 * Handshake message types.
1413 #define BR_SSL_HELLO_REQUEST 0
1414 #define BR_SSL_CLIENT_HELLO 1
1415 #define BR_SSL_SERVER_HELLO 2
1416 #define BR_SSL_CERTIFICATE 11
1417 #define BR_SSL_SERVER_KEY_EXCHANGE 12
1418 #define BR_SSL_CERTIFICATE_REQUEST 13
1419 #define BR_SSL_SERVER_HELLO_DONE 14
1420 #define BR_SSL_CERTIFICATE_VERIFY 15
1421 #define BR_SSL_CLIENT_KEY_EXCHANGE 16
1422 #define BR_SSL_FINISHED 20
1427 #define BR_LEVEL_WARNING 1
1428 #define BR_LEVEL_FATAL 2
1431 * Low-level I/O state.
1433 #define BR_IO_FAILED 0
1436 #define BR_IO_INOUT 3
1439 * Mark a SSL engine as failed. The provided error code is recorded if
1440 * the engine was not already marked as failed. If 'err' is 0, then the
1441 * engine is marked as closed (without error).
1443 void br_ssl_engine_fail(br_ssl_engine_context
*cc
, int err
);
1446 * Test whether the engine is closed (normally or as a failure).
1449 br_ssl_engine_closed(const br_ssl_engine_context
*cc
)
1451 return cc
->iomode
== BR_IO_FAILED
;
1455 * Configure a new maximum fragment length. If possible, the maximum
1456 * length for outgoing records is immediately adjusted (if there are
1457 * not already too many buffered bytes for that).
1459 void br_ssl_engine_new_max_frag_len(
1460 br_ssl_engine_context
*rc
, unsigned max_frag_len
);
1463 * Test whether the current incoming record has been fully received
1464 * or not. This functions returns 0 only if a complete record header
1465 * has been received, but some of the (possibly encrypted) payload
1466 * has not yet been obtained.
1468 int br_ssl_engine_recvrec_finished(const br_ssl_engine_context
*rc
);
1471 * Flush the current record (if not empty). This is meant to be called
1472 * from the handshake processor only.
1474 void br_ssl_engine_flush_record(br_ssl_engine_context
*cc
);
1477 * Test whether there is some accumulated payload to send.
1480 br_ssl_engine_has_pld_to_send(const br_ssl_engine_context
*rc
)
1482 return rc
->oxa
!= rc
->oxb
&& rc
->oxa
!= rc
->oxc
;
1486 * Initialize RNG in engine. Returned value is 1 on success, 0 on error.
1487 * This function will try to use the OS-provided RNG, if available. If
1488 * there is no OS-provided RNG, or if it failed, and no entropy was
1489 * injected by the caller, then a failure will be reported. On error,
1490 * the context error code is set.
1492 int br_ssl_engine_init_rand(br_ssl_engine_context
*cc
);
1495 * Reset the handshake-related parts of the engine.
1497 void br_ssl_engine_hs_reset(br_ssl_engine_context
*cc
,
1498 void (*hsinit
)(void *), void (*hsrun
)(void *));
1501 * Get the PRF to use for this context, for the provided PRF hash
1504 br_tls_prf_impl
br_ssl_engine_get_PRF(br_ssl_engine_context
*cc
, int prf_id
);
1507 * Consume the provided pre-master secret and compute the corresponding
1508 * master secret. The 'prf_id' is the ID of the hash function to use
1509 * with the TLS 1.2 PRF (ignored if the version is TLS 1.0 or 1.1).
1511 void br_ssl_engine_compute_master(br_ssl_engine_context
*cc
,
1512 int prf_id
, const void *pms
, size_t len
);
1515 * Switch to CBC decryption for incoming records.
1516 * cc the engine context
1517 * is_client non-zero for a client, zero for a server
1518 * prf_id id of hash function for PRF (ignored if not TLS 1.2+)
1519 * mac_id id of hash function for HMAC
1520 * bc_impl block cipher implementation (CBC decryption)
1521 * cipher_key_len block cipher key length (in bytes)
1523 void br_ssl_engine_switch_cbc_in(br_ssl_engine_context
*cc
,
1524 int is_client
, int prf_id
, int mac_id
,
1525 const br_block_cbcdec_class
*bc_impl
, size_t cipher_key_len
);
1528 * Switch to CBC encryption for outgoing records.
1529 * cc the engine context
1530 * is_client non-zero for a client, zero for a server
1531 * prf_id id of hash function for PRF (ignored if not TLS 1.2+)
1532 * mac_id id of hash function for HMAC
1533 * bc_impl block cipher implementation (CBC encryption)
1534 * cipher_key_len block cipher key length (in bytes)
1536 void br_ssl_engine_switch_cbc_out(br_ssl_engine_context
*cc
,
1537 int is_client
, int prf_id
, int mac_id
,
1538 const br_block_cbcenc_class
*bc_impl
, size_t cipher_key_len
);
1541 * Switch to GCM decryption for incoming records.
1542 * cc the engine context
1543 * is_client non-zero for a client, zero for a server
1544 * prf_id id of hash function for PRF
1545 * bc_impl block cipher implementation (CTR)
1546 * cipher_key_len block cipher key length (in bytes)
1548 void br_ssl_engine_switch_gcm_in(br_ssl_engine_context
*cc
,
1549 int is_client
, int prf_id
,
1550 const br_block_ctr_class
*bc_impl
, size_t cipher_key_len
);
1553 * Switch to GCM encryption for outgoing records.
1554 * cc the engine context
1555 * is_client non-zero for a client, zero for a server
1556 * prf_id id of hash function for PRF
1557 * bc_impl block cipher implementation (CTR)
1558 * cipher_key_len block cipher key length (in bytes)
1560 void br_ssl_engine_switch_gcm_out(br_ssl_engine_context
*cc
,
1561 int is_client
, int prf_id
,
1562 const br_block_ctr_class
*bc_impl
, size_t cipher_key_len
);
1565 * Switch to ChaCha20+Poly1305 decryption for incoming records.
1566 * cc the engine context
1567 * is_client non-zero for a client, zero for a server
1568 * prf_id id of hash function for PRF
1570 void br_ssl_engine_switch_chapol_in(br_ssl_engine_context
*cc
,
1571 int is_client
, int prf_id
);
1574 * Switch to ChaCha20+Poly1305 encryption for outgoing records.
1575 * cc the engine context
1576 * is_client non-zero for a client, zero for a server
1577 * prf_id id of hash function for PRF
1579 void br_ssl_engine_switch_chapol_out(br_ssl_engine_context
*cc
,
1580 int is_client
, int prf_id
);
1583 * Calls to T0-generated code.
1585 void br_ssl_hs_client_init_main(void *ctx
);
1586 void br_ssl_hs_client_run(void *ctx
);
1587 void br_ssl_hs_server_init_main(void *ctx
);
1588 void br_ssl_hs_server_run(void *ctx
);
1591 * Get the hash function to use for signatures, given a bit mask of
1592 * supported hash functions. This implements a strict choice order
1593 * (namely SHA-256, SHA-384, SHA-512, SHA-224, SHA-1). If the mask
1594 * does not document support of any of these hash functions, then this
1595 * functions returns 0.
1597 int br_ssl_choose_hash(unsigned bf
);
1599 /* ==================================================================== */