bign.h - Man Page
Алгоритмы СТБ 34.101.45 (bign)
Synopsis
#include 'bee2/defs.h'
Классы
struct bign_params
Долговременные параметры bign.
Функции
err_t bignStdParams (bign_params *params, const char *name)
Загрузка стандартных долговременных параметров
err_t bignValParams (const bign_params *params)
Проверка долговременных параметров
err_t bignOidToDER (octet oid_der[], size_t *oid_len, const char *oid)
Кодирование идентификатора объекта
err_t bignGenKeypair (octet privkey[], octet pubkey[], const bign_params *params, gen_i rng, void *rng_state)
Генерация пары ключей
err_t bignValKeypair (const bign_params *params, const octet privkey[], const octet pubkey[])
Проверка пары ключей
err_t bignValPubkey (const bign_params *params, const octet pubkey[])
Проверка открытого ключа
err_t bignCalcPubkey (octet pubkey[], const bign_params *params, const octet privkey[])
Построение открытого ключа по личному
err_t bignDH (octet key[], const bign_params *params, const octet privkey[], const octet pubkey[], size_t key_len)
Построение общего ключа протокола Диффи -- Хеллмана
err_t bignSign (octet sig[], const bign_params *params, const octet oid_der[], size_t oid_len, const octet hash[], const octet privkey[], gen_i rng, void *rng_state)
Выработка ЭЦП
err_t bignSign2 (octet sig[], const bign_params *params, const octet oid_der[], size_t oid_len, const octet hash[], const octet privkey[], const void *t, size_t t_len)
Детерминированная выработка ЭЦП
err_t bignVerify (const bign_params *params, const octet oid_der[], size_t oid_len, const octet hash[], const octet sig[], const octet pubkey[])
Проверка ЭЦП
err_t bignKeyWrap (octet token[], const bign_params *params, const octet key[], size_t len, const octet header[16], const octet pubkey[], gen_i rng, void *rng_state)
Создание токена ключа
err_t bignKeyUnwrap (octet key[], const bign_params *params, const octet token[], size_t len, const octet header[16], const octet privkey[])
Разбор токена ключа
err_t bignIdExtract (octet id_privkey[], octet id_pubkey[], const bign_params *params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet sig[], octet pubkey[])
Извлечение пары ключей
err_t bignIdSign (octet id_sig[], const bign_params *params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_privkey[], gen_i rng, void *rng_state)
Выработка идентификационной ЭЦП
err_t bignIdSign2 (octet id_sig[], const bign_params *params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_privkey[], const void *t, size_t t_len)
Детерминированная выработка идентификационной ЭЦП
err_t bignIdVerify (const bign_params *params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_sig[], const octet id_pubkey[], const octet pubkey[])
Проверка идентификационной ЭЦП
Подробное описание
СТБ 34.101.45 (bign): Общие положения
Реализованы алгоритмы СТБ 34.101.45 (bign). При ссылках на алгоритмы, таблицы, другие объекты подразумеваются разделы СТБ 34.101.45-2013, в которых эти объекты определены.
Ожидается [ERR_BAD_INPUT]:\n Все входные указатели корректны.
Регулярность:\n todo
Идентификатор объекта
В функциях ЭЦП используется идентификатор используемого алгоритма хэширования. Идентификатор представляет собой последовательность неотрицательных целых чисел {d1 d2 ... dn}. Эта последовательность должна удовлетворять базовым ограничениям ACH.1 (см. приложение A) и, дополнительно, числа di не должны превосходить 2^32 - 1 = 4294967295.
Идентификатор задается либо строкой 'd1.d2....dn', либо DER-кодом. Если идентификатор задается строкой, то числа di должны записываться без лидирующих нулей.
Функция bignOidEncode() выполняет преобразование строкового представления в DER-код.
Если идентификатор некорректен, то функции, в которых он используется, возвращают код ERR_BAD_OID.
Идентификационная ЭЦП
Идентификационная подпись при передаче и хранении должна объединяться с открытым ключом (см. Д.3). Объединенная подпись состоит из 7 * l / 8 октетов и включает две части: первая часть -- собственно подпись (3 * l / 8 октетов), вторая часть -- открытый ключ (l / 2 октетов).
Функции
err_t bignCalcPubkey (octet pubkey[], const bign_params * params, const octet privkey[])
При долговременных параметрах params по личному ключу [l / 4]privkey строится открытый ключ [l / 2]pubkey.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_PRIVKEY]:\n Личный ключ privkey корректен.
- Возвращает
ERR_OK, если открытый ключ успешно построен, и код ошибки в противном случае.
- Аргументы
pubkey открытый ключ
params долговременные параметры
privkey личный ключ
err_t bignDH (octet key[], const bign_params * params, const octet privkey[], const octet pubkey[], size_t key_len)
При долговременных параметрах params по личному ключу [l / 4]privkey и открытому ключу [l / 2]pubkey противоположной стороны строится общий ключ [key_len]key. Общий ключ определяется как privkey-кратное ключа pubkey, что соответствует протоколу Диффи -- Хеллмана.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_PRIVKEY]:\n Личный ключ privkey корректен.
Ожидается [ERR_BAD_PUBKEY]:\n Открытый ключ pubkey корректен.
Ожидается [ERR_BAD_SHAREDKEY]:\n key_len <= l / 2.
- Возвращает
ERR_OK, если общий ключ успешно построен, и код ошибки в противном случае.
- Аргументы
key общий ключ
params долговременные параметры
privkey личный ключ
pubkey открытый ключ (другой стороны)
key_len длина key в октетах
err_t bignGenKeypair (octet privkey[], octet pubkey[], const bign_params * params, gen_i rng, void * rng_state)
При долговременных параметрах params генерируются личный [l / 4]privkey и открытый [l / 2]pubkey ключи. При генерации используется генератор rng и его состояние rng_state.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_RNG]:\n Генератор rng (с состоянием rng_state) корректен.
Ожидается:\n Используется криптографически стойкий генератор rng.
- Возвращает
ERR_OK, если ключи успешно сгенерированы, и код ошибки в противном случае.
Прим.
Реализован алгоритм 6.2.2.
- Аргументы
privkey личный ключ
pubkey открытый ключ
params долговременные параметры
rng генератор случайных чисел
rng_state [in/out] состояние генератора
err_t bignIdExtract (octet id_privkey[], octet id_pubkey[], const bign_params * params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet sig[], octet pubkey[])
Из подписи [3 * l / 8]sig идентификатора с хэш-значением [l / 4]id_hash извлекаются личный [l / 4]id_privkey и открытый [l / 2]id_pubkey ключи. Используются долговременные параметры params и открытый ключ [l / 2]pubkey доверенной стороны. Считается, что хэш-значение id_hash получено с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_PUBKEY]:\n Открытый ключ pubkey корректен.
- Возвращает
ERR_OK, если ключи успешно извлечены, и код ошибки в противном случае.
Прим.
Реализован алгоритм B.2.3.
Одновременно с извлечением ключей проверяется подпись sig. Если подпись некорректна, то будет возвращен код ERR_BAD_SIG.
- Аргументы
id_privkey личный ключ
id_pubkey открытый ключ
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
id_hash хэш-значение идентификатора
sig подпись идентификатора
pubkey открытый ключ доверенной стороны
err_t bignIdSign (octet id_sig[], const bign_params * params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_privkey[], gen_i rng, void * rng_state)
Вырабатывается идентификационная подпись [3 * l / 8]id_sig сообщения с хэш-значением [l / 4]hash. Подпись вырабатывается на личном ключе [l / 4]id_privkey стороны, которая имеет идентификатор с хэш-значением [l / 4]id_hash. Считается, что хэш-значения id_hash и hash получены с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом. При выработке ЭЦП используются долговременные параметры params и генератор rng с состоянием rng_state.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_PRIVKEY]:\n Ключ id_privkey получен с помощью функции
bignIdExtract().
Ожидается [ERR_BAD_RNG]:\n Генератор rng (с состоянием rng_state) корректен.
Ожидается:\n Генератор rng является криптографически стойким.
- Возвращает
ERR_OK, если подпись выработана, и код ошибки в противном случае.
Прим.
Реализован алгоритм B.2.4.
- Аргументы
id_sig идентификационная подпись
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
id_hash хэш-значение идентификатора
hash хэш-значение сообщения
id_privkey личный ключ
rng генератор случайных чисел
rng_state [in/out] состояние генератора
err_t bignIdSign2 (octet id_sig[], const bign_params * params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_privkey[], const void * t, size_t t_len)
Вырабатывается идентификационная подпись [3 * l / 8]id_sig сообщения с хэш-значением [l / 4]hash. Подпись вырабатывается на личном ключе [l / 4]id_privkey стороны, которая имеет идентификатор с хэш-значением [l / 4]id_hash. Считается, что хэш-значения id_hash и hash получены с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом. При выработке ЭЦП используются долговременные параметры params. Одноразовый личный ключ генерируется по алгоритму 6.3.3 с использованием дополнительных данных [t_len]t. Если t == 0, то дополнительные данные не используются.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
- Ожидается [ERR_BAD_PRIVKEY]:\n Ключ id_privkey получен с помощью функции
bignIdExtract().
- Возвращает
ERR_OK, если подпись выработана, и код ошибки в противном случае.
Прим.
Реализованы алгоритмы B.2.4 и 6.3.3.
- Аргументы
id_sig идентификационная подпись
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
id_hash хэш-значение идентификатора
hash хэш-значение сообщения
id_privkey личный ключ
t дополнительные данные
t_len длина t в октетах
err_t bignIdVerify (const bign_params * params, const octet oid_der[], size_t oid_len, const octet id_hash[], const octet hash[], const octet id_sig[], const octet id_pubkey[], const octet pubkey[])
Проверяется идентификационная ЭЦП [3 * l / 8]id_sig сообщения с хэш-значением [l / 4]hash, выработанная стороной, хэш-значение идентификатора которой есть [l / 4]id_hash. При проверке используются долговременные параметры params, открытый ключ [l / 2]id_pubkey и открытый ключ доверенной стороны [l / 4]pubkey. Считается, что хэш-значения id_hash, hash получены с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_PUBKEY]:\n
- открытый ключ id_pubkey получен с помощью функции bignIdExtract();
- открытый ключ pubkey корректен.
- Возвращает
ERR_OK, если подпись корректна, и код ошибки в противном случае.
Прим.
Реализован алгоритм B.2.5.
При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
- Аргументы
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
id_hash хэш-значение идентификатора
hash хэш-значение сообщения
id_sig подпись
id_pubkey открытый ключ
pubkey открытый ключ доверенной стороны
err_t bignKeyUnwrap (octet key[], const bign_params * params, const octet token[], size_t len, const octet header[16], const octet privkey[])
Определяется ключ [len - (l / 4 + 16)]key, который имеет заголовок [16]header и содержится в токене [len]token. При разборе токена используются долговременные параметры params и личный ключ [l / 2]privkey.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_PRIVKEY]:\n Личный ключ privkey корректен.
- Возвращает
ERR_OK, если токен успешно разобран, и код ошибки в противном случае.
Прим.
Реализован алгоритм 7.2.4.
Может передаваться нулевой указатель header. В этом случае будет использоваться заголовок из всех нулей.
При нарушении целостности токена возвращается код ERR_BAD_KEYTOKEN. Этот код будет возвращен, если len < 32 + l / 4.
- Аргументы
key ключ
params долговременные параметры
token токен ключа
len длина токена в октетах
header заголовок ключа
privkey личный ключ получателя
err_t bignKeyWrap (octet token[], const bign_params * params, const octet key[], size_t len, const octet header[16], const octet pubkey[], gen_i rng, void * rng_state)
Создается токен [l / 4 + 16 + len]token ключа [len]key с заголовком [16]header. При создании токена используются долговременные параметры params, открытый ключ получателя pubkey и генератор rng с состоянием rng_state.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_INPUT]:\n len >= 16.
Ожидается [ERR_BAD_PUBKEY]:\n Открытый ключ pubkey корректен.
Ожидается [ERR_BAD_RNG]:\n Генератор rng (с состоянием rng_state) корректен.
Ожидается:\n Используется криптографически стойкий генератор rng.
- Возвращает
ERR_OK, если токен успешно создан, и код ошибки в противном случае.
Прим.
Реализован алгоритм 7.2.3.
Может передаваться нулевой указатель header. В этом случае будет использоваться заголовок из всех нулей.
- Аргументы
token токен ключа
params долговременные параметры
key транспортируемый ключ
len длина ключа в октетах
header заголовок ключа
pubkey открытый ключ получателя
rng генератор случайных чисел
rng_state [in/out] состояние генератора
err_t bignOidToDER (octet oid_der[], size_t * oid_len, const char * oid)
По строковому представлению oid идентификатора объекта строится его DER-код [?oid_len]oid_der.
- Возвращает
ERR_OK, если кодирование успешно выполнено или длина DER-кода успешно рассчитана, и код ошибки в противном случае.
- Аргументы
oid_der DER-код идентификатора
oid_len [in/out] длина буфера oid_der / длина DER-кода
oid строковое представление идентификатора
err_t bignSign (octet sig[], const bign_params * params, const octet oid_der[], size_t oid_len, const octet hash[], const octet privkey[], gen_i rng, void * rng_state)
Вырабатывается подпись [3 * l / 8]sig сообщения с хэш-значением [l / 4]hash, полученном с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом. Подпись вырабатывается на личном ключе [l / 4]privkey. При выработке ЭЦП используются долговременные параметры params и генератор rng с состоянием rng_state.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_INPUT]:\n Буферы sig и hash не пересекаются.
Ожидается [ERR_BAD_PRIVKEY]:\n Личный ключ privkey корректен.
Ожидается [ERR_BAD_RNG]:\n Генератор rng (с состоянием rng_state) корректен.
Ожидается:\n Генератор rng является криптографически стойким.
- Возвращает
ERR_OK, если подпись выработана, и код ошибки в противном случае.
Прим.
Реализован алгоритм 7.1.3.
- Аргументы
sig подпись
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
hash хэш-значение
privkey личный ключ
rng генератор случайных чисел
rng_state [in/out] состояние генератора
err_t bignSign2 (octet sig[], const bign_params * params, const octet oid_der[], size_t oid_len, const octet hash[], const octet privkey[], const void * t, size_t t_len)
Вырабатывается подпись [3 * l / 8]sig сообщения с хэш-значением [l / 4]hash, полученном с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом. Подпись вырабатывается на личном ключе [l / 4]privkey. При выработке ЭЦП используются долговременные параметры params. Одноразовый личный ключ генерируется по алгоритму 6.3.3 с использованием дополнительных данных [t_len]t. Если t == 0, то дополнительные данные не используются.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_INPUT]:\n Буферы sig и hash не пересекаются.
Ожидается [ERR_BAD_PRIVKEY]:\n Личный ключ privkey корректен.
- Возвращает
ERR_OK, если подпись выработана, и код ошибки в противном случае.
Прим.
Реализованы алгоритмы 7.1.3 и 6.3.3.
- Аргументы
sig подпись
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
hash хэш-значение
privkey личный ключ
t дополнительные данные
t_len размер дополнительных данных
err_t bignStdParams (bign_params * params, const char * name)
В params загружаются стандартные долговременные параметры с именем name. Поддерживаются следующие имена: '1.2.112.0.2.0.34.101.45.3.1', '1.2.112.0.2.0.34.101.45.3.2', '1.2.112.0.2.0.34.101.45.3.3'. Это имена стандартных параметров, заданных в таблицах Б.1, Б.2, Б.3.
- Возвращает
ERR_OK, если параметры успешно загружены, и код ошибки в противном случае.
- Аргументы
params стандартные параметры
name имя параметров
err_t bignValKeypair (const bign_params * params, const octet privkey[], const octet pubkey[])
При долговременных параметрах params проверяется корректность личного ключа [l / 8]privkey и соответствие ему открытого ключа [l / 2]pubkey.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
- Возвращает
ERR_OK, если пара корректна, и код ошибки в противном случае.
- Аргументы
params долговременные параметры
privkey личный ключ
pubkey открытый ключ
err_t bignValParams (const bign_params * params)
Проверяется корректность долговременных параметров params.
- Возвращает
ERR_OK, если параметры корректны, и код ошибки в противном случае.
Прим.
Реализован алгоритм 6.1.4.
- Аргументы
params долговременные параметры
err_t bignValPubkey (const bign_params * params, const octet pubkey[])
При долговременных параметрах params проверяется корректность открытого ключа [l / 2]pubkey.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
- Возвращает
ERR_OK, если ключ корректен, и код ошибки в противном случае.
Прим.
Реализован алгоритм 6.2.3.
- Аргументы
params долговременные параметры
pubkey проверяемый ключ
err_t bignVerify (const bign_params * params, const octet oid_der[], size_t oid_len, const octet hash[], const octet sig[], const octet pubkey[])
Проверяется ЭЦП [3 * l / 8]sig сообщения с хэш-значением [l / 4]hash. При проверке используются долговременные параметры params и открытый ключ [l / 2]pubkey. Считается, что хэш-значение [l / 4]hash получено с помощью алгоритма с идентификатором [oid_len]oid_der, заданным DER-кодом.
Ожидается [ERR_BAD_PARAMS]:\n Параметры params корректны.
Ожидается [ERR_BAD_OID]:\n Идентификатор oid_der корректен.
Ожидается [ERR_BAD_PUBKEY]:\n Открытый ключ pubkey корректен.
- Возвращает
ERR_OK, если подпись корректна, и код ошибки в противном случае.
Прим.
Реализован алгоритм 7.1.4.
При нарушении ограничений на ЭЦП возвращается код ERR_BAD_SIG.
- Аргументы
params долговременные параметры
oid_der идентификатор хэш-алгоритма
oid_len длина oid_der в октетах
hash хэш-значение
sig подпись
pubkey открытый ключ
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.