1bign.h(3) Library Functions Manual bign.h(3)
2
6 bign.h - Алгоритмы СТБ 34.101.45 (bign)
7
10 #include 'bee2/defs.h'
11 Классы
14 struct bign_params
15 Долговременные параметры bign.
16 Функции
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 Ожидается [ERR_BAD_INPUT]
82 Все входные указатели корректны.
83 Регулярность
85 todo
86
88 В функциях ЭЦП используется идентификатор используемого алгоритма
89 хэширования. Идентификатор представляет собой последовательность
90 неотрицательных целых чисел {d1 d2 ... dn}. Эта последовательность
91 должна удовлетворять базовым ограничениям ACH.1 (см. приложение A) и,
92 дополнительно, числа di не должны превосходить 2^32 - 1 = 4294967295.
93 Идентификатор задается либо строкой 'd1.d2....dn', либо DER-кодом. Если
95 идентификатор задается строкой, то числа di должны записываться без
96 лидирующих нулей.
97 Функция bignOidEncode() выполняет преобразование строкового
99 представления в DER-код.
100 Если идентификатор некорректен, то функции, в которых он используется,
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 Ожидается [ERR_BAD_PARAMS]
117 Параметры params корректны.
118 Ожидается [ERR_BAD_PRIVKEY]
120 Личный ключ privkey корректен.
121 Возвращает
123 ERR_OK, если открытый ключ успешно построен, и код ошибки в
124 противном случае.
125 Аргументы
127 pubkey открытый ключ
128 params долговременные параметры
129 privkey личный ключ
130 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 Ожидается [ERR_BAD_PARAMS]
139 Параметры params корректны.
140 Ожидается [ERR_BAD_PRIVKEY]
142 Личный ключ privkey корректен.
143 Ожидается [ERR_BAD_PUBKEY]
145 Открытый ключ pubkey корректен.
146 Ожидается [ERR_BAD_SHAREDKEY]
148 key_len <= l / 2.
149 Возвращает
151 ERR_OK, если общий ключ успешно построен, и код ошибки в противном
152 случае.
153 Аргументы
155 key общий ключ
156 params долговременные параметры
157 privkey личный ключ
158 pubkey открытый ключ (другой стороны)
159 key_len длина key в октетах
160 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 Ожидается [ERR_BAD_PARAMS]
168 Параметры params корректны.
169 Ожидается [ERR_BAD_RNG]
171 Генератор rng (с состоянием rng_state) корректен.
172 Ожидается
174 Используется криптографически стойкий генератор rng.
175 Возвращает
177 ERR_OK, если ключи успешно сгенерированы, и код ошибки в противном
178 случае.
179 Прим.
181 Реализован алгоритм 6.2.2.
182 Аргументы
184 privkey личный ключ
185 pubkey открытый ключ
186 params долговременные параметры
187 rng генератор случайных чисел
188 rng_state состояние генератора
189 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 Ожидается [ERR_BAD_PARAMS]
201 Параметры params корректны.
202 Ожидается [ERR_BAD_OID]
204 Идентификатор oid_der корректен.
205 Ожидается [ERR_BAD_PUBKEY]
207 Открытый ключ pubkey корректен.
208 Возвращает
210 ERR_OK, если ключи успешно извлечены, и код ошибки в противном
211 случае.
212 Прим.
214 Реализован алгоритм B.2.3.
215 Одновременно с извлечением ключей проверяется подпись sig. Если
217 подпись некорректна, то будет возвращен код ERR_BAD_SIG.
218 Аргументы
220 id_privkey личный ключ
221 id_pubkey открытый ключ
222 params долговременные параметры
223 oid_der идентификатор хэш-алгоритма
224 oid_len длина oid_der в октетах
225 id_hash хэш-значение идентификатора
226 sig подпись идентификатора
227 pubkey открытый ключ доверенной стороны
228 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 Ожидается [ERR_BAD_PARAMS]
241 Параметры params корректны.
242 Ожидается [ERR_BAD_OID]
244 Идентификатор oid_der корректен.
245 Ожидается [ERR_BAD_PRIVKEY]
247 Ключ id_privkey получен с помощью функции bignIdExtract().
248 Ожидается [ERR_BAD_RNG]
250 Генератор rng (с состоянием rng_state) корректен.
251 Ожидается
253 Генератор rng является криптографически стойким.
254 Возвращает
256 ERR_OK, если подпись выработана, и код ошибки в противном случае.
257 Прим.
259 Реализован алгоритм B.2.4.
260 Аргументы
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 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 Ожидается [ERR_BAD_PARAMS]
286 Параметры params корректны.
287 Ожидается [ERR_BAD_OID]
289 Идентификатор oid_der корректен.
290 Ожидается [ERR_BAD_PRIVKEY]
292 Ключ id_privkey получен с помощью функции bignIdExtract().
293 Возвращает
295 ERR_OK, если подпись выработана, и код ошибки в противном случае.
296 Прим.
298 Реализованы алгоритмы B.2.4 и 6.3.3.
299 Аргументы
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 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 Ожидается [ERR_BAD_PARAMS]
323 Параметры params корректны.
324 Ожидается [ERR_BAD_OID]
326 Идентификатор oid_der корректен.
327 Ожидается [ERR_BAD_PUBKEY]
329 • открытый ключ id_pubkey получен с помощью функции
332 bignIdExtract();
333 • открытый ключ pubkey корректен.
335 Возвращает
337 ERR_OK, если подпись корректна, и код ошибки в противном случае.
338 Прим.
340 Реализован алгоритм B.2.5.
341 При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
343 Аргументы
345 params долговременные параметры
346 oid_der идентификатор хэш-алгоритма
347 oid_len длина oid_der в октетах
348 id_hash хэш-значение идентификатора
349 hash хэш-значение сообщения
350 id_sig подпись
351 id_pubkey открытый ключ
352 pubkey открытый ключ доверенной стороны
353 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 Ожидается [ERR_BAD_PARAMS]
362 Параметры params корректны.
363 Ожидается [ERR_BAD_PRIVKEY]
365 Личный ключ privkey корректен.
366 Возвращает
368 ERR_OK, если токен успешно разобран, и код ошибки в противном
369 случае.
370 Прим.
372 Реализован алгоритм 7.2.4.
373 Может передаваться нулевой указатель header. В этом случае будет
375 использоваться заголовок из всех нулей.
376 При нарушении целостности токена возвращается код ERR_BAD_KEYTOKEN.
378 Этот код будет возвращен, если len < 32 + l / 4.
379 Аргументы
381 key ключ
382 params долговременные параметры
383 token токен ключа
384 len длина токена в октетах
385 header заголовок ключа
386 privkey личный ключ получателя
387 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 Ожидается [ERR_BAD_PARAMS]
397 Параметры params корректны.
398 Ожидается [ERR_BAD_INPUT]
400 len >= 16.
401 Ожидается [ERR_BAD_PUBKEY]
403 Открытый ключ pubkey корректен.
404 Ожидается [ERR_BAD_RNG]
406 Генератор rng (с состоянием rng_state) корректен.
407 Ожидается
409 Используется криптографически стойкий генератор rng.
410 Возвращает
412 ERR_OK, если токен успешно создан, и код ошибки в противном случае.
413 Прим.
415 Реализован алгоритм 7.2.3.
416 Может передаваться нулевой указатель header. В этом случае будет
418 использоваться заголовок из всех нулей.
419 Аргументы
421 token токен ключа
422 params долговременные параметры
423 key транспортируемый ключ
424 len длина ключа в октетах
425 header заголовок ключа
426 pubkey открытый ключ получателя
427 rng генератор случайных чисел
428 rng_state состояние генератора
429 err_t bignOidToDER (octet oid_der[], size_t * oid_len, const char * oid)
431 По строковому представлению oid идентификатора объекта строится его
432 DER-код [?oid_len]oid_der.
433 Возвращает
435 ERR_OK, если кодирование успешно выполнено или длина DER-кода
436 успешно рассчитана, и код ошибки в противном случае.
437 Аргументы
439 oid_der DER-код идентификатора
440 oid_len длина буфера oid_der / длина DER-кода
441 oid строковое представление идентификатора
442 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 Ожидается [ERR_BAD_PARAMS]
453 Параметры params корректны.
454 Ожидается [ERR_BAD_OID]
456 Идентификатор oid_der корректен.
457 Ожидается [ERR_BAD_INPUT]
459 Буферы sig и hash не пересекаются.
460 Ожидается [ERR_BAD_PRIVKEY]
462 Личный ключ privkey корректен.
463 Ожидается [ERR_BAD_RNG]
465 Генератор rng (с состоянием rng_state) корректен.
466 Ожидается
468 Генератор rng является криптографически стойким.
469 Возвращает
471 ERR_OK, если подпись выработана, и код ошибки в противном случае.
472 Прим.
474 Реализован алгоритм 7.1.3.
475 Аргументы
477 sig подпись
478 params долговременные параметры
479 oid_der идентификатор хэш-алгоритма
480 oid_len длина oid_der в октетах
481 hash хэш-значение
482 privkey личный ключ
483 rng генератор случайных чисел
484 rng_state состояние генератора
485 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 Ожидается [ERR_BAD_PARAMS]
499 Параметры params корректны.
500 Ожидается [ERR_BAD_OID]
502 Идентификатор oid_der корректен.
503 Ожидается [ERR_BAD_INPUT]
505 Буферы sig и hash не пересекаются.
506 Ожидается [ERR_BAD_PRIVKEY]
508 Личный ключ privkey корректен.
509 Возвращает
511 ERR_OK, если подпись выработана, и код ошибки в противном случае.
512 Прим.
514 Реализованы алгоритмы 7.1.3 и 6.3.3.
515 Аргументы
517 sig подпись
518 params долговременные параметры
519 oid_der идентификатор хэш-алгоритма
520 oid_len длина oid_der в октетах
521 hash хэш-значение
522 privkey личный ключ
523 t дополнительные данные
524 t_len размер дополнительных данных
525 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 Возвращает
533 ERR_OK, если параметры успешно загружены, и код ошибки в противном
534 случае.
535 Аргументы
537 params стандартные параметры
538 name имя параметров
539 err_t bignValKeypair (const bign_params * params, const octet privkey[],
541 const octet pubkey[])
542 При долговременных параметрах params проверяется корректность личного
543 ключа [l / 8]privkey и соответствие ему открытого ключа [l / 2]pubkey.
544 Ожидается [ERR_BAD_PARAMS]
546 Параметры params корректны.
547 Возвращает
549 ERR_OK, если пара корректна, и код ошибки в противном случае.
550 Аргументы
552 params долговременные параметры
553 privkey личный ключ
554 pubkey открытый ключ
555 err_t bignValParams (const bign_params * params)
557 Проверяется корректность долговременных параметров params.
558 Возвращает
560 ERR_OK, если параметры корректны, и код ошибки в противном случае.
561 Прим.
563 Реализован алгоритм 6.1.4.
564 Аргументы
566 params долговременные параметры
567 err_t bignValPubkey (const bign_params * params, const octet pubkey[])
569 При долговременных параметрах params проверяется корректность открытого
570 ключа [l / 2]pubkey.
571 Ожидается [ERR_BAD_PARAMS]
573 Параметры params корректны.
574 Возвращает
576 ERR_OK, если ключ корректен, и код ошибки в противном случае.
577 Прим.
579 Реализован алгоритм 6.2.3.
580 Аргументы
582 params долговременные параметры
583 pubkey проверяемый ключ
584 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 Ожидается [ERR_BAD_PARAMS]
594 Параметры params корректны.
595 Ожидается [ERR_BAD_OID]
597 Идентификатор oid_der корректен.
598 Ожидается [ERR_BAD_PUBKEY]
600 Открытый ключ pubkey корректен.
601 Возвращает
603 ERR_OK, если подпись корректна, и код ошибки в противном случае.
604 Прим.
606 Реализован алгоритм 7.1.4.
607 При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
609 Аргументы
611 params долговременные параметры
612 oid_der идентификатор хэш-алгоритма
613 oid_len длина oid_der в октетах
614 hash хэш-значение
615 sig подпись
616 pubkey открытый ключ
617
619 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
620Библиотека Bee2 Пт 23 Июн 2023 bign.h(3)