Add Stb99 paramgen (#47)

* Start stb99

* Update pfok and stb99

* Start test/stb99

* Update test/stb99

* Update crypto/stb99

* Fix bug in priExtendPrime2

* Add stb99ValSeed()

* Finish stb99

include/bee2/core/err.h

@@ -4,7 +4,7 @@
 \brief Errors
 \project bee2 [cryptographic library]
 \created 2012.07.09
-\version 2023.06.13
+\version 2023.09.08
 \copyright The Bee2 authors
 \license Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
 *******************************************************************************
@@ -208,6 +208,8 @@ Crypto
 #define ERR_SELFTEST				_ERR_REG(521)
 /* ошибка статистического тестирования */
 #define ERR_STATTEST				_ERR_REG(522)
+/* некорректные затравочные параметры */
+#define ERR_BAD_SEED				_ERR_REG(523)
 
 /*
 *******************************************************************************

include/bee2/crypto/pfok.h

@@ -4,7 +4,7 @@
 \brief Draft of RD_RB: key establishment protocols based on finite fields
 \project bee2 [cryptographic library]
 \created 2014.06.30
-\version 2023.02.02
+\version 2023.09.11
 \copyright The Bee2 authors
 \license Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
 *******************************************************************************
@@ -34,8 +34,7 @@ extern "C" {
 
 Реализованы протоколы Проекта РД РБ (pfok). При ссылках на протоколы, таблицы, 
 другие объекты подразумеваются разделы Проекта, в которых эти объекты 
-определены. Дополнительно используются данные, представленные 
-в СТБ П 34.101.50. 
+определены. Дополнительно используются данные, представленные в СТБ 34.101.50.
 
 \expect{ERR_BAD_INPUT} Все входные указатели корректны.
 
@@ -50,50 +49,56 @@ extern "C" {
 \section pfok-params Долговременные параметры
 
 Структура pfok_params описывает долговременные параметры pfok. Содержание 
-полей структуры определено в пунктах 3, 5.1, 5.2. 
+полей структуры определено в разделах 3, 5.1, 5.2. 
 
 В структуре pfok_params параметр l определяет используемое число октетов 
-в массивах p, g: используется O_OF_B(l) октетов. Неиспользуемые октеты 
-игнорируются. Параметр r определяет битовую длину личного ключа, 
+в массивах p, g: используется O_OF_B(l) октетов. Неиспользуемые октеты
+заполняются нулями. Параметр r определяет битовую длину личного ключа, 
 параметр n -- общего секретного. 
 
 Размерности l, r, n фигурирует в описаниях функций.
 
 Ограничения:
 -	l и r выбираются из таблицы 5.1;
--	p -- простое число битовой длины l. 
-	Число p определяет группу B_p. Эта группа чисел от 1 до p - 1 с операцией 
-	умножения Монтгомери: 
+-	p -- простое число битовой длины l такое, что q = (p - 1) / 2 простое. 
+	Число p определяет группу Монтгомери B_p. Эта группа неотрицательных 
+	вычетов mod p c операцией умножения Монтгомери: 
 	\code
-		a \circ b = a b R^{-1} \bmod p, R = 2^{l + 2};
+		u \circ v = u v R^{-1} \bmod p, R = 2^{l + 2};
 	\endcode
-	Возведение в степень в B_p обозначается круглыми скобками: a^(b) --- 
-	произведение Монтгомери b экземпляров элемента a;
+	Возведение в степень в B_p обозначается круглыми скобками: u^(v) --- 
+	произведение Монтгомери v экземпляров элемента u;
 -	0 < g < p;
--	g -- образующий группы B_p.
+-	g имеет порядок q в группе B_p. В протоколах используется группа GG,
+	порожденная g.
 .
 
 Размерности массивов p и g соответствуют максимальному значению l = 2942 
 (см. табл. 5.1).
 
-Структура pfok_seed описывает затравочные данные, по которым генерируются 
-долговременные параметры или проверяется результат генерации. 
-Ограничения на затравочные данные:
--	z[i] \in {1, 2,..., 65256};
--	массив (цепочка) lt начинается с числа lt[0] == 0 и заканчивается числом 
-	lt[t] \in {17,...,32}. Элементы массива после lt[t] игнорируются;
--	5 * lt[i + 1] / 4 + 4 < lt[i];
--	lt[i] <= 2 * lt[i + 1].
+Структура pfok_seed описывает затравочные параметры, по которым генерируются 
+долговременные параметры или проверяется результат генерации.
+
+Ограничения на затравочные параметры указаны в описании функции pfokValSeed().
+
+
+Ограничения на затравочные параметры:
+-	размерность l соответствует определенному уровню стойкости;
+-	zi[i] \in {1, 2,..., 65256};
+-	массив (цепочка) li начинается с числа li[0] = l - 1 и заканчивается числом
+	li[t] \in {17,...,32}, после которого идут нули;
+-	5 * li[i + 1] / 4 + 4 < li[i] <= 2 * li[i + 1], 0 <= i < t.
 .
 
-Размерности массива lt соответствуют следующей цепочке максимальной длины:
+Размерности массива li соответствуют следующей цепочке максимальной длины:
 	2941, 2349, 1875, 1496, 1193, 951, 757, 602, 478, 379, 299, 235, 184, 
 	143, 111, 85, 64, 47, 34, 23.
+Первый элемент цепочки: 2942 - 1.
+Следующий элемент определяется по текущему элементу x как (4 * x - 17) / 5.
 
-Параметр p имеет вид 2q + 1, где q -- (l - 1)-битовое простое. При генерации
-параметров простые числа q строятся до тех пор, пока 2q + 1 не окажется 
-простым. Процедура генерации параметров может быть очень длительной. Поэтому
-в функцию генерации параметров можно передавать указатель на функцию
+При генерации p = 2q + 1 простые числа q строятся до тех пор, пока 2q + 1 не 
+окажется простым. Процедура генерации параметров может быть очень длительной. 
+Поэтому в функцию генерации параметров можно передавать указатель на функцию
 интерфейса pfok_on_q_i, которая получает управление при построении каждого 
 нового кандидата q.
 *******************************************************************************
@@ -102,18 +107,19 @@ extern "C" {
 /*!	\brief Долговременные параметры */
 typedef struct
 {
-	u32 l;			/*!< битовая длина p */
-	u32 r;			/*!< битовая длина личного ключа */
-	u32 n;			/*!< битовая длина общего ключа */
-	octet p[368];	/*!< модуль p */
-	octet g[368];	/*!< образующий g */
+	size_t l;			/*!< битовая длина p */
+	size_t r;			/*!< битовая длина личного ключа */
+	size_t n;			/*!< битовая длина общего ключа */
+	octet p[368];		/*!< модуль p */
+	octet g[368];		/*!< образующий g */
 } pfok_params;
 
 /*!	\brief Затравочные данные */
 typedef struct
 {
-	u16 z[31];		/*!< числа z[i] */
-	u32 lt[20];		/*!< цепочка lt[i] */
+	size_t l;			/*!< битовая длина p */
+	u16 zi[31];			/*!< числа zi[i] */
+	size_t li[20];		/*!< цепочка li */
 } pfok_seed;
 
 /*!	\brief Обработка нового числа q
@@ -130,30 +136,61 @@ typedef void (*pfok_on_q_i) (
 	size_t num				/*!< [in] номер попытки */
 );
 
+/*!	\brief Проверка затравочных параметров
+
+	Проверяется, что затравочные параметры seed корректны:
+	-	размерность l соответствует определенному уровню стойкости;
+	-	zi[i] \in {1, 2,..., 65256};
+	-	массив (цепочка) li начинается с числа li[0] = l - 1 и заканчивается
+		числом li[t] \in {17,...,32}, после которого идут нули;
+	-	5 * li[i + 1] / 4 + 4 < li[i] <= 2 * li[i + 1], 0 <= i < t.
+	.
+	\return ERR_OK, если параметры корректны, и код ошибки в противном случае.
+*/
+err_t pfokValSeed(
+	const pfok_seed* seed	/*!< [in] затравочные параметры */
+);
+
+/*!	\brief Настройка затравочных параметров
+
+	В структуре seed незаполненным (нулевым) параметрам seed->zi и seed->li
+	присваиваются значения по умолчанию. Эти значения определяются с участием
+	seed->l следующим образом:
+	-	zi[0] = 1,..., zi[30] = 31;
+	-	li[0] = l - 1, li[1] = li[0] / 2 + 1, ...,
+			li[t] = li[t - 1] / 2 + 1 \in {17,..., 32}, 0, ...., 0.
+	.
+	\return ERR_OK, если итоговые параметры корректны, и код ошибки
+	в противном случае.
+*/
+err_t pfokAdjSeed(
+	pfok_seed* seed		/*!< [in/out] затравочные параметры */
+);
+
 /*!	\brief Загрузка стандартных долговременных параметров
 
 	В params загружаются стандартные долговременные параметры с именем name, 
-	а в seed -- затравочные данные, на которых получены params. Указатель
-	seed может быть нулевым, и в этом случае затравочные данные не загружаются.
+	а в seed -- затравочные параметры, на которых получены params. Указатель
+	seed может быть нулевым, и в этом случае затравочные параметры не загружаются.
 	Поддерживаются следующие имена:
 		"1.2.112.0.2.0.1176.2.3.3.2",
 		"1.2.112.0.2.0.1176.2.3.6.2",
 		"1.2.112.0.2.0.1176.2.3.10.2".
-	Это имена стандартных параметров, заданных в таблице В.3 СТБ П 34.101.50.
+	Это имена стандартных параметров, заданных в таблице В.3 СТБ 34.101.50.
 	Дополнительно поддерживается имя "test" тестовых параметров первого 
 	уровня стойкости (l == 638).
 	\return ERR_OK, если параметры успешно загружены, и код ошибки в
 	противном случае.
 */
 err_t pfokStdParams(
 	pfok_params* params,	/*!< [out] стандартные параметры */
-	pfok_seed* seed,		/*!< [out] затравочные данные */
+	pfok_seed* seed,		/*!< [out] затравочные параметры */
 	const char* name		/*!< [in] имя параметров */
 );
 
 /*!	\brief Генерация долговременных параметров
 
-	По затравочным данным seed генерируются долговременные параметры params.
+	По затравочным параметрам seed генерируются долговременные параметры params.
 	При построении очередного числа q, по которому определяется params->p, 
 	вызывается функция on_q.
 	\return ERR_OK, если параметры успешно сгенерированы, и код ошибки
@@ -165,7 +202,7 @@ err_t pfokStdParams(
 */
 err_t pfokGenParams(
 	pfok_params* params,	/*!< [out] долговременные параметры */
-	const pfok_seed* seed,	/*!< [in] затравочные данные */
+	const pfok_seed* seed,	/*!< [in] затравочные параметры */
 	pfok_on_q_i on_q		/*!< [in] обработчик */
 );
 
@@ -179,7 +216,7 @@ err_t pfokGenParams(
 	-	p -- l-битовое простое число;
 	-	q = (p - 1) / 2 -- простое;
 	-	g < p;
-	-	g является образующим группы B_p.
+	-	g имеет порядок q в группе Монтгомери mod p.
 	.
 	\return ERR_OK, если параметры корректны, и код ошибки в противном случае.
 	\warning Не проверяется, что p построен по алгоритму 5.2.