1bign.h(3) Library Functions Manual bign.h(3)
2
3
4
6 bign.h - Алгоритмы СТБ 34.101.45 (bign)
7
8
10 #include 'bee2/defs.h'
11
12
13 Классы
14 struct bign_params
15 Долговременные параметры bign.
16
17 Функции
18 err_t bignStdParams (bign_params *params, const char *name)
19 Загрузка стандартных долговременных параметров
20 err_t bignValParams (const bign_params *params)
21 Проверка долговременных параметров
22 err_t bignOidToDER (octet oid_der[], size_t *oid_len, const char *oid)
23 Кодирование идентификатора объекта
24 err_t bignGenKeypair (octet privkey[], octet pubkey[], const
25 bign_params *params, gen_i rng, void *rng_state)
26 Генерация пары ключей
27 err_t bignValKeypair (const bign_params *params, const octet privkey[],
28 const octet pubkey[])
29 Проверка пары ключей
30 err_t bignValPubkey (const bign_params *params, const octet pubkey[])
31 Проверка открытого ключа
32 err_t bignCalcPubkey (octet pubkey[], const bign_params *params, const
33 octet privkey[])
34 Построение открытого ключа по личному
35 err_t bignDH (octet key[], const bign_params *params, const octet
36 privkey[], const octet pubkey[], size_t key_len)
37 Построение общего ключа протокола Диффи -- Хеллмана
38 err_t bignSign (octet sig[], const bign_params *params, const octet
39 oid_der[], size_t oid_len, const octet hash[], const octet
40 privkey[], gen_i rng, void *rng_state)
41 Выработка ЭЦП
42 err_t bignSign2 (octet sig[], const bign_params *params, const octet
43 oid_der[], size_t oid_len, const octet hash[], const octet
44 privkey[], const void *t, size_t t_len)
45 Детерминированная выработка ЭЦП
46 err_t bignVerify (const bign_params *params, const octet oid_der[],
47 size_t oid_len, const octet hash[], const octet sig[], const octet
48 pubkey[])
49 Проверка ЭЦП
50 err_t bignKeyWrap (octet token[], const bign_params *params, const
51 octet key[], size_t len, const octet header[16], const octet
52 pubkey[], gen_i rng, void *rng_state)
53 Создание токена ключа
54 err_t bignKeyUnwrap (octet key[], const bign_params *params, const
55 octet token[], size_t len, const octet header[16], const octet
56 privkey[])
57 Разбор токена ключа
58 err_t bignIdExtract (octet id_privkey[], octet id_pubkey[], const
59 bign_params *params, const octet oid_der[], size_t oid_len, const
60 octet id_hash[], const octet sig[], octet pubkey[])
61 Извлечение пары ключей
62 err_t bignIdSign (octet id_sig[], const bign_params *params, const
63 octet oid_der[], size_t oid_len, const octet id_hash[], const octet
64 hash[], const octet id_privkey[], gen_i rng, void *rng_state)
65 Выработка идентификационной ЭЦП
66 err_t bignIdSign2 (octet id_sig[], const bign_params *params, const
67 octet oid_der[], size_t oid_len, const octet id_hash[], const octet
68 hash[], const octet id_privkey[], const void *t, size_t t_len)
69 Детерминированная выработка идентификационной ЭЦП
70 err_t bignIdVerify (const bign_params *params, const octet oid_der[],
71 size_t oid_len, const octet id_hash[], const octet hash[], const
72 octet id_sig[], const octet id_pubkey[], const octet pubkey[])
73 Проверка идентификационной ЭЦП
74
77 Реализованы алгоритмы СТБ 34.101.45 (bign). При ссылках на алгоритмы,
78 таблицы, другие объекты подразумеваются разделы СТБ 34.101.45-2013, в
79 которых эти объекты определены.
80
81 Ожидается [ERR_BAD_INPUT]
82 Все входные указатели корректны.
83
84 Регулярность
85 todo
86
88 В функциях ЭЦП используется идентификатор используемого алгоритма
89 хэширования. Идентификатор представляет собой последовательность
90 неотрицательных целых чисел {d1 d2 ... dn}. Эта последовательность
91 должна удовлетворять базовым ограничениям ACH.1 (см. приложение A) и,
92 дополнительно, числа di не должны превосходить 2^32 - 1 = 4294967295.
93
94 Идентификатор задается либо строкой 'd1.d2....dn', либо DER-кодом. Если
95 идентификатор задается строкой, то числа di должны записываться без
96 лидирующих нулей.
97
98 Функция bignOidEncode() выполняет преобразование строкового
99 представления в DER-код.
100
101 Если идентификатор некорректен, то функции, в которых он используется,
102 возвращают код ERR_BAD_OID.
103
105 Идентификационная подпись при передаче и хранении должна объединяться с
106 открытым ключом (см. Д.3). Объединенная подпись состоит из 7 * l / 8
107 октетов и включает две части: первая часть -- собственно подпись (3 * l
108 / 8 октетов), вторая часть -- открытый ключ (l / 2 октетов).
109
111 err_t bignCalcPubkey (octet pubkey[], const bign_params * params, const
112 octet privkey[])
113 При долговременных параметрах params по личному ключу [l / 4]privkey
114 строится открытый ключ [l / 2]pubkey.
115
116 Ожидается [ERR_BAD_PARAMS]
117 Параметры params корректны.
118
119 Ожидается [ERR_BAD_PRIVKEY]
120 Личный ключ privkey корректен.
121
122 Возвращает
123 ERR_OK, если открытый ключ успешно построен, и код ошибки в
124 противном случае.
125
126 Аргументы
127 pubkey открытый ключ
128 params долговременные параметры
129 privkey личный ключ
130
131 err_t bignDH (octet key[], const bign_params * params, const octet
132 privkey[], const octet pubkey[], size_t key_len)
133 При долговременных параметрах params по личному ключу [l / 4]privkey и
134 открытому ключу [l / 2]pubkey противоположной стороны строится общий
135 ключ [key_len]key. Общий ключ определяется как privkey-кратное ключа
136 pubkey, что соответствует протоколу Диффи -- Хеллмана.
137
138 Ожидается [ERR_BAD_PARAMS]
139 Параметры params корректны.
140
141 Ожидается [ERR_BAD_PRIVKEY]
142 Личный ключ privkey корректен.
143
144 Ожидается [ERR_BAD_PUBKEY]
145 Открытый ключ pubkey корректен.
146
147 Ожидается [ERR_BAD_SHAREDKEY]
148 key_len <= l / 2.
149
150 Возвращает
151 ERR_OK, если общий ключ успешно построен, и код ошибки в противном
152 случае.
153
154 Аргументы
155 key общий ключ
156 params долговременные параметры
157 privkey личный ключ
158 pubkey открытый ключ (другой стороны)
159 key_len длина key в октетах
160
161 err_t bignGenKeypair (octet privkey[], octet pubkey[], const bign_params *
162 params, gen_i rng, void * rng_state)
163 При долговременных параметрах params генерируются личный [l / 4]privkey
164 и открытый [l / 2]pubkey ключи. При генерации используется генератор
165 rng и его состояние rng_state.
166
167 Ожидается [ERR_BAD_PARAMS]
168 Параметры params корректны.
169
170 Ожидается [ERR_BAD_RNG]
171 Генератор rng (с состоянием rng_state) корректен.
172
173 Ожидается
174 Используется криптографически стойкий генератор rng.
175
176 Возвращает
177 ERR_OK, если ключи успешно сгенерированы, и код ошибки в противном
178 случае.
179
180 Прим.
181 Реализован алгоритм 6.2.2.
182
183 Аргументы
184 privkey личный ключ
185 pubkey открытый ключ
186 params долговременные параметры
187 rng генератор случайных чисел
188 rng_state состояние генератора
189
190 err_t bignIdExtract (octet id_privkey[], octet id_pubkey[], const
191 bign_params * params, const octet oid_der[], size_t oid_len, const
192 octet id_hash[], const octet sig[], octet pubkey[])
193 Из подписи [3 * l / 8]sig идентификатора с хэш-значением [l / 4]id_hash
194 извлекаются личный [l / 4]id_privkey и открытый [l / 2]id_pubkey ключи.
195 Используются долговременные параметры params и открытый ключ [l /
196 2]pubkey доверенной стороны. Считается, что хэш-значение id_hash
197 получено с помощью алгоритма с идентификатором [oid_len]oid_der,
198 заданным DER-кодом.
199
200 Ожидается [ERR_BAD_PARAMS]
201 Параметры params корректны.
202
203 Ожидается [ERR_BAD_OID]
204 Идентификатор oid_der корректен.
205
206 Ожидается [ERR_BAD_PUBKEY]
207 Открытый ключ pubkey корректен.
208
209 Возвращает
210 ERR_OK, если ключи успешно извлечены, и код ошибки в противном
211 случае.
212
213 Прим.
214 Реализован алгоритм B.2.3.
215
216 Одновременно с извлечением ключей проверяется подпись sig. Если
217 подпись некорректна, то будет возвращен код ERR_BAD_SIG.
218
219 Аргументы
220 id_privkey личный ключ
221 id_pubkey открытый ключ
222 params долговременные параметры
223 oid_der идентификатор хэш-алгоритма
224 oid_len длина oid_der в октетах
225 id_hash хэш-значение идентификатора
226 sig подпись идентификатора
227 pubkey открытый ключ доверенной стороны
228
229 err_t bignIdSign (octet id_sig[], const bign_params * params, const octet
230 oid_der[], size_t oid_len, const octet id_hash[], const octet hash[],
231 const octet id_privkey[], gen_i rng, void * rng_state)
232 Вырабатывается идентификационная подпись [3 * l / 8]id_sig сообщения с
233 хэш-значением [l / 4]hash. Подпись вырабатывается на личном ключе [l /
234 4]id_privkey стороны, которая имеет идентификатор с хэш-значением [l /
235 4]id_hash. Считается, что хэш-значения id_hash и hash получены с
236 помощью алгоритма с идентификатором [oid_len]oid_der, заданным
237 DER-кодом. При выработке ЭЦП используются долговременные параметры
238 params и генератор rng с состоянием rng_state.
239
240 Ожидается [ERR_BAD_PARAMS]
241 Параметры params корректны.
242
243 Ожидается [ERR_BAD_OID]
244 Идентификатор oid_der корректен.
245
246 Ожидается [ERR_BAD_PRIVKEY]
247 Ключ id_privkey получен с помощью функции bignIdExtract().
248
249 Ожидается [ERR_BAD_RNG]
250 Генератор rng (с состоянием rng_state) корректен.
251
252 Ожидается
253 Генератор rng является криптографически стойким.
254
255 Возвращает
256 ERR_OK, если подпись выработана, и код ошибки в противном случае.
257
258 Прим.
259 Реализован алгоритм B.2.4.
260
261 Аргументы
262 id_sig идентификационная подпись
263 params долговременные параметры
264 oid_der идентификатор хэш-алгоритма
265 oid_len длина oid_der в октетах
266 id_hash хэш-значение идентификатора
267 hash хэш-значение сообщения
268 id_privkey личный ключ
269 rng генератор случайных чисел
270 rng_state состояние генератора
271
272 err_t bignIdSign2 (octet id_sig[], const bign_params * params, const octet
273 oid_der[], size_t oid_len, const octet id_hash[], const octet hash[],
274 const octet id_privkey[], const void * t, size_t t_len)
275 Вырабатывается идентификационная подпись [3 * l / 8]id_sig сообщения с
276 хэш-значением [l / 4]hash. Подпись вырабатывается на личном ключе [l /
277 4]id_privkey стороны, которая имеет идентификатор с хэш-значением [l /
278 4]id_hash. Считается, что хэш-значения id_hash и hash получены с
279 помощью алгоритма с идентификатором [oid_len]oid_der, заданным
280 DER-кодом. При выработке ЭЦП используются долговременные параметры
281 params. Одноразовый личный ключ генерируется по алгоритму 6.3.3 с
282 использованием дополнительных данных [t_len]t. Если t == 0, то
283 дополнительные данные не используются.
284
285 Ожидается [ERR_BAD_PARAMS]
286 Параметры params корректны.
287
288 Ожидается [ERR_BAD_OID]
289 Идентификатор oid_der корректен.
290
291 Ожидается [ERR_BAD_PRIVKEY]
292 Ключ id_privkey получен с помощью функции bignIdExtract().
293
294 Возвращает
295 ERR_OK, если подпись выработана, и код ошибки в противном случае.
296
297 Прим.
298 Реализованы алгоритмы B.2.4 и 6.3.3.
299
300 Аргументы
301 id_sig идентификационная подпись
302 params долговременные параметры
303 oid_der идентификатор хэш-алгоритма
304 oid_len длина oid_der в октетах
305 id_hash хэш-значение идентификатора
306 hash хэш-значение сообщения
307 id_privkey личный ключ
308 t дополнительные данные
309 t_len длина t в октетах
310
311 err_t bignIdVerify (const bign_params * params, const octet oid_der[],
312 size_t oid_len, const octet id_hash[], const octet hash[], const octet
313 id_sig[], const octet id_pubkey[], const octet pubkey[])
314 Проверяется идентификационная ЭЦП [3 * l / 8]id_sig сообщения с
315 хэш-значением [l / 4]hash, выработанная стороной, хэш-значение
316 идентификатора которой есть [l / 4]id_hash. При проверке используются
317 долговременные параметры params, открытый ключ [l / 2]id_pubkey и
318 открытый ключ доверенной стороны [l / 4]pubkey. Считается, что
319 хэш-значения id_hash, hash получены с помощью алгоритма с
320 идентификатором [oid_len]oid_der, заданным DER-кодом.
321
322 Ожидается [ERR_BAD_PARAMS]
323 Параметры params корректны.
324
325 Ожидается [ERR_BAD_OID]
326 Идентификатор oid_der корректен.
327
328 Ожидается [ERR_BAD_PUBKEY]
329
330
331 • открытый ключ id_pubkey получен с помощью функции
332 bignIdExtract();
333
334 • открытый ключ pubkey корректен.
335
336 Возвращает
337 ERR_OK, если подпись корректна, и код ошибки в противном случае.
338
339 Прим.
340 Реализован алгоритм B.2.5.
341
342 При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
343
344 Аргументы
345 params долговременные параметры
346 oid_der идентификатор хэш-алгоритма
347 oid_len длина oid_der в октетах
348 id_hash хэш-значение идентификатора
349 hash хэш-значение сообщения
350 id_sig подпись
351 id_pubkey открытый ключ
352 pubkey открытый ключ доверенной стороны
353
354 err_t bignKeyUnwrap (octet key[], const bign_params * params, const octet
355 token[], size_t len, const octet header[16], const octet privkey[])
356 Определяется ключ [len - (l / 4 + 16)]key, который имеет заголовок
357 [16]header и содержится в токене [len]token. При разборе токена
358 используются долговременные параметры params и личный ключ [l /
359 2]privkey.
360
361 Ожидается [ERR_BAD_PARAMS]
362 Параметры params корректны.
363
364 Ожидается [ERR_BAD_PRIVKEY]
365 Личный ключ privkey корректен.
366
367 Возвращает
368 ERR_OK, если токен успешно разобран, и код ошибки в противном
369 случае.
370
371 Прим.
372 Реализован алгоритм 7.2.4.
373
374 Может передаваться нулевой указатель header. В этом случае будет
375 использоваться заголовок из всех нулей.
376
377 При нарушении целостности токена возвращается код ERR_BAD_KEYTOKEN.
378 Этот код будет возвращен, если len < 32 + l / 4.
379
380 Аргументы
381 key ключ
382 params долговременные параметры
383 token токен ключа
384 len длина токена в октетах
385 header заголовок ключа
386 privkey личный ключ получателя
387
388 err_t bignKeyWrap (octet token[], const bign_params * params, const octet
389 key[], size_t len, const octet header[16], const octet pubkey[], gen_i
390 rng, void * rng_state)
391 Создается токен [l / 4 + 16 + len]token ключа [len]key с заголовком
392 [16]header. При создании токена используются долговременные параметры
393 params, открытый ключ получателя pubkey и генератор rng с состоянием
394 rng_state.
395
396 Ожидается [ERR_BAD_PARAMS]
397 Параметры params корректны.
398
399 Ожидается [ERR_BAD_INPUT]
400 len >= 16.
401
402 Ожидается [ERR_BAD_PUBKEY]
403 Открытый ключ pubkey корректен.
404
405 Ожидается [ERR_BAD_RNG]
406 Генератор rng (с состоянием rng_state) корректен.
407
408 Ожидается
409 Используется криптографически стойкий генератор rng.
410
411 Возвращает
412 ERR_OK, если токен успешно создан, и код ошибки в противном случае.
413
414 Прим.
415 Реализован алгоритм 7.2.3.
416
417 Может передаваться нулевой указатель header. В этом случае будет
418 использоваться заголовок из всех нулей.
419
420 Аргументы
421 token токен ключа
422 params долговременные параметры
423 key транспортируемый ключ
424 len длина ключа в октетах
425 header заголовок ключа
426 pubkey открытый ключ получателя
427 rng генератор случайных чисел
428 rng_state состояние генератора
429
430 err_t bignOidToDER (octet oid_der[], size_t * oid_len, const char * oid)
431 По строковому представлению oid идентификатора объекта строится его
432 DER-код [?oid_len]oid_der.
433
434 Возвращает
435 ERR_OK, если кодирование успешно выполнено или длина DER-кода
436 успешно рассчитана, и код ошибки в противном случае.
437
438 Аргументы
439 oid_der DER-код идентификатора
440 oid_len длина буфера oid_der / длина DER-кода
441 oid строковое представление идентификатора
442
443 err_t bignSign (octet sig[], const bign_params * params, const octet
444 oid_der[], size_t oid_len, const octet hash[], const octet privkey[],
445 gen_i rng, void * rng_state)
446 Вырабатывается подпись [3 * l / 8]sig сообщения с хэш-значением [l /
447 4]hash, полученном с помощью алгоритма с идентификатором
448 [oid_len]oid_der, заданным DER-кодом. Подпись вырабатывается на личном
449 ключе [l / 4]privkey. При выработке ЭЦП используются долговременные
450 параметры params и генератор rng с состоянием rng_state.
451
452 Ожидается [ERR_BAD_PARAMS]
453 Параметры params корректны.
454
455 Ожидается [ERR_BAD_OID]
456 Идентификатор oid_der корректен.
457
458 Ожидается [ERR_BAD_INPUT]
459 Буферы sig и hash не пересекаются.
460
461 Ожидается [ERR_BAD_PRIVKEY]
462 Личный ключ privkey корректен.
463
464 Ожидается [ERR_BAD_RNG]
465 Генератор rng (с состоянием rng_state) корректен.
466
467 Ожидается
468 Генератор rng является криптографически стойким.
469
470 Возвращает
471 ERR_OK, если подпись выработана, и код ошибки в противном случае.
472
473 Прим.
474 Реализован алгоритм 7.1.3.
475
476 Аргументы
477 sig подпись
478 params долговременные параметры
479 oid_der идентификатор хэш-алгоритма
480 oid_len длина oid_der в октетах
481 hash хэш-значение
482 privkey личный ключ
483 rng генератор случайных чисел
484 rng_state состояние генератора
485
486 err_t bignSign2 (octet sig[], const bign_params * params, const octet
487 oid_der[], size_t oid_len, const octet hash[], const octet privkey[],
488 const void * t, size_t t_len)
489 Вырабатывается подпись [3 * l / 8]sig сообщения с хэш-значением [l /
490 4]hash, полученном с помощью алгоритма с идентификатором
491 [oid_len]oid_der, заданным DER-кодом. Подпись вырабатывается на личном
492 ключе [l / 4]privkey. При выработке ЭЦП используются долговременные
493 параметры params. Одноразовый личный ключ генерируется по алгоритму
494 6.3.3 с использованием дополнительных данных [t_len]t. Если t == 0, то
495 дополнительные данные не используются.
496
497
498 Ожидается [ERR_BAD_PARAMS]
499 Параметры params корректны.
500
501 Ожидается [ERR_BAD_OID]
502 Идентификатор oid_der корректен.
503
504 Ожидается [ERR_BAD_INPUT]
505 Буферы sig и hash не пересекаются.
506
507 Ожидается [ERR_BAD_PRIVKEY]
508 Личный ключ privkey корректен.
509
510 Возвращает
511 ERR_OK, если подпись выработана, и код ошибки в противном случае.
512
513 Прим.
514 Реализованы алгоритмы 7.1.3 и 6.3.3.
515
516 Аргументы
517 sig подпись
518 params долговременные параметры
519 oid_der идентификатор хэш-алгоритма
520 oid_len длина oid_der в октетах
521 hash хэш-значение
522 privkey личный ключ
523 t дополнительные данные
524 t_len размер дополнительных данных
525
526 err_t bignStdParams (bign_params * params, const char * name)
527 В params загружаются стандартные долговременные параметры с именем
528 name. Поддерживаются следующие имена: '1.2.112.0.2.0.34.101.45.3.1',
529 '1.2.112.0.2.0.34.101.45.3.2', '1.2.112.0.2.0.34.101.45.3.3'. Это имена
530 стандартных параметров, заданных в таблицах Б.1, Б.2, Б.3.
531
532 Возвращает
533 ERR_OK, если параметры успешно загружены, и код ошибки в противном
534 случае.
535
536 Аргументы
537 params стандартные параметры
538 name имя параметров
539
540 err_t bignValKeypair (const bign_params * params, const octet privkey[],
541 const octet pubkey[])
542 При долговременных параметрах params проверяется корректность личного
543 ключа [l / 8]privkey и соответствие ему открытого ключа [l / 2]pubkey.
544
545 Ожидается [ERR_BAD_PARAMS]
546 Параметры params корректны.
547
548 Возвращает
549 ERR_OK, если пара корректна, и код ошибки в противном случае.
550
551 Аргументы
552 params долговременные параметры
553 privkey личный ключ
554 pubkey открытый ключ
555
556 err_t bignValParams (const bign_params * params)
557 Проверяется корректность долговременных параметров params.
558
559 Возвращает
560 ERR_OK, если параметры корректны, и код ошибки в противном случае.
561
562 Прим.
563 Реализован алгоритм 6.1.4.
564
565 Аргументы
566 params долговременные параметры
567
568 err_t bignValPubkey (const bign_params * params, const octet pubkey[])
569 При долговременных параметрах params проверяется корректность открытого
570 ключа [l / 2]pubkey.
571
572 Ожидается [ERR_BAD_PARAMS]
573 Параметры params корректны.
574
575 Возвращает
576 ERR_OK, если ключ корректен, и код ошибки в противном случае.
577
578 Прим.
579 Реализован алгоритм 6.2.3.
580
581 Аргументы
582 params долговременные параметры
583 pubkey проверяемый ключ
584
585 err_t bignVerify (const bign_params * params, const octet oid_der[], size_t
586 oid_len, const octet hash[], const octet sig[], const octet pubkey[])
587 Проверяется ЭЦП [3 * l / 8]sig сообщения с хэш-значением [l / 4]hash.
588 При проверке используются долговременные параметры params и открытый
589 ключ [l / 2]pubkey. Считается, что хэш-значение [l / 4]hash получено с
590 помощью алгоритма с идентификатором [oid_len]oid_der, заданным
591 DER-кодом.
592
593 Ожидается [ERR_BAD_PARAMS]
594 Параметры params корректны.
595
596 Ожидается [ERR_BAD_OID]
597 Идентификатор oid_der корректен.
598
599 Ожидается [ERR_BAD_PUBKEY]
600 Открытый ключ pubkey корректен.
601
602 Возвращает
603 ERR_OK, если подпись корректна, и код ошибки в противном случае.
604
605 Прим.
606 Реализован алгоритм 7.1.4.
607
608 При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
609
610 Аргументы
611 params долговременные параметры
612 oid_der идентификатор хэш-алгоритма
613 oid_len длина oid_der в октетах
614 hash хэш-значение
615 sig подпись
616 pubkey открытый ключ
617
619 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
620
621
622
623Библиотека Bee2 Ср 19 Июл 2023 00:00:00 bign.h(3)