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

Получение

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

Состав SDK

Каталог “libs”

Каталог содержит все необходимые библиотеки:
  • Java-обертка над единой библиотекой PKCS #11, а также библиотекой обеспечивающую механизм JNA: jcPKCS11-2.jar, jna-min.jar;
  • arm64-v8a – каталог с набором библиотек для 64-битной архитектуры Android: libjcPKCS11-2.so, libgti_jni.so, libjnidispatch.so;
  • armeabi-v7a – каталог с набором библиотек для 32-битной архитектуры Android: libjcPKCS11-2.so, libgti_jni.so, libjnidispatch.so.

Каталог “sources”

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

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

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

Встраивание

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

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

Рассмотрим пример встраивания в приложение проект которого создан в IDE Eclipse for Java Developers.

  1. Скопировать папку libs и ее содержимое в корневую директорию проекта приложения.

Проект будет иметь следующую файловую структуру:

../../_images/android_project_fs.png

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

  1. В Java Build Path в закладку Libraries добавить:

    • common.jar;
    • jcPKCS11-2.jar;
    ../../_images/android_linked_libs.png
  2. Разрешить приложению получать доступ к Bluetooth и USB ридерам, для этого в AndroidManifest.xml добавить строчки:

    <manifest ...>
       <uses-feature android:name="android.hardware.usb.host" />
       <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="28"/>
       ...
       <uses-permission android:name="android.permission.BLUETOOTH" />
       <uses-permission android:name="android.permission.USB_PERMISSION" />
    
  3. Для того чтобы приложение получало уведомление о том, что подключено USB-устройство необходимо добавить в AndroidManifest.xml intent-filter для android.hardware.usb.action.USB_DEVICE_ATTACHED:

    <application ...>
       <activity ...>
       ...
          <intent-filter>
              <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
          </intent-filter>
    

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

Для администрирования смарт–карт JaCarta ГОСТ, JaCarta PKI и JaCarta PKI/ГОСТ следует использовать ПК Единый Клиент JaCarta, установленный на ПК.

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

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

  1. Выполнить подготовку сборочного окружения

    • Установить java 1.8

    • Установить Android SDK

    • Скопировать tools из android-sdk версии 25

    • Установить утилиту для автоматизации сборки Apache Ant

    • Задать переменные среды для Android SDK build-tools и утилиты автоматизации сборки Ant

      Например:

      export ANTROOT="/Users/username/Library/android/apache-ant"
      export ANDROID_HOME="/Users/username/Library/android/android-sdk"
      
    • Добавить в переменную PATH пути до папки, где установлен Android SDK и утилита автоматизации сборки Ant

      Например:

      export PATH=${PATH}:/Users/username/Library/android/apache-ant/bin
      export PATH=${PATH}:/Users/username/Library/android/android-sdk/build-tools/28.0.2
      export PATH=${PATH}:/Users/username/Library/android/android-sdk/platform-tools
      
  2. Выполнить сборку компонента common.jar. для этого нужно выполнить следующие действия:

    • перейти в директорию с компонентом common и выпонить команду:

      $ant -f common-build.xml debug
      
    • результат сборки окажется в папке libs в виде файла common.jar.

  3. Выполнить сборку интересующего примера:

    • перейти в директорию с необходимым примером (например ./sources/GOST2_info) и выполнить команду:

      $ant -f build.xml debug
      
    • результат сборки окажется в папке ./sources/GOST2_info/bin, в виде файла GOST2_info-debug.apk.

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

Рассмотрим пример сборки в среде Eclipse for Java Developers. Для сборки необходимо, чтобы был прописан путь к Android SDK, который указывается в настройках Eclipse->Preferences->Android в поле SDK Location. По указанному пути должны быть предустановлены необходимые SDK platform, platform-tools и build-tools. Например:

  • Android SDK platform - версии 29;
  • platform-tools - версии 29.0.2;
  • build-tools - версии 25.0.3.

Если сборочное окружение настроено корректно, то шаги по сборке выглядят следующим образом:

  1. Скопировать папку libs и ее содержимое в корневую директорию проекта компонента common и проекта с необходимым примером.

  2. Открыть IDE Eclipse for Java Developers.

  3. Выполнить иморт проекта компонента common и проекта интересующего примера выбрав пункт “Existing Projects into Workspace”.

  4. Добавить библиотеку jcPKCS11-2.jar для компонента common в Java Build Path в закладку Libraries.

  5. Собрать компонент common, выбрав выбрав пункт Build Project из выпадающего меню выбрав пункт меню Project -> Build Project. в папке common/bin окажется файл common.jar

  6. Скопировать файл common.jar в папку libs проекта примера.

  7. Добавить библиотеку jcPKCS11-2.jar и common.jar Java Build Path в закладку Libraries для проекта примера.

  8. Для запуска примера на смартфоне необходимо создать конфигурацию, для чего щелкнуть на проекте правой кнопкой мыши и выбрать пункт меню Run As -> Run Configurations.

    ../../_images/android_sample_run.png
  9. В открывшейся форме выбрать пункт Android Aplication и настроить ее.

  10. Подключить смартфон и нажать кнопку Run.

    ../../_images/android_run_configurations.png

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

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

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

  • GOST2_info – получение информации о библиотеке, ридере, слоте и апплете;
  • GOST2_initUser – подготовка JaCarta-2 ГОСТ к работе с jcPKCS11 после инициализации устройства в ПО “АРМ разработчика”;
  • GOST2_delete – очистка всех пользовательских данных с 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_reissue — перевыпуск сертификата;
  • PKI_delete – удаление сертификата с ключевой парой;
  • 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_appletStatus – получение информации о готовности апплета к использованию;
  • LICENSE_changeKey – смена ключа доступа вендора;
  • LICENSE_init – создание лицензий на апплете;
  • LICENSE_read – чтение всех лицензий;
  • LICENSE_delete – удаление лицензий с апплета.