ЖТЯИ.00074-01 90 03. КриптоПро IKE, ESP, AH. Руководство разработчика.
CollapseAll image

КриптоПро IKE, ESP, AH
Руководство разработчика

Средство "КриптоПро IKE, ESP, AH" предназначено для защиты конфиденциальной информации не составляющей государственную тайну при передаче по каналам связи. Средство используется в ОС Windows XP/2003/Vista/2008/7/2008 R2 и ОС Linux. Криптографическая подсистема использует СКЗИ "КриптоПро CSP" v.3.6 R2 и выше и базируется на стандартах криптографической защиты данных:

  • Стандарт шифрования ГОСТ 28147.89
  • Стандарт функции хеширования ГОСТ Р34.11.94
  • Стандарт ЭЦП ГОСТ Р34.10.2001

(C) "КРИПТО-ПРО" 2005-2011. Все права сохранены


Введение

Назначение модулей криптографической поддержки протоколов IKEv1 и ESP/AH

В КриптоПро CSP версии 3.6 включена криптографическая поддержка протоколов IKEv1 и ESP/AH группы протоколов IPSec.

Данная поддержка группы протоколов IPSec предназначена для защиты конфиденциальной информации в корпоративных сетях и сетях общего доступа.

Описание базовых пртоколов IPSec приведены в ряде документов RFC. RFC 2408, RFC 2409 определяют протокол аутентификации IKE v1 и защиту ISAKMP обменов. RFC 4301, RFC 4303 и RFC 4304 определяют защиту вложений (ESP) и защиту пакетов (AH).

Использование Российских стантартов криптографической защиты данных в протоколах IPSec производится в соответствии с проектами документов:

  • "Использование ГОСТ 28147-89, ГОСТ Р 34.11-94 и ГОСТ Р 34.10-2001 при управлении ключами IKE и ISAKMP",

  • "Комбинированный алгоритм шифрования вложений IPsec (ESP) на основе ГОСТ 28147-89",

  • "Алгоритмы обеспечения целостности IPsec (ESP, AH) на основе ГОСТ Р 34.11-94".

В данном документе описаны интерфейсы библиотеки уровня прользователя и модуля ядра ОС, предназначенные для реализации криптографических преобразований протоколов IKE и IPSec.

Уровень реализованного API библиотеки и модуля выбран исходя из следующих соображений:

  • уровнь криптографических вызовов реализуемых протоколов должен скрывать особенности использования криптографических функций уровня крипто API

  • обоснование корректности реализации протоколов и использования функций крипто API должно проводится для библиотеки и модуля

  • должна обеспечиваться минимизация трудоёмкости встраивания и обоснования корректности использования данного API в прикладных системах

  • функции библиотеки и модуля должны обеспечивать поддержку ключевой системы и операций SADB

Данный документ предназначен для использования разработчиками прикладных систем в качестве руководства по встраиванию библиотеки libike_gost и модуля esp_gost в приложения, реализующие протоколы сетевой аутентификации и защиты соединений.

Основные требования к среде функционирования библиотеки и модуля

Среда функционирования:

  • ОС Windows XP/2003/Vista/2008/7/2008 R2

  • ОС Linux.

Библиотеки и модуль ядра при работе используют установленный на целевом компьютере КриптоПро CSP версии 3.6:

  • на целевой компьютер устанавливается одна лицензия на CSP

  • проверка корректности и срока действия лицензии на КриптоПро CSP-3.6 выполняются средствами КриптоПро CSP

  • использование криптографической поддержки протоколов IKEv1 и ESP не влечёт за собой каких-либо изменений в использовании собственно CSP-3.6

Алгоритмы и преобразования, поддерживаемые библиотекой и модулем

Библиотека IKE обеспечивает поддержку трёх методов аутентификации:

  • IKE-GOST-PSK, переработанная версия PSK [RFC 2409]

  • IKE-GOST-SIGNATURE, переработанная версия 'digital signature' [RFC 2409]

  • IKE-GSS-API, при использовании совместно с сертифицированной реализацией GSS-API (или SSPI) [draft-ietf-ipsec-isakmp-gss-auth]

Поддерживается протокол NAT-Traversal (NAT-T) [RFC 3947].

Поддержка протоколов ESP/AH включает в себя реализацию 3-х комбинированных методов защиты данных (combined algorithms [ESP]):

  • ESP_GOST-SIMPLE-IMIT

  • ESP_GOST-4M-IMIT

  • ESP_GOST-1K-IMIT

двух методов контроля целостности ESP пакетов

  • GOST-HMAC-4M

  • GOST-HMAC-1K

двух методов контроля целостности AH пакетов

  • AH_GOST-HMAC-4M

  • AH_GOST-HMAC-1K

Порядок использования библиотеки и модуля

Перед использованием библиотека уровня пользователя и модуль ядра ОС должны быть инициализированы. При инициализации задаются параметры, определяющие основные свойства библиотеки и модуля:

  • количество обслуживаемых сессий согласования ключей (защиты информации)

  • настройки параметров безопасности

  • способ протоколирования событий

При использовании библиотеки IKE возможно одновременное использование обоих методов аутентификации - выбор метода аутентификации выполняется при создании сессии IKE фазы 1 при вызове функции библиотеки p1_CreateFn.

При использовании модуля IPSEC доступность различных методов защиты зависит от используемого исполнения CSP:

Note Замечание:

исполнение CSP не является конфигурируемым параметром, а выбирается на этапе инсталляции ПО

  • KC1/KC2/KC3 - доступны все преобразования

  • KB1 - недоступны преобразования ESP_GOST-SIMPLE-IMIT, ESP_GOST-4M-IMIT и AH_GOST-4M-IMIT

Состав

Реализация состоит из 6-и компонент (обозначение для ОС Linux (ОС Windows)):

  • динамической библиотеки уровня пользователя libike_gost.so (cpike.dll)

  • динамической библиотеки уровня пользователя libesp_gost.so (cpesp.dll)

  • модуля ядра esp_gost.o (cpesp.sys)

  • заголовочных файлов, необходимых для использования библиотеки libike_gost

  • заголовочных файлов, необходимых для использования библиотеки libesp_gost и модуля ядра ОС esp_gost

  • утилиты GenPSK генерации PSK

Библиотека уровня пользователя libike_gost предназначена для обслуживания процессов согласования и выработки ключевой информации:

  • поддержки протоколов IKEv1

  • организации защищённого обмена ключевой информацией с модулем ядра esp_gost (библиотекой libesp_gost)

Библиотека libike_gost содержит функции, необходимые для:

  • инициализации и завершения работы

  • реализации IKEv1 фазы 1, фазы 2

  • организации защищённого обмена ключевой информацией с модулем ядра esp_gost (библиотекой libesp_gost)

Библиотека уровня пользователя libesp_gost предназначена для обслуживания процессов обеспечения защищённого обмена:

  • поддержки протоколов ESP/AH

  • организации защищённого обмена ключевой информацией с библиотекой libike_gost

Библиотека libesp_gost содержит функции, необходимые для:

  • инициализации и завершения работы

  • реализации протоколов ESP/AH

  • организации защищённого обмена ключевой информацией с библиотекой libike_gost

Модуль ядра ОС esp_gost содержит функции, необходимые для:

  • инициализации и завершения работы

  • реализации протоколов ESP/AH

  • организации защищённого обмена ключевой информацией с библиотекой libike_gost

Библиотеки libike_gost, libesp_gost при работе использует КриптоПро CSP. Библиотеки могут использовать интерфейс КриптоПро CSP уровня CPC либо уровня Crypt. При использовании интерфейса уровня CPC приложение обязано создать провайдер, определяемый хендлом. Корректность хендла обеспечивается приложением.

Модуль esp_gost при работе использует модуль КриптоПро CSP уровня ядра. Запуск модуля КриптоПро CSP и создание контейнеров выполняются пользователем модуля esp_gost.


Особенности применения в ОС семейства Linux

Поддержка ОС

  • ALT Linux

  • SuSE 9.x и 10.х

  • Red Hat Enterprise Linux (RHEL) release 3.3, 4 и 5

  • Debian 4.х

Системные требования

В системе должен быть установлен "КриптоПро CSP 3.6" в составе:

  • lsb-cprocsp-base-3.6.1-3.noarch.rpm

  • lsb-cprocsp-kc1-3.6.1-3.i486.rpm

  • lsb-cprocsp-capilite-3.6.1-3.i486.rpm

  • cprocsp-drv-2.4.21-21cp-3.6.1-3.i486.rpm или cprocsp-drv-2.4.21-21cpsmp-3.6.1-3.i486.rpm

  • lsb-cprocsp-rdr-3.6.1-3.i486.rpm

Для использования на SPLAT дополнительно должны быть установлены

  • cprocsp-compat-splat-1.0.0-1.noarch.rpm

  • libstdc++-3.4.4-2.fc3.i386.rpm

Для использования SDK должны быть установлены

  • lsb-cprocsp-devel-3.6.1-3.noarch.rpm

  • cprocsp-drv-devel-3.6.1-3.noarch.rpm

Состав дистрибутива для 32-х бит платформы Intel

Модуль ядра ОС для SPLAT R65 HFA50 (RHEL-3.3)

  • cprocsp-ipsec-esp-2.4.21-21cp-3.6.1-3.i486.rpm или cprocsp-ipsec-esp-2.4.21-21cpsmp-3.6.1-3.i486.rpm

Модуль ядра ОС для SPLAT R71.10 (RHEL-5.2)

  • cprocsp-ipsec-esp-2.6.18-2s9221cp-3.6.1-4.i486.rpm или cprocsp-ipsec-esp-2.6.18-92cpsmp-3.6.1-4.i486.rpm

Модуль ядра, который надо собрать для целевого Linux

  • cprocsp-ipsec-esp-3.6.1-4.src.rpm

Динамические библиотеки уровня пользователя

  • cprocsp-ipsec-ike-3.6.1-3.i486.rpm

Утилиты PSK

  • cprocsp-ipsec-genpsk-3.6.1-3.i486.rpm

SDK и примеры использования

  • cprocsp-ipsec-devel-3.6.1-3.noarch.rpm


Особенности применения в Windows

Поддержка ОС

  • Microsoft Windows XP

  • Microsoft Windows 2003

  • Microsoft Windows Vista

  • Microsoft Windows 2008

  • Microsoft Windows 7

  • Microsoft Windows 2008 R2

Архитектура прикладного API

  • WIN32

Платформы

  • x86

  • x64

Системные требования

В системе должен быть установлен "КриптоПро CSP 3.6" в составе:

  • Основные файлы

  • Криптопровайдер уровня ядра ОС


Рекомендации по использованию модулей КриптоПро

IKE, ESP, AH

Инициализация библиотеки и модуля ядра

Инициализация библиотеки криптографической поддержки протоколов и преобразований IKEv1 осуществляется вызовом cpike_init_gost, завершение - cpike_shutdown_gost.

На этапе инициализации библиотеки необходимо выработать ключи в соответствии с Рекомендации по использованию API SADB.

Инициализация модуля ядра ОС криптографической поддержки протоколов и преобразований ESP/AH осуществляется вызовом cpesp_init_gost, завершение - cpesp_shutdown_gost.

На этапе инициализации модуля необходимо выработать ключи в соответствии с Рекомендации по использованию API SADB.

  • создать ключи

  • передать на уровень ядра данные для инициализации ПДСЧ модуля и открытый ключ узла сети

  • инициализировать ПДСЧ на уровне ядра ОС

  • передать на уровень приложения открытый ключ модуля ESP/AH

Режимы и методы фазы 1 IKE/ГОСТ

Базовыми методами в фазе 1 IKE/ГОСТ являются "Main Mode" и "Aggressive Mode". Они используются с ISAKMP-службой безопасности и предназначены для выработки аутентифицированного ключевого материала с использованием обмена по Диффи-Хеллману на асимметричных ключевых парах. Фаза 1 идентифицируется значением Messege_ID равным 0.

Фаза 1 IKE/ГОСТ состоит из процесса аутентификации, завершающегося вызовами функций p1_VerifyIRFn на каждой из сторон. Если хотя бы одна из функций возвратила ошибку, процессы на обеих сторонах должны завершиться по неуспеху.

После успешного завершения процесса стороны сериализуют данные сессии фазы 1. Для сериализации, десериализации и ресериализации используются вызовы p1_SerializeFn, p1_deSerializeFn и p1_reSerializeFn.

После согласования сторонами ассоциаций безопасности (SA), ISAKMP создаёт сессии IKE фазы 1 вызовом p1_CreateFn, на вход которого передаются параметры:

  • идентификатор метода аутентификации

  • параметр шифрования и имитовставки обмена ISAKMP

  • параметр группы алгоритма Диффи-Хеллмана

  • HASH_OID - идентификатор функции хеширования, использующейся в вызовах PRF и при выработке и проверке значений аутентифицирующих элементов фазы 1 и фазы 2

Далее с использованием функции p1_SetParamFn могут быть установлены иные параметры согласованной SA:

  • максимальное время жизни SA

  • максимальное число сессий фазы 2, создаваемых из сессии фазы 1

  • возможность неиспользования режима PFS

Функция p1_GetParamFn считывает установленные значения параметров.

Метод GOST-IKE-PSK

PSK-аутентификация. Main Mode

Аутентификация в режиме GOST-IKE-PSK требует, чтобы процессу ISAKMP был установлен предварительно распределённый ключ PSK. ISAKMP передаёт этот ключ в IKE с помощью p1_SetPSKFn. В данном режиме аутентификация в фазе IKE/ГОСТ ph1 проводится по схеме:

Таблица 1
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA | p1_Create p1_SetParam | ==> <== | p1_Create p1_SetParam | HDR,SA
HDR,KE_i,Ni | p1_Setup | ==> |  |
 | p1_SetPSK p1_Agree | <== | p1_Setup p1_SetPSK p1_Agree | HDR,KE_r,Nr
HDR*,IDii,HASH_I | p1_AuthIR(I) p1_Encap | ==> | p1_Decap p1_AuthIR(R) p1_VerifyIR(I) |
 | p1_Decap p1_VerifyIR(R) | <== | p1_Encap | HDR*,IDir,HASH_R

Метод GOST-IKE-PSK

PSK-аутентификация. Aggressive Mode

Таблица 2
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA,KE_i,Ni,IDii | p1_Create p1_SetParam p1_Setup | ==> | p1_Create p1_SetParam |
 | p1_SetPSK p1_SetParam p1_Agree p1_VerifyIR(R) | <== | p1_Setup p1_SetPSK p1_Agree p1_AuthIR(R) | HDR,SA,KE_r,Nr,IDir,HASH_R
HDR*,HASH_I | p1_AuthIR(I) p1_Encap | ==> | p1_Decap p1_VerifyIR(I) |

Метод GOST-IKE-SIGNATURE

Аутентификация на ключах подписи. Main Mode

Аутентификация в режиме GOST-IKE-SIGNATURE требует установленного ключа подписи пользователя. Также ISAKMP должен либо найти сертификат оппонента в хранилищах сертификатов компьютера, либо запросить сертификат у противоположной сторона запросом CERTREQ. Сертификат противоположной стороны должен быть проверен, разобран и передан функции p1_SetOtherCertFn.

Обмен данными при аутентификации в фазе 1 IKE/ГОСТ режима GOST-IKE-SIGNATURE Main Mode производится по варианту, обеспечивающему защиту идентификационных параметров Инициатора и Респондера с учётом моделей нарушителя "Пассивный наблюдатель" и "Ложный Инициатор".

Таблица 3
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA | p1_Create p1_SetParam | ==> <== | p1_Create p1_SetParam | HDR,SA
HDR,KE,Ni,[CERTREQ] | p1_Setup | ==> |  |
 | p1_Agree | <== | p1_Setup p1_Agree | HDR,KE,Nr,[CERTREQ]
HDR*,IDii,[CERT],SIG_I | p1_SetMyCertProv* p1_AuthIR(I) p1_Encap | ==> | p1_Decap p1_SetMyCertProv p1_AuthIR(R) p1_SetOtherCert p1_VerifyIR(I) |
 | p1_Decap p1_SetOtherCert p1_p1_VerifyIR(R) | <== | p1_Encap | HDR*,IDir,[CERT],SIG_R

Примечание: Функция p1_SetMyCertProvFn может быть вызвана на более ранних этапах обмена. После выполнения функции p1_AuthIRFn контекст, переданный в p1_SetMyCertProvFn, уничтожается приложением.

Метод GOST-IKE-SIGNATURE

Аутентификация на ключах подписи. Aggressive Mode

Обмен данными при аутентификации производится по варианту, обеспечивающему защиту идентификационных параметров Инициатора с учётом модели нарушителя "Ложный сервер".

Таблица 4
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA,KE_i,Ni,[CERTREQ] | p1_Create p1_SetParam p1_Setup | ==> | p1_Create p1_SetParam |
 | p1_SetParam p1_Agree p1_SetOtherCert p1_VerifyIR(R) | <== | p1_Setup p1_Agree p1_SetMyCertProv* p1_AuthIR(R) | HDR,SA,KE_r,Nr,[CERTREQ],IDir,[CERT],SIG_R
HDR*,IDii,[CERT],SIG_I | p1_SetMyCertProv* p1_AuthIR(I) p1_Encap | ==> | p1_Decap p1_SetOtherCert p1_VerifyIR(I) |

Примечание: Функция p1_SetMyCertProvFn может быть вызвана на более ранних этапах обмена. После выполнения функции p1_AuthIRFn контекст, переданный в p1_SetMyCertProvFn, уничтожается приложением.

Метод GOST-IKE-GSS-API

GSS-API-аутентификация. Main Mode

Аутентификация в режиме IKE-GSS-API требует, чтобы процесс ISAKMP использования SSPI-провайдера. ISAKMP передаёт идентификаторы сторон и токены в IKE с помощью p1_SetSSPIFn. GSS-API-аутентификация в Main Mode фазы 1 проводится по схеме:

Таблица 5
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA | p1_Create p1_SetParam | ==> <== | p1_Create p1_SetParam | HDR,SA
HDR,KE_i,Ni,GSSi | p1_Setup SSPI-> InitializeSecurityContext(Gi,0,GSSi) | ==> |  |
 | SSPI-> InitializeSecurityContext(0,GSSr,GSSI(n)) p1_SetSSPI(Gi,Gr,GSSi,GSSr) p1_Agree | <== | p1_Setup SSPI-> AcceptSecurityContext(Gr,GSSi,GSSr) p1_SetSSPI(Gi,Gr,GSSi,GSSr) p1_Agree | HDR,KE_r,Nr,GSSr
HDR*,IDii,[GSSI(n)|HASH_I] | [ SSPI-> InitializeSecurityContext(0,GSSR(n-1),GSSI(n)) | p1_AuthIR(I) SSPI->EncryptMessage(hs) ] p1_Encap | ==> | p1_Decap [ SSPI-> AcceptSecurityContext(0,GSSI(n-1),GSSR(n)) | SSPI-> DecryptMessage(hash) p1_VerifyIR(I) p1_AuthIR(R) SSPI-> EncryptMessage(hs) ] |
 | p1_Decap SSPI-> DecryptMessage(hash) p1_VerifyIR(R) | <== | p1_Encap | HDR*,IDir,[GSSR(n)|HASH_R]

Метод GOST-IKE-GSS-API

GSS-API-аутентификация. Agressive Mode

Этот режим допустим только в случае, если второй вызов SSPI->InitializeSecurityContext() на инициаторе и первый вызов SSPI->AcceptSecurityContext() на ответчике возвратил SEC_E_OK. В случае возврата SEC_I_CONTINUE_NEEDED, аутентификация должна быть прервана. Для этого режима макрос CPIKE_AV_GSS(n) всегда должен иметь значения аргумента n равное 0. GSS-API-аутентификация в Agressive Mode фазы 1 проводится по схеме:

Таблица 6
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR,SA,KE_i,Ni,IDii,GSSi | p1_Create p1_SetParam p1_Setup SSPI-> InitializeSecurityContext(Gi,0,GSSi) | ==> | p1_Create p1_SetParam |
 | SSPI-> InitializeSecurityContext(0,GSSr,0) p1_SetSSPI(Gi,Gr,GSSi,GSSr) p1_SetParam p1_Agree SSPI-> DecryptMessage(hash) p1_VerifyIR(R) | <== | p1_Setup SSPI-> AcceptSecurityContext(Gr,GSSi,GSSr) p1_SetSSPI(Gi,Gr,GSSi,GSSr) p1_Agree p1_AuthIR(R) SSPI-> EncryptMessage(hs) | HDR,SA,KE_r,Nr,IDir,GSSr,HASH_R
HDR*,HASH_I | p1_AuthIR(I) SSPI-> EncryptMessage(hs) p1_Encap | ==> | p1_Decap SSPI-> DecryptMessage(hash) p1_VerifyIR(I) |

Формат передачи сигнатуры

Signature передаётся в виде строки битов длиной 512.

Режимы и методы фазы 2 IKE /ГОСТ

Фаза 2 IKE/ГОСТ обмена ISAKMP включает режим Quick Mode, New Group Mode и Informational Mode.
Note Замечание:

Строго говоря, New Group Mode не принадлежит фазе 2, но, для упрощения, в дальнейшем на этом не будет акцентироваться внимание.
Сессия фазы 2 IKE/ГОСТ идентифицируется уникальным параметром M_ID, отличным от 0 и создаётся вызовом p2_CreateFn.

Сессия фазы 2 порождается на основе сессии фазы 1. Сессия фазы 1 может быть как исходной, так и десериализованной (полученной вызовами p1_SerializeFn и p1_deSerializeFn).

Сессии фазы 2 вызовом p2_SetParamFn могут быть установлены параметры согласованной SA:

  • CPIPSEC_AT_Group_Description - параметр группы алгоритма Диффи-Хеллмана режима PFS

  • CPIPSEC_AT_GOST_28147_SBOX - используемый SBox

  • CPIPSEC_AT_Life_Duration - ограничение на время жизни сессии в секундах/байтах

  • CPIPSEC_AT_Ext_Serial_Number - использование Extended SN

  • CPIPSEC_AT_Max_Auth_Error - максимальное значение счётчика ошибок аутентификации

  • CPIPSEC_AT_Max_Packet_Len - максимальный размер пакета

  • CPIPSEC_AT_Authentication_Algorithm - алгоритм аутентификации

  • CPIPSEC_ATP_Check_SN - использование оконного алгоритма

Значения установленных параметров могут быть получены вызовом p2_GetParamFn.

На основе одной сессии фазы 1 допускается создание не более CPIKE_PFSONLY_MAX_MSGS (2^12) сессий фазы 2 при условии использования PFS и не более CPIKE_NONPFS_MAX_MSGS (2^7) без использования PFS.

Режим Quick Mode фазы 2

В режиме IKE/ГОСТ Quick Mode вырабатываются ключи для протоколов ESP и AH/ГОСТ, согласовываются параметры и режимы работы протоколов для каждого значения индекса SPI, ключи и параметры подготавливаются для передачи модулю ядра ОС.

На уровне протокола ISAKMP обмен IKE/ГОСТ Quick Mode производится по схеме:

Таблица 7
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR*,HASH(1),SA0,[SA1,...]Ni,[KE_i,][IDci,IDcr] | p2_Create(M_ID,CERT_R) p2_SetParam p2_Setup p2_HashAFn(HASH(1)) p2_Encap | ==> | p2_Create(M_ID,CERT_I) p2_Decap p2_VerifyA(HASH(1)) p2_SetParam |
 | p2_Decap p2_VerifyA(HASH(2)) p2_Agree | <== | p2_Setup p2_Agree p2_HashA;(HASH(2)) p2_Encap | HDR*,HASH(2),SA0,[SA1,...]Nr,[KE_r,][IDci,IDcr]
HDR*,HASH(3) | p2_Hash3 p2_Encap | ==> | p2_Decap p2_Verify3 |
 | spiSerialize(SA*,...) |  | spiSerialize(SA*,...) |

SA0,[SA1,...]- одна или несколько SA, определяющих алгоритмы, режимы, параметры протоколов ESP/AH. Для каждой из SA Инициатор в составе первого пакета передаёт SPI для направления Инициатор - Респондер. В ответном пакете Респондер передаёт для каждой ассоциации своё значение SPI для направления Респондер-Инициатор.

Режим PFS

Инициатор и Респондер вырабатывают эфемерные ключевые пары вызовом функции p2_SetupFn. Эти вызовы возвращают открытые ключи, после обмена которыми, вызовами p2_AgreeFn вырабатываются ключи согласования, используемые при получении результирующих ключей. Параметры ключевых пар PFS согласуются в составе SA0. Режим PFS по умолчанию обязателен. Необязательное использование режима PFS может быть согласовано в составе SA на первой фазе протокола и установлено вызовом p1_SetParamFn с параметром CPIKE_AC_PFS_Control со значением CPIKE_PFSC_Non_Mandatory_PFS.

Note Замечание:

Значения HASH(1) и HASH(2) вычисляются приложением вызовами функции p2_HashAFn и проверяются p2_VerifyAFn. Значения HASH(3) вырабатываются вызовами p2_Hash3Fn и проверяются p2_Verify3Fn.

Режим "Новая группа параметров"

Режим "Новая группа параметров" не должен использоваться до установления ISAKMP SA. Определение новой группы параметров должно следовать за обменом фазы1, но не является обменом фазы 2, (M-ID отличен от 0).

Таблица 8
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR*,HASH(1),SA | p2_Create(M_ID,CERT_R) HashA p2_Encap | ==> | p2_Create(M_ID,CERT_I) p2_Decap VerifyA |
 | p2_Decap VerifyA | <== | HashA p2_Encap | HDR*,HASH(2),SA

Аутентичность сообщения обеспечивается передачей HASH(1) и HASH(2).

ISAKMP информационный обмен

Для защиты пакетов информационного обмена после создания ключей SKEYID_e и SKEYID_a может использоваться протокол:

Таблица 9
Initiator | Вызываемые функции | Направление передачи | Вызываемые функции | Responder
HDR*,HASH(1),N/D | p2_Create(M_ID,CERT_R) HashA p2_Encap | ==> | p2_Create(M_ID,CERT_I) p2_Decap VerifyA |

где

  • N/D - данные протокола ISAKMP

  • Шифрование производится в согласованных в ISAKMP SA режимах

Закрытые ключи, сертификаты, проверка сертификатов

Закрытые ключи

Приложение ISAKMP должно представить библиотеке libike_gost ключ компьютера (ключ администратора безопасности компьютера) и ключ аутентификации пользователя. Эти ключи могут быть представлены либо в форме PSK либо в форме ключевого контейнера КриптоПро CSP-3.6. Ключи в форме PSK устанавливаются вызовами CreatePSKFn, p1_SetPSKFn для ключа компьютера и ключа пользователя соответственно. Ключи в форме ключевого контейнера КриптоПро CSP-3.6 устанавливаются вызовами CreateProvFn и p1_SetMyCertProvFn. Функции CreateProvFn и p1_SetMyCertProvFn для ключа компьютера и ключа пользователя создают хэндлы ключей для использования в библиотеке без обращения к интерфейсу пользователя (SILENT режим). Ключевые контейнеры должны содержать закрытые ключи обмена AT_KEYEXCHANGE и сертификаты этих ключей. Ключ аутентификации пользователя устанавливается в библиотеку вызовом p1_SetMyCertProvFn, передающем хендл провайдера с подготовленным для режима SILENT ключевым контейнером.

Требование к сертификатам сторон

  • сертификат должен быть выпущен "КриптоПро УЦ 1.3 или выше" (соответствовать RFC 4490)

  • срок действия закрытого ключа сертификата должен удовлетворять установленному регламенту и требованиям используемой версии "КриптоПро CSP" (обычно не более 1 года и трёх месяцев)

  • в случае, если сертификат используется не только для IKE и срок действия сертификата превышает срок действия закрытого ключа, то сертификат должен содержать расширение Private Key Usage Period [RFC3280]. При этом данное расширение должно контролироваться обеими сторонами для обоих сертификатов

  • проверяемый сертификат должен содержать в расширении EKU (Extended Key Usage) [RFC3280] назначение "1.3.6.1.5.5.8.2.2" (сертификат IKE посредник IP безопасности)

  • проверяемый сертификат должен содержать в расширении Key Usage [RFC3280] флаги: digitalSignature (цифровая подпись) и/или nonRepudiation (неотрекаемость), keyEncipherment (шифрование ключей) и/или keyAgreement (согласование ключей).

Поиск и проверка сертификатов

Поиск и проверка сертификата пользователя:

  • сертификат пользователя должен быть установлен в ключевом контейнере закрытого ключа пользователя

  • сертификат должен контролироваться приложением до вызова модуля IKE вызовом ikeCheckCert

Поиск и проверка сертификата оппонента:

  • поиск и проверка осуществляется приложением ISAKMP на этапе создания SA

  • если сертификат оппонента не найден, приложение устанавливает вложение ISAKMP CERTREQ в соответствующей фазе обмена и должна получить сертификат в ответном сообщении

  • полученный сертификат должен быть проверен вызовом ikeCheckCert

  • проверка сертификата должна включать проверку всей цепочки сертификата

  • сертификат корневого центра сертификации (ЦС), на котором заканчивается цепочка проверяемого сертификата, должен храниться в хранилище "Root" (доверенные корневые центры сертификации)

Закрытый ключ используется функцией p1_AuthIRFn. Рекомендуется до вызова:

  • задать PIN для доступа к ключевому носителю функцией SetProvParam(PP_KEYEXCHANGE_PIN)

  • открыть контейнер в режиме CRYPT_SILENT для запрета интерактивного взаимодействия СКЗИ "КриптоПро CSP" с пользователем

Время жизни SA

Результатом проверки срока действия ключа и сертификат функцией ikeCheckCert или проверки PSK функцией getPSKnotAfterFn является срок окончания действия ключа или запланированый срок следующего обновления статуса сертифката по СОС (CRL) или OCSP. Согласно п. 4.4.2.1 RFC 4301 [ARCH] рекомендуется согласовывать время жизни SA, которая завершится ранее полученного срока. Согласованные времена жизни SA должны быть установлены вызовами p1_SetParamFn (...CPIKE_AC_Life_Duration...CPIKE_LIFET_SECONDS...) и p2_SetParamFn (...CPIPSEC_AT_Life_Duration...CPIPSEC_LIFET_SECONDS...).

Note Замечание:

На ОС семейства Windows для проверки сертификата на отзыв по протоколу OCSP требуется установить Revocation Provider и клиент службы OCSP (являются дополнительными компонентами CSP 3.6).

На ОС семейства Linux проверка по протоколу OCSP должна быть реализована приложением самостоятельно


Рекомендации по использованию API SADB

API SADB

Управление ключами и данными протокола IPSec в вычислительной среде кластера (отдельного компьютера) обеспечивается средствами базы данных. В задачи базы данных входит:

  • обеспечение обмена и хранения ключей протокола в защищённом виде

  • обеспечение собственной ключевой системы

Система защиты ключей протокола определяется ассоциацией безопасности базы данных, задающей алгоритмы защиты ключей и их параметры. В дальнейшем комплекс управления ключами протокола IPSec и управления ключами базы данных будем обозначать SADB. Построение комплекса SADB осуществляется на базе API SADB.

Клиенты SADB и схемы обмена ключами и данными протокола IPSec.

Клиентами обмена ключами и данными протокола IPSec могут быть:

  • сессия фазы 1 протокола IKE (прикладной уровень)

  • сессия фазы 2 протокола IKE (прикладной уровень)

  • SADB - сессия базы данных (прикладной уровень)

  • сессии ESP/AH - процесса уровня ядра

Между клиентами производятся обмены информацией следующих типов:

  • обмен между различными объектами фазы 1 осуществляется транспортным представлением структуры SADBIKESA

  • обмен между различными объектами фазы 2 осуществляется транспортным представлением структуры SADBIPSECSA

  • обмен между объектами фазы 2 и ESP/AH осуществляется транспортным представлением структуры SADBIPSECSA

Ключевая система SADB

Ключевая система SADB включает закрытые и открытые ключи администраторов клиентов SADB и ключи обмена. В случае кластера закрытые ключи клиентов прикладного уровня могут совпадать с единственным ключом администратора кластера.

Виды закрытых ключей:

  • ключ на базе PSK

  • ключ из ключевого контейнера, хранящегося на устройстве долговременной внешней памяти

  • эфемерный ключ

В API SADB пользовательский ключ представляется структурой PRIVKEY, подготовка и сопровождение даннй структуры (создание ключей, уничтожение ключей, смена ключей) осуществляется приложением SADB. Открытый ключ, соответствующий закрытому ключу, представляется структурой SADBSA. Клиенты SADB, обменивающиеся информацией, также должны обменяться открытыми ключами. Обмен открытыми ключами осуществляется приложением SADB. В случае кластера с единым ключом все клиенты прикладного уровня имеют единый открытый ключ. Во внутреннем обмене клиент использует представление открытого ключа структурой PUBKEY.

Ключ обмена вырабатывается функциями API SADB из закрытого ключа клиента-отправителя информации, открытого ключа клиента-получателя и UKM, передаваемого в составе структуры данных.

Алгоритмы и параметры SADB

Алгоритм выработки закрытого ключа из PSK

Закрытый ключ SADB получается из PSK хешированием ASCII представления HEX-кода PSK. Длина представления - 34 байта. Параметры алгоритма выработки закрытого ключа из PSK:

  • CPIKE_HASH_A = 65501, // id-GostR3411-94-CryptoProParamSet

Алгоритм выработки ключа обмена

Ключ обмена вырабатывается по алгоритму VKO GOST R 34.10-2001 (п. 5.2. RFC 4357). Параметры алгоритма выработки ключа обмена:

  • CPIKE_HASH_A = 65501, // id-GostR3411-94-CryptoProParamSet

  • CPIKE_GROUP_XchA = 65509, // id-GostR3410-2001-CryptoPro-XchA-ParamSet

Алгоритмы экспорта/импорта ключей IKE и SPI

Экспорт/импорт ключей IKE и SPI осуществляется по алгоритму GOST 28147-89 Key Wrap, GOST 28147-89 Key Unwrap (пп. 6.1, 6.2. RFC 4357). Параметры алгоритмов экспорта/импорта ключей IKE и SPI:

  • CPIKE_ENC_A = 65502, // id-Gost28147-89-CryptoPro-A-ParamSet

Состав API SADB

Функции SADB

  • CreateProvFn

  • CreatePSKFn

  • CreateEphemFn

  • deSerializePubKeyFn

  • DestroyPrivKeyFn

  • DestroyPubKeyFn

Функции CreateEphemFn, deSerializePubKeyFn, DestroyPrivKeyFn, DestroyPubKeyFn используются как на прикладном уровне, так и на уровне ядра ОС.

Функции CreateProvFn и CreatePSKFn используются на прикладном уровне.

Функции API SADB не осуществляют выделения памяти под объекты. Приложение SADB должно обеспечить выделение памяти под структуры PRIVKEY, PRIVKEY и под транспортное представление структур.

Сценарии работы SADB. Подготовка закрытых ключей приложением SADB

Перед началом работы с клиентом приложение SADB должно создать контекст провайдера и установить пароль ключа на контекст.

  • CryptAcquireContext(&hProv, pszContanerName, ..., PROV_GOST_2001_DH, 0)

  • CryptSetProvParam(hProv, PP_KEYEXCHANGE_PIN, PIN, 0)

При использовании PSK необходимо создать контекст провайдера вызовом:

  • CryptAcquireContext(&hProv, NULL, ..., PROV_GOST_2001_DH, CRYPT_VERIFYCONTEXT)

На уровне ядра должны быть определены hModule, hProv вызовами:

  • CPCCreateProvider(&hModule, pConfig)

  • CPCAcquireContext(hModule, &hProv, NULL, CRYPT_VERIFYCONTEXT, pVTable)

В случае кластера все клиенты прикладного уровня используют единый ключ администратора кластера и единую структуру PRIVKEY. Для процесса ядра необходимо создать собственные ключи и собственные структуры PRIVKEY.

Сценарии работы SADB. Последовательность вызовов при инициализации

Последовательность при загрузке шлюза
User space | Kernel
создание данных для инициализации программного ДСЧ | инициализация программного ДСЧ
sadb.CreateProvFn или sadb.CreatePSKFn - создание PRIVKEY и сериализованного PubKey sadb.deSerializePubKeyFn - десериализация ESP PubKey | sadb.deSerializePubKeyFn - десериализация IKE PubKey sadb.CreateEphemFn - создание PRIVKEY и сериализованного PubKey

создание данных для инициализации программного ДСЧ

Copy Code
    DWORD dwDatalen;
    HCRYPTPROV hProv;
    BYTE *data;

    CryptAcquireContext(&hProv, 0, 0, PROV_GOST_2001_DH, CRYPT_VERIFYCONTEXT);
    CryptGetProvParam(hProv, PP_RANDOM, 0, &dwDatalen, 0);
    data = malloc(dwDatalen);
    CryptGetProvParam(hProv, PP_RANDOM, data, &dwDatalen, 0);
    CryptReleaseContext(hProv, 0);

инициализация программного ДСЧ

Входные данные data, PRNG_data_length.

Copy Code
    BYTE *data - указатель на данные
    DWORD PRNG_data_length - длина данных

    HCRYPTMODULE hModule;
    HCRYPTPROV hProv;
    DWORD dwDatalen;
    BYTE *data;

    CPCCreateProvider(&hModule, pConfig);
    hModule->AcquireContext(hModule, &hProv, NULL, CRYPT_VERIFYCONTEXT);

    dwDataLen = 0;
    hModule->GetProvParam(hModule, hProv, PP_RANDOM, NULL, &dwDataLen, 0);

    if(dwDataLen != PRNG_data_length) {
        ошибка длины данных;
    }
    CRYPT_DATA_BLOB CBlob;
    CBlob.cbData = dwDataLen;
    CBlob.pbData = data;

    hModule->SetProvParam(hModule, hProv, PP_RANDOM, (BYTE*)&CBlob, 0);

    hModule->ReleaseContext(hModule, hProv, 0);

Сценарии работы SADB. Рестарт vpnd

User space | Kernel
 | sadb.DestroyPubKeyFn(IKE_PubKey)
sadb.DestroyPubKeyFn(ESP_PubKey) sadb.DestroyPubFn (IKE_hpsadb) sadb.DestroyKeyFn (IKE_hsadb) cpike_shutdown_gost рестарт cpike_init_gost ike_init_espFn - игнорируем буфер инициализатор ДСЧ sadb.CreateProvFn или sadb.CreatePSKFn sadb.deSerializeFn | sadb.deSerializeFn Возвращаем ранее созданную SADB SA sadb.deSerializeFn

Сценарии работы SADB. Смена ключа модуля ядра.

Останавливаемся, а потом получаем открытый ключ SADB от модуля ядра.
User space | Kernel
 | sadb.CreateEphemFn
sadb.deSerializeFn sadb.DestroyPubFn ESP_hpsadb = ESP_hpsadb_new | sadb. DestroyKeyFn ESP_hsadb = ESP_hsadb_new

Сценарии работы SADB. Cмена ключа vpnd.

Для всех элементов IKE SA SADB выполняем операции:

  • p1_deSerializeFn(<старый ключ>)

  • p1_SerializeFn(<новый ключ>)

Для всех элементов IPsec SA SADB выполняем операции:

  • spireSerializeFn(<старый ключ>, <открытый новый>)

  • spireSerializeFn(<новый ключ>, <открытый новый>)

После этих действий, все узлы кластера выполняют сценарий:
User space | Kernel
sadb.DestroyPubFn (ESP_hpsadb) sadb.DestroyPubFn (IKE_hpsadb) sadb.DestroyKeyFn (IKE_hsadb) sadbCreateProvFn или sadbCreatePSKFn sadb.deSerializeFn |
 | sadb.DestroyPubFn (IKE_hpsadb) sadb.deSerializeFn Возвращаем ранее созданную SADB SA
sadb.deSerializeFn |


Справочник IKE

Общее описание библиотеки IKE

Библиотека libike_gost инициализируется приложением. Частичная инициализация выполняется автоматически при загрузке библиотеки в ОЗУ и окончательно вызовом функции инициализации cpike_init_gost.

Жизненный цикл IKE SA

IKE SA делятся на:

  • IKE SA фазы 1

  • IKE SA фазы 2

Над IKE SA фазы 1 допустимы операции:

  • Создание

  • Уничтожение

  • Наследование

  • Сериализация/десериализация

  • Установка/получение значений параметров

Над IKE SA фазы 2 допустимы операции:

  • Создание

  • Уничтожение

  • Наследование

  • Установка/получение значений параметров

В процессе работы может быть создано

  • на основе IKE SA фазы 1 - не более 2^12 IKE SA фазы 2 при условии использования PFS и 2^7 без использования PFS

  • время жизни IKE SA фазы 1 ограничено 10 сутками

  • время жизни обменов фазы 2 ограничено 24 часами

Создание IKE SA:

  • IKE SA фазы 1 создаётся при успешном выполнении сетевых обменов и вычислений фазы 1

  • Последним вызовом, участвующим в создании криптографических объектов IKE SA фазы 1, является p1_AgreeFn

  • IKE SA фазы 2 создаётся на основе IKE SA фазы 1 при успешном выполнении сетевых обменов и вычислений фазы 2

  • Последним вызовом, участвующим в создании криптографических объектов IKE SA фазы 2, является p2_AgreeFn

Хранение IKE SA:

  • сериализованные IKE SA могут быть сохранены на устройствах долговременной памяти

  • защита сериализованных IKE SA осуществляется с использованием ключа узла сети

Уничтожение IKE SA фаз 1 и 2:

  • вызовом destroyFn в процессе работы

  • вызовом cpike_shutdown_gost при завершении работы. При этом уничтожаются все криптографические объекты и очищаются все рабочие данные, ассоциированные со всеми SA

  • Уничтожение IKE SA фазы 1 не приводит к уничтожению IKE SA фазы 2, созданных на её основе

    Note Замечание:

    Рекомендуется сериализовать данные сессии фазы 1 IKE (p1_SerializeFn) и уничтожать сессию фазы 1. При необходимости создания сессии фазы 2 будет необходимо создать сессию фазы 1 из сериализованных данных (p1_deSerializeFn)
    Наследование IKE SA.

Под наследованием IKE SA понимается создание объектов на основе существующей IKE SA:

  • IKE SA фазы 2 на основе IKE SA фазы 1

  • SPI SA на основе IKE SA фазы 2

Сериализация/десериализация IKE SA фазы 1.

Сериализация/десериализация IKE SA фазы 1 используется для обеспечения отказоустойчивости при работе в составе кластера и повышения производительности:

  • Успешно созданная SA может быть сериализована

  • SA в неактивном состоянии не может быть сериализована

  • SA может быть сериализована по завершении выработки очередной IKE SA фазы 2

  • SA после сериализации может продолжать существовать

  • SA может быть десериализована произвольное количество раз

  • SA сериализуются вызовом p1_SerializeFn

  • SA десериализуются вызовом p1_deSerializeFn

  • при сериализации SA защищается с использованием ключа узла сети

Установка/получение параметров

  • Ряд параметров IKE SA согласовывается в ходе выполнения протокола ISAKMP

  • Ряд параметров IKE SA может быть установлен локально

  • Для части параметров по умолчанию заданы максимальные значения

  • Для этих параметров значения могут быть уменьшены и не могут быть увеличены

Кроме того:

  • Работа с параметрами IKE SA возможна после успешного вызовов p1_CreateFn, p2_CreateFn

  • Невозможна работа с параметрами IKE SA, находящейся в неактивном состоянии

  • Установка параметров невозможна во время создания производных объектов

  • Установка значений параметров осуществляется вызовами p1_SetParamFn, p2_SetParamFn

  • Получение значений параметров осуществляется вызовами p1_GetParamFn, p2_GetParamFn

Контроль времени жизни IKE SA

Под временем жизни IKE SA понимается как время жизни в секундах после создания, так и время жизни, измеренное в количестве обработанных данных.

Параметры библиотеки libike_gost

Библиотека имеет параметры инициализации. Эти параметры не связаны с параметрами, согласуемыми в процессе выполнения обменов IKE. При инициализации библиотеки не используются параметры, согласуемые в процессе работы.

Фиксированные параметры задаются на этапе компиляции исходных текстов библиотеки:

  • Версия API_MAJOR и API_MINOR

  • максимальное количество сессий фазы 1 и фазы 2

  • внешняя функция журналирования

  • дополнительный аргумент для внешней функции журналирования

Параметры IKE SA фазы 1

Фиксированные параметры SA:

  • Максимальное количество порождаемых из одной IKE SA фазы 1 IKE SA фазы 2 - 2^7 без PFS, 2^12 с PFS

  • максимальные значения счётчиков ошибок аутентификации фазы 2 - 10^6

  • максимальное время жизни SA - 10 суток

  • максимальный объём передаваемых данных до расшифровывания - 2^22 байтов

Следующие параметры имеют значения по умолчанию и могут быть изменены в процессе согласования:

  • узел замены для алгоритмов хэширования и ключевого хэширования - id-Gost28147-89-CryptoPro-B-ParamSet в соответствии с RFC 4357, п.8.2

  • В алгоритме выработки ключа Диффи-Хеллмана используется параметр UKM=1 в соответствии с RFC 4357, п.5.2

  • параметры шифрования и имитозащиты в протоколе - id-Gost28147-89-CryptoPro-B-ParamSet

  • параметры эллиптической кривой - id-GostR3410-2001-CryptoPro-XchB-ParamSet

  • время жизни SA в секундах - 3600 секунд. Максимальное значение 846000 (10 суток)

  • допустимое количество IKE SA фазы 2 - 2^7 без использования PFS, 2^12 с использованием PFS

Параметры IKE SA фазы 2

Фиксированные параметры IKE SA фазы 2:

  • Максимальное количество порождаемых ESP SA - 2

  • максимальное время жизни - 24 часа

  • максимальный объём передаваемых данных (до расшифровывания) - 2^22 байтов

Следующие параметры имеют значения по умолчанию и могут быть изменены в процессе согласования:

  • узел замены для алгоритмов хэширования и ключевого хэширования - id-Gost28147-89-CryptoPro-B-ParamSet в соответствии с RFC 4357, п.8.2

  • в алгоритме выработки ключа Диффи-Хеллмана используется параметр UKM=1 в соответствии с RFC 4357, п.5.2

  • параметры шифрования и имитозащиты в протоколе - id-Gost28147-89-CryptoPro-B-ParamSet

  • параметры эллиптической кривой - id-GostR3410-2001-CryptoPro-XchB-ParamSet

API библиотеки libike_gost

В реализации библиотеки и модуля ядра ОС используются соглашения, заимствуемые из базовой ОС и/или зависящие от неё:

  • определения используемых типов данных

  • определения прототипов функций, экспортируемых модулем

  • определения кодов возврата функций

  • определения кодов важности событий

  • определение прототипа внешней функции протоколирования

  • соглашения о вызовах функций модуля, включая определение порядка инициализации, ограничения на допустимые последовательности вызовов функций, ограничения на многонитевое использование

  • определение прототипа функции инициализации модуля

Перед началом использования библиотеки/модуля должна быть вызвана функция инициализации с указанием параметров. В число параметров входят данные, необходимые для:

  • контроля целостности ПО

  • контроля выполнения ограничений на используемый объём ОЗУ

Соглашение о вызовах:

  • Все функции библиотеки возвращают код возврата

  • Для работы с данными неопределённой длины используются соглашения, описанные, например, в документации на API MicroSoft

Многопоточная работа

Следующие функции не должны вызываться одновременно из различных потоков:

  • cpike_init_gost

  • cpike_shutdown_gost

  • CreateEphemFn

  • deSerializePubKeyFn

  • p1_CreateFn

  • p1_DestroyFn

  • p2_CreateFn

  • p2_DestroyFn

Остальные функции могут вызываться из различных потоков для различных сессий IKE.


Инициализация и завершение

Expand image Инициализация и завершение

 | Имя | Описание
function member | cpike_init_gost | Функция инициализации библиотеки libike_gost.
function member | cpike_shutdown_gost | Завершает работу библиотеки.
function member | LogUfn | Определяемая пользователем функция протоколирования.
function member | SetLogLvlUfn | Определяемая пользователем функция управлением протоколирования.


Функция cpike_init_gost
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Функция инициализации библиотеки libike_gost.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC cpike_init_gost (
   ike_gost_handle h,
   const ike_gost_in *in,
   unsigned uFlags,
   ike_gost_out *out
 );

Параметры

h
[in] handle библиотеки.
in
[in] Ссылка на структуру-описатель окружения выполнения библиотеки и требования к инициализации библиотеки.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
out
Ссылка на структуру-описатель свойств библиотеки.

Возвращаемое значение

handle библиотеки при успешном завершении, 0 при ошибке

Expand image Примечания

Функция вызывается 2 раза: на первом вызове функция определяет потребности в памяти для работы. На втором вызове, получив требуемую память, выполняет инициализацию библиотеки.


Функция cpike_shutdown_gost
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Завершает работу библиотеки.

Expand image Синтаксис

C/C++ Copy Code
 void CAPI_EXTC cpike_shutdown_gost (
   ike_gost_handle h,
   unsigned uFlags
 );

Параметры

h
[in] handle библиотеки.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.


Функция LogUfn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Определяемая пользователем функция протоколирования.

Expand image Синтаксис

C/C++ Copy Code
 static void CAPI_EXTC LogUfn (
   void *pUfnArg,
   log_severity_t severity,
   unsigned uFlags,
   const char *fmt,
   ...
 );

Параметры

pUfnArg
[in] Аргумент, переданный пользователем в структуре cpike_gost_in
severity
[in] Уровень важности сообщения.
uFlags
[in] Зарезервировано для будущего использования. Передаётся 0.
fmt
[in] Описатель формата вывода. Синтаксис соответствует синтаксису форматной строки printf().

Expand image Примечания

Если не задана, то используется стандартный printf(), который печатает все сообщения с уровнем важности больше или равный тому, который был установлен SetLogLvlUfn.

При её задании, должна быть также задана функция SetLogLvlUfn.


Функция SetLogLvlUfn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Определяемая пользователем функция управлением протоколирования.

Expand image Синтаксис

C/C++ Copy Code
 static void CAPI_EXTC SetLogLvlUfn (
   void *pUfnArg,
   log_severity_t severity,
   unsigned uFlags
 );

Параметры

pUfnArg
[int] Аргумент, переданный пользователем в структуре cpike_gost_in.
severity
[in] Уровень важности сообщения, ниже которого сообщения не протоколируются.
uFlags
[in] Зарезервировано для будущего использования. Передаётся 0.

Expand image Примечания

Игнорируется, если не задана функция LogUfn.


Работа с долговременными ключами и сертификатами IKE

Expand image Работа с долговременными ключами и сертификатами IKE

 | Имя | Описание
function member | getPSKnotAfterFn | Время истечения срока действия PSK.
function member | ikeCheckCert | Проверка сертификата на валидность.
function member | ikeCheckPrivateKeyUsagePeriod | Проверка срока действия закрытого ключа.


Функция getPSKnotAfterFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Время истечения срока действия PSK.

Expand image Синтаксис

C/C++ Copy Code
 static capi_result CAPI_EXTC getPSKnotAfterFn (
   ike_gost_handle h,
   const vblob & pPSKs,
   const vblob & pSiteNetID,
   const vblob & pSiteID,
   unsigned uFlags,
   time_t *ptNotAfter
 );

Параметры

h
[in] handle библиотеки;
pPSKs
[in] Строка, содержащая один или несколько PSK узлов сети.
pSiteNetID
[in] Идентификатор канала связи, которому принадлежит Site.
pSiteID
[in] Уникальный идентификатор узла сети (аналог fingerprint сертификата, серийного номера или аппаратного адреса).
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
ptNotAfter
[out] время истечения срока действия PSK.

Возвращаемое значение

CAPI_NOERROR Нормальное завершение.

CAPI_CALL_ERROR Неверные входные аргументы.

CAPI_PSK_TTL_EXPIRED_ERROR Срок действия PSK истёк.

CAPI_IMITA_ERROR PSK искажён (или в строке не найден PSK соответствующий pSiteID и pSiteNetID).

CAPI_PSK_ERROR PSK несовместимы - в строке есть PSK у которого не совпадает имитовставка или версия.

Expand image Примечания

SEE ALSO

p1_SetPSKFn, p1_SetParamFn, p2_SetParamFn, genpsk


Функция ikeCheckCert
Заголовочный файл: ike_cert.h
Библиотека: libike_gost.so

Проверка сертификата на валидность.

Expand image Синтаксис

C/C++ Copy Code
 capi_result ikeCheckCert (
   ike_gost_handle h,
   const BYTE *pbCert,
   unsigned uCertLen,
   PCCERT_CONTEXT *ppCertCtx,
   time_t *ptNotAfter
 );

Параметры

h
[in] handle библиотеки;
pbCert
[in] проверяемый сертификат
uCertLen
[in] длина проверяемого сертификата
ppCertCtx
[out] разобранный сертификат, в случае успешной проверки
ptNotAfter
[out] время истечения срока действия ключа или или срока следующего обновления СОС (CRL).

Возвращаемое значение

CAPI_NOERROR Нормальное завершение.

CAPI_CALL_ERROR Неверные входные аргументы.

CAPI_CHAIN_ERROR Ошибка при проверке сертификата и его цепочки.

Expand image Примечания

Данная функция представлена в виде исходного кода и находится в файле ike_cert.cpp.

SEE ALSO

p1_SetParamFn (), p2_SetParamFn ()


Функция ikeCheckPrivateKeyUsagePeriod
Заголовочный файл: ike_cert.h
Библиотека: libike_gost.so

Проверка срока действия закрытого ключа.

Expand image Синтаксис

C/C++ Copy Code
 static bool ikeCheckPrivateKeyUsagePeriod (
   ike_gost_handle h,
   PCCERT_CONTEXT pCertContext,
   FILETIME *pftNotAfter
 );

Параметры

h
[in] handle библиотеки;
pCertContext
[in] контекст проверяемого сертификата
pftNotAfter
[in] время окончания срока действия ключа

Возвращаемое значение

true Нормальное завершение.

false Ошибка.

Expand image Примечания

Данная функция представлена в виде исходного кода и находится в файле ike_cert.cpp.

Если расширение privateKeyUsagePeriod не задано, то срок действия закрытого ключа совпадает со сроком действия сертификата.

Если значение privateKeyUsagePeriod.NotBefore не задано, то время начала действия закрытого ключа совпадает со временем выпуска сертификата.

Значение privateKeyUsagePeriod.NotBefore должен быть обязательно задано, если это расширение присутствует.


Защита вложений ISAKMP

Expand image Защита вложений ISAKMP

 | Имя | Описание
function member | p1_DecapFn | Декапсуляция и расшифрование аутентификационных пакетов IKE (ISAKMP фаза 1).
function member | p1_EncapFn | Инкапсуляция и зашифрование аутентификационных пакетов IKE (ISAKMP фаза 1).
function member | p2_DecapFn | Декапсуляция и расшифрование данных сетевого обмена.
function member | p2_EncapFn | Инкапсуляция и зашифрование данных сетевого обмена.
function member | p2_HashAFn | Функция для расчёта HASH(1) и HASH(2) в соответствии с RFC2409 п.5.5. Аргументы SKEYID_a и M-ID подставляются автоматически.
function member | p2_VerifyAFn | Функция для проверки HASH(1) и HASH(2) в соответствии с RFC2409 п.5.5. Аргументы SKEYID_a и M-ID подставляются автоматически.


Функция p1_DecapFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Декапсуляция и расшифрование аутентификационных пакетов IKE (ISAKMP фаза 1).

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_DecapFn (
   P1_HANDLE sid,
   unsigned uFlags,
   void *pData,
   unsigned *puDataLen
 );

Параметры

sid
[in] handle IKE сессии фазы 1
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
pData
[in/out] Входной/выходной буфер данных
puDataLen
[in/out] Входная/выходная длина (выходная длина всегда меньше входной)

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и размер расшифрованных данных

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Применяется для расшифрования пакетов IKE (ISAKMP фаза 1)

После успешной аутентификации для декапсуляции и расшифрования данных информационного обмена следует использовать p2_DecapFn

Аутентификация считается законченной после выполнения функций p1_SerializeFn или p2_CreateFn


Функция p1_EncapFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Инкапсуляция и зашифрование аутентификационных пакетов IKE (ISAKMP фаза 1).

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_EncapFn (
   P1_HANDLE sid,
   unsigned uFlags,
   void *data,
   unsigned *datalen,
   unsigned buflen
 );

Параметры

sid
[in] handle IKE сессии фазы 1
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
data
[in/out] Входной/выходной буфер данных
datalen
[in/out] Входная/выходная длина
buflen
[in] Размер буфера данных

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и размер зашифрованных данных

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

CAPI_NOT_ENOUGH_SPACE Размер буфера недостаточен для инкапсуляции и шифрования данных

Expand image Примечания

Применяется для шифрования пакетов IKE фазы 1

После успешной аутентификации для инкапсуляции и зашифрования данных информационного обмена следует использовать p2_EncapFn

Аутентификация считается законченной после выполнения функций p1_SerializeFn или после p2_CreateFn


Функция p2_DecapFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Декапсуляция и расшифрование данных сетевого обмена.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_DecapFn (
   P2_HANDLE sid,
   unsigned uFlags,
   void *pData,
   unsigned *puDataLen
 );

Параметры

sid
[in] handle сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
pData
[in/out] Входной/выходной буфер данных
puDataLen
[in/out] Входная/выходная длина (выходная длина всегда меньше входной)

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и размер расшифрованных данных

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверный вызов

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Внутренняя ошибка библиотеки

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

CAPI_TTL_BYTES_EXPIRED_ERROR Превышено допустимое количество данных в рамках сессии

CAPI_TTL_SECS_EXPIRED_ERROR Превышено допустимое время жизни сессии

CAPI_IMITA_ERROR Ошибка имитовставки

CAPI_XAUTH Превышено максимальное количество ошибок имитовставки

Expand image Примечания

Используется для обслуживания информационного обмена, и для обмена пакетами аутентификации фазы 2 (Quick Mode)

Во время аутентификации IKE (ISAKMP фаза 1) следует использовать p1_DecapFn

Precondition:

  • Успешно созданная сесия фазы 2 p2_CreateFn

  • M_ID != 0


Функция p2_EncapFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Инкапсуляция и зашифрование данных сетевого обмена.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_EncapFn (
   P2_HANDLE sid,
   unsigned uFlags,
   void *pData,
   unsigned *puDataLen,
   unsigned uBufLen
 );

Параметры

sid
[in] ID сессии
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
pData
[in/out] Входной/выходной буфер данных
puDataLen
[in/out] Входная/выходная длина
uBufLen
[in] Размер буфера данных

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и размер зашифрованных данных

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверный вызов

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_TTL_BYTES_EXPIRED_ERROR Превышено допустимое количество данных в рамках сессии

CAPI_TTL_SECS_EXPIRED_ERROR Превышено допустимое время жизни сессии

CAPI_NOT_ENOUGH_SPACE Размер буфера недостаточен для инкапсуляции и

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

Expand image Примечания

Используется, как для обслуживания информационного обмена, так и для обмена пакетами аутентификации фазы 2 (Quick Mode)

Во время аутентификации IKE (ISAKMP фаза 1) следует использовать p1_EncapFn

Precondition:

  • Успешно созданная сесия фазы 2 p2_CreateFn

  • M_ID != 0


Функция p2_HashAFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Функция для расчёта HASH(1) и HASH(2) в соответствии с RFC2409 п.5.5. Аргументы SKEYID_a и M-ID подставляются автоматически.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_HashAFn (
   P2_HANDLE sid,
   unsigned uFlags,
   vblob **HASH,
   unsigned N,
   ...
 );

Параметры

sid
[in] handle сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
HASH
[out] Рассчитанный HASH
N
[in] Количество аргументов типа vblob*

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

Expand image Примечания

Вычисляет HASH = prf(SKEYID_a, M-ID | arg1 | ...)

Precondition:

  • Успешно созданная сесия фазы 2 p2_CreateFn

  • M_ID != 0


Функция p2_VerifyAFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Функция для проверки HASH(1) и HASH(2) в соответствии с RFC2409 п.5.5. Аргументы SKEYID_a и M-ID подставляются автоматически.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_VerifyAFn (
   P2_HANDLE sid,
   unsigned uFlags,
   const vblob *HASH,
   unsigned N,
   ...
 );

Параметры

sid
[in] handle сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
HASH
[in] Проверяемый HASH
N
[in] Количество аргументов типа vblob*

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Внутренняя ошибка библиотеки

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

Expand image Примечания

Проверяет HASH = prf(SKEYID_a, M-ID | arg1 | ...)

Precondition:

  • Успешно созданная сесия фазы 2 p2_CreateFn

  • M_ID != 0

Postcondition:

  • Выполнено одно из условий разрешения аутентификация Quick Mode функциями p2_Hash3Fn и p2_Verify3Fn


Аутентификация сторон IKE фазы 1

Expand image Аутентификация сторон IKE фазы 1

 | Имя | Описание
function member | p1_AgreeFn | Обработка параметров противоположной стороны обмена.
function member | p1_AuthIRFn | Расчёт HASH_I/R или SIG_I/R.
function member | p1_CreateFn | Создание описателя сессии IKE (фаза 1). Установка обязательных параметров сессии IKE.
function member | p1_DestroyFn | Удаляет сессию фазы 1.
function member | p1_GetParamFn | Получение значений параметров сессии IKE фазы 1.
function member | p1_NatDHashFn | Получение NatDHash.
function member | p1_SetMyCertProvFn | Устанавливает закрытый ключ и собственный сертификат для направления связи.
function member | p1_SetOtherCertFn | Устанавливает открытый ключ сертификата оппонента для направления связи.
function member | p1_SetParamFn | Установка необязательных атрибутов сессии IKE фазы 1.
function member | p1_SetPSKFn | Устанавливает PSK для направления связи.
function member | p1_SetupFn | Расчёт собственных Nonce, PublicKey.
function member | p1_VerifyIRFn | Проверка HASH_IR или SIG_IR.


Функция p1_AgreeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Обработка параметров противоположной стороны обмена.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_AgreeFn (
   P1_HANDLE sid,
   const vblob *SAi_b,
   const vblob *KEx_b,
   const vblob *Nonce_b,
   const vblob *CKY,
   unsigned uFlags
 );

Параметры

sid
[in] handle IKE сессии фазы 1
SAi_b
[in] SA противоположной стороны обмена
KEx_b
[in] Открытый ключ противоположной стороны обмена в сетевом представлении
Nonce_b
[in] Nonce противоположной стороны обмена
CKY
[in] CKY противоположной стороны обмена
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки


Функция p1_AuthIRFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Расчёт HASH_I/R или SIG_I/R.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_AuthIRFn (
   P1_HANDLE sid,
   const vblob *IDix_b,
   unsigned uFlags,
   vblob **hs
 );

Параметры

sid
[in] handle сессии IKE фазы 1
IDix_b
[in] собственный идентификатор
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hs
[out] Рассчитанный HASH_I/R или SIG_I/R

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

Expand image Примечания

В зависимости от выбранного метода аутентификации рассчитывает HASH_IR или SIG_IR.

TODO: Описать особенности функционирования в режиме CPIKE_AUTH_GSS_API


Функция p1_CreateFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Создание описателя сессии IKE (фаза 1). Установка обязательных параметров сессии IKE.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_CreateFn (
   ike_gost_handle h,
   const vblob **pcVendor_ID_b,
   CPIKE_AUTH_T am,
   IKE_ROLE role,
   CPIKE_ENC_T enc_mac_id,
   CPIKE_HASH_T hash_id,
   CPIKE_GTYPE_T gtype_id,
   CPIKE_GROUP_T group_id,
   unsigned uFlags,
   P1_HANDLE *sid
 );

Параметры

h
[in] handle библиотеки
pcVendor_ID_b
[in] список используемых приложением пространств приватных идентификаторов IKE, завершается нулевым указателем
am
[in] метод аутентификации (CPIKE_AUTH_GOST_PSK, CPIKE_AUTH_GOST_SIGNATURE, CPIKE_AUTH_GSS_API)
role
[in] Роль: Initiator или Responder
enc_mac_id
[in] согласованный идентификатор алгоритма шифрования и имитозащиты ISAKMP SA
hash_id
[in] согласованный идентификатор алгоритма хэш функции и PRF
gtype_id
[in] согласованный идентификатор типа группы Диффи-Хеллмана фазы 1
group_id
[in] согласованная группа Диффи-Хелмана фазы 1
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
sid
[out] ID созданной сессии

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и SID новой сессии

CAPI_NOERROR Нормальный возврат

CAPI_NOFREE_SID_ERROR Нет свободных SID

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Необязательные параметры сессии, которые имеют рекомендованные значения по умолчанию, могут быть изменены функцией p1_SetParamFn

Сроки действия PSK, закрытых ключей и сертификатов, которые будут использованы для аутентификации, рекомендуется учитывать путём установки параметра CPIKE_AC_Life_Duration

Функция p1_GetParamFn предназначена для получения действующих параметров сессии


Функция p1_DestroyFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Удаляет сессию фазы 1.

Expand image Синтаксис

C/C++ Copy Code
 void CAPI_EXTC p1_DestroyFn (
   P1_HANDLE sid,
   unsigned uFlags
 );

Параметры

sid
[in] handle удаляемой сессии
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0


Функция p1_GetParamFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Получение значений параметров сессии IKE фазы 1.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_GetParamFn (
   const P1_HANDLE sid,
   CPIKE_AC_T iacAtrCls,
   unsigned upClsType,
   unsigned uFlags,
   void *pClsVal,
   unsigned *puValLen
 );

Параметры

sid
[in] ID сессии
iacAtrCls
[in] ID параметра (Attribute Class)
upClsType
[in] значение типа параметра, если не равно нулю
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
pClsVal
[out] значение параметра (Class Value)
puValLen
[in/out] длина значения параметра

Возвращаемое значение

CAPI_NOERROR при нормальном завершении

CAPI_CALL_ERROR неверная последовательность вызовов

CAPI_UNSUPPORTED_ERROR получение данного параметра не поддерживается

CAPI_NOT_ENOUGH_SPACE недостаточно места для выдачи значения


Функция p1_NatDHashFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Получение NatDHash.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_NatDHashFn (
   P1_HANDLE sid,
   const vblob *CKY,
   const vblob *IP,
   const vblob *Port,
   unsigned uFlags,
   vblob **NatDHash
 );

Параметры

sid
[in] handle сессии IKE фазы 1
CKY
[in] CKY противоположной стороны обмена
IP
[in] IP-адрес (RFC 3947)
Port
[in] Port, соответствующий IP-адресу
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
NatDHash
[out] расчитанный хеш NatD

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и NatDHash

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR неверные аргументы

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки


Функция p1_SetMyCertProvFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Устанавливает закрытый ключ и собственный сертификат для направления связи.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SetMyCertProvFn (
   P1_HANDLE sid,
   HCRYPTPROV hProv,
   unsigned uFlags
 );

Параметры

sid
[in] handle сессии IKE фазы 1
hProv
[in] контекст контейнера
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Функция выполняет генерацию служебных ключей на основе ключа шифрования из hProv. При использовании сертификата требуется обеспечить, чтобы время жизни сессии не превышло срока действия сертификата. При необходимости воспользоваться функцией p1_SetParamFn.


Функция p1_SetOtherCertFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Устанавливает открытый ключ сертификата оппонента для направления связи.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SetOtherCertFn (
   P1_HANDLE sid,
   PCCERT_CONTEXT otherCertContext,
   unsigned uFlags
 );

Параметры

sid
[in] handle сессии IKE фазы 1
otherCertContext
[in] контекст открытого сертификата
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

При использовании сертификата требуется обеспечить, чтобы время жизни сессии не превышло срока действия сертификата. При необходимости воспользоваться функцией p1_SetParamFn.


Функция p1_SetParamFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Установка необязательных атрибутов сессии IKE фазы 1.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SetParamFn (
   P1_HANDLE sid,
   CPIKE_AC_T iacAtrCls,
   uintptr_t upClsVal,
   unsigned upClsType,
   unsigned uFlags
 );

Параметры

sid
[in] ID сессии
iacAtrCls
[in] ID параметра (Attribute Class)
upClsVal
[in] значение параметра (Class Value)
upClsType
[in] значение типа параметра, если не равно нулю
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

CAPI_NOERROR нормальное завершение

CAPI_UNSUPPORTED_ERROR смена данного параметра не поддерживается

CAPI_CALL_ERROR неверные аргументы вызова

Expand image Примечания

Обязательные атрибуты IKE (ISAKMP SA) устанавливаются функцией p1_CreateFn

Атрибуты, перечисленные ниже, имеют значения по умолчанию

ID параметра | Описание параметра | Значение по умолчанию | Используется функциями
CPIKE_AC_Life_Duration | Ограничение жизни ISAKMP SA по времени (CPIKE_LIFET_SECONDS) и по объёму данных (CPIKE_LIFET_KILOBYTES) При установке значений, превышающих CPIKE_MAX_SEC_LDURATION (CPIKE_MAX_BYTES_LDURATION), функция завершается без ошибки. Рекомендуется устанавливать оба ограничения. | 8 часов | p2_CreateFn, p2_DecapFn, p2_EncapFn
CPIKE_AC_Max_Messages | Максимальное количество сессий фазы 2, порождаемых из одной сессии фазы 1 Учитываются все сессии фазы 2: Quick Mode, информационные обмены, обмены с ошибкой | 2^12, если все Quick Mode были с PFS 2^7, если хотя бы одна Quick Mode создана без PFS | p2_CreateFn
CPIKE_AC_PFS_Control | если установлен CPIKE_PFSC_Mandatory_PFS, Quick Mode без PFS запрещена если установлен CPIKE_PFSC_Non_Mandatory_PFS, Quick Mode может быть как с PFS, так и без него. | CPIKE_PFSC_Non_Mandatory_PFS | p2_SetupFn

Смотри также:

  • [ipsec-registry] Internet Key Exchange (IKE) Attributes <http://www.iana.org/assignments/ipsec-registry>;

  • [IKE] The Internet Key Exchange (IKE) <http://tools.ietf.org/html/rfc2409#page-34>;

  • [draft.CPIKE] Использование ГОСТ 28147-89, ГОСТ Р 34.11-94 и ГОСТ Р 34.10-2001 при управлении ключами IKE и ISAKMP

SEE ALSO

ikeCheckCert, getPSKnotAfterFn chkpsk


Функция p1_SetPSKFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Устанавливает PSK для направления связи.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SetPSKFn (
   P1_HANDLE sid,
   const vblob *PSK,
   const vblob *SiteNetID,
   const vblob *SiteID,
   unsigned uFlags
 );

Параметры

sid
[in] handle IKE сессии фазы 1
PSK
[in] PSK парной связи
SiteNetID
[in] Идентификатор канала связи, которому принадлежит Site
SiteID
[in] Уникальный идентификатор узла сети (например, fingerprint сертификата, серийный номер или аппаратный адрес устройства связи)
uFlags
[in] Должен быть равен 0 или P1_SETPSK_HCRYPT. В случае P1_SETPSK_HCRYPT параметр PSK воспринимается как HCRYPTKEY (симметричный экспортируемый ключ), параметр SiteNetID как HCRYPTPROV провайдер, на котором получен ключ HCRYPTKEY в PSK, параметр SiteID игнорируется.

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы

CAPI_PSK_TTL_EXPIRED_ERROR Срок действия PSK истёк

CAPI_IMITA_ERROR PSK искажён

CAPI_PSK_ERROR PSK несовместимы - в строке есть PSK у которого не совпадает имитовставка или версия

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

При использовании PSK требуется обеспечить, чтобы время жизни сессии не превышло времени жизни PSK. При необходимости воспользоваться функцией p1_SetParamFn.

see also

getPSKnotAfterFn, genpsk


Функция p1_SetupFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Расчёт собственных Nonce, PublicKey.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SetupFn (
   P1_HANDLE sid,
   const vblob *CKY,
   unsigned uFlags,
   vblob **KE,
   vblob **Nonce
 );

Параметры

sid
[in] handle сессии IKE фазы 1
CKY
[in] собственный CKY
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
KE
[out] собственный открытый ключ Диффи-Хелмана
Nonce
[out] собственный Nonce

Возвращаемое значение

При успехе возвращает CAPI_NOERROR, Nonce и KE

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR неверные аргументы

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки


Функция p1_VerifyIRFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Проверка HASH_IR или SIG_IR.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_VerifyIRFn (
   P1_HANDLE sid,
   const vblob *IDix_b,
   vblob **hash,
   unsigned uFlags
 );

Параметры

sid
[in] handle сессии IKE фазы 1
IDix_b
[in] идентификатор оппонента
hash
[in/out] Проверяемый HASH или SIG. В случае флага FLAG_P1_VERIFY_WITH_BLOB_RETURN создаётся
uFlags
[in] возможные значения

  • 0

  • FLAG_P1_VERIFY_WITH_BLOB_RETURN

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_MSG_FORMAT_ERROR Ошибка проверки HASH

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

В зависимости от выбранного метода аутентификации проверяет HASH_IR или SIG_IR, полученный от оппонента

TODO: Описать особенности функционирования в режиме CPIKE_AUTH_GSS_API


Сериализация и десериализация данных IKE фазы 1

Expand image Сериализация и десериализация данных IKE фазы 1

 | Имя | Описание
function member | p1_deSerializeFn | Десериализация данных фазы 1.
function member | p1_reSerializeFn | Ресериализация данных фазы 2.
function member | p1_SerializeFn | Сериализация данных фазы 1.


Функция p1_deSerializeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Десериализация данных фазы 1.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_deSerializeFn (
   CAPI_IN ike_gost_handle h,
   CAPI_IN PRIVKEY & hPriv,
   CAPI_IN PUBKEY & hPub,
   CAPI_IN const vblob *p1_data,
   CAPI_IN unsigned uFlags,
   CAPI_OUT P1_HANDLE *sid
 );

Параметры

h
[in] handle библиотеки.
hPriv
[in] Закрытый ключ десериализации.
hPub
[in] Открытый ключ десериализации.
p1_data
[in] инкапсулированные и защищённые данные фазы 1.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
sid
[out] handle новой сессии фазы 1.

Возвращаемое значение

При успехе возвращает десериализованную SA

CAPI_NOERROR Нормальный возврат.

CAPI_CSP_ERROR Ошибка вызова криптобиблиотеки.

CAPI_NOFREE_SID_ERROR Недостаточно памяти для создания сессии.

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки.

CAPI_CALL_ERROR Ошибка в аргументах при вызове.

CAPI_PROTOCOL_ERROR Открытый ключ или создан "в будущем" или истекло его время жизни

Expand image Примечания

При десериализации данных сессии фазы 1 восстанавливаются ключи SKEYID_a, SKEYID_d, SKEYID_e, Last-ICV, AUTH-I, AUTH-R. Ключи импортируются как SIMPLEBLOB. Импорт осуществляется на ключевой паре (hPriv,hPub).


Функция p1_reSerializeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Ресериализация данных фазы 2.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_reSerializeFn (
   CAPI_IN ike_gost_handle h,
   CAPI_IN PRIVKEY & hPriv_from,
   CAPI_IN PRIVKEY & hPriv_to,
   CAPI_IN PUBKEY & hPub_from,
   CAPI_IN PUBKEY & hPub_to,
   CAPI_IN const vblob *p1_data_from,
   CAPI_IN unsigned uFlags,
   CAPI_OUT vblob **p1_data_to
 );

Параметры

h
[in] handle библиотеки.
hPriv_from
[in] Закрытый ключ десериализации.
hPriv_to
[in] Закрытый ключ сериализации.
hPub_from
[in] Открытый ключ источника.
hPub_to
[in] Открытый ключ приёмника.
p1_data_from
[in] Входные данные. Защищены на ключе источника.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
p1_data_to
[out] Выходные данные. Защищены на ключе получателя.

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат.

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки.

CAPI_PROTOCOL_ERROR Открытый ключ или создан "в будущем" или истекло его время жизни.

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_CALL_ERROR Вызов с недопустимыми аргументами

Expand image Примечания

Данные защищаются на ключе адресата и подготавливаются к транспорту. Входные и выходные данные не должны совпадать


Функция p1_SerializeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Сериализация данных фазы 1.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p1_SerializeFn (
   CAPI_IN const P1_HANDLE sid,
   CAPI_IN PRIVKEY & hPriv,
   CAPI_IN PUBKEY & hPub,
   CAPI_IN unsigned uFlags,
   CAPI_OUT vblob **p1_data
 );

Параметры

sid
[in] ID сессии.
hPriv
[in] Закрытый ключ сериализации.
hPub
[in] Открытый ключ сериализации.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
p1_data
[out] инкапсулированные и защищённые данные фазы 1.

Возвращаемое значение

При успехе возвращает сериализованную SA

CAPI_NOERROR Нормальный возврат.

CAPI_CSP_ERROR Ошибка вызова криптобиблиотеки.

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки.

CAPI_CALL_ERROR Ошибка в аргументах при вызове.

CAPI_PROTOCOL_ERROR Открытый ключ или создан "в будущем" или истекло его время жизни.

Expand image Примечания

При сериализации данных сессии фазы 1 сохраняются ключи SKEYID_a, SKEYID_d, SKEYID_e, Last-phase-1-ICV, AUTH-I, AUTH-R и сумма CKY-I + CKY-R + M_ID. Ключи экспортируются в виде SIMPLEBLOB. Для экспорта внешний ключ - пара (hPriv,hPub).

Сериализация сигнализирует о завершении аутентификации, запрещает операции обмена данными аутентификации фазы 1 p1_EncapFn/p1_DecapFn.


Функции фазы 2

Expand image Функции фазы 2

 | Имя | Описание
function member | p2_AgreeFn | Обработка параметров соединения.
function member | p2_CreateFn | Создание описателя сессии фазы 2. Установка основных параметров сессии.
function member | p2_DestroyFn | Удаляет сессию IKE фазы 2.
function member | p2_GetParamFn | Получение значений параметров IPsec.
function member | p2_Hash3Fn | Вычисление HASH_3.
function member | p2_SetParamFn | Установка параметров IPsec.
function member | p2_SetupFn | Расчёт Nonce, собственного KE и, в случае использования PFS, AgreeKey.
function member | p2_Verify3Fn | Проверка HASH_3.


Функция p2_AgreeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Обработка параметров соединения.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_AgreeFn (
   P2_HANDLE sid,
   const vblob *KEo_b,
   const vblob *nonce,
   unsigned uFlags
 );

Параметры

sid
[in] handle сессии IKE фазы 2
KEo_b
[in] полученное от оппонента вложение Key Exchange
nonce
[in] Nonce противоположной стороны обмена
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Precondition:

  • успешный вызов p2_SetupFn в данной сессии

  • Если KE_b == 0, то параметр IKE (фаза 1) CPIKE_AC_PFS_Control должен иметь значение CPIKE_PFSC_Enable_Non_PFS;

  • Если KE_b != 0, то успешная установка группы Диффи-Хелмана функцией p2_SetParamFn

Postcondition:

  • Выполнено одно из условий разрешения аутентификация Quick Mode функциями p2_Hash3Fn и p2_Verify3Fn


Функция p2_CreateFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Создание описателя сессии фазы 2. Установка основных параметров сессии.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_CreateFn (
   ike_gost_handle h,
   P1_HANDLE p1sid,
   IKE_ROLE role,
   const vblob *M_ID,
   unsigned uFlags,
   P2_HANDLE *sid
 );

Параметры

h
[in] handle библиотеки
p1sid
[in] handle сессии IKE фазы 1, на основе который создаётся сессия фазы 2
role
[in] Инициатор или Респондер
M_ID
[in] Message ID
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
sid
[out] handle созданной сессии IKE фазы 2

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и SID новой сессии

CAPI_NOERROR Нормальный возврат

CAPI_NOFREE_SID_ERROR Нет свободных SID

CAPI_PROTOCOL_ERROR Неверная последовательность вызовов

CAPI_CALL_ERROR неверные аргументы вызова

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Предназначено для создания всех типов сессий обменов фазы 2

Сроки действия PSK, закрытых ключей и сертификатов, которые использовались для аутентификации на фазе 1, рекомендуется учитывать путём установки параметра CPIPSEC_AT_Life_Duration.

Precondition:

  • фаза 1 c успешно завершённой аутентификацией (p1_VerifyIRFn) или фаза 1 успешно из кэш (p1_deSerializeFn)

  • M_ID != 0 и является уникальным в рамках данной сессии фазы 1

  • время жизни CPIKE_AC_Life_Duration фазы 1 ещё не истекло

  • счётчик CPIKE_AC_Max_Messages не исчерпан

Postcondition:

  • Успешно созданная сессия фазы 2 с параметрами по умолчанию (см. p2_SetParamFn);

  • Для фазы 1 запрещён обмен пакетами функциями p1_EncapFn и p1_DecapFn

  • Для фазы 1 запрещён экспорт её в кэш функцией p1_SerializeFn

  • счётчики CPIKE_AC_Max_Messages не исчерпаны


Функция p2_DestroyFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Удаляет сессию IKE фазы 2.

Expand image Синтаксис

C/C++ Copy Code
 void CAPI_EXTC p2_DestroyFn (
   P2_HANDLE sid,
   unsigned uFlags
 );

Параметры

sid
[in] handle удаляемой сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0


Функция p2_GetParamFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Получение значений параметров IPsec.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_GetParamFn (
   P2_HANDLE sid,
   CPIPSEC_AT_T iatAtrCls,
   unsigned upClsType,
   unsigned uFlags,
   void *pClsVal,
   unsigned *puValLen
 );

Параметры

sid
[in] handle сессии IKE фазы 2
iatAtrCls
[in] ID параметра (Attribute Class)
upClsType
[in] значение типа параметра, если не равно нулю
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
pClsVal
[in] значение параметра (Class Value)
puValLen
[in/out] длина значения параметра

Возвращаемое значение

CAPI_NOERROR при нормальном завершении

CAPI_UNSUPPORTED_ERROR получение данного параметра не поддерживается

CAPI_CALL_ERROR неверно заданы параметры

CAPI_NOT_ENOUGH_SPACE недостаточно места для выдачи значения

CAPI_INTERNAL_ERROR внутренняя ошибка библиотеки

Expand image Примечания

Precondition:

  • Успешно созданная сессия фазы 2 p2_CreateFn


Функция p2_Hash3Fn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Вычисление HASH_3.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_Hash3Fn (
   P2_HANDLE sid,
   unsigned uFlags,
   vblob **HASH3
 );

Параметры

sid
[in] handle сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
HASH3
[out] Вычисляемый HASH_3

Возвращаемое значение

При успехе возвращает CAPI_NOERROR и значение HASH_3

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Precondition:

  • успешный вызов p2_VerifyAFn в данной сессии

  • успешный вызов p2_AgreeFn в данной сессии.

Postcondition:

  • разрешена выработка non-ISAKMP SA вызовом spiSerializeFn.


Функция p2_SetParamFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Установка параметров IPsec.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_SetParamFn (
   P2_HANDLE sid,
   CPIPSEC_AT_T iatAtrCls,
   uintptr_t upClsVal,
   unsigned upClsType,
   unsigned uFlags
 );

Параметры

sid
[in] ID сессии
iatAtrCls
[in] ID параметра (Attribute Class)
upClsVal
[in] значение параметра (Class Value)
upClsType
[in] значение типа параметра, если не равно нулю.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

CAPI_NOERROR нормальное завершение

CAPI_CALL_ERROR неверно заданы параметры

CAPI_UNSUPPORTED_ERROR параметр не поддерживатеся

Expand image Примечания

При установке параметра CPIPSEC_AT_Group_Description устанавливается использование PFS с ключами Диффи-Хелмана в соответствующей группе.

Установленные параметры IPsec передаются реализациям других протоколов (например, ESP) функцией spiSerializeFn.

ID параметра | Описание параметра | Значение по умолчанию | Используется функциями
CPIPSEC_AT_Life_Duration | Ограничение жизни IPsec SA по объёму (CPIPSEC_LIFET_KILOBYTES) и по времени (CPIPSEC_LIFET_SECONDS) При установке значений, которые превышают CPIPSEC_MAX_SEC_LDURATION, - CPIPSEC_MAX_SIMPLE_KBS, CPIPSEC_MAX_4M_KBS или CPIPSEC_MAX_1K_KBS, функция исполняется успешно, но при экспорте IPsec SA функцией spiSerializeFn в протокол будет выдано сообщение уровня CAPI_NOTICE | По объёму: 4 Мб для CPESP_GOST_SIMPLE_IMIT, 2^32-1 Кбайт для остальных По времени: 24 часа или ограничение фазы 1 по времени, в зависимости от того, что меньше. Рекомендуется устанавливать оба ограничения. | espDecapFn, espEncapFn
CPIPSEC_AT_Group_Description | Параметры группы Диффи-Хелмана для PFS | PFS не используется | p2_SetupFn, p2_AgreeFn
CPIPSEC_AT_Ext_Serial_Number | Управление ESN в IPsec SA. Если передано значение CPESP_ESN_Enable, то IPsec SA предназначена для обмена пакетами с расширенными 64-бит серийными номерами (ESN) | ESN запрещён | espDecapFn, espEncapFn
CPIPSEC_AT_Max_Packet_Len | максимальный размер ESP-пакета | 64KB | espDecapFn, espEncapFn
CPIPSEC_AT_GOST_28147_SBOX | Узлы замены ГОСТ 28147-89 | CPESP_SBOX_B | espDecapFn, espEncapFn
CPIPSEC_AT_Max_Auth_Error | Максимальное значение кол-ва ошибок аутентификации (CAPI_IMITA_ERROR) При установке значений, которые превышают CPIPSEC_SIMPLE_MAX_AUTH_ERR, CPIPSEC_4M_MAX_AUTH_ERR, CPIPSEC_1K_MAX_AUTH_ERR или CPIPSEC_1K_KC_MAX_AUTH_ERR, функция исполняется успешно, но при экспорте non-ISAKMP SA функцией spiSerializeFn в протокол будет выдано сообщение уровня CAPI_NOTICE | 10^6 | espDecapFn, espEncapFn
CPIPSEC_ATP_Check_SN | Управление проверкой SN (ESN) в IPsec SA. Если проверка включена (CPESP_CHKSN_Enable), то функции espDecapFn, espEncapFn дополнительно возвращают код ошибки CAPI_SN_ERROR. | Проверка включена | espDecapFn, espEncapFn

Смотри так же:

  • [Magic-Numbers] "Magic Numbers" for ISAKMP Protocol <http://www.iana.org/assignments/isakmp-registry>;

  • [ISAKMP] Internet Security Association and Key Management Protocol (ISAKMP) <http://tools.ietf.org/html/rfc2408#section-3.5>;

  • [DOI] The Internet IP Security Domain of Interpretation for ISAKMP <http://tools.ietf.org/html/rfc2407#section-4.4.3>;

  • [rus.CPESP] Использование ГОСТ 28147-89 при шифрования вложений IPsec (ESP) <rus-fedchenko-cpesp-ipsecme-gost-NN.xml>.

Precondition:

  • Успешно созданная сессия фазы 2 p2_CreateFn

Postcondition:

  • При успешной установке CPIKE_AC_Group_Description для функций p2_SetupFn и p2_AgreeFn предписывается использование PFS

SEE ALSO

ikeCheckCert, getPSKnotAfterFn


Функция p2_SetupFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Расчёт Nonce, собственного KE и, в случае использования PFS, AgreeKey.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_SetupFn (
   P2_HANDLE sid,
   unsigned uFlags,
   vblob **KE_b,
   vblob **N_b
 );

Параметры

sid
[in] handle сессии IKE фазы 2
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
KE_b
[in/out] вложение Key Exchange для передачи оппоненту (открытый ключ Диффи-Хелмана)

  • входное значение 0 означает отказ от генерации ключа

N_b
[out] Nonce

Возвращаемое значение

При успехе возвращает CAPI_NOERROR, N_b и KE_b

CAPI_NOERROR Нормальный возврат

CAPI_CALL_ERROR Неверные аргументы вызова

CAPI_CSP_ERROR ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Precondition:

  • Успешно созданная сессия фазы 2 p2_CreateFn

  • Если KE_b == 0, то параметр IKE (фаза 1) CPIKE_AC_PFS_Control должен иметь значение CPIKE_PFSC_Enable_Non_PFS

  • Если KE_b != 0, то успешная установка группы Диффи-Хелмана функцией p2_SetParamFn

Postcondition:

  • Разрешена p2_AgreeFn


Функция p2_Verify3Fn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Проверка HASH_3.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC p2_Verify3Fn (
   P2_HANDLE sid,
   const vblob *HASH3,
   unsigned uFlags
 );

Параметры

sid
[in] handle сессии IKE фазы 2
HASH3
[in] Проверяемый HASH_3
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат

CAPI_IMITA_ERROR Ошибка имитовставки

CAPI_CALL_ERROR Неверная последовательность вызовов

CAPI_CSP_ERROR ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Precondition:

  • успешный вызов p2_VerifyAFn в данной сессии

  • успешный вызов p2_AgreeFn в данной сессии

Postcondition:

  • разрешена выработка non-ISAKMP SA вызовом spiSerializeFn


Сериализация и десериализация данных QuickMode

Expand image Сериализация и десериализация данных QuickMode

 | Имя | Описание
function member | spireSerializeFn | Ресериализация данных фазы 2.
function member | spiSerializeFn | Сериализация данных IPsec SA/ESP.


Функция spireSerializeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Ресериализация данных фазы 2.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC spireSerializeFn (
   CAPI_IN ike_gost_handle h,
   CAPI_IN PRIVKEY & hPriv_from,
   CAPI_IN PRIVKEY & hPriv_to,
   CAPI_IN PUBKEY & hPub_from,
   CAPI_IN PUBKEY & hPub_to,
   CAPI_IN const vblob *spi_data_from,
   CAPI_IN unsigned uFlags,
   CAPI_OUT vblob **spi_data_to
 );

Параметры

h
[in] handle библиотеки.
hPriv_from
[in] Закрытый ключ десериализации.
hPriv_to
[in] Закрытый ключ сериализации.
hPub_from
[in] Открытый ключ источника.
hPub_to
[in] Открытый ключ приёмника.
spi_data_from
[in] Входные данные. Защищены на ключе источника.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
spi_data_to
[out] Выходные данные. Защищены на ключе получателя.

Возвращаемое значение

При успехе возвращает CAPI_NOERROR.

CAPI_NOERROR Нормальный возврат.

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки.

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_CALL_ERROR Вызов с недопустимыми аргументами

CAPI_PROTOCOL_ERROR Открытый ключ или создан "в будущем" или истекло его время жизни.

Expand image Примечания

Данные защищаются на ключе адресата и подготавливаются к транспорту. Входные и выходные данные не должны совпадать


Функция spiSerializeFn
Заголовочный файл: ike_gost.h
Библиотека: libike_gost.so

Сериализация данных IPsec SA/ESP.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC spiSerializeFn (
   CAPI_IN P2_HANDLE sid,
   CAPI_IN PRIVKEY & hPriv,
   CAPI_IN PUBKEY & hPub,
   CAPI_IN const vblob *spi,
   CAPI_IN CPESP_DIRECTION_T dir,
   CAPI_IN CPIPSEC_PROTOCOL_ID_T ip_satype,
   CAPI_IN CPESP_TRANSFORM_ID ip_encrypt,
   CAPI_IN CPAH_TRANSFORM_ID ip_auth,
   CAPI_IN unsigned uFlags,
   CAPI_OUT vblob **spi_data
 );

Параметры

sid
[in] ID сессии
hPriv
[in] Закрытый ключ сериализации
hPub
[in] Открытый ключ сериализации
spi
[in] SPI
dir
[in] направление SPI
ip_satype
[in] тип SA
ip_encrypt
[in] Идентификатор алгоритма шифрования
ip_auth
[in] Идентификатор алгоритма аутентификации
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
spi_data
[out] сериализованные данные фазы 2

Возвращаемое значение

При успехе возвращает CAPI_NOERROR

CAPI_NOERROR Нормальный возврат.

CAPI_PROTOCOL_ERROR Запрос на сериализацию при недопустимом состоянии сессии. Открытый ключ или создан "в будущем" или истекло его время жизни.

CAPI_CALL_ERROR Вызов с недопустимыми аргументами

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Сохраняются: тип сессии, SPIcookies и 2 симметричных ключа

Для DOI (RFC 2407) определены протоколы:

  • CPIKE_PROTO_ISAKMP;

  • CPIKE_PROTO_IPSEC_ESP;

  • CPIKE_PROTO_IPSEC_AH;

  • CPIKE_PROTO_IPCOMP;

Возможные значения параметров ip_encrypt, ip_auth для CPIPSEC_PROTO_IPSEC_ESP:

CPESP_GOST_SIMPLE_IMIT, CPESP_MAC_NULL - трансформ ESP, ипользующийся для поддержки совместимости с предшествующими реализациями

CPESP_GOST_4M_IMIT, CPESP_MAC_NULL - трансформ ESP с фиксированным ключом на 64 пакета, обеспечивающий шифрование и имитозащиту вложения

CPESP_GOST_1K_IMIT, CPESP_MAC_NULL - трансформ ESP с ключом на пакет, обеспечивающий шифрование и имитозащиту вложения

CPESP_NULL, CPAH_GOST_HMAC_4M - трансформ AH с фиксированным ключом на 64 пакета, обеспечивающий аутентичность вложения

CPESP_NULL, CPAH_GOST_HMAC_1K - трансформ AH с ключом на пакет, обеспечивающий аутентичность вложения

Возможные значения параметров ip_encrypt, ip_auth для CPIPSEC_PROTO_IPSEC_AH:

CPESP_NULL, CPAH_GOST_HMAC_4M - трансформ AH с фиксированным ключом на 64 пакета, обеспечивающий аутентичность пакета

CPESP_NULL, CPAH_GOST_HMAC_1K - трансформ AH с ключом на пакет, обеспечивающий аутентичность пакета


Описание типа vblob

Expand image Описание типа vblob

 | Имя | Описание
enum member | DATA_TYPE | Описание типов vblob.
function member | vcreate | Создание vblob из неконстантных данных.
function member | vdelete | Удаление vblob.
function member | vdtype | Возвращает тип хранимых данных.
function member | vis_valid | Проверяет корректность объекта.
function member | vref | Выдаёт указатель для доступа на чтение.
function member | vsize | Возвращает длину данных.


Перечисление DATA_TYPE
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Описание типов vblob.

Expand image Примечания

  • DT_SITEID -- идентификатор узла сети (Site). Текстовая строка. Имеет произвольную длину. Задаётся пользователем библиотеки.

  • DT_PSK -- PreShared Key. Текстовая строка. Имеет длину 28 или 56 байтов. Задаётся пользователем библиотеки.

  • DT_NETID -- идентификатор сети. Текстовая строка. Имеет произвольную длину. Задаётся пользователем библиотеки.

  • DT_SA -- SA. Имеет произвольную длину. Задаётся пользователем библиотеки.

  • DT_CKY -- CKY. Имеет длину 4 байта. Задаётся пользователем библиотеки.

  • DT_M_ID -- M-ID. Возможная длина от 4 до 256 байтов. Задаётся пользователем библиотеки.

  • DT_KEY -- PUBLICKEYBLOB. 100 байтов. Создаётся библиотекой.

  • DT_NONCE -- Nonce. При генерации длина и данные задаются внутри библиотеки. При использовании (на "другой" стороне соединения) должны быть известны пользователю библиотеки.

  • DT_SIG_IR -- Цифровая подпись. При генерации длина и данные задаются внутри библиотеки. При использовании (на "другой" стороне соединения) должны быть известны пользователю библиотеки.

  • DT_HASH_IR, DT_HASH -- различные хэш внутри фазы 1 IKE. При генерации длина и данные задаются внутри библиотеки. При использовании (на "другой" стороне соединения) должны быть известны пользователю библиотеки.

  • DT_P1_DATA - сериализованные данные сессии фазы 1 IKE. Создаётся библиотекой.

  • DT_SPI_DATA - сериализованные данные для создания SPI-сессии в ESP. Создаётся библиотекой.

  • DT_EXTDATA -- неспецифицируемые данные. Имеют произвольную длину. Задаются пользователем библиотеки.

Особенности реализации: Для всех данных vblob выполняет распределение памяти.


Функция vcreate
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Создание vblob из неконстантных данных.

Expand image Синтаксис

C/C++ Copy Code
 vblob* vcreate (
   DATA_TYPE dp,
   char *d,
   unsigned l
 );

Параметры

dp
[in] тип данных
d
[in] указатель на данные
l
[in] длина данных

Возвращаемое значение

указатель на созданный vblob или 0


Функция vdelete
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Удаление vblob.

Expand image Синтаксис

C/C++ Copy Code
 void vdelete (
   vblob **v
 );

Параметры

v
[in] указатель на указатель на vblob


Функция vdtype
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Возвращает тип хранимых данных.

Expand image Синтаксис

C/C++ Copy Code
 DATA_TYPE vdtype (
   vblob *v
 );

Параметры

v
[in] указатель на vblob

Возвращаемое значение

Тип хранимых данных


Функция vis_valid
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Проверяет корректность объекта.

Expand image Синтаксис

C/C++ Copy Code
 bool vis_valid (
   vblob *v
 );

Параметры

v
[in] указатель на vblob

Возвращаемое значение

true если объект корректен, иначе false


Функция vref
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Выдаёт указатель для доступа на чтение.

Expand image Синтаксис

C/C++ Copy Code
 const char* vref (
   vblob *v
 );

Параметры

v
[in] указатель на vblob

Возвращаемое значение

Валидный указатель или 0


Функция vsize
Заголовочный файл: vblob.h
Библиотека: libike_gost.so

Возвращает длину данных.

Expand image Синтаксис

C/C++ Copy Code
 unsigned vsize (
   vblob *v
 );

Параметры

v
[in] указатель на vblob

Возвращаемое значение

Длина данных


Справочник ESP/AH

Общее описание библиотеки и модуля ядра ESP/AH

Реализация поддержки протоколов семейства ESP/AH реализована в виде модуля уровня ядра ОС esp_gost.o и библиотеки уровня пользователя libesp_gost.so.

Библиотека и модуль ядра инициализируются кодом пользователя. Частичная инициализация выполняется автоматически при загрузке в ОЗУ и окончательно вызовами функции инициализации cpesp_init_gost.

Жизненный цикл ESP SA

Поддержка протоколов ESP/AH включает в себя реализацию 3-х комбинированных методов защиты данных (combined algorithms [ESP]):

  • ESP_GOST-SIMPLE-IMIT

  • ESP_GOST-4M-IMIT

  • ESP_GOST-1K-IMIT

  • AH_GOST-HMAC-4M

  • AH_GOST-HMAC-1K

Над ESP/AH SA допустимы операции:

  • Создание

  • Уничтожение

  • Десериализация

  • Использование для обработки входных/выходных данных

Создание ESP/AH SA:

  • SA создаётся на основе IKE SA фазы 2. Последним вызовом, участвующим в создании криптографических объектов, является spiCreateFn.

Хранение ESP/AH SA:

  • сериализованные ESP/AH SA могут быть сохранены на устройствах долговременной памяти (HDD)

  • защита сериализованных ESP SA осуществляется с использованием ключа защиты канала связи между адресными пространствами пользователя и ядра ОС

  • перед транспортировкой ESP SA в модуль ядра ОС выполняется преобразование защиты с использованием ключа защиты канала между адресными пространствами пользователя и ядра ОС

  • ключ защиты канала связи согласовывается в процессе работы

    Note Замечание:

    При использовании libesp_gost должен использоваться ключ защиты канала между приложениями пользователя

    не рекомендуется использование libike_gost и libesp_gost в составе одного приложения
    Транспорт SA:

  • SA создаётся в libike_gost и используется в libesp_gost

  • Для транспортировки SA используется отдельный механизм передачи (транспорт) ключевой информации

Транспорт ключевой информации между IKE (производителем) и ESP/AH (получателем) удовлетворяет следующим требованиям:

  • Только успешно созданная SA может быть передана

  • SA подготавливается к транспортировке вызовом spireSerializeFn/spireSerializeFn в libike_gost

  • SA в esp_gost создаётся из сериализованных данных вызовом spiCreateFn

Уничтожение ESP/AH SA:

  • вызовом destroyFn. При этом уничтожаются криптографические объекты и очищаются рабочие данные, ассоциированные с SA

  • вызовом shutdownFn при завершении работы. При этом уничтожаются все криптографические объекты и очищаются все рабочие данные, ассоциированные со всеми SA

  • Уничтожение IKE SA фазы 2 не приводит к уничтожению ESP/AH SA, созданных на её основе

Контроль времени жизни ESP/AH SA: Под временем жизни ESP SA понимается как время жизни в секундах после создания, так и время жизни, измеренное в количестве обработанных данных.

Время жизни проверяется согласно критериям:

  • время жизни SA не может превышать 24 часа

  • при каждом использовании ESP/AH SA проверяется срок её жизни, выраженный как в секундах, так и в объёме обработанных данных

При превышении времени жизни ESP/AH SA переводится в неактивное состояние, уничтожаются криптографические объекты и очищаются ассоциированные с ней рабочие данные.

Параметры инициализации

Модуль ядра(библиотека) имеет параметры инициализации. Эти параметры не связаны с параметрами, согласуемыми в процессе выполнения обменов IKE. При инициализации не используются параметры, согласуемые в процессе работы.

Фиксированные параметры задаются на этапе компиляции исходных текстов библиотеки:

  • Версия API_MAJOR и API_MINOR

  • максимальные значения счётчиков неаутентифицированных пакетов: SIMPLE/4M/1K - 10^6, 1K в режиме KB1 - 10

  • максимальное время жизни SA - 24 часа

  • максимальный объём передаваемых данных (до расшифровывания): ESP-SIMPLE - 2^22 байтов, 4M/1K - 2^35 байтов

  • максимальный размер пакета: SIMPLE/4M - 2^16 байт, 1K - 2^32 байт

  • минимальная ширина окна для определения повторных пакетов - 128

  • возможность использования методов семейств SIMPLE и 4M зависит от исполнения ПО

Параметры, задаваемые при инициализации:

  • Распределитель памяти и его параметры

  • внешняя функция журналирования

  • дополнительный аргумент для внешней функции журналирования

  • Размер таблицы ESP SA - минимальное значение 2

Следующие параметры имеют значения по умолчанию и могут быть изменены в процессе согласования:

  • По уровням защиты КС1-КС3 по умолчанию используются преобразования ESP_GOST-SIMPLE-IMIT и AH_GOST-HMAC-4M

  • Преобразование ESP_GOST-SIMPLE-IMIT опционально

  • По уровням защиты КС1-КС3 преобразования ESP_GOST-1K-IMIT и AH_GOST-HMAC-1K опциональны

  • По уровню защиты КВ1 и выше могут использоваться только преобразования ESP_GOST-1K-IMIT и AH_GOST-HMAC-1K

  • в алгоритмах хэширования и ключевого хэширования используется узел замены id-Gost28147-89-CryptoPro-B-ParamSet в соответствии с RFC 4357, п.8.2

  • В алгоритме выработки ключа Диффи-Хеллмана используется параметр UKM=1 в соответствии с RFC 4357, п.5.2

  • параметры шифрования и имитозащиты - id-Gost28147-89-CryptoPro-B-ParamSet

  • время жизни SA в секундах - 3600 секунд. Максимальное значение 84600 (1 сутки)

Установка параметров ESP/AH SA:

  • Установка параметров возможна до создания и экспорта SA (spiSerializeFn) и выполняется функцией p2_SetParamFn

API

В реализации библиотеки и модуля ядра ОС используются соглашения, заимствуемые из базовой ОС и/или зависящие от неё:

  • определения используемых типов данных

  • определения прототипов функций, экспортируемых модулем

  • определения кодов возврата функций

  • определения кодов важности событий

  • определение прототипа внешней функции протоколирования

  • соглашения о вызовах функций модуля, включая определение порядка инициализации

  • ограничения на допустимые последовательности вызовов функций

  • ограничения на многонитевое использование

  • определение прототипа функции инициализации модуля

Перед началом использования библиотеки/модуля должна быть вызвана функция инициализации с указанием параметров.

В число параметров входят данные, необходимые для:

  • контроля целостности ПО

  • контроля выполнения ограничений на используемый объём ОЗУ

Соглашения о вызовах:

  • Все функции модуля возвращают код возврата

  • Для работы с данными неопределённой длины используются соглашения, описанные, например, в документации на API Microsoft

Многопоточная работа

Следующие функции не должны вызываться одновременно из различных потоков:

  • cpesp_init_gost

  • cpesp_shutdown_gost

  • CreateEphemFn

  • deSerializePubKeyFn

  • spiCreateFn

  • destroyFn

Функции espDecapFn и espEncapFn могут вызываться из различных потоков для различных сессий ESP/AH


Функции инициализации библиотеки ESP

Expand image Функции инициализации библиотеки ESP

 | Имя | Описание
function member | cpesp_init_gost | Используется для инициализации библиотеки libesp_gost. Функция вызывается 2 раза: на первом вызове функция определяет потребности в памяти для работы. На втором вызове, получив требуемую память, выполняет инициализацию библиотеки.
function member | cpesp_shutdown_gost | Завершает работу библиотеки.
function member | LogUfn | Определяемая пользователем функция протоколирования.
function member | SetLogLvlUfn | Определяемая пользователем функция управлением протоколирования.


Функция cpesp_init_gost
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Используется для инициализации библиотеки libesp_gost. Функция вызывается 2 раза: на первом вызове функция определяет потребности в памяти для работы. На втором вызове, получив требуемую память, выполняет инициализацию библиотеки.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC cpesp_init_gost (
   esp_gost_handle h,
   const struct esp_gost_in *in,
   unsigned uFlags,
   struct esp_gost_out *out
 );

Параметры

h
[in] Дескриптор библиотеки.
in
[in] Указатель на структуру-описатель окружения выполнения библиотеки и требований к инициализации библиотеки.
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0.
out
[out] Указатель на структуру - описатель свойств библиотеки и изменений в окружении выполнения библиотеки.

Возвращаемое значение

CAPI_NOERROR Успешное завершение.

CAPI_INTERNAL_ERROR Внутренняя ошибка. Необходимо связаться с разработчиками.


Функция cpesp_shutdown_gost
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Завершает работу библиотеки.

Expand image Синтаксис

C/C++ Copy Code
 void CAPI_EXTC cpesp_shutdown_gost (
   esp_gost_handle h,
   unsigned uFlags
 );

Параметры

h
[in] Дескриптор библиотеки
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0


Функция LogUfn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Определяемая пользователем функция протоколирования.

Expand image Синтаксис

C/C++ Copy Code
 static void CAPI_EXTC LogUfn (
   void *pUfnArg,
   log_severity_t severity,
   unsigned uFlags,
   const char *fmt,
   ...
 );

Параметры

pUfnArg
[int] Аргумент, переданный пользователем в структуре cpesp_gost_in.
severity
[in] Уровень важности сообщения.
uFlags
[in] Зарезервировано для будущего использования. Передаётся 0.
fmt
[in] Описатель формата вывода. Синтаксис соответствует синтаксису форматной строки printf().

Expand image Примечания

Если не задана, то используется стандартный printf(), который печатает все сообщения с уровнем важности больше или равный тому, который был установлен SetLogLvlUfn.

При её задании, должна быть также задана функция SetLogLvlUfn.


Функция SetLogLvlUfn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Определяемая пользователем функция управлением протоколирования.

Expand image Синтаксис

C/C++ Copy Code
 static void CAPI_EXTC SetLogLvlUfn (
   void *pUfnArg,
   log_severity_t severity,
   unsigned uFlags
 );

Параметры

pUfnArg
[in] Аргумент, переданный пользователем в структуре cpesp_gost_in.
severity
[in] Уровень важности сообщения, ниже которого сообщения не протоколируются.
uFlags
[in] Зарезервировано для будущего использования. Передаётся 0.

Expand image Примечания

Игнорируется, если не задана функция LogUfn.


Функции защиты ESP-вложений

Expand image Функции защиты ESP-вложений

Имя Описание
function member espDecapFn Используется для расшифрования и декапсуляции данных по трансформам:

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_SIMPLE_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_1K

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_4M_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_1K.

function member espEncapFn Используется для шифрования и инкапсуляции данных по трансформам:

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_SIMPLE_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_1K

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_4M_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_1K.

function member espGetParamFn Возвращает значения параметров сессии ESP и последнего обработанного пакета.


Функция espDecapFn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Используется для расшифрования и декапсуляции данных по трансформам:

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_SIMPLE_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_1K

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_4M_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_1K.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC espDecapFn (
   ESP_HANDLE sid,
   unsigned uFlags,
   char *pcNextProto,
   void *pData,
   unsigned *puDataLen
 );

Параметры

sid
[in] Идентификатор сессии ESP
uFlags
[in] Для трансформов CPIPSEC_PROTO_IPSEC_ESP может принимать значение 0 или ESP_DATA_IOVEC.

  • Значение ESP_DATA_IOVEC означает, что pData интерпретируются как указатель на массив CSP_iovec.

  • Значение 0 означает, что pData интерпретируются как указатель на линейный буфер.

  • Для трансформов CPIPSEC_PROTO_IPSEC_AH в младшем байте uFlags передаётся значение смещения заголовка AH относительно pData

pcNextProto
[out] ID вложенного протокола инкапсуляции (например, сжатия данных)
pData
[in/out] Декапсулируемые данные,

  • указатель на линейный буфер при uFlags == 0,

  • указатель на массив IOVec при uFlags == ESP_DATA_IOVEC.

puDataLen
[in/out] Длина данных, на входе в функцию

  • длина буфера, если uFlags & ESP_DATA_IOVEC == 0,

  • число координа вектор ввода вывода, если uFlags & ESP_DATA_IOVEC == ESP_DATA_IOVEC;

  • на выходе - суммарная длина ESP-заголовка и payload

Возвращаемое значение

CAPI_NOERROR Успешное завершение

CAPI_INTERNAL_ERROR Внутренняя ошибка

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_CALL_ERROR Неверные аргументы и/или неверный SPI

CAPI_PROTOCOL_ERROR Функция вызвана неверно

CAPI_SN_ERROR Ошибка SN/ESN (повторный пакет)

CAPI_PRELIMINARY_CHK_ERROR Ошибка предварительного контроля (пакет не соответствует сессии, SPI и SN/ESN)

CAPI_HMAC_ERROR Ошибка внешней имитозащиты режима CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL. В других режимах возвращается в случае несовпадения HMAC

CAPI_IMITA_ERROR Ошибка внутренней имитозащиты в режиме CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL, и имитозащиты в режиме CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_4M_IMIT, CPESP_MAC_NULL. В перечисленных режимах вычисленные значения могут быть получены функцией espGetParamFn

Expand image Примечания

Функция обрабатывает входные пакеты, представленные в форме линейного буфера или в форме IOVEC, для трансформов CPIPSEC_PROTO_IPSEC_ESP, кроме трансформа CPESP_GOST_SIMPLE_IMIT, в зависмости от значения флага uFlags. Функция обрабатывает входные пакеты, представленные в форме линейного буфера, для трансформов CPIPSEC_PROTO_IPSEC_AH.

Функция espDecap() при работе с пакетом в виде iovec воспринимает набор из N+2 координат.

  • [0]: приложением не используется, на входе должны быть обнулены, ptr - NULL, len == 0

  • [1]/[N]: содержат заголовок пакета, IV (в режимах CPESP_NULL отсутствует), PAYLOAD, padding + 2 + сумма размеров Imit-ы либо Hmac.

  • [N+1]: приложением не используется, на входе должны быть обнулены, ptr - NULL, len == 0

после успешного выполнения помещает расшифрованные значения полей PL, padding, padlen, nextproto в соответствии со структурой входного пакета этой функции. Другие поля не изменяются. Функция возвращает сумму длин заголовка пакета и PL.

При несовпадении имиты приложение имеет возможность получить значение расчитанной имиты вызовом espGetParamFn с параметром ESP_PACKETIMITA.


Функция espEncapFn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Используется для шифрования и инкапсуляции данных по трансформам:

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_SIMPLE_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_NULL, CPAH_GOST_HMAC_1K

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_4M_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_ESP, CPESP_GOST_1K_IMIT, CPESP_MAC_NULL

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_4M

  • CPIPSEC_PROTO_IPSEC_AH, CPESP_NULL, CPAH_GOST_HMAC_1K.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC espEncapFn (
   ESP_HANDLE sid,
   unsigned uFlags,
   char cNextProto,
   void *pData,
   unsigned *puDataLen,
   unsigned uBufLen
 );

Параметры

sid
[in] Идентификатор сессии ESP
uFlags
[in] Для трансформов CPIPSEC_PROTO_IPSEC_ESP может принимать значение 0 или ESP_DATA_IOVEC.

  • Значение ESP_DATA_IOVEC означает, что pData интерпретируются как указатель на массив CSP_iovec.

  • Значение 0 означает, что pData интерпретируются как указатель на линейный буфер.

  • Для трансформов CPIPSEC_PROTO_IPSEC_AH в младшем байте uFlags передаётся значение смещения заголовка AH относительно pData

cNextProto
[in] ID вложенного протокола инкапсуляции (например, сжатия данных)
pData
[in/out] Инкапсулируемые данные,

  • указатель на линейный буфер при uFlags == 0,

  • указатель на массив IOVec при uFlags == ESP_DATA_IOVEC.

  • В случае pData=0, т.е. в случае запроса длины данных инкапсуляции, uFlags д.б. равен 0, расчётная длина буфера данных будет возвращена через параметр puDataLen

puDataLen
[in/out] Входная длина данных (Длина esp header + длина PL), на выходе общая длина пакета (сумма длин заголовока пакета, IV (в режимах CPECP_NULL отсутствует), PAYLOAD, padding + 2 + Imit-ы либо Hmac)
uBufLen
[in] Размер линейного буфера данных. Число элементов массива IOVec (N+2) при uFlags == ESP_DATA_IOVEC.

Возвращаемое значение

CAPI_NOERROR Успешное завершение

CAPI_CSP_ERROR Ошибка вызова CSP

CAPI_INTERNAL_ERROR Внутренняя ошибка

CAPI_NOT_ENOUGH_SPACE Размер буфера недостаточен для инкапсуляции и шифрования данных

CAPI_CALL_ERROR Неверные аргументы

CAPI_PROTOCOL_ERROR Функция вызвана неверно

CAPI_TTL_SECS_EXPIRED_ERROR Превышено время жизни сессии

CAPI_TTL_BYTES_EXPIRED_ERROR Превышен объём данных, который может быть обработан в сессии

Expand image Примечания

Функция обрабатывает входные пакеты, представленные в форме линейного буфера или в форме IOVEC, для трансформов CPIPSEC_PROTO_IPSEC_ESP, кроме трансформа CPESP_GOST_SIMPLE_IMIT, в зависмости от значения флага uFlags. Функция обрабатывает входные пакеты, представленные в форме линейного буфера, для трансформов CPIPSEC_PROTO_IPSEC_AH.

Функция espEncap() при работе с пакетом в виде iovec воспринимает набор из N+2 координат.

  • [0]: приложением не используется, на входе должны быть обнулены, ptr - NULL, len == 0

  • [1]/[N]: содержат заголовок пакета, IV (в режимах CPESP_NULL отсутствует), PAYLOAD, padding + 2 + сумма размеров Imit-ы либо Hmac.

  • [N+1]: приложением не используется, на входе должны быть обнулены, ptr - NULL, len == 0

После успешного выполнения:

  • [0]: приложением не используется

  • [1]/[N]: содержат обработанный пакет (заголовок пакета, IV (в режимах CPESP_NULL отсутствует), PAYLOAD в шифрованном виде), шифрованный паддинг +2 и имиты (HMAC), суммарный размер координат не изменяется.

  • [N+1] приложением не используется.

Финальный пакет представлен набором координат [1..N]


Функция espGetParamFn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Возвращает значения параметров сессии ESP и последнего обработанного пакета.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC espGetParamFn (
   ESP_HANDLE sid,
   unsigned uFlags,
   unsigned uParam,
   void *pData,
   unsigned *puDataLen
 );

Параметры

sid
[in] Идентификатор сессии ESP
uFlags
[in] Значения флагов. Параметр зарезервирован для будущего использования и должен быть нулевым.
uParam
[in]

Значение uParam

Содержимое буфера pData

ESP_LENPARAMS

Возвращает длины полей синхровектора IV, ICV и значение выравнивания данных при инкапсуляции в структуре CPESP_LENPARAMS_T

  • struct CPESP_LENPARAMS_T {

  • unsigned IV_SIZE;

  • unsigned PAD_MODULE;

  • unsigned ICV_SIZE;

  • };

ESP_PACKETIMITA

Значение имитовставки пакета (внутренней для режима CPESP_GOST_1K_IMIT и значение имитовставки для режима CPESP_GOST_4M_IMIT).

pData
[in/out] Указатель на буфер данных параметра. Функция копирует соответствующие параметру данные в буфер. Формат этих данных зависит от значения uParam. Если параметр - NULL, то данные не копируются. Требуемый размер буфера в байтах возвращается в puDataLen.
puDataLen
[in/out] Указатель на буфер, содержащий длину данных параметра. При вызове функции указанный параметр содержит число байтов в буфере pData. После её исполнения параметр будет установлен числом байтов данных параметра, скопированных в буфер pData. Если буфер, соответствующий pData, недостаточно большой, чтобы в него копировать запрошенные данные, будет возвращен код ошибки CAPI_CALL_ERROR. В этом случае требуемый размер буфера возвращается в puDataLen.

Возвращаемое значение

CAPI_NOERROR Успешное завершение

CAPI_CALL_ERROR Неверные аргументы


Функции ESP, обслуживающие взаимодействие libike_gost и libesp_gost

Expand image Функции ESP, обслуживающие взаимодействие libike_gost и libesp_gost

 | Имя | Описание
function member | destroyFn | Удаление сессии ESP.
function member | spiCreateFn | Создание SPI сессии.


Функция destroyFn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Удаление сессии ESP.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC destroyFn (
   unsigned uFlags,
   ESP_HANDLE sid
 );

Параметры

uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
sid
[in] Дескриптор сессии ESP

Возвращаемое значение

CAPI_CALL_ERROR

CAPI_NOERROR


Функция spiCreateFn
Заголовочный файл: esp_gost.h
Библиотека: esp_gost.o

Создание SPI сессии.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC spiCreateFn (
   CAPI_IN esp_gost_handle h,
   CAPI_IN PRIVKEY *hPriv,
   CAPI_IN PUBKEY *hPub,
   CAPI_IN const unsigned char *pcIPsecSA,
   CAPI_IN unsigned uIPsecSALen,
   CAPI_IN unsigned uFlags,
   CAPI_OUT ESP_HANDLE *sid
 );

Параметры

h
[in] Дескриптор библиотеки
hPriv
[in] Закрытый ключ ESP обмена с IKE
hPub
[in] Открытый ключ IKE обмена с ESP. Пара (hPriv, hPub) определяет ключ обмена между ESP и IKE
pcIPsecSA
[in] Сериализованные данные из IKE
uIPsecSALen
[in] Длина сериализованных данных из IKE
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
sid
[out] Дескриптор созданной сессии

Возвращаемое значение

CAPI_NOERROR Успешное завершение

CAPI_INTERNAL_ERROR Внутренняя ошибка

CAPI_PROTOCOL_ERROR Открытый ключ или создан "в будущем" или истекло его время жизни

CAPI_NOFREE_SID_ERROR переполнена таблица ESP-сессий

CAPI_CALL_ERROR Неверные входные аргументы

CAPI_CSP_ERROR Криптографическая ошибка обработки входных данных


Справочник SADB


Структуры данных SADB

Expand image Структуры данных SADB

 | Имя | Описание
struct member | CPSADB_KEYWRAP_T | описатель зашифрованного ключа.
struct member | PRIVKEY | описатель закрытого ключа.
struct member | PUBKEY | описатель открытого ключа.
struct member | sadb_ike_param | SADB данные сессии фазы 1.
struct member | sadb_ipsec_param | Параметры spi сессии.
struct member | sadb_kdg_content_ipsec | Ключи и параметры spi сессии.
struct member | sadb_kdg_ike_content | Зашифрованные ключи и параметры фазы 1 IKE.
struct member | sadb_kdg_sadb_content | Открытый ключ SADB.
struct member | sadb_key_data_ike_gost | SADB данные сессии фазы 1.
struct member | sadb_key_data_ipsec_gost | SADB данные сессии spi.
struct member | sadb_key_data_sadb_gost | Ключ и параметры ключа SADB.
struct member | sadb_sa_param | Параметры SADB.
struct member | SADBIKESA | Сериализованные данные фазы 1 протокола IKE.
struct member | SADBIPSECSA | Сериализованные данные фазы 2 протокола IKE, описатель сессии spi.
struct member | SADBSA | Данные SADB.


Структура CPSADB_KEYWRAP_T
Заголовочный файл: typedefs_sadb.h

описатель зашифрованного ключа.

C++ Copy Code
 typedef struct CPSADB_KEYWRAP {
   CPSADB_UKM_T cpsadb_ukm;
   CPSADB_WKEY_T cpsadb_wkey;
   CPSADB_IMIT_T cpsadb_imit;
 } CPSADB_KEYWRAP_T;

Параметры

cpsadb_ukm

Поле синхровектора зашифрованного ключа.

cpsadb_wkey

Поле зашифрованного ключа.

cpsadb_imit

Поле имитозащиты зашифрованного ключа.


Структура PRIVKEY
Заголовочный файл: typedefs_sadb.h

описатель закрытого ключа.

C++ Copy Code
 typedef struct privkey {
   HCRYPTMODULE hModule;
   HCRYPTPROV hProv;
   HCRYPTKEY hKey;
 } PRIVKEY;

Параметры

hModule

Дескриптор криптопровайдера "КриптоПро CSP" (используется на уровне ядра).

hProv

Дескриптор контекста закрытого ключа.

hKey

Дескриптор закрытого ключа.


Структура PUBKEY
Заголовочный файл: typedefs_sadb.h

описатель открытого ключа.

C++ Copy Code
 typedef struct pubkey {
   Tpubkeyblob sa;
   long long born_time;
   CPIPSEC_LDURATION_T ttlutc;
 } PUBKEY;

Параметры

sa

Поле открытого ключа.

born_time

Время создания открытого ключа.

ttlutc

Время жизни открытого ключа.


Структура sadb_ike_param
Заголовочный файл: typedefs_sadb.h

SADB данные сессии фазы 1.

C++ Copy Code
 typedef struct sadbIKE_SA::sadb_ike_param {
   uint16_t sadb_ikep_auth;
   uint16_t sadb_ikep_encrypt;
   uint16_t sadb_ikep_hash;
   uint8_t sadb_ikep_ivlen;
   uint8_t sadb_ikep_padmod;
   uint8_t sadb_ikep_icvlen;
   uint8_t sadb_ikep_kelen;
   uint8_t sadb_ikep_hashlen;
 } sadb_ike_param;

Параметры

sadb_ikep_auth

Режим аутентификации CPIKE_AUTH_GOST_PSK, CPIKE_AUTH_GOST_SIGNATURE.

sadb_ikep_encrypt

Идентификатор узла замены алгорита шиврования данных ISAKMP.

sadb_ikep_hash

Идентификатор узла замены алгорита хеширования данных ISAKMP.

sadb_ikep_ivlen

Размер InitVector.

sadb_ikep_padmod

Модуль выравнивания.

sadb_ikep_icvlen

Размер ICV.

sadb_ikep_kelen

Размер KE.

sadb_ikep_hashlen

Размер HASH.


Структура sadb_ipsec_param
Заголовочный файл: typedefs_sadb.h

Параметры spi сессии.

C++ Copy Code
 typedef struct sadbIPsec_SA::sadb_ipsec_param {
   uint8_t sadb_ip_spi [4];
   uint8_t sadb_ip_dir;
   uint8_t sadb_ip_satype;
   uint8_t sadb_ip_encrypt;
   uint16_t sadb_ip_auth;
   uint8_t sadb_ip_replay;
   uint32_t sadb_ip_flags;
   uint8_t sadb_ip_ivlen;
   uint8_t sadb_ip_padmod;
   uint8_t sadb_ip_icvlen;
   uint8_t sadb_ip_hashlen;
   uint8_t sadb_ip_hmaclen;
 } sadb_ipsec_param;

Параметры

sadb_ip_spi

Поле spi.

sadb_ip_dir

Направление spi (CPESP_DIRECTION_T).

sadb_ip_satype

CPIPSEC_PROTO_IPSEC_ESP, CPIPSEC_PROTO_IPSEC_AH или SADB_SATYPE_AH/SADB_SATYPE_ESP.

sadb_ip_encrypt

комбинированный алгоритм (CPESP_TRANSFORM_ID_T)

sadb_ip_auth

Опциональный алгоритм контроля целостности (CPAH_TRANSFORM_ID_T).

sadb_ip_replay

Размер окна, всегда равен 128.

sadb_ip_flags

Признак ECN (бит CPIPSEC_AT_Ext_Serial_Number, CPIPSEC_ATP_Check_SN).

sadb_ip_ivlen

Размер SPIcookie или IV.

sadb_ip_padmod

Модуль выравнивания.

sadb_ip_icvlen

Размер ICV.

sadb_ip_hashlen

Размер HASH.

sadb_ip_hmaclen

Размер HMAC.


Структура sadb_kdg_content_ipsec
Заголовочный файл: typedefs_sadb.h

Ключи и параметры spi сессии.

C++ Copy Code
 typedef struct sadbIPsec_SA::sadb_key_data_ipsec_gost::sadb_kdg_content_ipsec {
   uint32_t sadb_kdgc_AlgId;
   uint32_t sadb_kdgc_Magic;
   CPSADB_KEYWRAP_T sadb_kdgc_Kr_e;
   CPSADB_KEYWRAP_T sadb_kdgc_Kr_i;
   uint8_t sadb_kdgc_spicookie [4];
   uint16_t sadb_kdgc_sbox;
   CPIPSEC_MAX_AUTH_ERR_T sadb_kdgc_maxauth;
   CPESP_MAX_PKTLEN_T sadb_kdgc_maxmsg;
   CPIPSEC_LDURATION_T sadb_kdgc_ttlkb;
   CPIPSEC_LDURATION_T sadb_kdgc_ttlutc;
 } sadb_kdg_content_ipsec;

Параметры

sadb_kdgc_AlgId

Идентификатор алгоритма шифрования ключа spi.

sadb_kdgc_Magic

Признак ключей по ГОСТ 28147-89.

sadb_kdgc_Kr_e

Зашифрованный ключ шифрования сессии spi.

sadb_kdgc_Kr_i

Зашифрованный ключ аутентификации сессии spi.

sadb_kdgc_spicookie

Поле spi cookie.

sadb_kdgc_sbox

Идентификатор узла замены алгоритма шифрования сессии spi.

sadb_kdgc_maxauth

Максимально допустимое число ошибок аутентификации сессии spi.

sadb_kdgc_maxmsg

Максимальный размер пакета сессии spi в килобайтах.

sadb_kdgc_ttlkb

Максимальный объём трафика сессии spi в килобайтах.

sadb_kdgc_ttlutc

Максимальное время жизни сессии spi в секундах.


Структура sadb_kdg_ike_content
Заголовочный файл: typedefs_sadb.h

Зашифрованные ключи и параметры фазы 1 IKE.

C++ Copy Code
 typedef struct sadbIKE_SA::sadb_key_data_ike_gost::sadb_kdg_ike_content {
   uint32_t sadb_kdgc_AlgId;
   uint32_t sadb_kdgc_Magic;
   CPSADB_KEYWRAP_T sadb_kdgc_SID_d;
   CPSADB_KEYWRAP_T sadb_kdgc_SID_a;
   CPSADB_KEYWRAP_T sadb_kdgc_SID_e;
   uint16_t sadb_kdgc_sbox;
   uint8_t sadb_kdgc_pfs;
   CPESP_MAX_PKTLEN_T sadb_kdgc_maxmsg;
   CPIPSEC_LDURATION_T sadb_kdgc_ttlkb;
   CPIPSEC_LDURATION_T sadb_kdgc_ttlutc;
   CPSADB_HASH_T sadb_kdgc_AUTH_I;
   CPSADB_HASH_T sadb_kdgc_AUTH_R;
   CPSADB_IMIT_T sadb_kdgc_Last_ICV;
 } sadb_kdg_ike_content;

Параметры

sadb_kdgc_AlgId

Идентификатор алгоритма шифрования данных ISAKMP.

sadb_kdgc_Magic

Признак ключей по ГОСТ 28147-89.

sadb_kdgc_SID_d

Зашифрованный ключ SKEYID_d сессии фазы 1.

sadb_kdgc_SID_a

Зашифрованный ключ SKEYID_a сессии фазы 1.

sadb_kdgc_SID_e

Зашифрованный ключ SKEYID_e сессии фазы 1.

sadb_kdgc_sbox

Идентификатор узла замены алгорита шиврования данных ISAKMP.

sadb_kdgc_pfs

Признак использования режима PFS Quick Mode.

sadb_kdgc_maxmsg

Максимально допустимое число сессий фазы 2, вырабатываемых из сессии фазы 1.

sadb_kdgc_ttlkb

Максимальный объём трафика сессии в килобайтах.

sadb_kdgc_ttlutc

Максимальное время жизни сессии в секундах.

sadb_kdgc_AUTH_I

Поле аутентификатора инициатора.

sadb_kdgc_AUTH_R

Поле аутентификатора ответчика.

sadb_kdgc_Last_ICV

Результирующий синхровектор сессии фазы 1.


Структура sadb_kdg_sadb_content
Заголовочный файл: typedefs_sadb.h

Открытый ключ SADB.

C++ Copy Code
 typedef struct sadbSADB_SA::sadb_key_data_sadb_gost::sadb_kdg_sadb_content {
   uint32_t sadb_kdgs_AlgId;
   uint32_t sadb_kdgs_Magic;
   CPSADB_KE_T sadb_kdgs_ke;
   CPIPSEC_LDURATION_T sadb_kdgs_ttlutc;
 } sadb_kdg_sadb_content;

Параметры

sadb_kdgs_AlgId

Идентификатор алгоритма открытого ключа SADB.

sadb_kdgs_Magic

Признак открытого ключа SADB.

sadb_kdgs_ke

Поле открытого ключа SADB.

sadb_kdgs_ttlutc

Максимальное время жизни ключа SADB в секундах.


Структура sadb_key_data_ike_gost
Заголовочный файл: typedefs_sadb.h

SADB данные сессии фазы 1.

C++ Copy Code
 typedef struct sadbIKE_SA::sadb_key_data_ike_gost {
   CPSADB_UKM_T sadb_kdgc_ukm;
   sadbIKE_SA::sadb_key_data_ike_gost::sadb_kdg_ike_content tbh;
   CPSADB_IMIT_T hmac;
 } sadb_key_data_ike_gost;

Параметры

sadb_kdgc_ukm

Синхровектор протокола согласования ключей клиентов SADB (выработки ключа обмена SADB).

tbh

Зашифрованные ключи и параметры фазы 1 IKE.

hmac

Контрольная сумма данных в структуре kd, substr(0..3, HMAC(XCH_SADB_vko, tbh)).


Структура sadb_key_data_ipsec_gost
Заголовочный файл: typedefs_sadb.h

SADB данные сессии spi.

C++ Copy Code
 typedef struct sadbIPsec_SA::sadb_key_data_ipsec_gost {
   CPSADB_UKM_T sadb_kdgc_ukm;
   sadbIPsec_SA::sadb_key_data_ipsec_gost::sadb_kdg_content_ipsec tbh;
   CPSADB_IMIT_T hmac;
 } sadb_key_data_ipsec_gost;

Параметры

sadb_kdgc_ukm

Синхровектор протокола согласования ключей клиентов SADB (выработки ключа обмена SADB).

tbh

Ключи и параметры spi сессии.

hmac

Контрольная сумма данных в структуре kd, substr(0..3, HMAC(XCH_SADB_vko, tbh)).


Структура sadb_key_data_sadb_gost
Заголовочный файл: typedefs_sadb.h

Ключ и параметры ключа SADB.

C++ Copy Code
 typedef struct sadbSADB_SA::sadb_key_data_sadb_gost {
   sadbSADB_SA::sadb_key_data_sadb_gost::sadb_kdg_sadb_content tbh;
   CPSADB_IMIT_T hash;
 } sadb_key_data_sadb_gost;

Параметры

tbh

Открытый ключ SADB.

hash

Контрольная сумма данных в структуре kd.


Структура sadb_sa_param
Заголовочный файл: typedefs_sadb.h

Параметры SADB.

C++ Copy Code
 typedef struct sadbSADB_SA::sadb_sa_param {
   uint16_t sadb_sadbp_gtype;
   uint16_t sadb_sadbp_group;
   uint16_t sadb_sadbp_hash;
 } sadb_sa_param;

Параметры

sadb_sadbp_gtype

Идентификатор алгоритма выработки ключа обмена SADB.

sadb_sadbp_group

Идентификатор параметра алгоритма выработки ключа обмена SADB.

sadb_sadbp_hash

Идентификатор алгоритма хеширования выработки ключа обмена SADB.


Структура SADBIKESA
Заголовочный файл: typedefs_sadb.h

Сериализованные данные фазы 1 протокола IKE.

C++ Copy Code
 typedef struct sadbIKE_SA {
   sadbIKE_SA::sadb_ike_param sap;
   sadbIKE_SA::sadb_key_data_ike_gost kd;
 } SADBIKESA;

Параметры

sap

Параметры ISAKMP.

kd

SADB данные сессии фазы 1.


Структура SADBIPSECSA
Заголовочный файл: typedefs_sadb.h

Сериализованные данные фазы 2 протокола IKE, описатель сессии spi.

C++ Copy Code
 typedef struct sadbIPsec_SA {
   sadbIPsec_SA::sadb_ipsec_param sap;
   sadbIPsec_SA::sadb_key_data_ipsec_gost kd;
 } SADBIPSECSA;

Параметры

sap

Параметры spi сессии.

kd

SADB данные сессии spi.


Структура SADBSA
Заголовочный файл: typedefs_sadb.h

Данные SADB.

C++ Copy Code
 typedef struct sadbSADB_SA {
   sadbSADB_SA::sadb_sa_param sap;
   sadbSADB_SA::sadb_key_data_sadb_gost kd;
 } SADBSA;

Параметры

sap

Параметры SADB.

kd

Ключ и параметры ключа SADB.


Работа с долговременными ключами SADB

Expand image Работа с долговременными ключами SADB

 | Имя | Описание
function member | CreateEphemFn | Создаёт открытый и закрытый ключи на основе эфемерального ключа.
function member | CreateProvFn | Создаёт открытый и закрытый ключи, используя дескриптор открытого ключевого контейнера.
function member | CreatePSKFn | Создаёт открытый и закрытый ключи из PSK.
function member | deSerializePubKeyFn | Преобразует структуру SADBSA во внутреннее представление открытого ключа PUBKEY.
function member | DestroyPrivKeyFn | Удаляет внутреннее представление закрытого ключа.
function member | DestroyPubKeyFn | Удаляет внутреннее представление открытого ключа.


Функция CreateEphemFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so, esp_gost.o

Создаёт открытый и закрытый ключи на основе эфемерального ключа.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC CreateEphemFn (
   CAPI_IN HCRYPTMODULE m,
   CAPI_IN HCRYPTPROV hProv,
   CAPI_IN unsigned uFlags,
   CAPI_INOUT PRIVKEY *hPriv,
   CAPI_INOUT unsigned char *pcsadbSA,
   CAPI_INOUT unsigned *pusadbSALen
 );

Параметры

m
[in] Дескриптор CSP, в котором будет создан контекста провайдера
hProv
[in] Дескриптор контекста провайдера CRYPT_VERIFYCONTEXT, в котором будет создан ключ обмена
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPriv
[out] внутреннее представление закрытого ключа
pcsadbSA
[out] Данные SADBSA
pusadbSALen
[out] Длина данных SADBSA

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы

CAPI_CSP_ERROR Криптографическая ошибка обработки входных данных

Expand image Примечания

Ключи вырабатываются на основе эфемерального ключа. Вырабатывает новые ключи шифрования, далее используемые для сериализации и десериализации SA фазы 1 и фазы 2 в/из кэша SA. Всегда будут использоваться ключи шифрования

Если указатель на выходной буфер равен 0, то все аргументы, кроме pusadbSALen, могут быть неопределены. В этом случае в pusadbSALen будет возвращена требуемая длина буфера


Функция CreateProvFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so

Создаёт открытый и закрытый ключи, используя дескриптор открытого ключевого контейнера.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC CreateProvFn (
   CAPI_IN HCRYPTMODULE hModule,
   CAPI_IN HCRYPTPROV hProv,
   CAPI_IN unsigned uFlags,
   CAPI_OUT PRIVKEY & hPriv,
   CAPI_OUT unsigned char *pcsadbSA,
   CAPI_OUT unsigned *pusadbSALen
 );

Параметры

hModule
[in] Дескриптор CSP
hProv
[in] контекст контейнера
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPriv
[out] внутреннее представление закрытого ключа
pcsadbSA
[out] буфер транспортного представления открытого ключа
pusadbSALen
[out] размер буфера транспортного представления открытого ключа

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы

CAPI_CSP_ERROR Криптографическая ошибка обработки входных данных

Expand image Примечания

Ключи вырабатываются на основе hProv. вырабатывает новые ключи, далее используемые для сериализации и десериализации SA фазы 1 и фазы 2 в/из кэша SA. Всегда будут использоваться ключи шифрования. hProv не нужен после вызова и может быть освобождён

Если указатель на выходной буфер равен 0, то все аргументы, кроме pusadbSALen, могут быть неопределены. В этом случае в pusadbSALen будет возвращена требуемая длина буфера


Функция CreatePSKFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so

Создаёт открытый и закрытый ключи из PSK.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC CreatePSKFn (
   CAPI_IN HCRYPTMODULE hModule,
   CAPI_IN HCRYPTPROV hProv,
   CAPI_IN const vblob & SitePSK,
   CAPI_IN const vblob & SiteNetID,
   CAPI_IN const vblob & SiteID,
   CAPI_IN unsigned uFlags,
   CAPI_OUT PRIVKEY & hPriv,
   CAPI_OUT unsigned char *pcsadbSA,
   CAPI_INOUT unsigned *pusadbSALen
 );

Параметры

hModule
[in] Дескриптор CSP
hProv
[in] Дескриптор контекста провайдера CRYPT_VERIFYCONTEXT
SitePSK
[in] PSK узла сети
SiteNetID
[in] Идентификатор канала связи
SiteID
[in] Уникальный идентификатор узла сети (например, fingerprint сертификата, серийный номер или аппаратный адрес)
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPriv
[inout] внутреннее представление закрытого ключа.
pcsadbSA
[inout] буфер транспортного представления открытого ключа
pusadbSALen
[inout] размер буфера транспортного представления открытого ключа

Возвращаемое значение

CAPI_NOERROR Нормальное завершение.

CAPI_CALL_ERROR Неверные входные аргументы.

CAPI_PSK_TTL_EXPIRED_ERROR Срок действия PSK истёк.

CAPI_IMITA_ERROR PSK искажён (или PSK не соответствует SiteID и SiteNetID).

CAPI_PSK_ERROR PSK искажён (или PSK не соответствует SiteID и SiteNetID).

CAPI_CSP_ERROR ошибка вызова CSP

Expand image Примечания

Ключи вырабатываются из SitePSK. Вырабатывает новые ключи шифрования, далее используемые для сериализации и десериализации SA фазы 1 и фазы 2 в/из кэша SA. Всегда будут использоваться ключи шифрования

Если указатель на выходной буфер равен 0, то все аргументы, кроме pusadbSALen, могут быть неопределены. В этом случае в pusadbSALen будет возвращена требуемая длина буфера

SEE ALSO

p1_SetPSKFn, getPSKnotAfterFn, genpsk


Функция deSerializePubKeyFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so, esp_gost.o

Преобразует структуру SADBSA во внутреннее представление открытого ключа PUBKEY.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC deSerializePubKeyFn (
   CAPI_IN HCRYPTMODULE m,
   CAPI_IN HCRYPTPROV hProv,
   CAPI_IN const unsigned char *pcsadbSA,
   CAPI_IN unsigned pcsadbSALen,
   CAPI_IN unsigned uFlags,
   CAPI_INOUT PUBKEY *hPub
 );

Параметры

m
[in] handle CSP, в котором будет создан ключ обмена с IKE. Используется только в ядре
hProv
[in] Дескриптор контекста провайдера
pcsadbSA
[in] Данные SADBSA
pcsadbSALen
[in] Длина данных SADBSA
uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPub
[out] внутреннее представление открытого ключа

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы

CAPI_INTERNAL_ERROR Внутренняя ошибка библиотеки

Expand image Примечания

Преобразовывает PUBLICKEYBLOB во внутреннее представление


Функция DestroyPrivKeyFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so, esp_gost.o

Удаляет внутреннее представление закрытого ключа.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC DestroyPrivKeyFn (
   CAPI_IN unsigned uFlags,
   CAPI_INOUT PRIVKEY *hPriv
 );

Параметры

uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPriv
[inout] внутреннее представление закрытого ключа

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы

Expand image Примечания

Возможные ошибки CSP не проверяются и не возвращаются


Функция DestroyPubKeyFn
Заголовочный файл: sadb.h
Библиотека: libike_gost.so, esp_gost.o

Удаляет внутреннее представление открытого ключа.

Expand image Синтаксис

C/C++ Copy Code
 capi_result CAPI_EXTC DestroyPubKeyFn (
   CAPI_IN unsigned uFlags,
   CAPI_INOUT PUBKEY *hPub
 );

Параметры

uFlags
[in] Зарезервировано для будущего использования. Должен быть равен 0
hPub
[inout] внутреннее представление открытого ключа

Возвращаемое значение

CAPI_NOERROR Нормальное завершение

CAPI_CALL_ERROR Неверные входные аргументы


Справочник утилит

В этом разделе

Создание PSK


Создание PSK

NAME

genpsk - Утилита генерации и проверки PSK

SYNOPSIS

genpsk [-n <NetId>] [-D <NetName>] -f <Function> [-d <FilePath>] [-k <Container>] [-p <PIN>] [-r] [-m <PSK time to live>] [-P <PrintType>] [-K <checking PSK>] [-S <on/off>] [-N <NodeID #1> <NodeID #2> ...]

DESCRIPTION

Создаёт или проверяет PSK для данного канала связи (направления связи). Выдаёт значения ключей в "стандартный вывод" либо в файл.

OPTIONS

Ключ | Описание
-n <NetId> | Идентификатор сети. При создании ключевого контейнера либо при генерации ключей по умолчанию используется Идентификатор сети. При генерации PSK без ключевого контейнера Идентификатор сети должен передаваться в аргументах командной строки -- в противном случае возвращается ошибка.
-D <NetName> | Название направления связи. Используется как заголовок при печати ключей. Задаётся при создании ключевого контейнера. При генерации ключей по умолчанию используется имя, определённое при создании контейнера. При генерации PSK без ключевого контейнера название направления связи должно передаваться в аргументах командной строки -- в противном случае возвращается ошибка. Используется как имя файла при записи в файл.
-d <FilePath> | Путь к файлам ключей. Должен завершаться символом '/'. полные имена файлов: FilePath|NetName_0, FilePath|NetName_1. Если отсутствует, то печать в файлы не производится.
-f <Function> | Выполняемая функция(CreateBasePSK, DeleteBasePSK, GenPSK, chkpsk).
-k <Container> | Имя ключевого контейнера, использующегося как хранилище ключа. Full qualified container name в случае ОС Linux.
-p <PIN> | Пароль (PIN) на ключевой контейнер.
-P <PrintType> | Форма вывода на печать. По признаку "Net" осуществляется печать PSK в двух частях, по признаку "CMAK" - единым массивом.
-S | Если установлен, то производится выдача на экран.
-m <PSK time to live> | Срок действия PSK в месяцах (не более 6 месяцев).
-r | Удалять разделители ':', '-', '/' и '\' из идентификаторов узлов.
-K <checked PSK> | Значение проверяемого PSK.
-N <Stations List> | Список узлов связи.

EXAMPLES

Вариаты использования программы genpsk:

Создание ключевого контейнера с именем "BasePSK_SM", ключ которого будет использоваться для генерации PSK с постоянным значением:
genpsk -D Moscow -n Net73 -f CreateBasePSK -k BasePSK_SM -p 123456 -m 6

Генерация PSK от контейнера "BasePSK_SM". Допускается многократное воспроизведение PSK:
genpsk -D Moscow -n Net73 -v 23 -f GenPSK -k BasePSK_SM -p 123456 -m 6 -P Net -S -N St1 St2 St3

Уничтожение ключевого контейнера с именем "BasePSK_SM":
genpsk -f DeleteBasePSK -k BasePSK_SM

Разовое создание PSK (эквивалент командной строки genpsk предыдущей версии):
genpsk -D Moscow -n Net73 -v 23 -f GenPSK -m 5 -P Net -S -N St1 St2 St3

Проверка значения PSK. Для каждой станции проверка должна осуществляться независимо:
genpsk -D Moscow -n Net73 -v 23 -f chkpsk -K ZQGAVC9XX2LDZPW3K96TZYQU8QGY -N St1

Дополнение:
в случае использование утилиты genpsk в ОС Linux, имя контейнера должно быть full qualified container name. Например, вместо "-k PC" будет "-k '\\.\HDIMAGE\PС'"

Примеры использования программы genpsk:

genpsk -n "Moscow-Smolensk" -D Net73 -f GenPSK -m 6 -P Net -S -N Moscow-1 Smolensk-1 Moscow-2
genpsk
UTC Mon Jan 17 13:38:44 2011

Net73. Moscow-Smolensk. Number of stations 3.
Stations: Moscow-1 Smolensk-1 Moscow-2
Part 0. Valid for (months) 6.

Net73 UTC Mon Jan 17 13:38:44 2011
Moscow-1 part 0 valid for (months) 6
Z3AW6ND731KADX0
Z3AW6ND731KADX0
Z3AW6ND731KADX0

Net73 UTC Mon Jan 17 13:38:44 2011
Moscow-2 part 0 valid for (months) 6
6AKXUEEKPMPTFX0
6AKXUEEKPMPTFX0
6AKXUEEKPMPTFX0

genpsk
UTC Mon Jan 17 13:38:44 2011

Net73. Moscow-Smolensk. Number of stations 3.
Stations: Moscow-1 Smolensk-1 Moscow-2
Part 1. Valid for (months) 6.

Net73 UTC Mon Jan 17 13:38:44 2011
Moscow-1 part 1 valid for (months) 6
AY1GZ94WQEQD6E0
AY1GZ94WQEQD6E0
AY1GZ94WQEQD6E0

Net73 UTC Mon Jan 17 13:38:44 2011
Smolensk-1 part 1 valid for (months) 6
YQYYD7FEMQ5Y9E0
YQYYD7FEMQ5Y9E0
YQYYD7FEMQ5Y9E0

Net73 UTC Mon Jan 17 13:38:44 2011
Moscow-2 part 1 valid for (months) 6
1T0ZM1P53ZF20E0
1T0ZM1P53ZF20E0
1T0ZM1P53ZF20E0

EXIT STATUS

В случае ошибки код завершения не равен 0

SEE ALSO

p1_SetPSKFn, getPSKnotAfterFn