Руководство по работе с SDK

Получение

Для получения комплекта разработчика JC-Mobile SDK iOS оформите заявку.

Состав SDK

Каталог “libs”

Каталог содержит все необходимые библиотеки:
  • jcPKCS11 – каталог с Единой библиотекой PKCS #11.
    • include – каталог с заголовочными файлами;
    • lib – каталог со статической библиотекой: jcPKCS11-2.a;
    • jcPKCS11_version.txt – текстовый файл с информацией о сборке.
  • openssl – каталог с OpenSSL v.1.1.0f.
    • include – каталог с заголовочными файлами;
    • lib – каталог со статическими библиотеками: libssl.a, libcrypto.a;
    • openssl_version.txt – текстовый файл с информацией о сборке.
  • openssl_gost_engine – каталог с реализацией алгоритмов ГОСТ для OpenSSL v.1.1.0f.
    • include – каталог с заголовочными файлами;
    • lib – каталог со статической библиотекой: libgost_engine.a;
    • openssl_ge_version.txt – текстовый файл с информацией о сборке.

Каталог “samples”

Каталог содержит примеры по работе с Единой библиотекой PKCS #11.

  • примеры «GOST2_...» демонстрируют работу с апплетом Криптотокен 2 ЭП;
  • примеры «PKI_...» демонстрируют работу с апплетом Laser;
  • примеры «GOST_...» демонстрируют работу с апплетом Криптотокен;
  • примеры «LICENSE_...» демонстрируют работу с апплетом Лицензионный.

Полный список примеров представлен в разделе Список примеров.

Встраивание

Для работы с устройствами JaCarta используется Единая библиотека PKCS #11, предоставляющая высокоуровневый интерфейс (см. API Единой библиотеки PKCS #11) для взаимодействия по стандарту PKCS #11 v2.30.

Принципы работы с Единой библиотекой PKCS #11 описаны в разделе Руководство по работе с библиотекой.

Интеграция в приложение

Предположим, что проект имеет следующую файловую структуру:

../../_images/ios_project_fs.png

Шаги по интеграции в проект:

  1. В Linked Frameworks and Libraries добавить:

    • ExternalAccessory.framework;
    • CoreBluetooth.framework;
    • libjcPKCS11-2.a;
    • libssl.a;
    • libcrypto.a;
    • libgost_engine.a.

    Примечание

    Если API JC-Mobile SDK вызывается в файлах с расширением *.m, то дополнительно требуется добавить libc++.tdb.

    ../../_images/ios_linked_libs.png
  2. В Build Settings отключить Bitcode установив в параметр Enable Bitcode значение No.

    ../../_images/ios_bitcode.png
  3. В Build Settings в параметр Header Search Paths добавить путь к директории заголовочных файлов jcPKCS11/include, входящей в состав дистрибутива.

    Примечание

    Если используете openssl, то дополнительно требуется добавить openssl/include.

    ../../_images/ios_header_sp.png
  4. В Build Settings в параметр Library Search Paths добавить пути к директории с библиотеками jcPKCS11/lib, openssl/lib и openssl_gost_engine/lib, входящих в состав дистрибутива.

    ../../_images/ios_lib_sp.png
  5. В Info.plist добавить ключ Supported external accessory protocols со следующими значениями:

    • com.ftsafe.iR301 - для ридеров iR301-UL c разъемом Lightning;
    • com.ftsafe.bR301 - для Bluetooth ридеров bR301.
    ../../_images/ios_info_plist.png
  6. В Info.plist добавить ключ NSBluetoothPeripheralUsageDescription и предупредить пользователя, что приложение может работать с Bluetooth-устройствами.

    Важно

    Без этого ключа приложение не пройдет проверку в App Store Connect.

  7. Для использования API в исходном коде необходимо импортировать файл jcPKCS11/jcPKCS11.h.

    #import "jcPKCS11/jcPKCS11.h"
    

Администрирование смарт-карт JaCarta

Для выполнение некоторых административных функций со смарт–картами JaCarta ГОСТ, JaCarta PKI и JaCarta PKI/ГОСТ можно использовать мобильное приложение JaCarta, опубликованное в Apple App Store.

Для расширенного администрирования смарт–карт следует использовать ПК Единый Клиент JaCarta, установленный на ПК.

Работа с примерами

Сборка с помощью CLI

  1. Выбрать интересующий пример. Наименования всех примеров можно получить выполнив команду:

    $ xcodebuild -list -workspace samples/iOSSamples.xcworkspace | grep -v common
    
  2. Собрать приложение, например GOST2_info, выполнив команду:

    $ xcodebuild -workspace samples/iOSSamples.xcworkspace -scheme GOST2_info -configuration Release DSTROOT=../../_out clean install
    

    Результат сборки будет лежать в директории ./_out.

Сборка с помощью Xcode

  1. Открыть с помощью Xcode открыть iOSSamples.workspace.
  2. Собрать интересующий проект, выбрав его на верхней панели из выпадающего списка и нажав клавиши CMD+B или выбрав пункт меню Product -> Build.

Список примеров

В комплект разработчика JC-Mobile SDK iOS входят примеры работы с апплетами:
  • Криптотокен 2 ЭП;
  • Laser;
  • Криптотокен;
  • Лицензионный.

Примеры для Криптотокен 2 ЭП

  • GOST2_info – получение информации о библиотеке, ридере, слоте и апплете;
  • GOST2_initUser – подготовка JaCarta-2 ГОСТ к работе с jcPKCS11 после инициализации устройства в ПО “АРМ разработчика”;
  • GOST2_clear – очистка всех пользовательских данных с JaCarta-2 ГОСТ;
  • GOST2_keyPairAndCertificate2012 – создание/удаление ключевой пары ГОСТ Р 34.10–2012 (длина ключа 256 бит) и соответствующего ей сертификата;
  • GOST2_certificateInfo – получение информации о сертификатах;
  • GOST2_certificateRenewal – создания запроса на перевыпуск сертификата;
  • GOST2_signAndVerify2012 – создания и проверки подписи данных по ГОСТ Р 34.10–2012 (длина ключа 256 бит);
  • GOST2_signAndVerifyExternalHash2012 – создания и проверки подписи хэша по ГОСТ Р 34.11–2012 (длина хэш–кода 256 бит);
  • GOST2_cmsSignAndVerify2012 – создания и проверки подписи сообщения в формате CMS типа signed data с ГОСТ Р 34.10–2012 (длина ключа 256 бит);
  • GOST2_changePinUser – смена PIN-кода пользователя;
  • GOST2_unlockPinUser – разблокировка PIN-кода пользователя с помощью предъявления PUK-кода;
  • GOST2_data – создание, поиск и удаление бинарных объектов.

Примеры для Laser

  • PKI_appletStatus – получение информации о готовности апплета к использованию;
  • PKI_init – инициализация апплета и выпуск сертификата;
  • PKI_info – получение полной информации о библиотеке, слоте и электронном ключе;
  • PKI_pinUser – изменение PIN-кода пользователя;
  • PKI_certInfo – получение информации о сертификатах, размещённых в памяти электронного ключа;
  • PKI_certReissue — перевыпуск сертификата;
  • PKI_certDelete – удаление сертификата с ключевой парой;
  • PKI_signAndVerify – создание и проверка электронной подписи;
  • PKI_CMSSignAndVerify – создание и проверка электронной подписи в формате CMS;
  • PKI_data – запись и чтение файлов в памяти электронного ключа;
  • PKI_pinAdmin – изменение PIN-кода администратора;
  • PKI_pinUserUnblock – сброс попыток предъявления PIN-кода пользователя.

Примеры для Криптотокен

  • GOST_appletStatus – получение информации о готовности апплета к использованию;
  • GOST_init – установка PIN-кода пользователя и выпуск сертификата;
  • GOST_info – получение полной информации о библиотеке, слоте и электронном ключе;
  • GOST_pinUser – изменение PIN-кода пользователя;
  • GOST_certInfo – получение информации о сертификатах, размещённых в памяти электронного ключа;
  • GOST_reissue – перевыпуск сертификата;
  • GOST_delete – удаление сертификата с ключевой парой;
  • GOST_signAndVerify – создание и проверка электронной подписи;
  • GOST_pkcs7SignAndVerify – создание и проверка электронной подписи в формате PKCS #7;
  • GOST_data – запись и чтение файлов в памяти электронного ключа;
  • GOST_encryption – зашифрование и расшифрование данных;
  • GOST_pinAdmin – изменение PIN-кода администратора;
  • GOST_pinUserUnblock – сброс попыток предъявления PIN-кода пользователя.

Примеры для апплета Лицензионный

  • LICENSE_vendorsList – получение списка вендоров, установленных в апплете;
  • LICENSE_changeKey – смена ключа доступа вендора;
  • LICENSE_createLicenses – создание лицензий на апплете;
  • LICENSE_readLicenses – чтение всех лицензий;
  • LICENSE_deleteLicenses – удаление лицензий с апплета.