1dstu.h(3) Library Functions Manual dstu.h(3)
2
6 dstu.h - Алгоритмы ДСТУ 4145-2002 (Украина)
7
10 #include 'bee2/defs.h'
11 Классы
14 struct dstu_params
15 Долговременные параметры dstu.
16 Функции
18 err_t dstuStdParams (dstu_params *params, const char *name)
19 Загрузка стандартных долговременных параметров
20 err_t dstuValParams (const dstu_params *params)
21 Проверка долговременных параметров
22 err_t dstuGenPoint (octet point[], const dstu_params *params, gen_i
23 rng, void *rng_state)
24 Генерация точки
25 err_t dstuValPoint (const dstu_params *params, const octet point[])
26 Проверка точки
27 err_t dstuCompressPoint (octet xpoint[], const dstu_params *params,
28 const octet point[])
29 Сжатие точки
30 err_t dstuRecoverPoint (octet point[], const dstu_params *params, const
31 octet xpoint[])
32 Восстановление точки
33 err_t dstuGenKeypair (octet privkey[], octet pubkey[], const
34 dstu_params *params, gen_i rng, void *rng_state)
35 Генерация пары ключей
36 err_t dstuSign (octet sig[], const dstu_params *params, size_t ld,
37 const octet hash[], size_t hash_len, const octet privkey[], gen_i
38 rng, void *rng_state)
39 Выработка ЭЦП
40 err_t dstuVerify (const dstu_params *params, size_t ld, const octet
41 hash[], size_t hash_len, const octet sig[], const octet pubkey[])
42 Проверка ЭЦП
43
45 Реализованы алгоритмы украинского стандарта ДСТУ 4145-2002.
46 Поля структуры долговременных параметров обозначаются также как в ДСТУ.
48 Максимальная размерность DSTU_SIZE соответствуют неприводимому
50 многочлену степени 509, указанному в ДСТУ.
51 Базовое поле f = GF(2^m) описывается массивом из 4 размерностей,
53 задающих полиномиальный или нормальный базисы. Первый элемент массива
54 p[0] -- это степень расширения m поля f, элементы массива невозрастают:
55 p[0] >= p[1] >= p[2] >= p[3].
56 В полиномиальном базисе поле строится как кольцо вычетов GF(2) /
58 (p(x)), где p(x) –- неприводимый трехчлен или пятичлен степени m.
59 Многочлен p(x) определяется следующим образом: p(x) = x^p[0] + x^p[1] +
60 x^p[2] + x^p[3] + 1. При p[2] == 0 должно выполняться также p[3] == 0 и
61 p(x) -- трехчлен.
62 Нормальный базис задается установкой p[0] = m, p[1] = p[2] = p[3] = 0.
64 Операции в нормальном базисе не реализованы.
65 Степень m базового поля f определяет используемое число октетов в
67 массиве dstu_params::B: в этом массиве используется O_OF_B(m) октет. В
68 буфере сжатой точки xpoint также используется O_OF_B(m) октет. В
69 массиве dstu_params::P, в буферах открытого ключа pubkey и точки point
70 используется 2 * O_OF_B(m) октетов.
71 В структуре dstu_params неиспользуемые октеты могут быть заданы
73 произвольным образом.
74 Порядок группы точек dstu_params::n не превосходит (2^m + 1 + 2 * 2^{m
76 / 2}) / c, где кофактор c >= 2. Таким образом, порядок dstu_params::n
77 укладывается в O_OF_B(m) октетов и даже, может быть, в меньшее число
78 октетов.
79 Прим.
81 Кофактор c >= 2, поскольку точка (0, \sqrt(dstu_params::B)) лежит
82 на кривой и имеет порядок 2.
83 Для стандартных кривых, заданных в приложении Г, кофактор равняется
85 2 при dstu_params::A == 1 или 4 при dstu_params::A == 0.
86 В буфере личного ключа privkey используется order_no октетов, где
88 order_no -- число значащих (без завершающих нулевых) октетов буфера
89 [O_OF_B(m)]dstu_params::n, т. е. длина числа dstu_params::n в октетах.
90 Ожидается [ERR_BAD_INPUT]
92 Все входные указатели корректны.
93 Регулярность
95 todo
96
98 err_t dstuCompressPoint (octet xpoint[], const dstu_params * params, const
99 octet point[])
100 Точка point эллиптической кривой, заданной долговременными параметрами
101 params, сжимается в точку xpoint.
102 Ожидается [ERR_BAD_PARAMS]
104 Параметры params корректны.
105 Возвращает
107 ERR_OK, если точка сжата, и код ошибки в противном случае.
108 Прим.
110 Реализован алгоритм из раздела 6.9 ДСТУ.
111 Буферы point и xpoint могут пересекаться.
113 Аргументы
115 xpoint сжатая точка
116 params параметры
117 point сжимаемая точка
118 err_t dstuGenKeypair (octet privkey[], octet pubkey[], const dstu_params *
120 params, gen_i rng, void * rng_state)
121 Для заданных параметров params генерируются личный и открытый ключи
122 privkey и pubkey ключи. При генерации используется генератор rng и его
123 состояние rng_state.
124 Ожидается [ERR_BAD_PARAMS]
126 Параметры params корректны.
127 Ожидается [ERR_BAD_RNG]
129 Генератор rng (с состоянием rng_state) корректен.
130 Ожидается
132 Используется криптографически стойкий генератор rng.
133 Возвращает
135 ERR_OK, если ключи сгенерированы, и код ошибки в противном случае.
136 Прим.
138 Реализован алгоритм из раздела 9 ДСТУ.
139 Аргументы
141 privkey личный ключ
142 pubkey открытый ключ
143 params долговременные параметры
144 rng генератор случайных чисел
145 rng_state состояние генератора
146 err_t dstuGenPoint (octet point[], const dstu_params * params, gen_i rng,
148 void * rng_state)
149 Генерируется точка point эллиптической кривой, заданной долговременными
150 параметрами params. При генерации используется генератор rng и его
151 состояние rng_state. Дополнительно проверяется, что порядок point
152 равняется params->n.
153 Ожидается [ERR_BAD_PARAMS]
155 Параметры params (кроме базовой точки P) корректны.
156 Возвращает
158 ERR_OK, если точка сгенерирована, и код ошибки в противном случае.
159 Прим.
161 Указатели point и params->P могут совпадать.
162 Реализован алгоритм из раздела 6.8 ДСТУ.
164 Аргументы
166 point точка
167 params долговременные параметры
168 rng генератор случайных чисел
169 rng_state состояние генератора
170 err_t dstuRecoverPoint (octet point[], const dstu_params * params, const
172 octet xpoint[])
173 Точка point эллиптической кривой, заданной долговременными параметрами
174 params, восстанавливается из x-координаты (point->x).
175 Ожидается [ERR_BAD_PARAMS]
177 Параметры params корректны.
178 Возвращает
180 ERR_OK, если точка восстановлена, и код ошибки в противном случае.
181 Прим.
183 Реализован алгоритм из раздела 6.10 ДСТУ.
184 Буферы point и xpoint могут пересекаться.
186 Аргументы
188 point восстановленная точка
189 params параметры
190 xpoint сжатая точка
191 err_t dstuSign (octet sig[], const dstu_params * params, size_t ld, const
193 octet hash[], size_t hash_len, const octet privkey[], gen_i rng, void *
194 rng_state)
195 Вырабатывается подпись [ld / 8]sig сообщения с хэш-значением
196 [hash_len]hash. Подпись вырабатывается на личном ключе privkey. При
197 выработке ЭЦП используются долговременные параметры params и генератор
198 rng c состоянием rng_state.
199 Ожидается [ERR_BAD_PARAMS]
201 Параметры params корректны.
202 Ожидается [ERR_BAD_INPUT]
204 :
205 • ld делится на 16;
207 • два вычета по модулю params->n укладываются в ld битов.
209 Ожидается [ERR_BAD_PRIVKEY]
211 Личный ключ privkey корректен.
212 Ожидается [ERR_BAD_RNG]
214 Генератор rng (с состоянием rng_state) корректен.
215 Ожидается
217 Используется криптографически стойкий генератор rng.
218 Возвращает
220 ERR_OK, если подпись выработана, и код ошибки в противном случае.
221 Аргументы
223 sig подпись
224 params долговременные параметры
225 ld длина подписи в битах
226 hash хэш-значение
227 hash_len длина хэш-значения в октетах
228 privkey личный ключ
229 rng генератор случайных чисел
230 rng_state состояние генератора
231 err_t dstuStdParams (dstu_params * params, const char * name)
233 В params загружаются стандартные долговременные параметры с именем
234 name. Поддерживаются имена '1.2.804.2.1.1.1.1.3.1.1.1.2.0', ...,
235 '1.2.112.0.2.0.34.101.45.3.2.9'. Это имена стандартных эллиптических
236 кривых, заданных в таблице Г.2. Первым именем названа кривая над
237 GF(2^163), последним -- кривая над GF(2^431).
238 Возвращает
240 ERR_OK, если параметры загружены, и код ошибки в противном случае.
241 Прим.
243 Имена (идентификаторы) параметров взяты из файла
244 http://www.crypto.org.ua/Media/Default/patches/dstu101e.patch
245 (patch для OpenSSL).
246 ДСТУ не определяет стандартные базовые точки. Их надо генерировать
248 дополнительно, например, с помощью функции dstuGenPoint().
249 Аргументы
251 params стандартные параметры
252 name имя параметров
253 err_t dstuValParams (const dstu_params * params)
255 Проверяется корректность долговременных параметров params.
256 Возвращает
258 ERR_OK, если параметры корректны, и код ошибки в противном случае.
259 Прим.
261 Проверяется корректность в том числе и базовой точки P.
262 Аргументы
264 params параметры
265 err_t dstuValPoint (const dstu_params * params, const octet point[])
267 Проверяется, что точка point эллиптической кривой, заданной
268 долговременными параметрами params, удовлетворяет требованиям ДСТУ.
269 Ожидается [ERR_BAD_PARAMS]
271 Параметры params корректны.
272 Возвращает
274 ERR_OK, если точка корректна, и код ошибки в противном случае.
275 Прим.
277 Реализован алгоритм из раздела 10.1 ДСТУ.
278 Аргументы
280 params долговременные параметры
281 point проверяемая точка
282 err_t dstuVerify (const dstu_params * params, size_t ld, const octet
284 hash[], size_t hash_len, const octet sig[], const octet pubkey[])
285 Проверяется подпись [ld / 8]sig сообщения с хэш-значением
286 [hash_len]hash. При проверке используются долговременные параметры
287 params и открытый ключ pubkey.
288 Ожидается [ERR_BAD_PARAMS]
290 Параметры params корректны.
291 Ожидается [ERR_BAD_PUBKEY]
293 Открытый ключ pubkey корректен.
294 Возвращает
296 ERR_OK, если подпись корректна, и код ошибки в противном случае.
297 Аргументы
299 params долговременные параметры
300 ld длина подписи в битах
301 hash хэш-значение
302 hash_len длина хэш-значения в октетах
303 sig подпись
304 pubkey открытый ключ
305
307 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
308Библиотека Bee2 Пт 23 Июн 2023 dstu.h(3)